From: mathew Date: 2006-04-19T10:59:55+09:00 Subject: RDoc patches for GetoptLong --------------060107040206090004020708 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit I added RDoc documentation to GetoptLong. The patches are attached. As usual, no code changes, only comments. (I picked GetoptLong because people often ask about it in comp.lang.ruby.) I e-mailed Motoyuki Kasahara , the author of the code, who replied: > I'm currently not working with Ruby, so your report about > GetoptLong surprised me. How many Ruby users may have > questions or frustrate GetoptLong? :-) > > Anyway, your patch seems good. > [...] > Would you send it to the core team? > Thank you for your work and contacting me. So, attached are the patches against the current trunk. Hopefully someone can inspect them and check them in. mathew --------------060107040206090004020708 Content-Type: text/plain; name="getoptlong.diff" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="getoptlong.diff" Index: lib/getoptlong.rb =================================================================== RCS file: /src/ruby/lib/getoptlong.rb,v retrieving revision 1.14 diff -u -b -d -d -r1.14 getoptlong.rb --- lib/getoptlong.rb 7 Sep 2005 16:07:43 -0000 1.14 +++ lib/getoptlong.rb 14 Apr 2006 03:05:35 -0000 @@ -1,17 +1,94 @@ -# -*- Ruby -*- -# Copyright (C) 1998, 1999, 2000 Motoyuki Kasahara # -# You may redistribute it and/or modify it under the same license +# GetoptLong for Ruby +# +# Copyright (C) 1998, 1999, 2000 Motoyuki Kasahara. +# +# You may redistribute and/or modify this library under the same license # terms as Ruby. # +# See GetoptLong for documentation. +# +# Additional documents and the latest version of `getoptlong.rb' can be +# found at http://www.sra.co.jp/people/m-kasahr/ruby/getoptlong/ +# The GetoptLong class allows you to parse command line options similarly to +# the GNU getopt_long() C library call. Note, however, that GetoptLong is a +# pure Ruby implementation. # -# Documents and latest version of `getoptlong.rb' are found at: -# http://www.sra.co.jp/people/m-kasahr/ruby/getoptlong/ +# GetoptLong allows for POSIX-style options like --file as well +# as single letter options like -f # - +# The empty option -- (two minus symbols) is used to end option +# processing. This can be particularly important if options have optional +# arguments. # -# Parse command line options just like GNU getopt_long(). +# Here is a simple example of usage: +# +# # == Synopsis +# # +# # hello: greets user, demonstrates command line parsing +# # +# # == Usage +# # +# # hello [OPTION] ... DIR +# # +# # -h, --help: +# # show help +# # +# # --repeat x, -n x: +# # repeat x times +# # +# # --name [name]: +# # greet user by name, if name not supplied default is John +# # +# # DIR: The directory in which to issue the greeting. +# +# require 'getoptlong' +# require 'rdoc/usage' +# +# opts = GetoptLong.new( +# [ '--help', '-h', GetoptLong::NO_ARGUMENT ], +# [ '--repeat', '-n', GetoptLong::REQUIRED_ARGUMENT ], +# [ '--name', GetoptLong::OPTIONAL_ARGUMENT ] +# ) +# +# dir = nil +# name = nil +# repetitions = 1 +# opts.each do |opt, arg| +# case opt +# when '--help' +# RDoc::usage +# when '--repeat' +# repetitions = arg.to_i +# when '--name' +# if arg == '' +# name = 'John' +# else +# name = arg +# end +# end +# end +# +# if ARGV.length != 1 +# puts "Missing dir argument (try --help)" +# exit 0 +# end +# +# dir = ARGV.shift +# +# Dir.chdir(dir) +# for i in (1..repetitions) +# print "Hello" +# if name +# print ", #{name}" +# end +# puts +# end +# +# Example command line: +# +# hello -n 6 --name -- /tmp # class GetoptLong # @@ -40,13 +117,20 @@ class InvalidOption < Error; end # - # The arguments are passed to new() as an array of arrays. Each - # subarray has a number of option names which carry the same - # meaning, and a ARGUMENT_FLAG, being one of - # GetoptLong::NO_ARGUMENT, GetoptLong::REQUIRED_ARGUMENT or - # GetoptLong::OPTIONAL_ARGUMENT. These determine whether the - # option takes an argument or not, or whether it is optional The - # actual processing is done later with #each(). + # Set up option processing. + # + # The options to support are passed to new() as an array of arrays. + # Each sub-array contains any number of String option names which carry + # the same meaning, and one of the following flags: + # + # GetoptLong::NO_ARGUMENT :: Option does not take an argument. + # + # GetoptLong::REQUIRED_ARGUMENT :: Option always takes an argument. + # + # GetoptLong::OPTIONAL_ARGUMENT :: Option may or may not take an argument. + # + # The first option name is considered to be the preferred (canonical) name. + # Other than that, the elements of each sub-array can be in any order. # def initialize(*arguments) # @@ -109,11 +193,53 @@ end # - # Set the handling of the ordering of options. The supplied - # argument ordering must be a member of ORDERINGS, i.e one of - # GetoptLong::REQUIRE_ORDER, GetoptLong::PERMUTE, - # GetoptLong::RETURN_IN_ORDER. A RuntimeError is raised if - # option processing has already started. + # Set the handling of the ordering of options and arguments. + # A RuntimeError is raised if option processing has already started. + # + # The supplied value must be a member of GetoptLong::ORDERINGS. It alters + # the processing of options as follows: + # + # REQUIRE_ORDER : + # + # Options are required to occur before non-options. + # + # Processing of options ends as soon as a word is encountered that has not + # been preceded by an appropriate option flag. + # + # For example, if -a and -b are options which do not take arguments, + # parsing command line arguments of '-a one -b two' would result in + # 'one', '-b', 'two' being left in ARGV, and only ('-a', '') being + # processed as an option/arg pair. + # + # This is the default ordering, if the environment variable + # POSIXLY_CORRECT is set. (This is for compatibility with GNU getopt_long.) + # + # PERMUTE : + # + # Options can occur anywhere in the command line parsed. This is the + # default behavior. + # + # Every sequence of words which can be interpreted as an option (with or + # without argument) is treated as an option; non-option words are skipped. + # + # For example, if -a does not require an argument and -b optionally takes + # an argument, parsing '-a one -b two three' would result in ('-a','') and + # ('-b', 'two') being processed as option/arg pairs, and 'one','three' + # being left in ARGV. + # + # If the ordering is set to PERMUTE but the environment variable + # POSIXLY_CORRECT is set, REQUIRE_ORDER is used instead. This is for + # compatibility with GNU getopt_long. + # + # RETURN_IN_ORDER : + # + # All words on the command line are processed as options. Words not + # preceded by a short or long option flag are passed as arguments + # with an option of '' (empty string). + # + # For example, if -a requires an argument but -b does not, a command line + # of '-a one -b two three' would result in option/arg pairs of ('-a', 'one') + # ('-b', ''), ('', 'two'), ('', 'three') being processed. # def ordering=(ordering) # @@ -144,7 +270,9 @@ attr_reader :ordering # - # Set options + # Set options. Takes the same argument as GetoptLong.new. + # + # Raises a RuntimeError if option processing has already started. # def set_options(*arguments) # @@ -233,7 +361,7 @@ alias quiet? quiet # - # Terminate option processing. + # Explicitly terminate option processing. # def terminate return nil if @status == STATUS_TERMINATED @@ -253,7 +381,7 @@ end # - # Examine whether option processing is terminated or not. + # Returns true if option processing has terminated, false otherwise. # def terminated? return @status == STATUS_TERMINATED @@ -286,16 +414,22 @@ # alias error? error - # - # Return an error message. + # Return the appropriate error message in POSIX-defined format. + # If no error has occurred, returns nil. # def error_message return @error_message end # - # Get next option name and its argument as an array. - # Return nil if the processing is complete (as determined by + # Get next option name and its argument, as an Array of two elements. + # + # The option name is always converted to the first (preferred) + # name given in the original options to GetoptLong.new. + # + # Example: ['--option', 'value'] + # + # Returns nil if the processing is complete (as determined by # STATUS_TERMINATED). # def get @@ -462,9 +596,15 @@ # alias get_option get + # Iterator version of `get'. # - # Iterator version of `get', passes the option and the - # corresponding argument to the supplied block for processing. + # The block is called repeatedly with two arguments: + # The first is the option name. + # The second is the argument which followed it (if any). + # Example: ('--opt', 'value') + # + # The option name is always converted to the first (preferred) + # name given in the original options to GetoptLong.new. # def each loop do --------------060107040206090004020708--