* sprintf.c (rb_str_format): allow %c to print one character

  string (e.g. ?x).

* lib/tempfile.rb (Tempfile::make_tmpname): put dot between
  basename and pid.  [ruby-talk:196272]
* parse.y (do_block): remove -> style block.

* parse.y (parser_yylex): remove tLAMBDA_ARG.

* eval.c (rb_call0): binding for the return event hook should have
  consistent scope.  [ruby-core:07928]

* eval.c (proc_invoke): return behavior should depend whether it
  is surrounded by a lambda or a mere block.

* eval.c (formal_assign): handles post splat arguments.

* eval.c (rb_call0): ditto.

* st.c (strhash): use FNV-1a hash.

* parse.y (parser_yylex): removed experimental ';;' terminator.

* eval.c (rb_node_arity): should be aware of post splat arguments.

* eval.c (rb_proc_arity): ditto.

* parse.y (f_args): syntax rule enhanced to support arguments
  after the splat.

* parse.y (block_param): ditto for block parameters.

* parse.y (f_post_arg): mandatory formal arguments after the splat
  argument.

* parse.y (new_args_gen): generate nodes for mandatory formal
  arguments after the splat argument.

* eval.c (rb_eval): dispatch mandatory formal arguments after the
  splat argument.

* parse.y (args): allow more than one splat in the argument list.

* parse.y (method_call): allow aref [] to accept all kind of
  method argument, including assocs, splat, and block argument.

* eval.c (SETUP_ARGS0): prepare block argument as well.

* lib/mathn.rb (Integer): remove Integer#gcd2. [ruby-core:07931]

* eval.c (error_line): print receivers true/false/nil specially.

* eval.c (rb_proc_yield): handles parameters in yield semantics.

* eval.c (nil_yield): gives LocalJumpError to denote no block
  error.

* io.c (rb_io_getc): now takes one-character string.

* string.c (rb_str_hash): use FNV-1a hash from Fowler/Noll/Vo
  hashing algorithm.

* string.c (rb_str_aref): str[0] now returns 1 character string,
  instead of a fixnum.	[Ruby2]

* parse.y (parser_yylex): ?c now returns 1 character string,
  instead of a fixnum.	[Ruby2]

* string.c (rb_str_aset): no longer support fixnum insertion.

* eval.c (umethod_bind): should not update original class.
  [ruby-dev:28636]

* eval.c (ev_const_get): should support constant access from
  within instance_eval().  [ruby-dev:28327]

* time.c (time_timeval): should round for usec floating
  number.  [ruby-core:07896]

* time.c (time_add): ditto.

* dir.c (sys_warning): should not call a vararg function
  rb_sys_warning() indirectly.	[ruby-core:07886]

* numeric.c (flo_divmod): the first element of Float#divmod should
  be an integer. [ruby-dev:28589]

* test/ruby/test_float.rb: add tests for divmod, div, modulo and remainder.

* re.c (rb_reg_initialize): should not allow modifying literal
  regexps.  frozen check moved from rb_reg_initialize_m as well.

* re.c (rb_reg_initialize): should not modify untainted objects in
  safe levels higher than 3.

* re.c (rb_memcmp): type change from char* to const void*.

* dir.c (dir_close): should not close untainted dir stream.

* dir.c (GetDIR): add tainted/frozen check for each dir operation.

* lib/rdoc/parsers/parse_rb.rb (RDoc::RubyParser::parse_symbol_arg):
  typo fixed.  a patch from Florian Gross <florg at florg.net>.

* eval.c (EXEC_EVENT_HOOK): trace_func may remove itself from
  event_hooks.	no guarantee for arbitrary hook deletion.
  [ruby-dev:28632]

* util.c (ruby_strtod): differ addition to minimize error.
  [ruby-dev:28619]

* util.c (ruby_strtod): should not raise ERANGE when the input
  string does not have any digits.  [ruby-dev:28629]

* eval.c (proc_invoke): should restore old ruby_frame->block.
  thanks to ts <decoux at moulon.inra.fr>.  [ruby-core:07833]
  also fix [ruby-dev:28614] as well.

* signal.c (trap): sig should be less then NSIG.  Coverity found
  this bug.  a patch from Kevin Tew <tewk at tewk.com>.
  [ruby-core:07823]

* math.c (math_log2): add new method inspired by
  [ruby-talk:191237].

* math.c (math_log): add optional base argument to Math::log().
  [ruby-talk:191308]

* ext/syck/emitter.c (syck_scan_scalar): avoid accessing
  uninitialized array element.	a patch from Pat Eyler
  <rubypate at gmail.com>.  [ruby-core:07809]

* array.c (rb_ary_fill): initialize local variables first.  a
  patch from Pat Eyler <rubypate at gmail.com>.	 [ruby-core:07810]

* ext/syck/yaml2byte.c (syck_yaml2byte_handler): need to free
  type_tag.  a patch from Pat Eyler <rubypate at gmail.com>.
  [ruby-core:07808]

* ext/socket/socket.c (make_hostent_internal): accept ai_family
  check from Sam Roberts <sroberts at uniserve.com>.
  [ruby-core:07691]

* util.c (ruby_strtod): should not cut off 18 digits for no
  reason.  [ruby-core:07796]

* array.c (rb_ary_fill): internalize local variable "beg" to
  pacify Coverity.  [ruby-core:07770]

* pack.c (pack_unpack): now supports CRLF newlines.  a patch from
  <tommy at tmtm.org>.	[ruby-dev:28601]

* applied code clean-up patch from Stefan Huehner
  <stefan at huehner.org>.  [ruby-core:07764]

* lib/jcode.rb (String::tr_s): should have translated non
  squeezing character sequence (i.e. a character) as well.  thanks
  to Hiroshi Ichikawa <gimite at gimite.ddo.jp> [ruby-list:42090]

* ext/socket/socket.c: document update patch from Sam Roberts
  <sroberts at uniserve.com>.  [ruby-core:07701]

* lib/mathn.rb (Integer): need not to remove gcd2.  a patch from
  NARUSE, Yui <naruse at airemix.com>.	[ruby-dev:28570]

* parse.y (arg): too much NEW_LIST()

* eval.c (SETUP_ARGS0): remove unnecessary access to nd_alen.

* eval.c (rb_eval): use ARGSCAT for NODE_OP_ASGN1.
  [ruby-dev:28585]

* parse.y (arg): use NODE_ARGSCAT for placeholder.

* lib/getoptlong.rb (GetoptLong::get): RDoc update patch from
  mathew <meta at pobox.com>.  [ruby-core:07738]

* variable.c (rb_const_set): raise error when no target klass is
  supplied.  [ruby-dev:28582]

* prec.c (prec_prec_f): documentation patch from
  <gerardo.santana at gmail.com>.  [ruby-core:07689]

* bignum.c (rb_big_pow): second operand may be too big even if
  it's a Fixnum.  [ruby-talk:187984]

* README.EXT: update symbol description.  [ruby-talk:188104]

* COPYING: explicitly note GPLv2.  [ruby-talk:187922]

* parse.y: remove some obsolete syntax rules (unparenthesized
  method calls in argument list).

* eval.c (rb_call0): insecure calling should be checked for non
  NODE_SCOPE method invocations too.

* eval.c (rb_alias): should preserve the current safe level as
  well as method definition.

* process.c (rb_f_sleep): remove RDoc description about SIGALRM
  which is not valid on the current implementation. [ruby-dev:28464]

 Thu Mar 23 21:40:47 2006  K.Kosako  <sndgk393 AT ybb.ne.jp>

* eval.c (method_missing): should support argument splat in
  super.  a bug in combination of super, splat and
  method_missing.  [ruby-talk:185438]

* configure.in: Solaris SunPro compiler -rapth patch from
  <kuwa at labs.fujitsu.com>.  [ruby-dev:28443]

* configure.in: remove enable_rpath=no for Solaris.
  [ruby-dev:28440]

* ext/win32ole/win32ole.c (ole_val2olevariantdata): change behavior
  of converting  OLE Variant object with VT_ARRAY|VT_UI1 and Ruby
  String object.

* ruby.1: a clarification patch from David Lutterkort
  <dlutter at redhat.com>.  [ruby-core:7508]

* lib/rdoc/ri/ri_paths.rb (RI::Paths): adding paths from rubygems
  directories.	a patch from Eric Hodel <drbrain at segment7.net>.
  [ruby-core:07423]

* eval.c (rb_clear_cache_by_class): clearing wrong cache.

* ext/extmk.rb: use :remove_destination to install extension libraries
  to avoid SEGV.  [ruby-dev:28417]

* eval.c (rb_thread_fd_writable): should not re-schedule output
  from KILLED thread (must be error printing).

* array.c (rb_ary_flatten_bang): allow specifying recursion
  level.  [ruby-talk:182170]

* array.c (rb_ary_flatten): ditto.

* gc.c (add_heap): a heap_slots may overflow.  a patch from Stefan
  Weil <weil at mail.berlios.de>.

* eval.c (rb_call): use separate cache for fcall/vcall
  invocation.

* eval.c (rb_eval): NODE_FCALL, NODE_VCALL can call local
  functions.

* eval.c (rb_mod_local): a new method to specify newly added
  visibility "local".

* eval.c (search_method): search for local methods which are
  visible only from the current class.

* class.c (rb_class_local_methods): a method to list local methods.

* object.c (Init_Object): add BasicObject class as a top level
  BlankSlate class.

* ruby.h (SYM2ID): should not cast to signed long.
  [ruby-core:07414]

* class.c (rb_include_module): allow module duplication.


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

1 files changed, 168 insertions, 28 deletions

diff --git a/lib/getoptlong.rb b/lib/getoptlong.rb
index 8fb302d741..922d25371c 100644
--- a/lib/getoptlong.rb
+++ b/lib/getoptlong.rb
@@ -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 <tt>--file</tt> as well 
+# as single letter options like <tt>-f</tt>
 #
-
+# The empty option <tt>--</tt> (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 GetoptLong
   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 @@ class GetoptLong
   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:
+  #
+  # <b>REQUIRE_ORDER</b> :
+  # 
+  # 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.)
+  #
+  # <b>PERMUTE</b> :
+  #  
+  # 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.
+  #
+  # <b>RETURN_IN_ORDER</b> :
+  #
+  # 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 @@ class GetoptLong
   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 @@ class GetoptLong
   alias quiet? quiet
 
   #
-  # Terminate option processing.
+  # Explicitly terminate option processing.
   #
   def terminate
     return nil if @status == STATUS_TERMINATED
@@ -253,7 +381,7 @@ class GetoptLong
   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 @@ class GetoptLong
   #
   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 @@ class GetoptLong
   #
   alias get_option get
 
+  # Iterator version of `get'.
+  #
+  # 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')
   #
-  # Iterator version of `get', passes the option and the
-  # corresponding argument to the supplied block for processing.
+  # The option name is always converted to the first (preferred)
+  # name given in the original options to GetoptLong.new.
   #
   def each
     loop do