From 8c21437aa1deaafdc60720f680a350c7fff92bf9 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 15 Apr 2021 17:26:26 -0500 Subject: [PATCH 1/3] More on tutorial --- doc/optparse/ruby/basic.rb | 5 +- doc/optparse/tutorial.rdoc | 113 ++++++++++++++++++++++--------------- lib/optparse.rb | 10 +++- 3 files changed, 80 insertions(+), 48 deletions(-) diff --git a/doc/optparse/ruby/basic.rb b/doc/optparse/ruby/basic.rb index 617d337..91d3762 100644 --- a/doc/optparse/ruby/basic.rb +++ b/doc/optparse/ruby/basic.rb @@ -12,5 +12,6 @@ parser.on('-z', 'Whether to Z') do |value| p ['z', value] end -# Parse the command line. -parser.parse! +# Parse the command line and return pared-down ARGV. +p parser.parse! + diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index dfdc244..8ee7568 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -27,10 +27,7 @@ With \OptionParser, you can define options so that for each option: - 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. +The class also has method #help, which displays automatically-generated help text. === Contents @@ -57,6 +54,8 @@ The class also has: - {Default Values for Options}[#label-Default+Values+for+Options] - {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] === To Begin With @@ -83,52 +82,29 @@ From these defined options, the parser automatically builds help text: When an option is found during parsing, the block defined for the option is called with the argument value. +An invalid option raises an exception. -Executions: - - $ ruby basic.rb -x -z - ["x", true] - ["z", true] - $ ruby basic.rb -z -y -x - ["z", true] - ["y", true] - ["x", true] - -=== To Begin With - -To use \OptionParser: - -1. Require the \OptionParser code. -2. Create an \OptionParser object. -3. Define one or more options. -4. Parse the command line. - -File +basic.rb+ defines three options, -x, --y, and -z, each with a descriptive string, -and each with a block. - - :include: ruby/basic.rb - -From these defined options, the parser automatically builds help text: - - $ ruby basic.rb --help - Usage: basic [options] - -x Whether to X - -y Whether to Y - -z Whether to Z - -When an option is found during parsing, -the block defined for the option is called with the argument value. +Method #parse!, which is used most often in this tutorial, +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 pared-down \ARGV array. Executions: $ ruby basic.rb -x -z ["x", true] ["z", true] + [] $ ruby basic.rb -z -y -x ["z", true] ["y", true] ["x", true] + [] + $ ruby basic.rb -x input_file.txt output_file.txt + ["x", true] + ["input_file.txt", "output_file.txt"] + $ ruby basic.rb -a + basic.rb:16:in `
': invalid option: -a (OptionParser::InvalidOption) === Defining Options @@ -187,11 +163,6 @@ Multiple short names can "share" a hyphen: ["-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 @@ -633,3 +604,57 @@ Execution: -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. + +=== Top List and Base List + +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 top list, given by \OptionParser#top. +- The base list, given by \OptionParser#base. + +When \OptionParser builds its help text, the options in the top list +precede those in the base list. + +=== Methods for Defining Options + +Option-defining methods allow you to create an option and also append or prepend it +to either the top list or 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), +and returns the created option: + +- \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_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, + except that it returns the parser object +self+. + +- \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, + 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]. + This method is unlike others here in that it: + - Accepts an array of parameters; + others accept a sequence of parameter arguments. + - Returns an array containing the created option object, + option names, and other values; + others return either the created option object + or the parser object +self+. diff --git a/lib/optparse.rb b/lib/optparse.rb index 2a8efb6..060b134 100644 --- a/lib/optparse.rb +++ b/lib/optparse.rb @@ -48,6 +48,10 @@ # # == OptionParser # +# === New to \OptionParser? +# +# See the {Tutorial}[./doc/optparse/tutorial_rdoc.html]. +# # === Introduction # # OptionParser is a class for command-line option analysis. It is much more @@ -415,8 +419,10 @@ # # === Further documentation # -# The above examples should be enough to learn how to use this class. If you -# have any questions, file a ticket at http://bugs.ruby-lang.org. +# The above examples, along with the accompanying +# {Tutorial}[./doc/optparse/tutorial_rdoc.html], +# should be enough to learn how to use this class. +# If you have any questions, file a ticket at http://bugs.ruby-lang.org. # class OptionParser OptionParser::Version = "0.1.1" From d0ea61b9a1901604b2981b15af77f42bed3da306 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 16 Apr 2021 07:05:16 -0500 Subject: [PATCH 2/3] More on tutorial --- doc/optparse/tutorial.rdoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index 8ee7568..6e3fd9c 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -87,7 +87,7 @@ 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, leaving other non-option arguments for the program to handle on its own. -The method returns the pared-down \ARGV array. +The method returns the possibly-reduced \ARGV array. Executions: @@ -621,8 +621,8 @@ precede those in the base list. === Methods for Defining Options -Option-defining methods allow you to create an option and also append or prepend it -to either the top list or the base list. +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), From b1f5e3edda56f5d30d540395dca5e504dbf3e158 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 22 Apr 2021 07:18:51 -0500 Subject: [PATCH 3/3] Update tutorial.rdoc Added comma, as suggested. --- doc/optparse/tutorial.rdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index 6e3fd9c..d2124a9 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -624,7 +624,7 @@ precede those in the base list. 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 +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), and returns the created option: