diff options
Diffstat (limited to 'doc/optparse/tutorial.rdoc')
| -rw-r--r-- | doc/optparse/tutorial.rdoc | 127 |
1 files changed, 75 insertions, 52 deletions
diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index 1d7c52b19e..1134f94ddf 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -1,10 +1,10 @@ == Tutorial -=== Why \OptionParser? +=== 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: +This simple program just prints its +ARGV+: :include: ruby/argv.rb @@ -18,7 +18,7 @@ the command-line options. OptionParser offers methods for parsing and handling those options. -With \OptionParser, you can define options so that for each option: +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. @@ -55,7 +55,7 @@ The class also has method #help, which displays automatically-generated help tex - {Argument Converters}[#label-Argument+Converters] - {Help}[#label-Help] - {Top List and Base List}[#label-Top+List+and+Base+List] -- {Defining Options}[#label-Defining+Options] +- {Methods for Defining Options}[#label-Methods+for+Defining+Options] - {Parsing}[#label-Parsing] - {Method parse!}[#label-Method+parse-21] - {Method parse}[#label-Method+parse] @@ -66,10 +66,10 @@ The class also has method #help, which displays automatically-generated help tex === To Begin With -To use \OptionParser: +To use +OptionParser+: -1. Require the \OptionParser code. -2. Create an \OptionParser object. +1. Require the +OptionParser+ code. +2. Create an +OptionParser+ object. 3. Define one or more options. 4. Parse the command line. @@ -92,9 +92,9 @@ the block defined for the option is called with the argument value. An invalid option raises an exception. Method #parse!, which is used most often in this tutorial, -removes from \ARGV the options and arguments it finds, +removes from +ARGV+ the options and arguments it finds, leaving other non-option arguments for the program to handle on its own. -The method returns the possibly-reduced \ARGV array. +The method returns the possibly-reduced +ARGV+ array. Executions: @@ -111,11 +111,11 @@ Executions: ["x", true] ["input_file.txt", "output_file.txt"] $ ruby basic.rb -a - basic.rb:16:in `<main>': invalid option: -a (OptionParser::InvalidOption) + basic.rb:16:in '<main>': invalid option: -a (OptionParser::InvalidOption) === Defining Options -A common way to define an option in \OptionParser +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 @@ -232,11 +232,11 @@ Executions: $ ruby mixed_names.rb --xxx ["--xxx", true] $ ruby mixed_names.rb -y - mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument) + mixed_names.rb:12:in '<main>': missing argument: -y (OptionParser::MissingArgument) $ ruby mixed_names.rb -y FOO ["--yyy", "FOO"] $ ruby mixed_names.rb --yyy - mixed_names.rb:12:in `<main>': missing argument: --yyy (OptionParser::MissingArgument) + mixed_names.rb:12:in '<main>': missing argument: --yyy (OptionParser::MissingArgument) $ ruby mixed_names.rb --yyy BAR ["--yyy", "BAR"] $ ruby mixed_names.rb -z @@ -270,9 +270,9 @@ Executions: $ ruby name_abbrev.rb --draft ["--draft", true] $ ruby name_abbrev.rb --d - name_abbrev.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption) + name_abbrev.rb:9:in '<main>': ambiguous option: --d (OptionParser::AmbiguousOption) $ ruby name_abbrev.rb --dr - name_abbrev.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption) + name_abbrev.rb:9:in '<main>': ambiguous option: --dr (OptionParser::AmbiguousOption) $ ruby name_abbrev.rb --dry ["--dry-run", true] $ ruby name_abbrev.rb --dra @@ -285,7 +285,7 @@ You can disable abbreviation using method +require_exact+. Executions: $ ruby no_abbreviation.rb --dry-ru - no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption) + no_abbreviation.rb:10:in '<main>': invalid option: --dry-ru (OptionParser::InvalidOption) $ ruby no_abbreviation.rb --dry-run ["--dry-run", true] @@ -323,7 +323,7 @@ Executions: Omitting a required argument raises an error: $ ruby required_argument.rb -x - required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument) + required_argument.rb:9:in '<main>': missing argument: -x (OptionParser::MissingArgument) ==== Option with Optional Argument @@ -351,6 +351,29 @@ Executions: Omitting an optional argument does not raise an error. +==== Argument Abbreviations + +Specify an argument list as an Array or a Hash. + + :include: ruby/argument_abbreviation.rb + +When an argument is abbreviated, the expanded argument yielded. + +Executions: + + $ ruby argument_abbreviation.rb --help + Usage: argument_abbreviation [options] + Usage: argument_abbreviation [options] + -x, --xxx=VALUE Argument abbreviations + -y, --yyy=VALUE Argument abbreviations + $ ruby argument_abbreviation.rb --xxx A + ["--xxx", "ABC"] + $ ruby argument_abbreviation.rb --xxx c + argument_abbreviation.rb:9:in '<main>': invalid argument: --xxx c (OptionParser::InvalidArgument) + $ ruby argument_abbreviation.rb --yyy a --yyy d + ["--yyy", "XYZ"] + ["--yyy", "FOO"] + === Argument Values Permissible argument values may be restricted @@ -380,7 +403,7 @@ Executions: -xXXX Values for required argument -y [YYY] Values for optional argument $ ruby explicit_array_values.rb -x - explicit_array_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument) + explicit_array_values.rb:9:in '<main>': missing argument: -x (OptionParser::MissingArgument) $ ruby explicit_array_values.rb -x foo ["-x", "foo"] $ ruby explicit_array_values.rb -x f @@ -388,9 +411,9 @@ Executions: $ ruby explicit_array_values.rb -x bar ["-x", "bar"] $ ruby explicit_array_values.rb -y ba - explicit_array_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument) + explicit_array_values.rb:9:in '<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument) $ ruby explicit_array_values.rb -x baz - explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument) + explicit_array_values.rb:9:in '<main>': invalid argument: -x baz (OptionParser::InvalidArgument) ===== Explicit Values in Hash @@ -410,7 +433,7 @@ Executions: -xXXX Values for required argument -y [YYY] Values for optional argument $ ruby explicit_hash_values.rb -x - explicit_hash_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument) + explicit_hash_values.rb:9:in '<main>': missing argument: -x (OptionParser::MissingArgument) $ ruby explicit_hash_values.rb -x foo ["-x", 0] $ ruby explicit_hash_values.rb -x f @@ -418,7 +441,7 @@ Executions: $ ruby explicit_hash_values.rb -x bar ["-x", 1] $ ruby explicit_hash_values.rb -x baz - explicit_hash_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument) + explicit_hash_values.rb:9:in '<main>': invalid argument: -x baz (OptionParser::InvalidArgument) $ ruby explicit_hash_values.rb -y ["-y", nil] $ ruby explicit_hash_values.rb -y baz @@ -426,7 +449,7 @@ Executions: $ ruby explicit_hash_values.rb -y bat ["-y", 3] $ ruby explicit_hash_values.rb -y ba - explicit_hash_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument) + explicit_hash_values.rb:9:in '<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument) $ ruby explicit_hash_values.rb -y bam ["-y", nil] @@ -449,7 +472,7 @@ Executions: $ ruby matched_values.rb --xxx FOO ["--xxx", "FOO"] $ ruby matched_values.rb --xxx bar - matched_values.rb:6:in `<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument) + matched_values.rb:6:in '<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument) === Keyword Argument +into+ @@ -501,7 +524,7 @@ Executions: -y, --yyyYYY Short and long, required argument -z, --zzz [ZZZ] Short and long, optional argument $ ruby missing_options.rb --yyy FOO - missing_options.rb:11:in `<main>': Missing required options: [:xxx, :zzz] (RuntimeError) + missing_options.rb:11:in '<main>': Missing required options: [:xxx, :zzz] (RuntimeError) ==== Default Values for Options @@ -522,11 +545,11 @@ Executions: === Argument Converters An option can specify that its argument is to be converted -from the default \String to an instance of another class. +from the default +String+ to an instance of another class. There are a number of built-in converters. Example: File +date.rb+ -defines an option whose argument is to be converted to a \Date object. +defines an option whose argument is to be converted to a +Date+ object. The argument is converted by method Date#parse. :include: ruby/date.rb @@ -541,12 +564,12 @@ Executions: [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date] You can also define custom converters. -See {Argument Converters}[./argument_converters_rdoc.html] +See {Argument Converters}[./argument_converters.rdoc] for both built-in and custom converters. === Help -\OptionParser makes automatically generated help text available. ++OptionParser+ makes automatically generated help text available. The help text consists of: @@ -614,50 +637,50 @@ Execution: === Top List and Base List -An \OptionParser object maintains a stack of \OptionParser::List objects, +An +OptionParser+ object maintains a stack of OptionParser::List objects, each of which has a collection of zero or more options. It is unlikely that you'll need to add or take away from that stack. The stack includes: -- The <em>top list</em>, given by \OptionParser#top. -- The <em>base list</em>, given by \OptionParser#base. +- The <em>top list</em>, given by OptionParser#top. +- The <em>base list</em>, given by OptionParser#base. -When \OptionParser builds its help text, the options in the top list +When +OptionParser+ builds its help text, the options in the top list precede those in the base list. -=== Defining Options +=== Methods for Defining Options Option-defining methods allow you to create an option, and also append/prepend it to the top list or append it to the base list. Each of these next three methods accepts a sequence of parameter arguments and a block, -creates an option object using method \Option#make_switch (see below), +creates an option object using method OptionParser#make_switch (see below), and returns the created option: -- \Method \OptionParser#define appends the created option to the top list. +- \Method OptionParser#define appends the created option to the top list. -- \Method \OptionParser#define_head prepends the created option to the top list. +- \Method OptionParser#define_head prepends the created option to the top list. -- \Method \OptionParser#define_tail appends the created option to the base list. +- \Method OptionParser#define_tail appends the created option to the base list. These next three methods are identical to the three above, except for their return values: -- \Method \OptionParser#on is identical to method \OptionParser#define, +- \Method OptionParser#on is identical to method OptionParser#define, except that it returns the parser object +self+. -- \Method \OptionParser#on_head is identical to method \OptionParser#define_head, +- \Method OptionParser#on_head is identical to method OptionParser#define_head, except that it returns the parser object +self+. -- \Method \OptionParser#on_tail is identical to method \OptionParser#define_tail, +- \Method OptionParser#on_tail is identical to method OptionParser#define_tail, except that it returns the parser object +self+. Though you may never need to call it directly, here's the core method for defining an option: -- \Method \OptionParser#make_switch accepts an array of parameters and a block. - See {Parameters for New Options}[./option_params_rdoc.html]. +- \Method OptionParser#make_switch accepts an array of parameters and a block. + See {Parameters for New Options}[optparse/option_params.rdoc]. This method is unlike others here in that it: - Accepts an <em>array of parameters</em>; others accept a <em>sequence of parameter arguments</em>. @@ -668,7 +691,7 @@ here's the core method for defining an option: === Parsing -\OptionParser has six instance methods for parsing. ++OptionParser+ has six instance methods for parsing. Three have names ending with a "bang" (<tt>!</tt>): @@ -699,9 +722,9 @@ Each of these methods: (see {Keyword Argument into}[#label-Keyword+Argument+into]). - Returns +argv+, possibly with some elements removed. -==== \Method parse! +==== \Method +parse!+ -\Method parse!: +\Method +parse!+: - Accepts an optional array of string arguments +argv+; if not given, +argv+ defaults to the value of OptionParser#default_argv, @@ -756,9 +779,9 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined: ["--xxx", true] Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array) -==== \Method parse +==== \Method +parse+ -\Method parse: +\Method +parse+: - Accepts an array of string arguments _or_ zero or more string arguments. @@ -810,25 +833,25 @@ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined: ["--xxx", true] Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array) -==== \Method order! +==== \Method +order!+ Calling method OptionParser#order! gives exactly the same result as calling method OptionParser#parse! with environment variable +POSIXLY_CORRECT+ defined. -==== \Method order +==== \Method +order+ Calling method OptionParser#order gives exactly the same result as calling method OptionParser#parse with environment variable +POSIXLY_CORRECT+ defined. -==== \Method permute! +==== \Method +permute!+ Calling method OptionParser#permute! gives exactly the same result as calling method OptionParser#parse! with environment variable +POSIXLY_CORRECT+ _not_ defined. -==== \Method permute +==== \Method +permute+ Calling method OptionParser#permute gives exactly the same result as calling method OptionParser#parse with environment variable |