optparse 0.3.1 → 0.5.0

data/lib/optparse.rb

@@ -8,7 +8,6 @@
 # See OptionParser for documentation.
 #
 
-
 #--
 # == Developer Documentation (not for RDoc output)
 #
@@ -48,7 +47,7 @@
 #
 # == OptionParser
 #
-# === New to \OptionParser?
+# === New to +OptionParser+?
 #
 # See the {Tutorial}[optparse/tutorial.rdoc].
 #
@@ -152,14 +151,14 @@
 # OptionParser supports the ability to coerce command line arguments
 # into objects for us.
 #
-# OptionParser comes with a few ready-to-use kinds of  type
+# OptionParser comes with a few ready-to-use kinds of type
 # coercion. They are:
 #
-# - Date  -- Anything accepted by +Date.parse+
-# - DateTime -- Anything accepted by +DateTime.parse+
-# - Time -- Anything accepted by +Time.httpdate+ or +Time.parse+
-# - URI  -- Anything accepted by +URI.parse+
-# - Shellwords -- Anything accepted by +Shellwords.shellwords+
+# - Date  -- Anything accepted by +Date.parse+ (need to require +optparse/date+)
+# - DateTime -- Anything accepted by +DateTime.parse+ (need to require +optparse/date+)
+# - Time -- Anything accepted by +Time.httpdate+ or +Time.parse+ (need to require +optparse/time+)
+# - URI  -- Anything accepted by +URI.parse+ (need to require +optparse/uri+)
+# - Shellwords -- Anything accepted by +Shellwords.shellwords+ (need to require +optparse/shellwords+)
 # - String -- Any non-empty string
 # - Integer -- Any integer. Will convert octal. (e.g. 124, -3, 040)
 # - Float -- Any float. (e.g. 10, 3.14, -100E+13)
@@ -425,7 +424,8 @@
 # If you have any questions, file a ticket at http://bugs.ruby-lang.org.
 #
 class OptionParser
-  OptionParser::Version = "0.3.1"
+  # The version string
+  OptionParser::Version = "0.5.0"
 
   # :stopdoc:
   NoArgument = [NO_ARGUMENT = :NONE, nil].freeze
@@ -438,6 +438,8 @@ class OptionParser
   # and resolved against a list of acceptable values.
   #
   module Completion
+    # :nodoc:
+
     def self.regexp(key, icase)
       Regexp.new('\A' + Regexp.quote(key).gsub(/\w+\b/, '\&\w*'), icase)
     end
@@ -459,7 +461,7 @@ class OptionParser
       candidates
     end
 
-    def candidate(key, icase = false, pat = nil)
+    def candidate(key, icase = false, pat = nil, &_)
       Completion.candidate(key, icase, pat, &method(:each))
     end
 
@@ -510,6 +512,8 @@ class OptionParser
   # RequiredArgument, etc.
   #
   class Switch
+    # :nodoc:
+
     attr_reader :pattern, :conv, :short, :long, :arg, :desc, :block
 
     #
@@ -697,6 +701,11 @@ class OptionParser
       q.object_group(self) {pretty_print_contents(q)}
     end
 
+    def omitted_argument(val)   # :nodoc:
+      val.pop if val.size == 3 and val.last.nil?
+      val
+    end
+
     #
     # Switch that takes no arguments.
     #
@@ -710,10 +719,10 @@ class OptionParser
         conv_arg(arg)
       end
 
-      def self.incompatible_argument_styles(*)
+      def self.incompatible_argument_styles(*) # :nodoc:
       end
 
-      def self.pattern
+      def self.pattern          # :nodoc:
         Object
       end
 
@@ -730,7 +739,7 @@ class OptionParser
       #
       # Raises an exception if argument is not present.
       #
-      def parse(arg, argv)
+      def parse(arg, argv, &_)
         unless arg
           raise MissingArgument if argv.empty?
           arg = argv.shift
@@ -755,7 +764,7 @@ class OptionParser
         if arg
           conv_arg(*parse_arg(arg, &error))
         else
-          conv_arg(arg)
+          omitted_argument conv_arg(arg)
         end
       end
 
@@ -774,13 +783,14 @@ class OptionParser
       #
       def parse(arg, argv, &error)
         if !(val = arg) and (argv.empty? or /\A-./ =~ (val = argv[0]))
-          return nil, block, nil
+          return nil, block
         end
         opt = (val = parse_arg(val, &error))[1]
         val = conv_arg(*val)
         if opt and !arg
           argv.shift
         else
+          omitted_argument val
           val[0] = nil
         end
         val
@@ -798,6 +808,8 @@ class OptionParser
   # matching pattern and converter pair. Also provides summary feature.
   #
   class List
+    # :nodoc:
+
     # Map from acceptable argument types to pattern and converter pairs.
     attr_reader :atype
 
@@ -837,7 +849,7 @@ class OptionParser
     def accept(t, pat = /.*/m, &block)
       if pat
         pat.respond_to?(:match) or
-          raise TypeError, "has no `match'", ParseError.filter_backtrace(caller(2))
+          raise TypeError, "has no 'match'", ParseError.filter_backtrace(caller(2))
       else
         pat = t if t.respond_to?(:match)
       end
@@ -1033,11 +1045,31 @@ XXX
     to << "#compdef #{name}\n"
     to << COMPSYS_HEADER
     visit(:compsys, {}, {}) {|o, d|
-      to << %Q[  "#{o}[#{d.gsub(/[\"\[\]]/, '\\\\\&')}]" \\\n]
+      to << %Q[  "#{o}[#{d.gsub(/[\\\"\[\]]/, '\\\\\&')}]" \\\n]
     }
     to << "  '*:file:_files' && return 0\n"
   end
 
+  def help_exit
+    if STDOUT.tty? && (pager = ENV.values_at(*%w[RUBY_PAGER PAGER]).find {|e| e && !e.empty?})
+      less = ENV["LESS"]
+      args = [{"LESS" => "#{!less || less.empty? ? '-' : less}Fe"}, pager, "w"]
+      print = proc do |f|
+        f.puts help
+      rescue Errno::EPIPE
+        # pager terminated
+      end
+      if Process.respond_to?(:fork) and false
+        IO.popen("-") {|f| f ? Process.exec(*args, in: f) : print.call(STDOUT)}
+        # unreachable
+      end
+      IO.popen(*args, &print)
+    else
+      puts help
+    end
+    exit
+  end
+
   #
   # Default options for ARGV, which never appear in option summary.
   #
@@ -1049,8 +1081,7 @@ XXX
   #
   Officious['help'] = proc do |parser|
     Switch::NoArgument.new do |arg|
-      puts parser.help
-      exit
+      parser.help_exit
     end
   end
 
@@ -1129,6 +1160,10 @@ XXX
       default.to_i + 1
     end
   end
+
+  #
+  # See self.inc
+  #
   def inc(*args)
     self.class.inc(*args)
   end
@@ -1167,11 +1202,19 @@ XXX
   def terminate(arg = nil)
     self.class.terminate(arg)
   end
+  #
+  # See #terminate.
+  #
   def self.terminate(arg = nil)
     throw :terminate, arg
   end
 
   @stack = [DefaultList]
+  #
+  # Returns the global top option list.
+  #
+  # Do not use directly.
+  #
   def self.top() DefaultList end
 
   #
@@ -1192,9 +1235,9 @@ XXX
   #
   # Directs to reject specified class argument.
   #
-  # +t+:: Argument class specifier, any object including Class.
+  # +type+:: Argument class specifier, any object including Class.
   #
-  #   reject(t)
+  #   reject(type)
   #
   def reject(*args, &blk) top.reject(*args, &blk) end
   #
@@ -1284,10 +1327,24 @@ XXX
     end
   end
 
+  #
+  # Shows warning message with the program name
+  #
+  # +mesg+:: Message, defaulted to +$!+.
+  #
+  # See Kernel#warn.
+  #
   def warn(mesg = $!)
     super("#{program_name}: #{mesg}")
   end
 
+  #
+  # Shows message with the program name then aborts.
+  #
+  # +mesg+:: Message, defaulted to +$!+.
+  #
+  # See Kernel#abort.
+  #
   def abort(mesg = $!)
     super("#{program_name}: #{mesg}")
   end
@@ -1309,6 +1366,9 @@ XXX
   #
   # Pushes a new List.
   #
+  # If a block is given, yields +self+ and returns the result of the
+  # block, otherwise returns +self+.
+  #
   def new
     @stack.push(List.new)
     if block_given?
@@ -1532,6 +1592,12 @@ XXX
       nolong
   end
 
+  # ----
+  # Option definition phase methods
+  #
+  # These methods are used to define options, or to construct an
+  # OptionParser instance in other words.
+
   # :call-seq:
   #   define(*params, &block)
   #
@@ -1607,6 +1673,13 @@ XXX
     top.append(string, nil, nil)
   end
 
+  # ----
+  # Arguments parse phase methods
+  #
+  # These methods parse +argv+, convert, and store the results by
+  # calling handlers.  As these methods do not modify +self+, +self+
+  # can be frozen.
+
   #
   # Parses command line arguments +argv+ in order. When a block is given,
   # each non-option argument is yielded. When optional +into+ keyword
@@ -1616,21 +1689,21 @@ XXX
   #
   # Returns the rest of +argv+ left unparsed.
   #
-  def order(*argv, into: nil, &nonopt)
+  def order(*argv, **keywords, &nonopt)
     argv = argv[0].dup if argv.size == 1 and Array === argv[0]
-    order!(argv, into: into, &nonopt)
+    order!(argv, **keywords, &nonopt)
   end
 
   #
   # Same as #order, but removes switches destructively.
   # Non-option arguments remain in +argv+.
   #
-  def order!(argv = default_argv, into: nil, &nonopt)
+  def order!(argv = default_argv, into: nil, **keywords, &nonopt)
     setter = ->(name, val) {into[name.to_sym] = val} if into
-    parse_in_order(argv, setter, &nonopt)
+    parse_in_order(argv, setter, **keywords, &nonopt)
   end
 
-  def parse_in_order(argv = default_argv, setter = nil, &nonopt)  # :nodoc:
+  def parse_in_order(argv = default_argv, setter = nil, exact: require_exact, **, &nonopt)  # :nodoc:
     opt, arg, val, rest = nil
     nonopt ||= proc {|a| throw :terminate, a}
     argv.unshift(arg) if arg = catch(:terminate) {
@@ -1641,19 +1714,24 @@ XXX
           opt, rest = $1, $2
           opt.tr!('_', '-')
           begin
-            sw, = complete(:long, opt, true)
-            if require_exact && !sw.long.include?(arg)
-              throw :terminate, arg unless raise_unknown
-              raise InvalidOption, arg
+            if exact
+              sw, = search(:long, opt)
+            else
+              sw, = complete(:long, opt, true)
             end
           rescue ParseError
             throw :terminate, arg unless raise_unknown
             raise $!.set_option(arg, true)
+          else
+            unless sw
+              throw :terminate, arg unless raise_unknown
+              raise InvalidOption, arg
+            end
           end
           begin
-            opt, cb, val = sw.parse(rest, argv) {|*exc| raise(*exc)}
-            val = cb.call(val) if cb
-            setter.call(sw.switch_name, val) if setter
+            opt, cb, *val = sw.parse(rest, argv) {|*exc| raise(*exc)}
+            val = callback!(cb, 1, *val) if cb
+            callback!(setter, 2, sw.switch_name, *val) if setter
           rescue ParseError
             raise $!.set_option(arg, rest)
           end
@@ -1671,7 +1749,7 @@ XXX
                 val = arg.delete_prefix('-')
                 has_arg = true
               rescue InvalidOption
-                raise if require_exact
+                raise if exact
                 # if no short options match, try completion with long
                 # options.
                 sw, = complete(:long, opt)
@@ -1683,7 +1761,7 @@ XXX
             raise $!.set_option(arg, true)
           end
           begin
-            opt, cb, val = sw.parse(val, argv) {|*exc| raise(*exc) if eq}
+            opt, cb, *val = sw.parse(val, argv) {|*exc| raise(*exc) if eq}
           rescue ParseError
             raise $!.set_option(arg, arg.length > 2)
           else
@@ -1691,8 +1769,8 @@ XXX
           end
           begin
             argv.unshift(opt) if opt and (!rest or (opt = opt.sub(/\A-*/, '-')) != '-')
-            val = cb.call(val) if cb
-            setter.call(sw.switch_name, val) if setter
+            val = callback!(cb, 1, *val) if cb
+            callback!(setter, 2, sw.switch_name, *val) if setter
           rescue ParseError
             raise $!.set_option(arg, arg.length > 2)
           end
@@ -1718,6 +1796,17 @@ XXX
   end
   private :parse_in_order
 
+  # Calls callback with _val_.
+  def callback!(cb, max_arity, *args) # :nodoc:
+    if (size = args.size) < max_arity and cb.to_proc.lambda?
+      (arity = cb.arity) < 0 and arity = (1-arity)
+      arity = max_arity if arity > max_arity
+      args[arity - 1] = nil if arity > size
+    end
+    cb.call(*args)
+  end
+  private :callback!
+
   #
   # Parses command line arguments +argv+ in permutation mode and returns
   # list of non-option arguments. When optional +into+ keyword
@@ -1725,18 +1814,18 @@ XXX
   # <code>[]=</code> method (so it can be Hash, or OpenStruct, or other
   # similar object).
   #
-  def permute(*argv, into: nil)
+  def permute(*argv, **keywords)
     argv = argv[0].dup if argv.size == 1 and Array === argv[0]
-    permute!(argv, into: into)
+    permute!(argv, **keywords)
   end
 
   #
   # Same as #permute, but removes switches destructively.
   # Non-option arguments remain in +argv+.
   #
-  def permute!(argv = default_argv, into: nil)
+  def permute!(argv = default_argv, **keywords)
     nonopts = []
-    order!(argv, into: into, &nonopts.method(:<<))
+    order!(argv, **keywords, &nonopts.method(:<<))
     argv[0, 0] = nonopts
     argv
   end
@@ -1748,20 +1837,20 @@ XXX
   # values are stored there via <code>[]=</code> method (so it can be Hash,
   # or OpenStruct, or other similar object).
   #
-  def parse(*argv, into: nil)
+  def parse(*argv, **keywords)
     argv = argv[0].dup if argv.size == 1 and Array === argv[0]
-    parse!(argv, into: into)
+    parse!(argv, **keywords)
   end
 
   #
   # Same as #parse, but removes switches destructively.
   # Non-option arguments remain in +argv+.
   #
-  def parse!(argv = default_argv, into: nil)
+  def parse!(argv = default_argv, **keywords)
     if ENV.include?('POSIXLY_CORRECT')
-      order!(argv, into: into)
+      order!(argv, **keywords)
     else
-      permute!(argv, into: into)
+      permute!(argv, **keywords)
     end
   end
 
@@ -1775,7 +1864,16 @@ XXX
   #   # params["bar"] = "x"  # --bar x
   #   # params["zot"] = "z"  # --zot Z
   #
-  def getopts(*args)
+  # Option +symbolize_names+ (boolean) specifies whether returned Hash keys should be Symbols; defaults to +false+ (use Strings).
+  #
+  #   params = ARGV.getopts("ab:", "foo", "bar:", "zot:Z;zot option", symbolize_names: true)
+  #   # params[:a] = true   # -a
+  #   # params[:b] = "1"    # -b1
+  #   # params[:foo] = "1"  # --foo
+  #   # params[:bar] = "x"  # --bar x
+  #   # params[:zot] = "z"  # --zot Z
+  #
+  def getopts(*args, symbolize_names: false, **keywords)
     argv = Array === args.first ? args.shift : default_argv
     single_options, *long_options = *args
 
@@ -1803,15 +1901,15 @@ XXX
       end
     end
 
-    parse_in_order(argv, result.method(:[]=))
-    result
+    parse_in_order(argv, result.method(:[]=), **keywords)
+    symbolize_names ? result.transform_keys(&:to_sym) : result
   end
 
   #
   # See #getopts.
   #
-  def self.getopts(*args)
-    new.getopts(*args)
+  def self.getopts(*args, symbolize_names: false)
+    new.getopts(*args, symbolize_names: symbolize_names)
   end
 
   #
@@ -1872,6 +1970,9 @@ XXX
     DidYouMean.formatter.message_for(all_candidates & checker.correct(opt))
   end
 
+  #
+  # Return candidates for +word+.
+  #
   def candidate(word)
     list = []
     case word
@@ -1913,10 +2014,10 @@ XXX
   # The optional +into+ keyword argument works exactly like that accepted in
   # method #parse.
   #
-  def load(filename = nil, into: nil)
+  def load(filename = nil, **keywords)
     unless filename
       basename = File.basename($0, '.*')
-      return true if load(File.expand_path(basename, '~/.options'), into: into) rescue nil
+      return true if load(File.expand_path(basename, '~/.options'), **keywords) rescue nil
       basename << ".options"
       return [
         # XDG
@@ -1928,11 +2029,11 @@ XXX
         '~/config/settings',
       ].any? {|dir|
         next if !dir or dir.empty?
-        load(File.expand_path(basename, dir), into: into) rescue nil
+        load(File.expand_path(basename, dir), **keywords) rescue nil
       }
     end
     begin
-      parse(*File.readlines(filename, chomp: true), into: into)
+      parse(*File.readlines(filename, chomp: true), **keywords)
       true
     rescue Errno::ENOENT, Errno::ENOTDIR
       false
@@ -1945,10 +2046,10 @@ XXX
   #
   # +env+ defaults to the basename of the program.
   #
-  def environment(env = File.basename($0, '.*'))
+  def environment(env = File.basename($0, '.*'), **keywords)
     env = ENV[env] || ENV[env.upcase] or return
     require 'shellwords'
-    parse(*Shellwords.shellwords(env))
+    parse(*Shellwords.shellwords(env), **keywords)
   end
 
   #
@@ -2114,6 +2215,7 @@ XXX
     # Reason which caused the error.
     Reason = 'parse error'
 
+    # :nodoc:
     def initialize(*args, additional: nil)
       @additional = additional
       @arg0, = args
@@ -2264,19 +2366,19 @@ XXX
     # Parses +self+ destructively in order and returns +self+ containing the
     # rest arguments left unparsed.
     #
-    def order!(&blk) options.order!(self, &blk) end
+    def order!(**keywords, &blk) options.order!(self, **keywords, &blk) end
 
     #
     # Parses +self+ destructively in permutation mode and returns +self+
     # containing the rest arguments left unparsed.
     #
-    def permute!() options.permute!(self) end
+    def permute!(**keywords) options.permute!(self, **keywords) end
 
     #
     # Parses +self+ destructively and returns +self+ containing the
     # rest arguments left unparsed.
     #
-    def parse!() options.parse!(self) end
+    def parse!(**keywords) options.parse!(self, **keywords) end
 
     #
     # Substitution of getopts is possible as follows. Also see
@@ -2289,8 +2391,8 @@ XXX
     #   rescue OptionParser::ParseError
     #   end
     #
-    def getopts(*args)
-      options.getopts(self, *args)
+    def getopts(*args, symbolize_names: false, **keywords)
+      options.getopts(self, *args, symbolize_names: symbolize_names, **keywords)
     end
 
     #
@@ -2300,7 +2402,8 @@ XXX
       super
       obj.instance_eval {@optparse = nil}
     end
-    def initialize(*args)
+
+    def initialize(*args)       # :nodoc:
       super
       @optparse = nil
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optparse
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Nobu Nakada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-22 00:00:00.000000000 Z
+date: 2024-04-15 00:00:00.000000000 Z
 dependencies: []
 description: OptionParser is a class for command-line option analysis.
 email:
@@ -17,12 +17,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".document"
+- ".rdoc_options"
 - COPYING
 - ChangeLog
 - README.md
+- doc/optparse/.document
 - doc/optparse/argument_converters.rdoc
 - doc/optparse/creates_option.rdoc
 - doc/optparse/option_params.rdoc
+- doc/optparse/ruby/argument_abbreviation.rb
 - doc/optparse/ruby/argument_keywords.rb
 - doc/optparse/ruby/argument_strings.rb
 - doc/optparse/ruby/argv.rb
@@ -115,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.0.dev
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: OptionParser is a class for command-line option analysis.