From 05e9efa323eb99727b099590c1d40d23f38443ef Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 6 Apr 2021 13:55:21 -0500 Subject: [ruby/optparse] More on tutorial (https://github.com/ruby/optparse/pull/9) * More on tutorial * More on tutorial * More on tutorial * More on tutorial: clearer example output https://github.com/ruby/optparse/commit/84dfd92d2a --- doc/ruby/argv.rb | 2 - doc/ruby/long_names.rb | 9 -- doc/ruby/mixed_names.rb | 9 -- doc/ruby/short_names.rb | 9 -- doc/tutorial.rdoc | 125 ------------------------- doc/tutorial/argv.rb | 2 + doc/tutorial/long_names.rb | 9 ++ doc/tutorial/mixed_names.rb | 9 ++ doc/tutorial/optional_argument.rb | 9 ++ doc/tutorial/required_argument.rb | 9 ++ doc/tutorial/short_names.rb | 9 ++ doc/tutorial/tutorial.rdoc | 186 ++++++++++++++++++++++++++++++++++++++ 12 files changed, 233 insertions(+), 154 deletions(-) delete mode 100644 doc/ruby/argv.rb delete mode 100644 doc/ruby/long_names.rb delete mode 100644 doc/ruby/mixed_names.rb delete mode 100644 doc/ruby/short_names.rb delete mode 100644 doc/tutorial.rdoc create mode 100644 doc/tutorial/argv.rb create mode 100644 doc/tutorial/long_names.rb create mode 100644 doc/tutorial/mixed_names.rb create mode 100644 doc/tutorial/optional_argument.rb create mode 100644 doc/tutorial/required_argument.rb create mode 100644 doc/tutorial/short_names.rb create mode 100644 doc/tutorial/tutorial.rdoc (limited to 'doc') diff --git a/doc/ruby/argv.rb b/doc/ruby/argv.rb deleted file mode 100644 index 12495cfa1f..0000000000 --- a/doc/ruby/argv.rb +++ /dev/null @@ -1,2 +0,0 @@ -p ARGV - 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/tutorial.rdoc b/doc/tutorial.rdoc deleted file mode 100644 index 3f60b462d6..0000000000 --- a/doc/tutorial.rdoc +++ /dev/null @@ -1,125 +0,0 @@ -== Tutorial - -=== Why OptionParser? - -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 - -Execution, with arguments and options: - - $ ruby doc/ruby/argv.rb foo --bar --baz bat bam - ["foo", "--bar", "--baz", "bat", "bam"] - -The executing program is responsible for parsing and handling -the command-line options. - -OptionParser offers methods for parsing and handling those options. - -With \OptionParser, you can define options so that for each option: - -- The code that defines the option and code that handles that option - are in the same place. -- The option may take no argument, a required argument, or an optional argument. -- The argument may be automatically converted to a specified class. -- 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. - -=== Defining Options - -A common way to define an option in \OptionParser -is with instance method OptionParser#on. - -The method may be called with any number of arguments -(whose order does not matter), -and may also have a trailing optional keyword argument +into+. - -The given arguments determine the characteristics of the new option. -These may include: - -- One or more short option names. -- One or more long option names. -- Whether the option takes no argument, an optional argument, or a required argument. -- Acceptable _forms_ for the argument. -- Acceptable _values_ for the argument. -- A proc or method to be called when the parser encounters the option. -- String descriptions for the option. - -=== Option Names - -You can give an option one or more names of two types: - -- Short (1-character) name, beginning with one hyphen (-). -- Long (multi-character) name, beginning with two hyphens (--). - -==== Short Option Names - -A short option name consists of a hyphen and a single character. - -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 - -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" - -Multiple short names can "share" a hyphen: - - $ ruby short_names.rb -x1% - "-x true" - "-1 or -% true" - "-1 or -% true" - -==== Long Option Names - -A long option name consists of two hyphens and a one or more characters -(usually two or more characters). - -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 - -Executions: - - $ ruby long_names.rb --xxx - "--xxx true" - $ ruby long_names.rb --y1% - "--y1% or -z2# true" - $ ruby long_names.rb --z2# - "--y1% or -z2# true" - -==== Mixing Option Names - -Many developers like to mix short and long option names, -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 - -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" diff --git a/doc/tutorial/argv.rb b/doc/tutorial/argv.rb new file mode 100644 index 0000000000..12495cfa1f --- /dev/null +++ b/doc/tutorial/argv.rb @@ -0,0 +1,2 @@ +p ARGV + 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/tutorial.rdoc b/doc/tutorial/tutorial.rdoc new file mode 100644 index 0000000000..60ead0a6c6 --- /dev/null +++ b/doc/tutorial/tutorial.rdoc @@ -0,0 +1,186 @@ +== Tutorial + +=== Why OptionParser? + +When a Ruby program executes, it captures its command-line arguments +and options into variable ARGV. +This simple program just prints its \ARGV: + + :include: argv.rb + +Execution, with arguments and options: + + $ ruby argv.rb foo --bar --baz bat bam + ["foo", "--bar", "--baz", "bat", "bam"] + +The executing program is responsible for parsing and handling +the command-line options. + +OptionParser offers methods for parsing and handling those options. + +With \OptionParser, you can define options so that for each option: + +- The code that defines the option and code that handles that option + are in the same place. +- The option may take no argument, a required argument, or an optional argument. +- The argument may be automatically converted to a specified class. +- The argument may be restricted to specified _forms_. +- The argument may be restricted to specified _values_. + +The class also has: + +- Method #summarize: returns a text summary of the options. +- Method #help: displays automatically-generated help text. + +=== Defining Options + +A common way to define an option in \OptionParser +is with instance method OptionParser#on. + +The method may be called with any number of arguments +(whose order does not matter), +and may also have a trailing optional keyword argument +into+. + +The given arguments determine the characteristics of the new option. +These may include: + +- One or more short option names. +- One or more long option names. +- Whether the option takes no argument, an optional argument, or a required argument. +- Acceptable _forms_ for the argument. +- Acceptable _values_ for the argument. +- A proc or method to be called when the parser encounters the option. +- String descriptions for the option. + +=== Option Names + +You can give an option one or more names of two types: + +- Short (1-character) name, beginning with one hyphen (-). +- Long (multi-character) name, beginning with two hyphens (--). + +==== Short Option Names + +A short option name consists of a hyphen and a single character. + +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: short_names.rb + +Executions: + + $ 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] + +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 `
': invalid option: -z (OptionParser::InvalidOption) + +==== Long Option Names + +A long option name consists of two hyphens and a one or more characters +(usually two or more characters). + +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: long_names.rb + +Executions: + + $ ruby long_names.rb --xxx + ["-xxx", true] + $ ruby long_names.rb --y1% + ["--y1% or --z2#", true] + $ ruby long_names.rb --z2# + ["--y1% or --z2#", true] + +==== Mixing Option Names + +Many developers like to mix short and long option names, +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: 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 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: 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. -- cgit v1.2.3