* lib/optparse.rb: incomplete RDoc documentation added in place of

existing RD comments.  Tabs converted to spaces.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5264 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Tue Dec 23 22:25:00 2003  Gavin Sinclair <gsinclair@soyabean.com.au>
+
+	* lib/optparse.rb: incomplete RDoc documentation added in place of
+	  existing RD comments.  Tabs converted to spaces.
+
 Tue Dec 23 19:44:47 2003  NAKAMURA, Hiroshi  <nahi@ruby-lang.org>
 
 	* test/soap/test_streamhandler.rb (test_basic_auth): removed.

lib/optparse.rb

@@ -1,61 +1,184 @@
-# optparse library, not octopus.
+#
+# optparse.rb - command-line option analysis with the OptionParser class.
+# 
+# Author:: Nobu Nakada
+# Documentation:: Nobu Nakada and Gavin Sinclair.
+#
 
-=begin
-= Summary
-Library for command line option analysis.
-
-features:
-(1) It is possible <option switch of a short form and a long form> to
-    exist together. It is also possible in one to bring the switch of
-    a short form together.
-(2) It is possible to write bringing specification and the handler of
-    the switch together respectively in one place.
-(3) The argument of the switch is converted into the class which
-    automatically specifies it.
-(4) The option summary can be made.
-(5) The option can be added on the way later.
-
-=end #'#"#`#
-# Not yet (;_;)
-=begin
-
-== Class tree
-   * ((<OptionParser>)) front end
-   * ((<OptionParser::Switch>)) each switches
-   * ((<OptionParser::List>)) options list
-   * ((<OptionParser::ParseError>)) errors on parsing
-     * ((<OptionParser::AmbiguousOption>))
-     * ((<OptionParser::NeedlessArgument>))
-     * ((<OptionParser::MissingArgument>))
-     * ((<OptionParser::InvalidOption>))
-     * ((<OptionParser::InvalidArgument>))
-       * ((<OptionParser::AmbiguousArgument>))
-
-== Object relations
-   +--------------+
-   | OptionParser |<>-----+
-   +--------------+       |          	         +--------+
-                          |          	       ,-| Switch |
-        on_head -------->+---------------+    /  +--------+
-        accept/reject -->| List        	 |<|>-
-                         |             	 |<|>-  +----------+
-        on ------------->+---------------+    `-| argument |
-                         :             	 :      |  class   |
-                         +---------------+      |==========|
-        on_tail -------->|             	 |      |pattern   |
-                         +---------------+      |----------|
-   OptionParser.accept ->| DefaultList 	 |      |converter |
-                reject   |(shared between|      +----------+
-                         | all instances)|
-                         +---------------+
-
-=end #'#"#`#
-
-=begin
-= Classes & Modules
-=end #'#"#`#
 
+#
+# == OptionParser
+#
+# === Introduction
+#
+# OptionParser (in optparse.rb) is a library for command-line option analysis.
+# It is much more advanced, yet also easier to use, than GetoptLong, and is a
+# more Ruby-oriented solution.
+#
+# === Features
+# 
+# 1. The argument specification and the code to handle it are written in the same
+#    place.
+# 2. It can output an option summary; you don't need to maintain this string
+#    separately.
+# 3. Optional and mandatory arguments are specified very gracefully.
+# 4. Arguments can be automatically converted to a specified class.
+# 5. Arguments can be restricted to a certain set.
+#
+# All of these features are demonstrated in the example below.
+#
+# === Class tree
+#
+# - OptionParser:: front end
+# - OptionParser::Switch:: each switches
+# - OptionParser::List:: options list
+# - OptionParser::ParseError:: errors on parsing
+#   - OptionParser::AmbiguousOption
+#   - OptionParser::NeedlessArgument
+#   - OptionParser::MissingArgument
+#   - OptionParser::InvalidOption
+#   - OptionParser::InvalidArgument
+#     - OptionParser::AmbiguousArgument
+#
+# === Object relationship diagram
+#
+#  +--------------+
+#  | OptionParser |<>-----+
+#  +--------------+       |                      +--------+
+#                         |                    ,-| Switch |
+#       on_head -------->+---------------+    /  +--------+
+#       accept/reject -->| List          |<|>-
+#                        |               |<|>-  +----------+
+#       on ------------->+---------------+    `-| argument |
+#                          :           :        |  class   |
+#                        +---------------+      |==========|
+#       on_tail -------->|               |      |pattern   |
+#                        +---------------+      |----------|
+#  OptionParser.accept ->| DefaultList   |      |converter |
+#               reject   |(shared between|      +----------+
+#                        | all instances)|
+#                        +---------------+
+# === Example
+#
+# The following example is a complete Ruby program.  You can run it and see the
+# effect of specifying various options.
+#
+#   require 'optparse'
+#   require 'optparse/time'
+#   require 'ostruct'
+#   require 'pp'
+#   
+#   class OptparseExample
+#   
+#     CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
+#     CODE_ALIASES = {"jis" => "iso-2022-jp", "sjis" => "shift_jis"}
+#   
+#     #
+#     # Return a structure describing the options.
+#     #
+#     def self.parse(args)
+#       # The options specified on the command line will be collected in *options*.
+#       # We set default values here.
+#       options = OpenStruct.new
+#       options.library = []
+#       options.inplace = false
+#       options.encoding = "utf8"
+#       options.transfer_type = :auto
+#       options.verbose = false
+#       
+#       opts = OptionParser.new do |opts|
+#         opts.banner = "Usage: example.rb [options]"
+#       
+#         opts.separator ""
+#         opts.separator "Specific options:"
+#       
+#         # Mandatory argument.
+#         opts.on("-r", "--require LIBRARY",
+#                 "Require the LIBRARY before executing your script") do |lib|
+#           options.library << lib
+#         end
+#       
+#         # Optional argument; multi-line description.
+#         opts.on("-i", "--inplace [EXTENSION]",
+#                 "Edit ARGV files in place",
+#                 "  (make backup if EXTENSION supplied)") do |ext|
+#           options.inplace = true
+#           options.extension = ext || ''
+#           options.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
+#         end
+#       
+#         # Cast 'delay' argument to a Float.
+#         opts.on("--delay N", Float, "Delay N seconds before executing") do |n|
+#           options.delay = n
+#         end
+#       
+#         # Cast 'time' argument to a Time object.
+#         opts.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
+#           options.time = time
+#         end
+#       
+#         # Cast to octal integer.
+#         opts.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
+#                 "Specify record separator (default \\0)") do |rs|
+#           options.record_separator = rs
+#         end
+#       
+#         # List of arguments.
+#         opts.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
+#           options.list = list
+#         end
+#       
+#         # Keyword completion.  We are specifying a specific set of arguments (CODES
+#         # and CODE_ALIASES - notice the latter is a Hash), and the user may provide
+#         # the shortest unambiguous text.
+#         code_list = (CODE_ALIASES.keys + CODES).join(',')
+#         opts.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
+#                 "  (#{code_list})") do |encoding|
+#           options.encoding = encoding
+#         end
+#       
+#         # Optional argument with keyword completion.
+#         opts.on("--type [TYPE]", [:text, :binary, :auto], "Select transfer type (text, binary, auto)") do |t|
+#           options.transfer_type = t
+#         end
+#       
+#         # Boolean switch.
+#         opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
+#           options.verbose = v
+#         end
+#       
+#         opts.separator ""
+#         opts.separator "Common options:"
+#       
+#         # No argument, shows at tail.  This will print an options summary.
+#         # Try it and see!
+#         opts.on_tail("-h", "--help", "Show this message") do
+#           puts opts
+#           exit
+#         end
+#       
+#         # Another typical switch to print the version.
+#         opts.on_tail("--version", "Show version") do
+#           puts OptionParser::Version.join('.')
+#           exit
+#         end
+#       end
+#       
+#       opts.parse!(args)
+#       options
+#     end  # parse()
+#   
+#   end  # class OptparseExample
+#   
+#   options = OptparseExample.parse(ARGV)
+#   pp options
+#
+# Note: if you get errors or strange results from any of the above code, make
+# sure you have the latest version installed.  Some changes have been made since
+# Ruby 1.8.0 was released. 
+#
 class OptionParser
+  # :stopdoc:
   RCSID = %w$Id$[1..-1].each {|s| s.freeze}.freeze
   Version = (RCSID[1].split('.').collect {|s| s.to_i}.extend(Comparable).freeze if RCSID[1])
   LastModified = (Time.gm(*RCSID[2, 2].join('-').scan(/\d+/).collect {|s| s.to_i}) if RCSID[2])
@@ -64,21 +187,14 @@ class OptionParser
   NoArgument = [NO_ARGUMENT = :NONE, nil].freeze
   RequiredArgument = [REQUIRED_ARGUMENT = :REQUIRED, true].freeze
   OptionalArgument = [OPTIONAL_ARGUMENT = :OPTIONAL, false].freeze
+  # :startdoc:
 
-=begin private
-== ((:OptionParser::Completion:))
-Keyword completion module.
-=end #'#"#`#
-  module Completion
-=begin private
---- OptionParser::Completion#complete(key[, pat])
-    Searches ((|key|)), or ((|pat|)) with completion if not found.
-    :Parameters:
-      : ((|key|))
-        keyword to search.
-      : ((|pat|))
-        completion pattern.
-=end #'#"#`#
+  #
+  # Keyword completion module.  This allows partial arguments to be specified
+  # and resolved against a list of acceptable values.  The average user does not
+  # need to comprehend this.
+  #
+  module Completion # :nodoc:
     def complete(key, pat = nil)
       pat ||= Regexp.new('\A' + Regexp.quote(key).gsub(/\w+\b/, '\&\w*'),
                          ignore_case?)
@@ -119,11 +235,6 @@ Keyword completion module.
       end
     end
 
-=begin private
---- OptionParser::Completion#convert(opt, *val)
-    Extracts the first element from result of
-    ((<OptionParser::Completion#complete>)).
-=end #'#"#`#
     def convert(opt = nil, val = nil, *)
       val
     end
@@ -133,14 +244,10 @@ Keyword completion module.
     end
   end
 
-=begin private
-== ((:OptionParser::OptionMap:))
-Map from option/keyword string to object with completion.
-=== Superclass
-(({Hash}))
-=== Including modules
-((<OptionParser::Completion>))
-=end #'#"#`#
+
+  #
+  # Map from option/keyword string to object with completion.
+  #
   class OptionMap < Hash
     include Completion
   end
@@ -150,22 +257,17 @@ Map from option/keyword string to object with completion.
     end
   end
 
-
-=begin
-== ((:OptionParser::Switch:))
-Individual switch class.
-=end #'#"#`#
+
+  #
+  # Individual switch class.
+  #
   class Switch
     attr_reader :pattern, :conv, :short, :long, :arg, :desc, :block
 
-=begin private
-=== Class methods
-=end
-=begin private
---- OptionParser::Switch.guess(arg)
-    Guesses argument style from ((|arg|)).
-    Returns corresponding ((<OptionParser::Switch>)) subclass.
-=end #'#"#`#
+    #
+    # Guesses argument style from +arg+.  Returns corresponding
+    # OptionParser::Switch class (OptionalArgument, etc.).
+    #
     def self.guess(arg)
       case arg
       when ""
@@ -189,9 +291,6 @@ Individual switch class.
       NilClass
     end
 
-=begin private
---- OptionParser::Switch.new
-=end #'#"#`#
     def initialize(pattern = nil, conv = nil,
                    short = nil, long = nil, arg = nil,
                    desc = ([] if short or long), block = Proc.new)