summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/optparse/option_params.rdoc20
-rw-r--r--doc/optparse/ruby/parse.rb13
-rw-r--r--doc/optparse/ruby/parse_bang.rb13
-rw-r--r--doc/optparse/tutorial.rdoc179
4 files changed, 203 insertions, 22 deletions
diff --git a/doc/optparse/option_params.rdoc b/doc/optparse/option_params.rdoc
index c1f83eda88..3e6cb1be41 100644
--- a/doc/optparse/option_params.rdoc
+++ b/doc/optparse/option_params.rdoc
@@ -43,7 +43,6 @@ Contents:
- {Handler Blocks}[#label-Handler+Blocks]
- {Handler Procs}[#label-Handler+Procs]
- {Handler Methods}[#label-Handler+Methods]
-- {Terminators}[#label-Terminators]
=== Option Names
@@ -508,22 +507,3 @@ Executions:
["Handler method for -xxx called with value:", true]
$ ruby method.rb --yyy FOO
["Handler method for -yyy called with value:", "FOO"]
-
-=== Terminators
-
-And finally, the terminator parameter <tt>--</tt> tells the options parser
-to ignore any options farther to the right.
-This can be useful if there are options not meant for the current program.
-
-File +terminator.rb+ defines one option <tt>--my_option</tt>.
-
- :include: ruby/terminator.rb
-
-The first execution fails because <tt>--nosuch</tt> is not a defined option;
-the second succeeds because <tt>--</tt> causes that option to be ignored:
-
- $ ruby terminator.rb --my_option FOO --other_option BAR
- ["FOO", String]
- terminator.rb:6:in `<main>': invalid option: --other_option (OptionParser::InvalidOption)
- $ ruby terminator.rb --my_option FOO -- --other_option BAR
- ["FOO", String]
diff --git a/doc/optparse/ruby/parse.rb b/doc/optparse/ruby/parse.rb
new file mode 100644
index 0000000000..a5d4329484
--- /dev/null
+++ b/doc/optparse/ruby/parse.rb
@@ -0,0 +1,13 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('--xxx') do |value|
+ p ['--xxx', value]
+end
+parser.on('--yyy YYY') do |value|
+ p ['--yyy', value]
+end
+parser.on('--zzz [ZZZ]') do |value|
+ p ['--zzz', value]
+end
+ret = parser.parse(ARGV)
+puts "Returned: #{ret} (#{ret.class})"
diff --git a/doc/optparse/ruby/parse_bang.rb b/doc/optparse/ruby/parse_bang.rb
new file mode 100644
index 0000000000..567bc733cf
--- /dev/null
+++ b/doc/optparse/ruby/parse_bang.rb
@@ -0,0 +1,13 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('--xxx') do |value|
+ p ['--xxx', value]
+end
+parser.on('--yyy YYY') do |value|
+ p ['--yyy', value]
+end
+parser.on('--zzz [ZZZ]') do |value|
+ p ['--zzz', value]
+end
+ret = parser.parse!
+puts "Returned: #{ret} (#{ret.class})"
diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc
index d2124a9292..1d7c52b19e 100644
--- a/doc/optparse/tutorial.rdoc
+++ b/doc/optparse/tutorial.rdoc
@@ -55,7 +55,14 @@ 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]
-- {Methods for Defining Options}[#label-Methods+for+Defining+Options]
+- {Defining Options}[#label-Defining+Options]
+- {Parsing}[#label-Parsing]
+ - {Method parse!}[#label-Method+parse-21]
+ - {Method parse}[#label-Method+parse]
+ - {Method order!}[#label-Method+order-21]
+ - {Method order}[#label-Method+order]
+ - {Method permute!}[#label-Method+permute-21]
+ - {Method permute}[#label-Method+permute]
=== To Begin With
@@ -619,7 +626,7 @@ The stack includes:
When \OptionParser builds its help text, the options in the top list
precede those in the base list.
-=== Methods for Defining Options
+=== 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.
@@ -658,3 +665,171 @@ here's the core method for defining an option:
option names, and other values;
others return either the created option object
or the parser object +self+.
+
+=== Parsing
+
+\OptionParser has six instance methods for parsing.
+
+Three have names ending with a "bang" (<tt>!</tt>):
+
+- parse!
+- order!
+- permute!
+
+Each of these methods:
+
+- Accepts an optional array of string arguments +argv+;
+ if not given, +argv+ defaults to the value of OptionParser#default_argv,
+ whose initial value is ARGV.
+- Accepts an optional keyword argument +into+
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
+- Returns +argv+, possibly with some elements removed.
+
+The three other methods have names _not_ ending with a "bang":
+
+- parse
+- order
+- permute
+
+Each of these methods:
+
+- Accepts an array of string arguments
+ _or_ zero or more string arguments.
+- Accepts an optional keyword argument +into+ and its value _into_.
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
+- Returns +argv+, possibly with some elements removed.
+
+==== \Method parse!
+
+\Method parse!:
+
+- Accepts an optional array of string arguments +argv+;
+ if not given, +argv+ defaults to the value of OptionParser#default_argv,
+ whose initial value is ARGV.
+- Accepts an optional keyword argument +into+
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
+- Returns +argv+, possibly with some elements removed.
+
+The method processes the elements in +argv+ beginning at <tt>argv[0]</tt>,
+and ending, by default, at the end.
+
+Otherwise processing ends and the method returns when:
+
+- The terminator argument <tt>--</tt> is found;
+ the terminator argument is removed before the return.
+- Environment variable +POSIXLY_CORRECT+ is defined
+ and a non-option argument is found;
+ the non-option argument is not removed.
+ Note that the _value_ of that variable does not matter,
+ as only its existence is checked.
+
+File +parse_bang.rb+:
+
+ :include: ruby/parse_bang.rb
+
+Help:
+
+ $ ruby parse_bang.rb --help
+ Usage: parse_bang [options]
+ --xxx
+ --yyy YYY
+ --zzz [ZZZ]
+
+Default behavior:
+
+ $ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
+ ["--xxx", true]
+ ["--yyy", "FOO"]
+ ["--zzz", "BAR"]
+ Returned: ["input_file.txt", "output_file.txt"] (Array)
+
+Processing ended by terminator argument:
+
+ $ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
+ ["--xxx", true]
+ ["--yyy", "FOO"]
+ Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)
+
+Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
+
+ $ POSIXLY_CORRECT=true ruby parse_bang.rb --xxx input_file.txt output_file.txt -yyy FOO
+ ["--xxx", true]
+ Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
+
+==== \Method parse
+
+\Method parse:
+
+- Accepts an array of string arguments
+ _or_ zero or more string arguments.
+- Accepts an optional keyword argument +into+ and its value _into_.
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
+- Returns +argv+, possibly with some elements removed.
+
+If given an array +ary+, the method forms array +argv+ as <tt>ary.dup</tt>.
+If given zero or more string arguments, those arguments are formed
+into array +argv+.
+
+The method calls
+
+ parse!(argv, into: into)
+
+Note that environment variable +POSIXLY_CORRECT+
+and the terminator argument <tt>--</tt> are honored.
+
+File +parse.rb+:
+
+ :include: ruby/parse.rb
+
+Help:
+
+ $ ruby parse.rb --help
+ Usage: parse [options]
+ --xxx
+ --yyy YYY
+ --zzz [ZZZ]
+
+Default behavior:
+
+ $ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
+ ["--xxx", true]
+ ["--yyy", "FOO"]
+ ["--zzz", "BAR"]
+ Returned: ["input_file.txt", "output_file.txt"] (Array)
+
+Processing ended by terminator argument:
+
+ $ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
+ ["--xxx", true]
+ ["--yyy", "FOO"]
+ Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)
+
+Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
+
+ $ POSIXLY_CORRECT=true ruby parse.rb --xxx input_file.txt output_file.txt -yyy FOO
+ ["--xxx", true]
+ Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
+
+==== \Method order!
+
+Calling method OptionParser#order! gives exactly the same result as
+calling method OptionParser#parse! with environment variable
++POSIXLY_CORRECT+ defined.
+
+==== \Method order
+
+Calling method OptionParser#order gives exactly the same result as
+calling method OptionParser#parse with environment variable
++POSIXLY_CORRECT+ defined.
+
+==== \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
+
+Calling method OptionParser#permute gives exactly the same result as
+calling method OptionParser#parse with environment variable
++POSIXLY_CORRECT+ _not_ defined.