opt-simple 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3396db6ba0716fea38377347f6831c74c372324523123b0934c8356796b8b230
-  data.tar.gz: 60ef677dc68de3ea9459b8b6d428e2a235178187fddb4850405dd9567e3055cc
+  metadata.gz: 57cca5d40e69cf2f9a914290d54ca098293e06a122cfecbe0170045de81a3c2a
+  data.tar.gz: b069da5060d12936a2d2022053d414c3ecf84708ac62d530aae91d675a72f593
 SHA512:
-  metadata.gz: 85f93bd1282c725161c2db2106ff7f3ca19fe1b97f86313b73b0cd000540b8e2f5832b6523aaf087b59ef977921fe7e6aba6a193a852827d8a47635fef77f972
-  data.tar.gz: 16a47cde44882e07c1ae688db17be9e6df212f34b3227d958510b08f7e79e47bc0346f3e0a19109c75af4aa87af4237eba77204f8e180da35c6660a5b8c8ec6e
+  metadata.gz: 61a13e28947dc8ecf33690b7b6013692849fc6075136814fb831facb6cb82bdc0ae0fe90247f525e35b6ff8644cd3cdb98bd6f37d4cdbf8a715ea8e7335bd4b4
+  data.tar.gz: 4694df6658044f29a6c0dd2ad616bb2f0cc3ed636db884fe521f601139e4bdb2a0a4ca98a8a50063881d43b30048852a93f991d809169796ccf7152d0c4bca34

data/README.md

@@ -34,7 +34,7 @@ See OptSimple for the API specification
 It is recommended to install OptSimple using RubyGems:
 
 ```
- $ sudo gem install opt-simple
+ $ gem install opt-simple
 ```
 
 ## Examples
@@ -49,7 +49,7 @@ It is recommended to install OptSimple using RubyGems:
    :range => [5,10]
  }
  
- opts = OptSimple.new(defaults).parse_opts! do 
+ opts = OptSimple.new(defaults: defaults).parse_opts! do 
    argument %w[-i --infile], "Infile, multiple allowed", "FILE" do | arg |
      accumulate_opt arg
    end
@@ -108,27 +108,27 @@ It is recommended to install OptSimple using RubyGems:
  puts "Things: #{opts.things.inspect}"
 ```
 
-```
 Which prints out an automatic usage statement:
+```
  Usage: opt_ex.rb [options]
- 
+
    MANDATORY ARGS:
-     -i, --infile FILE                           Infile, multiple allowed
- 
+     -i, --infile FILE                      Infile, multiple allowed
+
    OPTIONS:
-     -d, --debug                                 debug mode
- 
-     -m, --cowbell, --morecowbell                I've got a fever, and this is the only prescription.
- 
-     -n, -num, --num-values VAL                  The answer to everything
- 
-     -p, --pattern, --glob-pattern PATTERN       glob pattern (default is '*')
- 
-         --range ARG                             range: min,max (both >0) (default is '[5, 10]')
+     -d, --debug                            debug mode
 
-         -t, --things THINGS                         Some things - variable number allowed 
+     -m, --cowbell, --morecowbell           I've got a fever, and this is the only prescription.
 
-     -h, --help                                  (for this help message)
+     -n, -num, --num-values VAL             The answer to everything (default is '42')
+
+     -p, --pattern, --glob-pattern PATTERN  glob pattern (default is '*')
+
+         --range ARG                        range: min,max (both >0) (default is '5,10')
+
+     -t, --things THINGS                    Some things - variable number allowed
+
+     -h, --help                             (for this help message)
 ```
 ### A very simple example with no error checking. Use at your own risk!
 ``` ruby
@@ -138,7 +138,7 @@ Which prints out an automatic usage statement:
  'max' => 40
  } 
  
- options = OptSimple.new(defaults).parse_opts! 
+ options = OptSimple.new(defaults: defaults).parse_opts! 
  
  puts "Options"
  puts options
@@ -165,7 +165,7 @@ Which prints out an automatic usage statement:
    "max" => 10
  }
  
- options = OptSimple.new(defaults).parse_opts! do 
+ options = OptSimple.new(defaults: defaults).parse_opts! do 
    banner "USAGE: #{$0}"
    summary "Show how to set a banner and summary."
  
@@ -246,7 +246,7 @@ Which prints out an automatic usage statement:
    option %w[-p --pattern --glob-pattern], "glob pattern","PATTERN"
  end
  
- os.register_opts({num: 7}) do 
+ os.register_opts(defaults: {num: 7}) do 
    option %w[-n -num --num-values],"Number of val","VAL" do |arg|
      set_opt arg.to_i
    end
@@ -283,7 +283,7 @@ Which prints out an automatic usage statement:
 
  # Note that b/c we define option [--odd] and [--evens] _after_ the max-out flag, 
  # they will override the max-out setting. 
- opts = OptSimple.new(defaults).parse_opts! do | opt_obj |
+ opts = OptSimple.new(defaults: defaults).parse_opts! do | opt_obj |
    flag %w[-m --max-out], "Maximize evens and odds." do 
      opt_obj.odd_val = allowed_odds.last
      opt_obj.even_val = allowed_evens.last
@@ -305,6 +305,24 @@ Which prints out an automatic usage statement:
  puts "Options"
  puts opts
 ```
+## Errors
+
+Parsing problems raise a subclass of `OptSimple::Error` (a `StandardError`):
+`MissingArgument`, `InvalidOption` or `ParameterUsageError`, and `error` inside a
+parameter block raises `OptSimple::Error`. The `message` is the reason followed by
+the usage statement; `reason` and `usage` are also available on their own.
+
+```ruby
+begin
+  opts = OptSimple.new.parse_opts! { argument '--model', 'Model name', 'MODEL' }
+rescue OptSimple::Error => e
+  abort e.message # or: abort "error: #{e.reason}"
+end
+```
+
+A registered switch is never taken as a value, so `--model --num 4` is reported
+as a missing value for `--model` (negative numbers like `--num -1` still work).
+
 ## Questions and/or Comments
   
 email [Ethan Stryker](mailto:e.stryker@gmail.com])

data/lib/opt_simple.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 =begin rdoc
 
 = OptSimple provides a very simple interface to command line parsing. 
@@ -91,12 +93,6 @@ class OptSimple
       # go through the  registered parameters, and pull out 
       # the specified parms from @arg
 
-      # first look for a call for help
-      unless (help_strings & @args).empty?
-	$stdout.puts self.to_s
-	exit(0)
-      end
-      
       mandatory_check = mandatory_opts.map {|m| m.switches}
       
       positional_args = []
@@ -104,15 +100,28 @@ class OptSimple
 	#remove the '--', but don't include it w/ positional arguments
 	positional_args = @args.slice!(loc..-1)[1..-1]
       end
+
+      # look for a call for help, but not in the positional args after '--'
+      unless (help_strings & @args).empty?
+	$stdout.puts self.to_s
+	exit(0)
+      end
       
-      # Handle the case where a user specifies --foo=bar, or --foo=bar,baz
-      equal_args = @args.find_all {|arg| arg.include?('=') }
-      @args.delete_if {|arg| arg.include?('=') }
-      equal_args.each do | e |
-	switch,list = e.split('=')
-	@args << switch
-	list.split(',').each {|val| @args << val }
+      # Handle the case where a user specifies --foo=bar, or --foo=bar,baz.
+      # Only switch-looking args are split, and they are expanded in place so
+      # values like 'a=b' and the order of positional args are left alone.
+      # replace (rather than reassign) keeps parse_opts! destructive on ARGV.
+      expanded = @args.flat_map do | arg |
+	if (m = arg.match(/\A(-[^=]+)=(.*)\z/m))
+	  [m[1], *m[2].split(',')]
+	else
+	  arg
+	end
       end
+      @args.replace(expanded)
+
+      # a value that is itself a registered switch means the real value is missing
+      all_switches = @parameters.flat_map(&:switches)
       
       # now actually parse the args, and call all the stored up blocks from the options
       @parameters.each do | parm |
@@ -152,11 +161,16 @@ class OptSimple
 	    if parm.block.arity > 0 and	(pieces.length < parm.block.arity) # or # pieces.any? {|p| p.start_with?('-')})
 	      raise OptSimple::ParameterUsageError.new "Not enough args following #{intersection}",self 
 	    end
+
+	    # but a registered switch is never a value: '--model --num 4' is a missing value
+	    if (clash = pieces.find {|p| all_switches.include?(p) })
+	      raise OptSimple::ParameterUsageError.new "Missing value for #{intersection.join(' OR ')} (found switch #{clash})",self
+	    end
 	    
 	    begin
 	      parm.instance_exec(*pieces,&parm.block)
 	    rescue OptSimple::Error => e
-	      raise OptSimple::Error.new e.message,self
+	      raise e.class.new(e.reason,self)
 	    end
 	  end
 	  @results.merge! parm.param_options
@@ -246,7 +260,7 @@ class OptSimple
       parm.set_opt @defaults[intersection.first]
       @results.merge! parm.param_options
     elsif intersection.length > 1
-      raise OptSimple::Error "Clashes in the defaults for #{parm.switches}"
+      raise OptSimple::Error.new("Clashes in the defaults for #{parm.switches}",self)
     end
     
     add_parameter(parm)
@@ -272,7 +286,7 @@ class OptSimple
   # returns the automatic usage statement
   def to_s
     if @help.empty?
-      help_str = ""
+      help_str = +""
       
       help_str << "  MANDATORY ARGS:\n" unless mandatory_opts.empty?
       mandatory_opts.each do | parm |
@@ -293,7 +307,9 @@ class OptSimple
 	elsif @defaults[intersection.first].nil?
 	  help_str << " (default is 'nil')\n\n"
 	else
-	  help_str << " (default is '#{@defaults[intersection.first]}')\n\n"
+	  default = @defaults[intersection.first]
+	  default = default.join(',') if default.is_a?(Array)
+	  help_str << " (default is '#{default}')\n\n"
 	end
       end
       help_str << "  SUMMARY:\n\n    #{@summary}\n\n" unless @summary.empty?
@@ -359,24 +375,23 @@ class OptSimple
     end
 
     def switch_len #:nodoc:
-      @switches.join(', ').length 
+      switch_str.length
     end
 
+    # Short switches first, then the rest in the order given. Without a short
+    # switch, indent so long switches line up under '-x, --long'.
+    # (Build a new string: the switches may be frozen literals.)
     def switch_str #:nodoc:
       short_parms = @switches.find_all {|st| st.start_with?('-') and st.length == 2 and st[1] != '-'} 
-      long_parms = @switches.find_all {|st| st.start_with?('--') or (st.start_with?('-') and st.length > 2)} 
-      other_parms = @switches.find_all {|st| not st.start_with?('-')}
+      other_parms = @switches - short_parms
       
-      sh_str = short_parms.empty? ?  " " * 4 : short_parms.first
-      long_str = long_parms.join(', ') + other_parms.join(', ')
-      sh_str << ', ' unless sh_str =~/^\s+$/ or long_str.empty?
-
-      sh_str + long_str
+      indent = short_parms.empty? ? " " * 4 : ""
+      indent + (short_parms + other_parms).join(', ')
     end
 
     # a single line that will be put in the overall usage string
     def help_str(switch_len)
-      "    %-#{switch_len}s"  % self.switch_str + " \t#{@help}"
+      "    %-#{switch_len}s" % self.switch_str + "  #{@help}"
     end
 
     # A shortcut for raising an OptSimple::Error exception
@@ -436,7 +451,6 @@ class OptSimple
   # leading '-'s removed) will be used as keys in the Result 
   # and the values set to the arg following the switch on the CL.
   class Option < Parameter
-    attr_reader = :metavar
     def initialize(switches,help="",metavar="ARG",&block)
       super(switches,help,&block)
       @metavar = metavar
@@ -447,13 +461,8 @@ class OptSimple
       @first_call = true # use this so we can accumulate non-defaults
     end
 
-    def switch_len #:nodoc:
-      metavar_space = @metavar.empty? ? 0 : @metavar.length + 1 
-      super + metavar_space
-    end
-
     def switch_str #:nodoc:
-      super + " #{@metavar}"
+      @metavar.empty? ? super : super + " #{@metavar}"
     end
 
     # append val to the parameter list
@@ -481,10 +490,15 @@ class OptSimple
     def mandatory?; true; end
   end
 
-  # A general error in the options
-  class Error < Exception
-    def initialize(string,option_obj=nil)
-      super("#{string}\n#{option_obj.to_s}")
+  # A general error in the options. The message is the reason followed by the
+  # usage statement; both are also available separately.
+  class Error < StandardError
+    attr_reader :reason, :usage
+
+    def initialize(string=nil,option_obj=nil)
+      @reason = string.to_s
+      @usage = option_obj.to_s
+      super("#{@reason}\n#{@usage}")
       set_backtrace []
     end
   end
@@ -583,7 +597,7 @@ class OptSimple
 
     # a hash looking return string.
     def to_s
-      ret = ""
+      ret = +""
       aliases.each do | a |
 	ret << "#{a}=>#{@inside_hash[a]},"
       end

data/test/test_regressions.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Regression tests for bugs found in 1.0.0. The magic comment above matters:
+# switch strings below are frozen, as they are in most modern Ruby files.
+require 'stringio'
+require 'opt_simple'
+require 'test/unit'
+require 'test_unit_extensions'
+
+class TestRegressions < Test::Unit::TestCase
+
+  def parse(args, defaults: {}, &block)
+    OptSimple.new(defaults: defaults, args: args).parse_opts!(&block)
+  end
+
+  # --- frozen switch strings -------------------------------------------------
+
+  must "build the usage statement when switches are frozen strings" do
+    os = OptSimple.new(args: [])
+    os.register_opts { option %w[-n --num], "a number", "N"; flag %w[-v --verbose] }
+    assert_nothing_raised { os.to_s }
+    assert_match(/-n, --num N/, os.to_s)
+    assert_match(/-v, --verbose/, os.to_s)
+  end
+
+  must "report a missing argument, not a FrozenError, when switches are frozen" do
+    assert_raise(OptSimple::MissingArgument) { parse([]) { argument %w[-i --infile] } }
+  end
+
+  must "leave the caller's switch strings unchanged after building usage" do
+    switches = %w[-n --num]
+    os = OptSimple.new(args: [])
+    os.register_opts { option switches }
+    os.to_s
+    assert_equal %w[-n --num], switches
+  end
+
+  must "show every short switch in the usage statement" do
+    os = OptSimple.new(args: [])
+    os.register_opts { flag %w[-v -V --verbose] }
+    assert_match(/-v, -V, --verbose/, os.to_s)
+  end
+
+  # --- '=' handling --------------------------------------------------------------
+
+  must "not treat a value containing '=' as a switch" do
+    o = parse(%w[--model a=b]) { option '--model' }
+    assert_equal 'a=b', o['model']
+    assert_equal [], o.positional_args
+  end
+
+  must "keep everything after the first '=' in --switch=value" do
+    o = parse(%w[--filter=key=val]) { option '--filter' }
+    assert_equal 'key=val', o['filter']
+  end
+
+  must "let the last repeated option win whether or not it uses '='" do
+    # 1.0.0 moved '=' args to the end, so '--a=1' was applied last
+    o = parse(%w[--a=1 --a 2]) { option '--a' }
+    assert_equal '2', o['a']
+  end
+
+  # --- switches used as values ---------------------------------------------------
+
+  must "raise a usage error when a switch is followed by another switch instead of a value" do
+    e = assert_raise(OptSimple::ParameterUsageError) do
+      parse(%w[--model --num 4]) { option '--model'; option '--num' }
+    end
+    assert_match(/--model.*--num/, e.reason)
+  end
+
+  # guard: the check above must not reject negative numbers
+  must "still allow negative numbers as values" do
+    o = parse(%w[--num -1]) { option('--num') { |v| set_opt v.to_i } }
+    assert_equal(-1, o['num'])
+  end
+
+  # --- error class ---------------------------------------------------------------
+
+  must "raise errors a plain rescue can catch" do
+    caught = begin
+      parse([]) { argument '--model' }
+    rescue => e
+      e
+    end
+    assert_kind_of OptSimple::MissingArgument, caught
+    assert_kind_of StandardError, caught
+  end
+
+  must "expose the reason and the usage statement separately" do
+    e = assert_raise(OptSimple::MissingArgument) { parse([]) { argument '--model' } }
+    assert_equal 'Must set the following parameters: --model', e.reason
+    assert_match(/\AUsage:/, e.usage)
+    assert_equal "#{e.reason}\n#{e.usage}", e.message
+  end
+
+  must "keep the error subclass and add usage when a block calls error" do
+    e = assert_raise(OptSimple::Error) do
+      parse(%w[--num x]) { option('--num') { |v| error "--num must be a number" } }
+    end
+    assert_equal '--num must be a number', e.reason
+    assert_match(/--num/, e.usage)
+  end
+
+  must "raise OptSimple::Error when two defaults name the same option" do
+    assert_raise(OptSimple::Error) do
+      parse([], defaults: { 'num-val' => 1, num_val: 2 }) { option '--num-val' }
+    end
+  end
+
+  # --- help ----------------------------------------------------------------------
+
+  must "not show help for --help after '--'" do
+    o = parse(%w[-- --help]) { option '--model' }
+    assert_equal %w[--help], o.positional_args
+  end
+
+  # guard: moving the help check after the '--' split must not break help
+  must "show help and exit for --help before '--'" do
+    out = StringIO.new
+    begin
+      $stdout = out
+      assert_raise(SystemExit) { parse(%w[--help --]) { option '--model' } }
+    ensure
+      $stdout = STDOUT
+    end
+    assert_match(/--model/, out.string)
+  end
+
+  must "line up the help descriptions in one column" do
+    os = OptSimple.new(args: [])
+    os.register_opts do
+      argument %w[-i --infile], "infile", "FILE"
+      option '--a-much-longer-option-name', "long one", "VAL"
+      flag '-v', "verbose"
+    end
+    lines = os.to_s.lines.grep(/infile$|long one$|verbose$/)
+    assert_equal 3, lines.size
+    columns = lines.map { |l| l.index(/infile$|long one$|verbose$/) }
+    assert_equal 1, columns.uniq.size, os.to_s
+  end
+
+  must "show array defaults the way they are typed on the command line" do
+    os = OptSimple.new(defaults: { tasks: %w[a b] }, args: [])
+    os.register_opts { option('--tasks') { |*t| set_opt t } }
+    assert_match(/default is 'a,b'/, os.to_s)
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: opt-simple
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ethan Stryker
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: "  Parameter specification, validity checking and argument transformations
   \n  can be put in one place, default parameters are easily set, and an \n  automatic
@@ -25,12 +24,13 @@ files:
 - lib/test_unit_extensions.rb
 - test/test_arglist.rb
 - test/test_help.rb
+- test/test_regressions.rb
 - test/test_return.rb
 - test/test_usage.rb
-homepage: http://opt-simple.rubyforge.org/
-licenses: []
+homepage: https://github.com/estryker/opt-simple
+licenses:
+- MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -45,8 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A simple and elegant command line option parser.
 test_files: []