From 2818587736660bed20e458aa2fb5d123b061a8ef Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 11 Apr 2021 13:43:32 -0500 Subject: [PATCH 1/3] More on tutorial --- doc/optparse/argument_converters.rdoc | 24 ++++++++++++++-- doc/optparse/ruby/basic.rb | 16 +++++++++++ doc/optparse/ruby/match_converter.rb | 9 ++++++ doc/optparse/tutorial.rdoc | 40 +++++++++++++++++++++++++-- 4 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 doc/optparse/ruby/basic.rb create mode 100644 doc/optparse/ruby/match_converter.rb diff --git a/doc/optparse/argument_converters.rdoc b/doc/optparse/argument_converters.rdoc index fc5a015..1e30394 100644 --- a/doc/optparse/argument_converters.rdoc +++ b/doc/optparse/argument_converters.rdoc @@ -344,9 +344,17 @@ Executions: === Custom Argument Converters +An argument converter has: + You can create custom argument converters. -To create a custom converter, call OptionParser#accept with a class argument, -along with a block that converts the argument and returns the converted value. +To create a custom converter, call OptionParser#accept with: + +- An identifier, which may be any object. +- An optional match pattern, which defaults to /.*/m. +- A block that accepts the argument and returns the converted value. + +This custom converter accepts any argument and converts it, +if possible, to a \Complex object. :include: ruby/custom_converter.rb @@ -360,3 +368,15 @@ Executions: [(1+2i), Complex] $ ruby custom_converter.rb --complex 0.3-0.5i [(0.3-0.5i), Complex] + +This custom converter accepts any 1-word argument +and capitalizes it, if possible. + + :include: ruby/match_converter.rb + +Executions: + + $ ruby match_converter.rb --capitalize foo + ["Foo", String] + $ ruby match_converter.rb --capitalize "foo bar" + match_converter.rb:9:in `
': invalid argument: --capitalize foo bar (OptionParser::InvalidArgument) diff --git a/doc/optparse/ruby/basic.rb b/doc/optparse/ruby/basic.rb new file mode 100644 index 0000000..617d337 --- /dev/null +++ b/doc/optparse/ruby/basic.rb @@ -0,0 +1,16 @@ +# Require the OptionParser code. +require 'optparse' +# Create an OptionParser object. +parser = OptionParser.new +# Define one or more options. +parser.on('-x', 'Whether to X') do |value| + p ['x', value] +end +parser.on('-y', 'Whether to Y') do |value| + p ['y', value] +end +parser.on('-z', 'Whether to Z') do |value| + p ['z', value] +end +# Parse the command line. +parser.parse! diff --git a/doc/optparse/ruby/match_converter.rb b/doc/optparse/ruby/match_converter.rb new file mode 100644 index 0000000..13dc5fc --- /dev/null +++ b/doc/optparse/ruby/match_converter.rb @@ -0,0 +1,9 @@ +require 'optparse/date' +parser = OptionParser.new +parser.accept(:capitalize, /\w*/) do |value| + value.capitalize +end +parser.on('--capitalize XXX', :capitalize) do |value| + p [value, value.class] +end +parser.parse! diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index 3474f1e..ad8486d 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -1,6 +1,6 @@ == Tutorial -=== Why OptionParser? +=== Why \OptionParser? When a Ruby program executes, it captures its command-line arguments and options into variable ARGV. @@ -34,6 +34,7 @@ The class also has: === Contents +- {To Begin With}[#label-To+Begin+With] - {Defining Options}[#label-Defining+Options] - {Option Names}[#label-Option+Names] - {Short Option Names}[#label-Short+Option+Names] @@ -50,6 +51,42 @@ The class also has: - {Default Values for Options}[#label-Default+Values+for+Options] - {Argument Converters}[#label-Argument+Converters] +=== To Begin With + +To use \OptionParser: + +1. Require the \OptionParser code. +2. Create an \OptionParser object. +3. Define one or more options. +4. Parse the command line. + +File +basic.rb+ defines three options, -x, +-y, and -z, each with a descriptive string, +and each with a block. + + :include: ruby/basic.rb + +From these defined options, the parser automatically builds help text: + + $ ruby basic.rb --help + Usage: basic [options] + -x Whether to X + -y Whether to Y + -z Whether to Z + +When an option is found during parsing, +the block defined for the option is called with the argument value. + +Executions: + + $ ruby basic.rb -x -z + ["x", true] + ["z", true] + $ ruby basic.rb -z -y -x + ["z", true] + ["y", true] + ["x", true] + === Defining Options A common way to define an option in \OptionParser @@ -361,7 +398,6 @@ Executions: $ ruby default_values.rb --yyy FOO {:yyy=>"FOO", :zzz=>"BBB"} - === Argument Converters An option can specify that its argument is to be converted From 58721084e4c503e2148c083f4d87f7e15014920b Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 11 Apr 2021 15:51:47 -0500 Subject: [PATCH 2/3] More on tutorial --- doc/optparse/argument_converters.rdoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/optparse/argument_converters.rdoc b/doc/optparse/argument_converters.rdoc index 1e30394..8ad29eb 100644 --- a/doc/optparse/argument_converters.rdoc +++ b/doc/optparse/argument_converters.rdoc @@ -344,8 +344,6 @@ Executions: === Custom Argument Converters -An argument converter has: - You can create custom argument converters. To create a custom converter, call OptionParser#accept with: From bf4801e4ca17d1797cb7f6db12ae83082c84b362 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 12 Apr 2021 16:59:36 -0500 Subject: [PATCH 3/3] More on tutorial --- doc/optparse/ruby/help.rb | 21 ++++++++ doc/optparse/ruby/help_banner.rb | 7 +++ doc/optparse/ruby/help_format.rb | 25 ++++++++++ doc/optparse/ruby/help_program_name.rb | 7 +++ doc/optparse/tutorial.rdoc | 69 ++++++++++++++++++++++++++ 5 files changed, 129 insertions(+) create mode 100644 doc/optparse/ruby/help.rb create mode 100644 doc/optparse/ruby/help_banner.rb create mode 100644 doc/optparse/ruby/help_format.rb create mode 100644 doc/optparse/ruby/help_program_name.rb diff --git a/doc/optparse/ruby/help.rb b/doc/optparse/ruby/help.rb new file mode 100644 index 0000000..72f1b93 --- /dev/null +++ b/doc/optparse/ruby/help.rb @@ -0,0 +1,21 @@ +require 'optparse' +parser = OptionParser.new +parser.on( + '-x', '--xxx', + 'Adipiscing elit. Aenean commodo ligula eget.', + 'Aenean massa. Cum sociis natoque penatibus', + ) +parser.on( + '-y', '--yyy YYY', + 'Lorem ipsum dolor sit amet, consectetuer.' +) +parser.on( + '-z', '--zzz [ZZZ]', + 'Et magnis dis parturient montes, nascetur', + 'ridiculus mus. Donec quam felis, ultricies', + 'nec, pellentesque eu, pretium quis, sem.', + ) +parser.parse! + + + diff --git a/doc/optparse/ruby/help_banner.rb b/doc/optparse/ruby/help_banner.rb new file mode 100644 index 0000000..0943a3e --- /dev/null +++ b/doc/optparse/ruby/help_banner.rb @@ -0,0 +1,7 @@ +require 'optparse' +parser = OptionParser.new +parser.banner = "Usage: ruby help_banner.rb" +parser.parse! + + + diff --git a/doc/optparse/ruby/help_format.rb b/doc/optparse/ruby/help_format.rb new file mode 100644 index 0000000..a2f1e85 --- /dev/null +++ b/doc/optparse/ruby/help_format.rb @@ -0,0 +1,25 @@ +require 'optparse' +parser = OptionParser.new( + 'ruby help_format.rb [options]', # Banner + 20, # Width of options field + ' ' * 2 # Indentation +) +parser.on( + '-x', '--xxx', + 'Adipiscing elit. Aenean commodo ligula eget.', + 'Aenean massa. Cum sociis natoque penatibus', + ) +parser.on( + '-y', '--yyy YYY', + 'Lorem ipsum dolor sit amet, consectetuer.' +) +parser.on( + '-z', '--zzz [ZZZ]', + 'Et magnis dis parturient montes, nascetur', + 'ridiculus mus. Donec quam felis, ultricies', + 'nec, pellentesque eu, pretium quis, sem.', + ) +parser.parse! + + + diff --git a/doc/optparse/ruby/help_program_name.rb b/doc/optparse/ruby/help_program_name.rb new file mode 100644 index 0000000..7b3fbff --- /dev/null +++ b/doc/optparse/ruby/help_program_name.rb @@ -0,0 +1,7 @@ +require 'optparse' +parser = OptionParser.new +parser.program_name = 'help_program_name.rb' +parser.parse! + + + diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index ad8486d..c14a418 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -50,6 +50,7 @@ The class also has: - {Checking for Missing Options}[#label-Checking+for+Missing+Options] - {Default Values for Options}[#label-Default+Values+for+Options] - {Argument Converters}[#label-Argument+Converters] +- {Help}[#label-Help] === To Begin With @@ -422,3 +423,71 @@ Executions: You can also define custom converters. See {Argument Converters}[./argument_converters_rdoc.html] for both built-in and custom converters. + +=== Help + +\OptionParser makes automatically generated help text available. + +The help text consists of: + +- A banner, showing the usage. +- Option short and long names. +- Option dummy argument names. +- Option descriptions. + +Example code: + + :include: ruby/help.rb + +The option names and dummy argument names are defined as described above. + +The option description consists of the strings that are not themselves option names; +An option can have more than one description string. +Execution: + + Usage: help [options] + -x, --xxx Adipiscing elit. Aenean commodo ligula eget. + Aenean massa. Cum sociis natoque penatibus + -y, --yyy YYY Lorem ipsum dolor sit amet, consectetuer. + -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur + ridiculus mus. Donec quam felis, ultricies + nec, pellentesque eu, pretium quis, sem. + +The program name is included in the default banner: +Usage: #{program_name} [options]; +you can change the program name. + + :include: ruby/help_program_name.rb + +Execution: + + $ ruby help_program_name.rb --help + Usage: help_program_name.rb [options] + +You can also change the entire banner. + + :include: ruby/help_banner.rb + +Execution: + + $ ruby help_banner.rb --help + Usage: ruby help_banner.rb + +By default, the option names are indented 4 spaces +and the width of the option-names field is 32 spaces. + +You can change these values, along with the banner, +by passing parameters to OptionParser.new. + + :include: ruby/help_format.rb + +Execution: + + $ ruby help_format.rb --help + ruby help_format.rb [options] + -x, --xxx Adipiscing elit. Aenean commodo ligula eget. + Aenean massa. Cum sociis natoque penatibus + -y, --yyy YYY Lorem ipsum dolor sit amet, consectetuer. + -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur + ridiculus mus. Donec quam felis, ultricies + nec, pellentesque eu, pretium quis, sem.