From e491fd07572ea23b1746936a8867a1686e3194f3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 30 Mar 2021 16:34:10 -0500 Subject: [PATCH 1/4] More on tutorial --- doc/ruby/optional_argument.rb | 9 ++++ doc/ruby/required_argument.rb | 9 ++++ doc/tutorial.rdoc | 85 ++++++++++++++++++++++++++++++----- 3 files changed, 93 insertions(+), 10 deletions(-) create mode 100644 doc/ruby/optional_argument.rb create mode 100644 doc/ruby/required_argument.rb diff --git a/doc/ruby/optional_argument.rb b/doc/ruby/optional_argument.rb new file mode 100644 index 0000000..8ea3b33 --- /dev/null +++ b/doc/ruby/optional_argument.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x [XXX]', '--xxx') do |option| + p "--xxx #{option}" +end +parser.on('-y', '--y [YYY]') do |option| + p "--yyy #{option}" +end +parser.parse! diff --git a/doc/ruby/required_argument.rb b/doc/ruby/required_argument.rb new file mode 100644 index 0000000..bb6bd47 --- /dev/null +++ b/doc/ruby/required_argument.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x XXX', '--xxx') do |option| + p "--xxx #{option}" +end +parser.on('-y', '--y YYY') do |option| + p "--yyy #{option}" +end +parser.parse! diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index 3f60b46..cd7a4c6 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -10,7 +10,7 @@ This simple program just prints its \ARGV: Execution, with arguments and options: - $ ruby doc/ruby/argv.rb foo --bar --baz bat bam + $ ruby argv.rb foo --bar --baz bat bam ["foo", "--bar", "--baz", "bat", "bam"] The executing program is responsible for parsing and handling @@ -27,8 +27,10 @@ With \OptionParser, you can define options so that for each option: - The argument may be restricted to specified _forms_. - The argument may be restricted to specified _values_. -The class also has a method #summarize that returns a string summary -of all defined options. +The class also has: + +- Method #summarize: returns a text summary of the options. +- Method #help: displays automatically-generated help text. === Defining Options @@ -69,11 +71,11 @@ and an option with two short names (aliases, in effect) -y and -z': invalid option: -z (OptionParser::InvalidOption) + ==== Long Option Names A long option name consists of two hyphens and a one or more characters @@ -115,11 +122,69 @@ defines options that each have both a short and a long name. Executions: - $ ruby doc/ruby/mixed_names.rb -x + $ ruby mixed_names.rb -x "--xxx true" - $ ruby doc/ruby/mixed_names.rb --xxx + $ ruby mixed_names.rb --xxx "--xxx true" - $ ruby doc/ruby/mixed_names.rb -y + $ ruby mixed_names.rb -y "--y1% true" - $ ruby doc/ruby/mixed_names.rb --y1% + $ ruby mixed_names.rb --y1% "--y1% true" + +=== Option Arguments + +An option may take no argument, a required argument, or an optional argument. + +==== Option with No Argument + +All the examples above define options with no argument. + +==== Option with Required Argument + +Specify a required argument for an option by adding a dummy word +to its name definition. + +File +required_argument.rb+ defines two options; +each has a required argument because the name definition has a following dummy word. + + :include: ruby/required_argument.rb + +When an option is found, its name and the given argument are yielded. + +Executions: + + $ ruby required_argument.rb -x AAA + "--xxx AAA" + $ ruby required_argument.rb -y BBB + "--yyy BBB" + +Omitting a required argument raises an error: + + $ ruby required_argument.rb -x + required_argument.rb:9:in `
': missing argument: -x (OptionParser::MissingArgument) + +==== Option with Optional Argument + +Specify an optional argument for an option by adding a dummy word +enclosed in square brackets to its name definition. + +File +optional_argument.rb+ defines two options; +each has an optional argument because the name definition has a following dummy word +in square brackets. + + :include: ruby/optional_argument.rb + +When an option with an argument is found, its name and the given argument are yielded. + +Executions: + + $ ruby optional_argument.rb -x AAA + "--xxx AAA" + $ ruby optional_argument.rb -y BBB + "--yyy BBB" + +Omitting an optional argument does not raise an error, +and the option name is yielded with no argument. + + $ ruby optional_argument.rb -x + "--xxx " From 9ac3df29e1055b3425dd3dedd98f7bcfeb85d10e Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 31 Mar 2021 07:53:59 -0500 Subject: [PATCH 2/4] More on tutorial --- doc/tutorial.rdoc | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc index cd7a4c6..1b2b217 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial.rdoc @@ -149,7 +149,7 @@ each has a required argument because the name definition has a following dummy w :include: ruby/required_argument.rb -When an option is found, its name and the given argument are yielded. +When an option is found, the given argument is yielded. Executions: @@ -174,7 +174,7 @@ in square brackets. :include: ruby/optional_argument.rb -When an option with an argument is found, its name and the given argument are yielded. +When an option with an argument is found, the given argument yielded. Executions: @@ -183,8 +183,4 @@ Executions: $ ruby optional_argument.rb -y BBB "--yyy BBB" -Omitting an optional argument does not raise an error, -and the option name is yielded with no argument. - - $ ruby optional_argument.rb -x - "--xxx " +Omitting an optional argument does not raise an error. From ee41ca43097495a9094ec9a8d657bbfa700b39ac Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 1 Apr 2021 11:06:36 -0500 Subject: [PATCH 3/4] More on tutorial --- doc/{ruby => tutorial}/argv.rb | 0 doc/{ruby => tutorial}/long_names.rb | 0 doc/{ruby => tutorial}/mixed_names.rb | 0 doc/{ruby => tutorial}/optional_argument.rb | 0 doc/{ruby => tutorial}/required_argument.rb | 0 doc/{ruby => tutorial}/short_names.rb | 0 doc/{ => tutorial}/tutorial.rdoc | 12 ++++++------ 7 files changed, 6 insertions(+), 6 deletions(-) rename doc/{ruby => tutorial}/argv.rb (100%) rename doc/{ruby => tutorial}/long_names.rb (100%) rename doc/{ruby => tutorial}/mixed_names.rb (100%) rename doc/{ruby => tutorial}/optional_argument.rb (100%) rename doc/{ruby => tutorial}/required_argument.rb (100%) rename doc/{ruby => tutorial}/short_names.rb (100%) rename doc/{ => tutorial}/tutorial.rdoc (96%) diff --git a/doc/ruby/argv.rb b/doc/tutorial/argv.rb similarity index 100% rename from doc/ruby/argv.rb rename to doc/tutorial/argv.rb diff --git a/doc/ruby/long_names.rb b/doc/tutorial/long_names.rb similarity index 100% rename from doc/ruby/long_names.rb rename to doc/tutorial/long_names.rb diff --git a/doc/ruby/mixed_names.rb b/doc/tutorial/mixed_names.rb similarity index 100% rename from doc/ruby/mixed_names.rb rename to doc/tutorial/mixed_names.rb diff --git a/doc/ruby/optional_argument.rb b/doc/tutorial/optional_argument.rb similarity index 100% rename from doc/ruby/optional_argument.rb rename to doc/tutorial/optional_argument.rb diff --git a/doc/ruby/required_argument.rb b/doc/tutorial/required_argument.rb similarity index 100% rename from doc/ruby/required_argument.rb rename to doc/tutorial/required_argument.rb diff --git a/doc/ruby/short_names.rb b/doc/tutorial/short_names.rb similarity index 100% rename from doc/ruby/short_names.rb rename to doc/tutorial/short_names.rb diff --git a/doc/tutorial.rdoc b/doc/tutorial/tutorial.rdoc similarity index 96% rename from doc/tutorial.rdoc rename to doc/tutorial/tutorial.rdoc index 1b2b217..c09edec 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial/tutorial.rdoc @@ -6,7 +6,7 @@ When a Ruby program executes, it captures its command-line arguments and options into variable ARGV. This simple program just prints its \ARGV: - :include: ruby/argv.rb + :include: argv.rb Execution, with arguments and options: @@ -67,7 +67,7 @@ File +short_names.rb+ defines an option with a short name, -x, and an option with two short names (aliases, in effect) -y and -z. - :include: ruby/short_names.rb + :include: short_names.rb Executions: @@ -99,7 +99,7 @@ File +long_names.rb+ defines an option with a long name, --xxx, and an option with two long names (aliases, in effect) --y1% and --z2#. - :include: ruby/long_names.rb + :include: long_names.rb Executions: @@ -118,7 +118,7 @@ so that a short name is in effect an abbreviation of a long name. File +mixed_names.rb+ defines options that each have both a short and a long name. - :include: ruby/mixed_names.rb + :include: mixed_names.rb Executions: @@ -147,7 +147,7 @@ to its name definition. File +required_argument.rb+ defines two options; each has a required argument because the name definition has a following dummy word. - :include: ruby/required_argument.rb + :include: required_argument.rb When an option is found, the given argument is yielded. @@ -172,7 +172,7 @@ File +optional_argument.rb+ defines two options; each has an optional argument because the name definition has a following dummy word in square brackets. - :include: ruby/optional_argument.rb + :include: optional_argument.rb When an option with an argument is found, the given argument yielded. From 95e3133013a5e3a8c3669cb377ea6b4f76825324 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 2 Apr 2021 06:32:07 -0500 Subject: [PATCH 4/4] More on tutorial: clearer example output --- doc/tutorial/long_names.rb | 8 ++++---- doc/tutorial/mixed_names.rb | 8 ++++---- doc/tutorial/optional_argument.rb | 8 ++++---- doc/tutorial/required_argument.rb | 8 ++++---- doc/tutorial/short_names.rb | 8 ++++---- doc/tutorial/tutorial.rdoc | 34 +++++++++++++++---------------- 6 files changed, 37 insertions(+), 37 deletions(-) diff --git a/doc/tutorial/long_names.rb b/doc/tutorial/long_names.rb index e36152d..a34b338 100644 --- a/doc/tutorial/long_names.rb +++ b/doc/tutorial/long_names.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('--xxx') do |option| - p "--xxx #{option}" +parser.on('--xxx') do |value| + p ['-xxx', value] end -parser.on('--y1%', '--z2#') do |option| - p "--y1% or --z2# #{option}" +parser.on('--y1%', '--z2#') do |value| + p ['--y1% or --z2#', value] end parser.parse! diff --git a/doc/tutorial/mixed_names.rb b/doc/tutorial/mixed_names.rb index b8f3ac9..e886049 100644 --- a/doc/tutorial/mixed_names.rb +++ b/doc/tutorial/mixed_names.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x', '--xxx') do |option| - p "--xxx #{option}" +parser.on('-x', '--xxx') do |value| + p ['--xxx', value] end -parser.on('-y', '--y1%') do |option| - p "--y1% #{option}" +parser.on('-y', '--y1%') do |value| + p ['--y1%', value] end parser.parse! diff --git a/doc/tutorial/optional_argument.rb b/doc/tutorial/optional_argument.rb index 8ea3b33..ebff2f4 100644 --- a/doc/tutorial/optional_argument.rb +++ b/doc/tutorial/optional_argument.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x [XXX]', '--xxx') do |option| - p "--xxx #{option}" +parser.on('-x [XXX]', '--xxx') do |value| + p ['--xxx', value] end -parser.on('-y', '--y [YYY]') do |option| - p "--yyy #{option}" +parser.on('-y', '--yyy [YYY]') do |value| + p ['--yyy', value] end parser.parse! diff --git a/doc/tutorial/required_argument.rb b/doc/tutorial/required_argument.rb index bb6bd47..7a5a868 100644 --- a/doc/tutorial/required_argument.rb +++ b/doc/tutorial/required_argument.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x XXX', '--xxx') do |option| - p "--xxx #{option}" +parser.on('-x XXX', '--xxx') do |value| + p ['--xxx', value] end -parser.on('-y', '--y YYY') do |option| - p "--yyy #{option}" +parser.on('-y', '--y YYY') do |value| + p ['--yyy', value] end parser.parse! diff --git a/doc/tutorial/short_names.rb b/doc/tutorial/short_names.rb index 0dc35b7..6581dfe 100644 --- a/doc/tutorial/short_names.rb +++ b/doc/tutorial/short_names.rb @@ -1,9 +1,9 @@ require 'optparse' parser = OptionParser.new -parser.on('-x') do |option| - p "-x #{option}" +parser.on('-x') do |value| + p ['x', value] end -parser.on('-1', '-%') do |option| - p "-1 or -% #{option}" +parser.on('-1', '-%') do |value| + p ['-1 or -%', value] end parser.parse! diff --git a/doc/tutorial/tutorial.rdoc b/doc/tutorial/tutorial.rdoc index c09edec..60ead0a 100644 --- a/doc/tutorial/tutorial.rdoc +++ b/doc/tutorial/tutorial.rdoc @@ -72,18 +72,18 @@ and an option with two short names (aliases, in effect) -y and -z--y1% and -- Executions: $ ruby long_names.rb --xxx - "--xxx true" + ["-xxx", true] $ ruby long_names.rb --y1% - "--y1% or -z2# true" + ["--y1% or --z2#", true] $ ruby long_names.rb --z2# - "--y1% or -z2# true" + ["--y1% or --z2#", true] ==== Mixing Option Names @@ -123,13 +123,13 @@ defines options that each have both a short and a long name. Executions: $ ruby mixed_names.rb -x - "--xxx true" + ["--xxx", true] $ ruby mixed_names.rb --xxx - "--xxx true" + ["--xxx", true] $ ruby mixed_names.rb -y - "--y1% true" + ["--y1%", true] $ ruby mixed_names.rb --y1% - "--y1% true" + ["--y1%", true] === Option Arguments @@ -154,9 +154,9 @@ When an option is found, the given argument is yielded. Executions: $ ruby required_argument.rb -x AAA - "--xxx AAA" + ["--xxx", "AAA"] $ ruby required_argument.rb -y BBB - "--yyy BBB" + ["--yyy", "BBB"] Omitting a required argument raises an error: @@ -179,8 +179,8 @@ When an option with an argument is found, the given argument yielded. Executions: $ ruby optional_argument.rb -x AAA - "--xxx AAA" + ["--xxx", "AAA"] $ ruby optional_argument.rb -y BBB - "--yyy BBB" + ["--yyy", "BBB"] Omitting an optional argument does not raise an error.