optparse 0.1.1 → 0.3.0

data/lib/optparse/ac.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: false
-require 'optparse'
+require_relative '../optparse'
 
 class OptionParser::AC < OptionParser
   private

data/lib/optparse/date.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: false
-require 'optparse'
+require_relative '../optparse'
 require 'date'
 
 OptionParser.accept(DateTime) do |s,|

data/lib/optparse/kwargs.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
-require 'optparse'
+require_relative '../optparse'
 
 class OptionParser
   # :call-seq:
   #   define_by_keywords(options, method, **params)
   #
+  # :include: ../../doc/optparse/creates_option.rdoc
+  #
   def define_by_keywords(options, meth, **opts)
     meth.parameters.each do |type, name|
       case type

data/lib/optparse/shellwords.rb

@@ -2,6 +2,6 @@
 # -*- ruby -*-
 
 require 'shellwords'
-require 'optparse'
+require_relative '../optparse'
 
 OptionParser.accept(Shellwords) {|s,| Shellwords.shellwords(s)}

data/lib/optparse/time.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: false
-require 'optparse'
+require_relative '../optparse'
 require 'time'
 
 OptionParser.accept(Time) do |s,|

data/lib/optparse/uri.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: false
 # -*- ruby -*-
 
-require 'optparse'
+require_relative '../optparse'
 require 'uri'
 
 OptionParser.accept(URI) {|s,| URI.parse(s) if s}

data/lib/optparse.rb

@@ -48,6 +48,10 @@
 #
 # == OptionParser
 #
+# === New to \OptionParser?
+#
+# See the {Tutorial}[optparse/tutorial.rdoc].
+#
 # === Introduction
 #
 # OptionParser is a class for command-line option analysis.  It is much more
@@ -240,14 +244,14 @@
 #
 #   require 'optparse'
 #
-#   params = {}
+#   options = {}
 #   OptionParser.new do |parser|
 #     parser.on('-a')
 #     parser.on('-b NUM', Integer)
 #     parser.on('-v', '--verbose')
-#   end.parse!(into: params)
+#   end.parse!(into: options)
 #
-#   p params
+#   p options
 #
 # Used:
 #
@@ -415,11 +419,13 @@
 #
 # === 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}[optparse/tutorial.rdoc],
+# 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"
+  OptionParser::Version = "0.3.0"
 
   # :stopdoc:
   NoArgument = [NO_ARGUMENT = :NONE, nil].freeze
@@ -547,7 +553,7 @@ class OptionParser
     # Parses +arg+ and returns rest of +arg+ and matched portion to the
     # argument pattern. Yields when the pattern doesn't match substring.
     #
-    def parse_arg(arg)
+    def parse_arg(arg) # :nodoc:
       pattern or return nil, [arg]
       unless m = pattern.match(arg)
         yield(InvalidArgument, arg)
@@ -572,7 +578,7 @@ class OptionParser
     # conversion. Yields at semi-error condition instead of raising an
     # exception.
     #
-    def conv_arg(arg, val = [])
+    def conv_arg(arg, val = []) # :nodoc:
       if conv
         val = conv.call(*val)
       else
@@ -668,6 +674,29 @@ class OptionParser
       end
     end
 
+    def pretty_print_contents(q) # :nodoc:
+      if @block
+        q.text ":" + @block.source_location.join(":") + ":"
+        first = false
+      else
+        first = true
+      end
+      [@short, @long].each do |list|
+        list.each do |opt|
+          if first
+            q.text ":"
+            first = false
+          end
+          q.breakable
+          q.text opt
+        end
+      end
+    end
+
+    def pretty_print(q)         # :nodoc:
+      q.object_group(self) {pretty_print_contents(q)}
+    end
+
     #
     # Switch that takes no arguments.
     #
@@ -687,6 +716,10 @@ class OptionParser
       def self.pattern
         Object
       end
+
+      def pretty_head           # :nodoc:
+        "NoArgument"
+      end
     end
 
     #
@@ -704,6 +737,10 @@ class OptionParser
         end
         conv_arg(*parse_arg(arg, &method(:raise)))
       end
+
+      def pretty_head           # :nodoc:
+        "Required"
+      end
     end
 
     #
@@ -721,18 +758,22 @@ class OptionParser
           conv_arg(arg)
         end
       end
+
+      def pretty_head           # :nodoc:
+        "Optional"
+      end
     end
 
     #
-    # Switch that takes an argument, which does not begin with '-'.
+    # Switch that takes an argument, which does not begin with '-' or is '-'.
     #
     class PlacedArgument < self
 
       #
-      # Returns nil if argument is not present or begins with '-'.
+      # Returns nil if argument is not present or begins with '-' and is not '-'.
       #
       def parse(arg, argv, &error)
-        if !(val = arg) and (argv.empty? or /\A-/ =~ (val = argv[0]))
+        if !(val = arg) and (argv.empty? or /\A-./ =~ (val = argv[0]))
           return nil, block, nil
         end
         opt = (val = parse_arg(val, &error))[1]
@@ -744,6 +785,10 @@ class OptionParser
         end
         val
       end
+
+      def pretty_head           # :nodoc:
+        "Placed"
+      end
     end
   end
 
@@ -775,6 +820,17 @@ class OptionParser
       @list = []
     end
 
+    def pretty_print(q)         # :nodoc:
+      q.group(1, "(", ")") do
+        @list.each do |sw|
+          next unless Switch === sw
+          q.group(1, "(" + sw.pretty_head, ")") do
+            sw.pretty_print_contents(q)
+          end
+        end
+      end
+    end
+
     #
     # See OptionParser.accept.
     #
@@ -806,7 +862,7 @@ class OptionParser
     # +lopts+::  Long style option list.
     # +nlopts+:: Negated long style options list.
     #
-    def update(sw, sopts, lopts, nsw = nil, nlopts = nil)
+    def update(sw, sopts, lopts, nsw = nil, nlopts = nil) # :nodoc:
       sopts.each {|o| @short[o] = sw} if sopts
       lopts.each {|o| @long[o] = sw} if lopts
       nlopts.each {|o| @long[o] = nsw} if nsw and nlopts
@@ -1092,6 +1148,7 @@ XXX
     @summary_indent = indent
     @default_argv = ARGV
     @require_exact = false
+    @raise_unknown = true
     add_officious
     yield self if block_given?
   end
@@ -1169,6 +1226,9 @@ XXX
   # abbreviated long option as short option).
   attr_accessor :require_exact
 
+  # Whether to raise at unknown option.
+  attr_accessor :raise_unknown
+
   #
   # Heading banner preceding summary.
   #
@@ -1287,6 +1347,29 @@ XXX
   def help; summarize("#{banner}".sub(/\n?\z/, "\n")) end
   alias to_s help
 
+  def pretty_print(q)           # :nodoc:
+    q.object_group(self) do
+      first = true
+      if @stack.size > 2
+        @stack.each_with_index do |s, i|
+          next if i < 2
+          next if s.list.empty?
+          if first
+            first = false
+            q.text ":"
+          end
+          q.breakable
+          s.pretty_print(q)
+        end
+      end
+    end
+  end
+
+  def inspect                   # :nodoc:
+    require 'pp'
+    pretty_print_inspect
+  end
+
   #
   # Returns option summary list.
   #
@@ -1300,7 +1383,7 @@ XXX
   # +prv+:: Previously specified argument.
   # +msg+:: Exception message.
   #
-  def notwice(obj, prv, msg)
+  def notwice(obj, prv, msg) # :nodoc:
     unless !prv or prv == obj
       raise(ArgumentError, "argument #{msg} given twice: #{obj}",
             ParseError.filter_backtrace(caller(2)))
@@ -1314,64 +1397,7 @@ XXX
   # :call-seq:
   #   make_switch(params, block = nil)
   #
-  # Creates an OptionParser::Switch from the parameters. The parsed argument
-  # value is passed to the given block, where it can be processed.
-  #
-  # See at the beginning of OptionParser for some full examples.
-  #
-  # +params+ can include the following elements:
-  #
-  # [Argument style:]
-  #   One of the following:
-  #     :NONE, :REQUIRED, :OPTIONAL
-  #
-  # [Argument pattern:]
-  #   Acceptable option argument format, must be pre-defined with
-  #   OptionParser.accept or OptionParser#accept, or Regexp. This can appear
-  #   once or assigned as String if not present, otherwise causes an
-  #   ArgumentError. Examples:
-  #     Float, Time, Array
-  #
-  # [Possible argument values:]
-  #   Hash or Array.
-  #     [:text, :binary, :auto]
-  #     %w[iso-2022-jp shift_jis euc-jp utf8 binary]
-  #     { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
-  #
-  # [Long style switch:]
-  #   Specifies a long style switch which takes a mandatory, optional or no
-  #   argument. It's a string of the following form:
-  #     "--switch=MANDATORY" or "--switch MANDATORY"
-  #     "--switch[=OPTIONAL]"
-  #     "--switch"
-  #
-  # [Short style switch:]
-  #   Specifies short style switch which takes a mandatory, optional or no
-  #   argument. It's a string of the following form:
-  #     "-xMANDATORY"
-  #     "-x[OPTIONAL]"
-  #     "-x"
-  #   There is also a special form which matches character range (not full
-  #   set of regular expression):
-  #     "-[a-z]MANDATORY"
-  #     "-[a-z][OPTIONAL]"
-  #     "-[a-z]"
-  #
-  # [Argument style and description:]
-  #   Instead of specifying mandatory or optional arguments directly in the
-  #   switch parameter, this separate parameter can be used.
-  #     "=MANDATORY"
-  #     "=[OPTIONAL]"
-  #
-  # [Description:]
-  #   Description string for the option.
-  #     "Run verbosely"
-  #   If you give multiple description strings, each string will be printed
-  #   line by line.
-  #
-  # [Handler:]
-  #   Handler for the parsed argument value. Either give a block or pass a
-  #   Proc or Method as an argument.
+  # :include: ../doc/optparse/creates_option.rdoc
   #
   def make_switch(opts, block = nil)
     short, long, nolong, style, pattern, conv, not_pattern, not_conv, not_style = [], [], []
@@ -1480,7 +1506,7 @@ XXX
         style = notwice(default_style.guess(arg = o), style, 'style')
         default_pattern, conv = search(:atype, Object) unless default_pattern
       else
-        desc.push(o)
+        desc.push(o) if o && !o.empty?
       end
     end
 
@@ -1509,6 +1535,8 @@ XXX
   # :call-seq:
   #   define(*params, &block)
   #
+  # :include: ../doc/optparse/creates_option.rdoc
+  #
   def define(*opts, &block)
     top.append(*(sw = make_switch(opts, block)))
     sw[0]
@@ -1517,8 +1545,7 @@ XXX
   # :call-seq:
   #   on(*params, &block)
   #
-  # Add option switch and handler. See #make_switch for an explanation of
-  # parameters.
+  # :include: ../doc/optparse/creates_option.rdoc
   #
   def on(*opts, &block)
     define(*opts, &block)
@@ -1529,6 +1556,8 @@ XXX
   # :call-seq:
   #   define_head(*params, &block)
   #
+  # :include: ../doc/optparse/creates_option.rdoc
+  #
   def define_head(*opts, &block)
     top.prepend(*(sw = make_switch(opts, block)))
     sw[0]
@@ -1537,7 +1566,9 @@ XXX
   # :call-seq:
   #   on_head(*params, &block)
   #
-  # Add option switch like with #on, but at head of summary.
+  # :include: ../doc/optparse/creates_option.rdoc
+  #
+  # The new option is added at the head of the summary.
   #
   def on_head(*opts, &block)
     define_head(*opts, &block)
@@ -1548,6 +1579,8 @@ XXX
   # :call-seq:
   #   define_tail(*params, &block)
   #
+  # :include: ../doc/optparse/creates_option.rdoc
+  #
   def define_tail(*opts, &block)
     base.append(*(sw = make_switch(opts, block)))
     sw[0]
@@ -1557,7 +1590,9 @@ XXX
   # :call-seq:
   #   on_tail(*params, &block)
   #
-  # Add option switch like with #on, but at tail of summary.
+  # :include: ../doc/optparse/creates_option.rdoc
+  #
+  # The new option is added at the tail of the summary.
   #
   def on_tail(*opts, &block)
     define_tail(*opts, &block)
@@ -1608,9 +1643,11 @@ XXX
           begin
             sw, = complete(:long, opt, true)
             if require_exact && !sw.long.include?(arg)
+              throw :terminate, arg unless raise_unknown
               raise InvalidOption, arg
             end
           rescue ParseError
+            throw :terminate, arg unless raise_unknown
             raise $!.set_option(arg, true)
           end
           begin
@@ -1642,6 +1679,7 @@ XXX
               end
             end
           rescue ParseError
+            throw :terminate, arg unless raise_unknown
             raise $!.set_option(arg, true)
           end
           begin
@@ -1780,7 +1818,7 @@ XXX
   # Traverses @stack, sending each element method +id+ with +args+ and
   # +block+.
   #
-  def visit(id, *args, &block)
+  def visit(id, *args, &block) # :nodoc:
     @stack.reverse_each do |el|
       el.__send__(id, *args, &block)
     end
@@ -1791,7 +1829,7 @@ XXX
   #
   # Searches +key+ in @stack for +id+ hash and returns or yields the result.
   #
-  def search(id, key)
+  def search(id, key) # :nodoc:
     block_given = block_given?
     visit(:search, id, key) do |k|
       return block_given ? yield(k) : k
@@ -1808,7 +1846,7 @@ XXX
   # +icase+:: Search case insensitive if true.
   # +pat+::   Optional pattern for completion.
   #
-  def complete(typ, opt, icase = false, *pat)
+  def complete(typ, opt, icase = false, *pat) # :nodoc:
     if pat.empty?
       search(typ, opt) {|sw| return [sw, opt]} # exact match or...
     end
@@ -1872,10 +1910,13 @@ XXX
   # directory ~/.options, then the basename with '.options' suffix
   # under XDG and Haiku standard places.
   #
-  def load(filename = nil)
+  # The optional +into+ keyword argument works exactly like that accepted in
+  # method #parse.
+  #
+  def load(filename = nil, into: nil)
     unless filename
       basename = File.basename($0, '.*')
-      return true if load(File.expand_path(basename, '~/.options')) rescue nil
+      return true if load(File.expand_path(basename, '~/.options'), into: into) rescue nil
       basename << ".options"
       return [
         # XDG
@@ -1887,11 +1928,11 @@ XXX
         '~/config/settings',
       ].any? {|dir|
         next if !dir or dir.empty?
-        load(File.expand_path(basename, dir)) rescue nil
+        load(File.expand_path(basename, dir), into: into) rescue nil
       }
     end
     begin
-      parse(*IO.readlines(filename).each {|s| s.chomp!})
+      parse(*File.readlines(filename, chomp: true), into: into)
       true
     rescue Errno::ENOENT, Errno::ENOTDIR
       false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optparse
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Nobu Nakada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-03-29 00:00:00.000000000 Z
+date: 2022-12-05 00:00:00.000000000 Z
 dependencies: []
 description: OptionParser is a class for command-line option analysis.
 email:
@@ -18,8 +18,67 @@ extensions: []
 extra_rdoc_files: []
 files:
 - COPYING
+- ChangeLog
 - README.md
-- Rakefile
+- doc/optparse/argument_converters.rdoc
+- doc/optparse/creates_option.rdoc
+- doc/optparse/option_params.rdoc
+- doc/optparse/ruby/argument_keywords.rb
+- doc/optparse/ruby/argument_strings.rb
+- doc/optparse/ruby/argv.rb
+- doc/optparse/ruby/array.rb
+- doc/optparse/ruby/basic.rb
+- doc/optparse/ruby/block.rb
+- doc/optparse/ruby/collected_options.rb
+- doc/optparse/ruby/custom_converter.rb
+- doc/optparse/ruby/date.rb
+- doc/optparse/ruby/datetime.rb
+- doc/optparse/ruby/decimal_integer.rb
+- doc/optparse/ruby/decimal_numeric.rb
+- doc/optparse/ruby/default_values.rb
+- doc/optparse/ruby/descriptions.rb
+- doc/optparse/ruby/explicit_array_values.rb
+- doc/optparse/ruby/explicit_hash_values.rb
+- doc/optparse/ruby/false_class.rb
+- doc/optparse/ruby/float.rb
+- doc/optparse/ruby/help.rb
+- doc/optparse/ruby/help_banner.rb
+- doc/optparse/ruby/help_format.rb
+- doc/optparse/ruby/help_program_name.rb
+- doc/optparse/ruby/integer.rb
+- doc/optparse/ruby/long_names.rb
+- doc/optparse/ruby/long_optional.rb
+- doc/optparse/ruby/long_required.rb
+- doc/optparse/ruby/long_simple.rb
+- doc/optparse/ruby/long_with_negation.rb
+- doc/optparse/ruby/match_converter.rb
+- doc/optparse/ruby/matched_values.rb
+- doc/optparse/ruby/method.rb
+- doc/optparse/ruby/missing_options.rb
+- doc/optparse/ruby/mixed_names.rb
+- doc/optparse/ruby/name_abbrev.rb
+- doc/optparse/ruby/no_abbreviation.rb
+- doc/optparse/ruby/numeric.rb
+- doc/optparse/ruby/object.rb
+- doc/optparse/ruby/octal_integer.rb
+- doc/optparse/ruby/optional_argument.rb
+- doc/optparse/ruby/parse.rb
+- doc/optparse/ruby/parse_bang.rb
+- doc/optparse/ruby/proc.rb
+- doc/optparse/ruby/regexp.rb
+- doc/optparse/ruby/required_argument.rb
+- doc/optparse/ruby/shellwords.rb
+- doc/optparse/ruby/short_names.rb
+- doc/optparse/ruby/short_optional.rb
+- doc/optparse/ruby/short_range.rb
+- doc/optparse/ruby/short_required.rb
+- doc/optparse/ruby/short_simple.rb
+- doc/optparse/ruby/string.rb
+- doc/optparse/ruby/terminator.rb
+- doc/optparse/ruby/time.rb
+- doc/optparse/ruby/true_class.rb
+- doc/optparse/ruby/uri.rb
+- doc/optparse/tutorial.rdoc
 - lib/optionparser.rb
 - lib/optparse.rb
 - lib/optparse/ac.rb
@@ -31,10 +90,6 @@ files:
 - lib/optparse/version.rb
 - misc/rb_optparse.bash
 - misc/rb_optparse.zsh
-- optparse.gemspec
-- rakelib/changelogs.rake
-- rakelib/epoch.rake
-- rakelib/version.rake
 homepage: https://github.com/ruby/optparse
 licenses:
 - Ruby
@@ -43,7 +98,10 @@ metadata:
   homepage_uri: https://github.com/ruby/optparse
   source_code_uri: https://github.com/ruby/optparse
 post_install_message:
-rdoc_options: []
+rdoc_options:
+- "--main=README.md"
+- "--op=rdoc"
+- "--page-dir=doc"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -57,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.0.dev
+rubygems_version: 3.4.0.dev
 signing_key:
 specification_version: 4
 summary: OptionParser is a class for command-line option analysis.

data/Rakefile

@@ -1,10 +0,0 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test/lib"
-  t.ruby_opts << "-rhelper"
-  t.test_files = FileList['test/**/test_*.rb']
-end
-
-task :default => :test

data/optparse.gemspec

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-name = File.basename(__FILE__, ".gemspec")
-version = ["lib", Array.new(name.count("-")+1, "..").join("/")].find do |dir|
-  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")) do |line|
-    /^\s*OptionParser::Version\s*=\s*"(.*)"/ =~ line and break $1
-  end rescue nil
-end
-
-Gem::Specification.new do |spec|
-  spec.name          = name
-  spec.version       = version
-  spec.authors       = ["Nobu Nakada"]
-  spec.email         = ["nobu@ruby-lang.org"]
-
-  spec.summary       = %q{OptionParser is a class for command-line option analysis.}
-  spec.description   = %q{OptionParser is a class for command-line option analysis.}
-  spec.homepage      = "https://github.com/ruby/optparse"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
-  spec.licenses      = ["Ruby", "BSD-2-Clause"]
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f|
-      f.match(%r{\A(?:(?:test|spec|features)/|Gemfile|\.(?:editor|git))})
-    }
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-end

data/rakelib/changelogs.rake

@@ -1,34 +0,0 @@
-task "build" => "changelogs"
-
-changelog = proc do |output, ver = nil, prev = nil|
-  ver &&= Gem::Version.new(ver)
-  range = [[prev], [ver, "HEAD"]].map {|ver, branch| ver ? "v#{ver.to_s}" : branch}.compact.join("..")
-  IO.popen(%W[git log --format=fuller --topo-order --no-merges #{range}]) do |log|
-    line = log.gets
-    FileUtils.mkpath(File.dirname(output))
-    File.open(output, "wb") do |f|
-      f.print "-*- coding: utf-8 -*-\n\n", line
-      log.each_line do |line|
-        line.sub!(/^(?!:)(?:Author|Commit)?(?:Date)?: /, '  \&')
-        line.sub!(/ +$/, '')
-        f.print(line)
-      end
-    end
-  end
-end
-
-tags = IO.popen(%w[git tag -l v[0-9]*]).grep(/v(.*)/) {$1}
-tags.sort_by! {|tag| tag.scan(/\d+/).map(&:to_i)}
-tags.inject(nil) do |prev, tag|
-  task("logs/ChangeLog-#{tag}") {|t| changelog[t.name, tag, prev]}
-  tag
-end
-
-desc "Make ChangeLog"
-task "ChangeLog", [:ver, :prev] do |t, ver: nil, prev: tags.last|
-  changelog[t.name, ver, prev]
-end
-
-changelogs = ["ChangeLog", *tags.map {|tag| "logs/ChangeLog-#{tag}"}]
-task "changelogs" => changelogs
-CLOBBER.concat(changelogs) << "logs"

data/rakelib/epoch.rake

@@ -1,5 +0,0 @@
-task "build" => "date_epoch"
-
-task "date_epoch" do
-  ENV["SOURCE_DATE_EPOCH"] = IO.popen(%W[git -C #{__dir__} log -1 --format=%ct], &:read).chomp
-end