More on tutorial (#24)

- Adds section "Parsing" to tutorial.rdoc.
- Removes section "Terminators" from option_params.rdoc. (Terminator '--' is not an option parameter.)

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]

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})"

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})"

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.