getoptlong 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97e8f8ce5f0f8b6e7e95b96399f60b00e3d2bc0e806d820db2c990abc9349fca
-  data.tar.gz: 1b376994a15f54503d342eb6286ba32b6117b409121fe267f0b5ac28da9f6969
+  metadata.gz: 4b270eb9d604cd1ffd4d5f0470b369d9c336c950d7feb0d2a07b4552048f0c85
+  data.tar.gz: 2443fc1bdf21695a9fe0c444d239064930eb3fbbe7b36638f5ed30879a22bc76
 SHA512:
-  metadata.gz: bdf3632da65a872ce28b4bbbb511b353d31f9c50c47fb31a07102ffc782fcb8b6ac3068abb149f043bd4331b371f2f0140d9c3a24be0c427a8b365dfe6d2a3d7
-  data.tar.gz: 9e83ccaf5dd67baf196394f0359e3f28f3f0017c67996fc35726da3e012b8e0e418a1c26c13da6658070ce997dbc6f253100c19b9603cd6d5357ce6193af2a34
+  metadata.gz: 3fdf473be5224dbd4151bd035f77862b77834ded4059a3ac4f4088f16ddbf8c84c52d90829dbe26a1da67a8e227489f362d3c190acd4f405baa97d142dff5524
+  data.tar.gz: ee73c1412d372f84e1de744d17a4aa3a2eb223fa79f39efccafd4e1f918c82632343c3fd440fa7428bf13e90fdb1b617737e6d4b93486af6389a7417f95b6496

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

data/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  ruby-versions:
+    runs-on: ubuntu-latest
+    outputs:
+      versions: ${{ steps.versions.outputs.value }}
+    steps:
+      - id: versions
+        run: |
+          versions=$(curl -s 'https://cache.ruby-lang.org/pub/misc/ci_versions/all.json' | jq -c '. + ["2.6"]')
+          echo "::set-output name=value::${versions}"
+  test:
+    needs: ruby-versions
+    name: build (${{ matrix.ruby }} / ${{ matrix.os }})
+    strategy:
+      matrix:
+        ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
+        os: [ ubuntu-latest, macos-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run test
+      run: bundle exec rake test

data/Gemfile

@@ -1,8 +1,4 @@
 source "https://rubygems.org"
 
-gemspec
-
-group :development do
-  gem "bundler"
-  gem "rake"
-end
+gem "rake"
+gem "test-unit"

data/Rakefile

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

data/getoptlong.gemspec

@@ -1,17 +1,22 @@
-lib = File.expand_path("lib", __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "getoptlong/version"
+# 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*VERSION\s*=\s*"(.*)"/ =~ line and break $1
+  end rescue nil
+end
 
 Gem::Specification.new do |spec|
-  spec.name          = "getoptlong"
-  spec.version       = GetoptLong::VERSION
+  spec.name          = name
+  spec.version       = version
   spec.authors       = ["Yukihiro Matsumoto"]
   spec.email         = ["matz@ruby-lang.org"]
 
   spec.summary       = %q{GetoptLong for Ruby}
   spec.description   = spec.summary
   spec.homepage      = "https://github.com/ruby/getoptlong"
-  spec.license       = "BSD-2-Clause"
+  spec.licenses      = ["Ruby", "BSD-2-Clause"]
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -19,9 +24,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z 2>/dev/null`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 end

data/lib/getoptlong.rb

@@ -6,85 +6,370 @@
 #
 # You may redistribute and/or modify this library under the same license
 # terms as Ruby.
+
+# \Class \GetoptLong provides parsing both for options
+# and for regular arguments.
 #
-# See GetoptLong for documentation.
+# Using \GetoptLong, you can define options for your program.
+# The program can then capture and respond to whatever options
+# are included in the command that executes the program.
 #
-# 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.
+# A simple example: file <tt>simple.rb</tt>:
+#
+#   :include: ../sample/getoptlong/simple.rb
+#
+# If you are somewhat familiar with options,
+# you may want to skip to this
+# {full example}[#class-GetoptLong-label-Full+Example].
+#
+# == Options
+#
+# A \GetoptLong option has:
+#
+# - A string <em>option name</em>.
+# - Zero or more string <em>aliases</em> for the name.
+# - An <em>option type</em>.
+#
+# Options may be defined by calling singleton method GetoptLong.new,
+# which returns a new \GetoptLong object.
+# Options may then be processed by calling other methods
+# such as GetoptLong#each.
+#
+# === Option Name and Aliases
+#
+# In the array that defines an option,
+# the first element is the string option name.
+# Often the name takes the 'long' form, beginning with two hyphens.
+#
+# The option name may have any number of aliases,
+# which are defined by additional string elements.
+#
+# The name and each alias must be of one of two forms:
+#
+# - Two hyphens, followed by one or more letters.
+# - One hyphen, followed by a single letter.
+#
+# File <tt>aliases.rb</tt>:
+#
+#   :include: ../sample/getoptlong/aliases.rb
+#
+# An option may be cited by its name,
+# or by any of its aliases;
+# the parsed option always reports the name, not an alias:
+#
+#   $ ruby aliases.rb -a -p --xxx --aaa -x
+#
+# Output:
+#
+#   ["--xxx", ""]
+#   ["--xxx", ""]
+#   ["--xxx", ""]
+#   ["--xxx", ""]
+#   ["--xxx", ""]
+#
+#
+# An option may also be cited by an abbreviation of its name or any alias,
+# as long as that abbreviation is unique among the options.
+#
+# File <tt>abbrev.rb</tt>:
+#
+#   :include: ../sample/getoptlong/abbrev.rb
+#
+# Command line:
+#
+#   $ ruby abbrev.rb --xxx --xx --xyz --xy
+#
+# Output:
+#
+#   ["--xxx", ""]
+#   ["--xxx", ""]
+#   ["--xyz", ""]
+#   ["--xyz", ""]
+#
+# This command line raises GetoptLong::AmbiguousOption:
+#
+#   $ ruby abbrev.rb --x
+#
+# === Repetition
+#
+# An option may be cited more than once:
+#
+#   $ ruby abbrev.rb --xxx --xyz --xxx --xyz
+#
+# Output:
+#
+#   ["--xxx", ""]
+#   ["--xyz", ""]
+#   ["--xxx", ""]
+#   ["--xyz", ""]
+#
+# === Treating Remaining Options as Arguments
+#
+# A option-like token that appears
+# anywhere after the token <tt>--</tt> is treated as an ordinary argument,
+# and is not processed as an option:
+#
+#   $ ruby abbrev.rb --xxx --xyz -- --xxx --xyz
+#
+# Output:
+#
+#   ["--xxx", ""]
+#   ["--xyz", ""]
+#
+# === Option Types
+#
+# Each option definition includes an option type,
+# which controls whether the option takes an argument.
+#
+# File <tt>types.rb</tt>:
+#
+#   :include: ../sample/getoptlong/types.rb
+#
+# Note that an option type has to do with the <em>option argument</em>
+# (whether it is required, optional, or forbidden),
+# not with whether the option itself is required.
+#
+# ==== Option with Required Argument
+#
+# An option of type <tt>GetoptLong::REQUIRED_ARGUMENT</tt>
+# must be followed by an argument, which is associated with that option:
+#
+#   $ ruby types.rb --xxx foo
+#
+# Output:
+#
+#   ["--xxx", "foo"]
+#
+# If the option is not last, its argument is whatever follows it
+# (even if the argument looks like another option):
+#
+#   $ ruby types.rb --xxx --yyy
+#
+# Output:
+#
+#   ["--xxx", "--yyy"]
+#
+# If the option is last, an exception is raised:
+#
+#   $ ruby types.rb
+#   # Raises GetoptLong::MissingArgument
+#
+# ==== Option with Optional Argument
+#
+# An option of type <tt>GetoptLong::OPTIONAL_ARGUMENT</tt>
+# may be followed by an argument, which if given is associated with that option.
+#
+# If the option is last, it does not have an argument:
+#
+#   $ ruby types.rb --yyy
+#
+# Output:
+#
+#   ["--yyy", ""]
+#
+# If the option is followed by another option, it does not have an argument:
+#
+#   $ ruby types.rb --yyy --zzz
+#
+# Output:
+#
+#   ["--yyy", ""]
+#   ["--zzz", ""]
+#
+# Otherwise the option is followed by its argument, which is associated
+# with that option:
+#
+#   $ ruby types.rb --yyy foo
+#
+# Output:
+#
+#   ["--yyy", "foo"]
+#
+# ==== Option with No Argument
+#
+# An option of type <tt>GetoptLong::NO_ARGUMENT</tt> takes no argument:
+#
+#   ruby types.rb --zzz foo
+#
+# Output:
+#
+#   ["--zzz", ""]
+#
+# === ARGV
+#
+# You can process options either with method #each and a block,
+# or with method #get.
+#
+# During processing, each found option is removed, along with its argument
+# if there is one.
+# After processing, each remaining element was neither an option
+# nor the argument for an option.
+#
+# File <tt>argv.rb</tt>:
+#
+#   :include: ../sample/getoptlong/argv.rb
+#
+# Command line:
+#
+#   $ ruby argv.rb --xxx Foo --yyy Bar Baz --zzz Bat Bam
 #
-# GetoptLong allows for POSIX-style options like <tt>--file</tt> as well
-# as single letter options like <tt>-f</tt>
+# Output:
 #
-# The empty option <tt>--</tt> (two minus symbols) is used to end option
-# processing. This can be particularly important if options have optional
-# arguments.
+#   Original ARGV: ["--xxx", "Foo", "--yyy", "Bar", "Baz", "--zzz", "Bat", "Bam"]
+#   ["--xxx", "Foo"]
+#   ["--yyy", "Bar"]
+#   ["--zzz", ""]
+#   Remaining ARGV: ["Baz", "Bat", "Bam"]
 #
-# Here is a simple example of usage:
+# === Ordering
 #
-#     require 'getoptlong'
+# There are three settings that control the way the options
+# are interpreted:
 #
-#     opts = GetoptLong.new(
-#       [ '--help', '-h', GetoptLong::NO_ARGUMENT ],
-#       [ '--repeat', '-n', GetoptLong::REQUIRED_ARGUMENT ],
-#       [ '--name', GetoptLong::OPTIONAL_ARGUMENT ]
-#     )
+# - +PERMUTE+.
+# - +REQUIRE_ORDER+.
+# - +RETURN_IN_ORDER+.
 #
-#     dir = nil
-#     name = nil
-#     repetitions = 1
-#     opts.each do |opt, arg|
-#       case opt
-#         when '--help'
-#           puts <<-EOF
-#     hello [OPTION] ... DIR
+# The initial setting for a new \GetoptLong object is +REQUIRE_ORDER+
+# if environment variable +POSIXLY_CORRECT+ is defined, +PERMUTE+ otherwise.
 #
+# ==== PERMUTE Ordering
+#
+# In the +PERMUTE+ ordering, options and other, non-option,
+# arguments may appear in any order and any mixture.
+#
+# File <tt>permute.rb</tt>:
+#
+#   :include: ../sample/getoptlong/permute.rb
+#
+# Command line:
+#
+#   $ ruby permute.rb Foo --zzz Bar --xxx Baz --yyy Bat Bam --xxx Bag Bah
+#
+# Output:
+#
+#   Original ARGV: ["Foo", "--zzz", "Bar", "--xxx", "Baz", "--yyy", "Bat", "Bam", "--xxx", "Bag", "Bah"]
+#   ["--zzz", ""]
+#   ["--xxx", "Baz"]
+#   ["--yyy", "Bat"]
+#   ["--xxx", "Bag"]
+#   Remaining ARGV: ["Foo", "Bar", "Bam", "Bah"]
+#
+# ==== REQUIRE_ORDER Ordering
+#
+# In the +REQUIRE_ORDER+ ordering, all options precede all non-options;
+# that is, each word after the first non-option word
+# is treated as a non-option word (even if it begins with a hyphen).
+#
+# File <tt>require_order.rb</tt>:
+#
+#   :include: ../sample/getoptlong/require_order.rb
+#
+# Command line:
+#
+#   $ ruby require_order.rb --xxx Foo Bar --xxx Baz --yyy Bat -zzz
+#
+# Output:
+#
+#   Original ARGV: ["--xxx", "Foo", "Bar", "--xxx", "Baz", "--yyy", "Bat", "-zzz"]
+#   ["--xxx", "Foo"]
+#   Remaining ARGV: ["Bar", "--xxx", "Baz", "--yyy", "Bat", "-zzz"]
+#
+# ==== RETURN_IN_ORDER Ordering
+#
+# In the +RETURN_IN_ORDER+ ordering, every word is treated as an option.
+# A word that begins with a hyphen (or two) is treated in the usual way;
+# a word +word+ that does not so begin is treated as an option
+# whose name is an empty string, and whose value is +word+.
+#
+# File <tt>return_in_order.rb</tt>:
+#
+#   :include: ../sample/getoptlong/return_in_order.rb
+#
+# Command line:
+#
+#   $ ruby return_in_order.rb Foo --xxx Bar Baz --zzz Bat Bam
+#
+# Output:
+#
+#   Original ARGV: ["Foo", "--xxx", "Bar", "Baz", "--zzz", "Bat", "Bam"]
+#   ["", "Foo"]
+#   ["--xxx", "Bar"]
+#   ["", "Baz"]
+#   ["--zzz", ""]
+#   ["", "Bat"]
+#   ["", "Bam"]
+#   Remaining ARGV: []
+#
+# === Full Example
+#
+# File <tt>fibonacci.rb</tt>:
+#
+#   :include: ../sample/getoptlong/fibonacci.rb
+#
+# Command line:
+#
+#   $ ruby fibonacci.rb
+#
+# Output:
+#
+#   Option --number is required.
+#   Usage:
+#
+#     -n n, --number n:
+#       Compute Fibonacci number for n.
+#     -v [boolean], --verbose [boolean]:
+#       Show intermediate results; default is 'false'.
+#     -h, --help:
+#       Show this help.
+#
+# Command line:
+#
+#   $ ruby fibonacci.rb --number
+#
+# Raises GetoptLong::MissingArgument:
+#
+#   fibonacci.rb: option `--number' requires an argument
+#
+# Command line:
+#
+#   $ ruby fibonacci.rb --number 6
+#
+# Output:
+#
+#   8
+#
+# Command line:
+#
+#   $ ruby fibonacci.rb --number 6 --verbose
+#
+# Output:
+#   1
+#   2
+#   3
+#   5
+#   8
+#
+# Command line:
+#
+# $ ruby fibonacci.rb --number 6 --verbose yes
+#
+# Output:
+#
+#   --verbose argument must be true or false
+#   Usage:
+#
+#     -n n, --number n:
+#       Compute Fibonacci number for n.
+#     -v [boolean], --verbose [boolean]:
+#       Show intermediate results; default is 'false'.
 #     -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.
-#           EOF
-#         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
+#       Show this help.
 #
 class GetoptLong
+  # Version.
+  VERSION = "0.2.0"
+
   #
   # Orderings.
   #
@@ -111,20 +396,18 @@ class GetoptLong
   class InvalidOption    < Error; end
 
   #
-  # 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:
+  # Returns a new \GetoptLong object based on the given +arguments+.
+  # See {Options}[#class-GetoptLong-label-Options].
   #
-  # GetoptLong::NO_ARGUMENT :: Option does not take an argument.
+  # Example:
   #
-  # GetoptLong::REQUIRED_ARGUMENT :: Option always takes an argument.
+  #   :include: ../sample/getoptlong/simple.rb
   #
-  # GetoptLong::OPTIONAL_ARGUMENT :: Option may or may not take an argument.
+  # Raises an exception if:
   #
-  # 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.
+  # - Any of +arguments+ is not an array.
+  # - Any option name or alias is not a string.
+  # - Any option type is invalid.
   #
   def initialize(*arguments)
     #
@@ -186,54 +469,22 @@ class GetoptLong
     end
   end
 
+  # Sets the ordering; see {Ordering}[#class-GetoptLong-label-Ordering];
+  # returns the new ordering.
   #
-  # 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 given +ordering+ is +PERMUTE+ and environment variable
+  # +POSIXLY_CORRECT+ is defined, sets the ordering to +REQUIRE_ORDER+;
+  # otherwise sets the ordering to +ordering+:
   #
-  # 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.
+  #   options = GetoptLong.new
+  #   options.ordering == GetoptLong::PERMUTE # => true
+  #   options.ordering = GetoptLong::RETURN_IN_ORDER
+  #   options.ordering == GetoptLong::RETURN_IN_ORDER # => true
+  #   ENV['POSIXLY_CORRECT'] = 'true'
+  #   options.ordering = GetoptLong::PERMUTE
+  #   options.ordering == GetoptLong::REQUIRE_ORDER # => true
   #
-  # <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.
+  # Raises an exception if +ordering+ is invalid.
   #
   def ordering=(ordering)
     #
@@ -259,14 +510,16 @@ class GetoptLong
   end
 
   #
-  # Return ordering.
+  # Returns the ordering setting.
   #
   attr_reader :ordering
 
   #
-  # Set options. Takes the same argument as GetoptLong.new.
+  # Replaces existing options with those given by +arguments+,
+  # which have the same form as the arguments to ::new;
+  # returns +self+.
   #
-  # Raises a RuntimeError if option processing has already started.
+  # Raises an exception if option processing has begun.
   #
   def set_options(*arguments)
     #
@@ -338,22 +591,23 @@ class GetoptLong
   end
 
   #
-  # Set/Unset `quiet' mode.
+  # Sets quiet mode and returns the given argument:
+  #
+  # - When +false+ or +nil+, error messages are written to <tt>$stdout</tt>.
+  # - Otherwise, error messages are not written.
   #
   attr_writer :quiet
 
   #
-  # Return the flag of `quiet' mode.
+  # Returns the quiet mode setting.
   #
   attr_reader :quiet
-
-  #
-  # `quiet?' is an alias of `quiet'.
-  #
   alias quiet? quiet
 
   #
-  # Explicitly terminate option processing.
+  # Terminate option processing;
+  # returns +nil+ if processing has already terminated;
+  # otherwise returns +self+.
   #
   def terminate
     return nil if @status == STATUS_TERMINATED
@@ -373,14 +627,14 @@ class GetoptLong
   end
 
   #
-  # Returns true if option processing has terminated, false otherwise.
+  # Returns +true+ if option processing has terminated, +false+ otherwise.
   #
   def terminated?
     return @status == STATUS_TERMINATED
   end
 
   #
-  # Set an error (a protected method).
+  # \Set an error (a protected method).
   #
   def set_error(type, message)
     $stderr.print("#{$0}: #{message}\n") if !@quiet
@@ -397,32 +651,25 @@ class GetoptLong
   protected :set_error
 
   #
-  # Examine whether an option processing is failed.
+  # Returns whether option processing has failed.
   #
   attr_reader :error
-
-  #
-  # `error?' is an alias of `error'.
-  #
   alias error? error
 
   # Return the appropriate error message in POSIX-defined format.
-  # If no error has occurred, returns nil.
+  # If no error has occurred, returns +nil+.
   #
   def error_message
     return @error_message
   end
 
   #
-  # 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.
+  # Returns the next option as a 2-element array containing:
   #
-  # Example: ['--option', 'value']
+  # - The option name (the name itself, not an alias).
+  # - The option value.
   #
-  # Returns nil if the processing is complete (as determined by
-  # STATUS_TERMINATED).
+  # Returns +nil+ if there are no more options.
   #
   def get
     option_name, option_argument = nil, ''
@@ -582,21 +829,32 @@ class GetoptLong
 
     return @canonical_names[option_name], option_argument
   end
+  alias get_option get
 
   #
-  # `get_option' is an alias of `get'.
+  # Calls the given block with each option;
+  # each option is a 2-element array containing:
   #
-  alias get_option get
-
-  # Iterator version of `get'.
+  # - The option name (the name itself, not an alias).
+  # - The option value.
+  #
+  # Example:
+  #
+  #   :include: ../sample/getoptlong/each.rb
   #
-  # 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')
+  # Command line:
   #
-  # The option name is always converted to the first (preferred)
-  # name given in the original options to GetoptLong.new.
+  #    ruby each.rb -xxx Foo -x Bar --yyy Baz -y Bat --zzz
+  #
+  # Output:
+  #
+  #   Original ARGV: ["-xxx", "Foo", "-x", "Bar", "--yyy", "Baz", "-y", "Bat", "--zzz"]
+  #   ["--xxx", "xx"]
+  #   ["--xxx", "Bar"]
+  #   ["--yyy", "Baz"]
+  #   ["--yyy", "Bat"]
+  #   ["--zzz", ""]
+  #   Remaining ARGV: ["Foo"]
   #
   def each
     loop do
@@ -605,9 +863,5 @@ class GetoptLong
       yield option_name, option_argument
     end
   end
-
-  #
-  # `each_option' is an alias of `each'.
-  #
   alias each_option each
 end

data/sample/getoptlong/abbrev.rb

@@ -0,0 +1,9 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', GetoptLong::NO_ARGUMENT],
+  ['--xyz', GetoptLong::NO_ARGUMENT]
+)
+options.each do |option, argument|
+  p [option, argument]
+end

data/sample/getoptlong/aliases.rb

@@ -0,0 +1,8 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', '-x', '--aaa', '-a', '-p', GetoptLong::NO_ARGUMENT]
+)
+options.each do |option, argument|
+  p [option, argument]
+end

data/sample/getoptlong/argv.rb

@@ -0,0 +1,12 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
+  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--zzz', GetoptLong::NO_ARGUMENT]
+)
+puts "Original ARGV: #{ARGV}"
+options.each do |option, argument|
+  p [option, argument]
+end
+puts "Remaining ARGV: #{ARGV}"

data/sample/getoptlong/each.rb

@@ -0,0 +1,12 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', '-x', GetoptLong::REQUIRED_ARGUMENT],
+  ['--yyy', '-y', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--zzz', '-z',GetoptLong::NO_ARGUMENT]
+)
+puts "Original ARGV: #{ARGV}"
+options.each do |option, argument|
+  p [option, argument]
+end
+puts "Remaining ARGV: #{ARGV}"

data/sample/getoptlong/fibonacci.rb

@@ -0,0 +1,62 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--number', '-n', GetoptLong::REQUIRED_ARGUMENT],
+  ['--verbose', '-v', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--help', '-h', GetoptLong::NO_ARGUMENT]
+)
+
+def help(status = 0)
+  puts <<~HELP
+    Usage:
+
+      -n n, --number n:
+        Compute Fibonacci number for n.
+      -v [boolean], --verbose [boolean]:
+        Show intermediate results; default is 'false'.
+      -h, --help:
+        Show this help.
+  HELP
+  exit(status)
+end
+
+def print_fibonacci (number)
+  return 0 if number == 0
+  return 1 if number == 1 or number == 2
+  i = 0
+  j = 1
+  (2..number).each do
+    k = i + j
+    i = j
+    j = k
+    puts j if @verbose
+  end
+  puts j unless @verbose
+end
+
+options.each do |option, argument|
+  case option
+  when '--number'
+    @number = argument.to_i
+  when '--verbose'
+    @verbose = if argument.empty?
+      true
+    elsif argument.match(/true/i)
+      true
+    elsif argument.match(/false/i)
+      false
+    else
+      puts '--verbose argument must be true or false'
+      help(255)
+    end
+  when '--help'
+    help
+  end
+end
+
+unless @number
+  puts 'Option --number is required.'
+  help(255)
+end
+
+print_fibonacci(@number)

data/sample/getoptlong/permute.rb

@@ -0,0 +1,12 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
+  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--zzz', GetoptLong::NO_ARGUMENT]
+)
+puts "Original ARGV: #{ARGV}"
+options.each do |option, argument|
+  p [option, argument]
+end
+puts "Remaining ARGV: #{ARGV}"

data/sample/getoptlong/require_order.rb

@@ -0,0 +1,13 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
+  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--zzz', GetoptLong::NO_ARGUMENT]
+)
+options.ordering = GetoptLong::REQUIRE_ORDER
+puts "Original ARGV: #{ARGV}"
+options.each do |option, argument|
+  p [option, argument]
+end
+puts "Remaining ARGV: #{ARGV}"

data/sample/getoptlong/return_in_order.rb

@@ -0,0 +1,13 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
+  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--zzz', GetoptLong::NO_ARGUMENT]
+)
+options.ordering = GetoptLong::RETURN_IN_ORDER
+puts "Original ARGV: #{ARGV}"
+options.each do |option, argument|
+  p [option, argument]
+end
+puts "Remaining ARGV: #{ARGV}"

data/sample/getoptlong/simple.rb

@@ -0,0 +1,7 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--number', '-n', GetoptLong::REQUIRED_ARGUMENT],
+  ['--verbose', '-v', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--help', '-h', GetoptLong::NO_ARGUMENT]
+)

data/sample/getoptlong/types.rb

@@ -0,0 +1,10 @@
+require 'getoptlong'
+
+options = GetoptLong.new(
+  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
+  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
+  ['--zzz', GetoptLong::NO_ARGUMENT]
+)
+options.each do |option, argument|
+  p [option, argument]
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: getoptlong
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yukihiro Matsumoto
-autorequire: 
-bindir: exe
+autorequire:
+bindir: bin
 cert_chain: []
-date: 2019-11-06 00:00:00.000000000 Z
+date: 2022-12-05 00:00:00.000000000 Z
 dependencies: []
 description: GetoptLong for Ruby
 email:
@@ -17,6 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
 - Gemfile
 - LICENSE.txt
@@ -26,14 +28,24 @@ files:
 - bin/setup
 - getoptlong.gemspec
 - lib/getoptlong.rb
-- lib/getoptlong/version.rb
+- sample/getoptlong/abbrev.rb
+- sample/getoptlong/aliases.rb
+- sample/getoptlong/argv.rb
+- sample/getoptlong/each.rb
+- sample/getoptlong/fibonacci.rb
+- sample/getoptlong/permute.rb
+- sample/getoptlong/require_order.rb
+- sample/getoptlong/return_in_order.rb
+- sample/getoptlong/simple.rb
+- sample/getoptlong/types.rb
 homepage: https://github.com/ruby/getoptlong
 licenses:
+- Ruby
 - BSD-2-Clause
 metadata:
   homepage_uri: https://github.com/ruby/getoptlong
   source_code_uri: https://github.com/ruby/getoptlong
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -48,8 +60,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.4.0.dev
+signing_key:
 specification_version: 4
 summary: GetoptLong for Ruby
 test_files: []

data/lib/getoptlong/version.rb

@@ -1,3 +0,0 @@
-class GetoptLong
-  VERSION = "0.1.0"
-end