diff options
-rw-r--r-- | doc/ruby/long_names.rb | 9 | ||||
-rw-r--r-- | doc/ruby/mixed_names.rb | 9 | ||||
-rw-r--r-- | doc/ruby/short_names.rb | 9 | ||||
-rw-r--r-- | doc/tutorial/argv.rb (renamed from doc/ruby/argv.rb) | 0 | ||||
-rw-r--r-- | doc/tutorial/long_names.rb | 9 | ||||
-rw-r--r-- | doc/tutorial/mixed_names.rb | 9 | ||||
-rw-r--r-- | doc/tutorial/optional_argument.rb | 9 | ||||
-rw-r--r-- | doc/tutorial/required_argument.rb | 9 | ||||
-rw-r--r-- | doc/tutorial/short_names.rb | 9 | ||||
-rw-r--r-- | doc/tutorial/tutorial.rdoc (renamed from doc/tutorial.rdoc) | 115 |
10 files changed, 133 insertions, 54 deletions
diff --git a/doc/ruby/long_names.rb b/doc/ruby/long_names.rb deleted file mode 100644 index e36152d097..0000000000 --- a/doc/ruby/long_names.rb +++ /dev/null @@ -1,9 +0,0 @@ -require 'optparse' -parser = OptionParser.new -parser.on('--xxx') do |option| - p "--xxx #{option}" -end -parser.on('--y1%', '--z2#') do |option| - p "--y1% or --z2# #{option}" -end -parser.parse! diff --git a/doc/ruby/mixed_names.rb b/doc/ruby/mixed_names.rb deleted file mode 100644 index b8f3ac9819..0000000000 --- a/doc/ruby/mixed_names.rb +++ /dev/null @@ -1,9 +0,0 @@ -require 'optparse' -parser = OptionParser.new -parser.on('-x', '--xxx') do |option| - p "--xxx #{option}" -end -parser.on('-y', '--y1%') do |option| - p "--y1% #{option}" -end -parser.parse! diff --git a/doc/ruby/short_names.rb b/doc/ruby/short_names.rb deleted file mode 100644 index 0dc35b789b..0000000000 --- a/doc/ruby/short_names.rb +++ /dev/null @@ -1,9 +0,0 @@ -require 'optparse' -parser = OptionParser.new -parser.on('-x') do |option| - p "-x #{option}" -end -parser.on('-1', '-%') do |option| - p "-1 or -% #{option}" -end -parser.parse! diff --git a/doc/ruby/argv.rb b/doc/tutorial/argv.rb index 12495cfa1f..12495cfa1f 100644 --- a/doc/ruby/argv.rb +++ b/doc/tutorial/argv.rb diff --git a/doc/tutorial/long_names.rb b/doc/tutorial/long_names.rb new file mode 100644 index 0000000000..a34b3382c2 --- /dev/null +++ b/doc/tutorial/long_names.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('--xxx') do |value| + p ['-xxx', value] +end +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 new file mode 100644 index 0000000000..e886049821 --- /dev/null +++ b/doc/tutorial/mixed_names.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x', '--xxx') do |value| + p ['--xxx', value] +end +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 new file mode 100644 index 0000000000..ebff2f466d --- /dev/null +++ b/doc/tutorial/optional_argument.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x [XXX]', '--xxx') do |value| + p ['--xxx', value] +end +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 new file mode 100644 index 0000000000..7a5a868265 --- /dev/null +++ b/doc/tutorial/required_argument.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x XXX', '--xxx') do |value| + p ['--xxx', value] +end +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 new file mode 100644 index 0000000000..6581dfe19a --- /dev/null +++ b/doc/tutorial/short_names.rb @@ -0,0 +1,9 @@ +require 'optparse' +parser = OptionParser.new +parser.on('-x') do |value| + p ['x', value] +end +parser.on('-1', '-%') do |value| + p ['-1 or -%', value] +end +parser.parse! diff --git a/doc/tutorial.rdoc b/doc/tutorial/tutorial.rdoc index 3f60b462d6..60ead0a6c6 100644 --- a/doc/tutorial.rdoc +++ b/doc/tutorial/tutorial.rdoc @@ -6,11 +6,11 @@ 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: - $ 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 @@ -65,23 +67,28 @@ File +short_names.rb+ defines an option with a short name, <tt>-x</tt>, and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>. - :include: ruby/short_names.rb + :include: short_names.rb Executions: - $ ruby doc/ruby/short_names.rb -x - "-x true" - $ ruby doc/ruby/short_names.rb -1 - "-1 or -% true" - $ ruby doc/ruby/short_names.rb -% - "-1 or -% true" + $ ruby short_names.rb -x + ["x", true] + $ ruby short_names.rb -1 + ["-1 or -%", true] + $ ruby short_names.rb -% + ["-1 or -%", true] Multiple short names can "share" a hyphen: $ ruby short_names.rb -x1% - "-x true" - "-1 or -% true" - "-1 or -% true" + ["x", true] + ["-1 or -%", true] + ["-1 or -%", true] + +This is a good time to note that giving an undefined option raises an exception: + + $ ruby short_names.rb -z + short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption) ==== Long Option Names @@ -92,16 +99,16 @@ File +long_names.rb+ defines an option with a long name, <tt>--xxx</tt>, and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>. - :include: ruby/long_names.rb + :include: long_names.rb 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 @@ -111,15 +118,69 @@ 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: + + $ ruby mixed_names.rb -x + ["--xxx", true] + $ ruby mixed_names.rb --xxx + ["--xxx", true] + $ ruby mixed_names.rb -y + ["--y1%", true] + $ 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: required_argument.rb + +When an option is found, the given argument is yielded. Executions: - $ ruby doc/ruby/mixed_names.rb -x - "--xxx true" - $ ruby doc/ruby/mixed_names.rb --xxx - "--xxx true" - $ ruby doc/ruby/mixed_names.rb -y - "--y1% true" - $ ruby doc/ruby/mixed_names.rb --y1% - "--y1% true" + $ 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 `<main>': 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: optional_argument.rb + +When an option with an argument is found, the given argument 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. |