optparse 0.1.1 → 0.2.0

data/lib/optparse/kwargs.rb

@@ -5,6 +5,8 @@ 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.rb

@@ -48,6 +48,10 @@
 #
 # == OptionParser
 #
+# === New to \OptionParser?
+#
+# See the {Tutorial}[./doc/optparse/tutorial_rdoc.html].
+#
 # === 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}[./doc/optparse/tutorial_rdoc.html],
+# 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.2.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
@@ -806,7 +812,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
@@ -1300,7 +1306,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 +1320,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 = [], [], []
@@ -1509,6 +1458,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 +1468,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 +1479,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 +1489,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 +1502,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 +1513,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)
@@ -1780,7 +1738,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 +1749,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 +1766,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optparse
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Nobu Nakada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-03-29 00:00:00.000000000 Z
+date: 2021-10-21 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

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

data/rakelib/version.rake

@@ -1,47 +0,0 @@
-class << (helper = Bundler::GemHelper.instance)
-  def mainfile
-    "lib/#{File.basename(gemspec.loaded_from, ".gemspec")}.rb"
-  end
-
-  def update_version
-    File.open(mainfile, "r+b") do |f|
-      d = f.read
-      if d.sub!(/^(\s*OptionParser::Version\s*=\s*)".*"/) {$1 + gemspec.version.to_s.dump}
-        f.rewind
-        f.truncate(0)
-        f.print(d)
-      end
-    end
-  end
-
-  def commit_bump
-    sh(%W[git -C #{File.dirname(gemspec.loaded_from)} commit -m bump\ up\ to\ #{gemspec.version}
-          #{mainfile}])
-  end
-
-  def version=(v)
-    gemspec.version = v
-    update_version
-    commit_bump
-  end
-end
-
-major, minor, teeny = helper.gemspec.version.segments
-
-task "bump:teeny" do
-  helper.version = Gem::Version.new("#{major}.#{minor}.#{teeny+1}")
-end
-
-task "bump:minor" do
-  helper.version = Gem::Version.new("#{major}.#{minor+1}.0")
-end
-
-task "bump:major" do
-  helper.version = Gem::Version.new("#{major+1}.0.0")
-end
-
-task "bump" => "bump:teeny"
-
-task "tag" do
-  helper.__send__(:tag_version)
-end