diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2021-04-06 13:55:21 -0500 |
---|---|---|
committer | Nobuyoshi Nakada <nobu@ruby-lang.org> | 2021-04-08 12:11:32 +0900 |
commit | fe72cff487283dbaadb9757e74f00291d772cb6f (patch) | |
tree | 17f23b59af67fee6f73a42c6e49c209343ba3152 /doc/tutorial | |
parent | 2b66b224793915adb8ed27308e9db26fc273635b (diff) | |
download | ruby-fe72cff487283dbaadb9757e74f00291d772cb6f.tar.gz |
[ruby/optparse] More on tutorial (#9)
* More on tutorial: clearer example output
https://github.com/ruby/optparse/commit/84dfd92d2a
Diffstat (limited to 'doc/tutorial')
-rw-r--r-- | doc/tutorial/argv.rb | 2 | ||||
-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 | 186 |
7 files changed, 233 insertions, 0 deletions
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 (<tt>-</tt>). +- Long (multi-character) name, beginning with two hyphens (<tt>--</tt>). + +==== 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, <tt>-x</tt>, +and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>. + + :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 `<main>': 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, <tt>--xxx</tt>, +and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>. + + :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 `<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. |