options_by_example 3.3.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ced46483d8abae62122bb45cd0d4753408c4d93e08405a3409583ec9fcfb477
-  data.tar.gz: e8484baa8976c72154fb2da2509482d985501c08960e7e67fdf04731e307787b
+  metadata.gz: 27abecec1f4038208d60c4a623de4664241e4b88db67b8e15918ba8d2e8c4ad3
+  data.tar.gz: e57931971bc3f57ac7a59fd9233f338530afc60d2a1f507a9a2344e10d9f5ab9
 SHA512:
-  metadata.gz: 22f691bf1fc36e14868996b32b15de17a1760add666aa046e6dc57fb0e09f8dad75c7c18260255930c88ea3e56a1c994285dd320a659e6c9ee92fc4ae45d3f10
-  data.tar.gz: 1d54dca36e9829f2018af7493586e18ca7d590819d112e28482c93684212adc4ccd53e5c5183d49885c927f4ddb9e23c0654874ddbceb0e617f95c6fc6b96258
+  metadata.gz: 7513e6747f9269e9618e4a4e277560fcbb7741663cc01a3c5767b0a30c52277cd67590c19b21e2eb79d42bc6678ad329d465b1d0b75f2da6079d12cc9978fe52
+  data.tar.gz: 1a4bfc340b15a0f63115e9025e4be96f37fa0d5a0808bbe81d44438c97648159154b41dc8380b94fe8aeb1a4ab5d5d7b6448572e6741ecf8a5e8bdf3d75166a3

data/README.md

@@ -45,7 +45,7 @@ __END__
 Establishes a network connection to a designated host and port, enabling
 users to assess network connectivity and diagnose potential problems.
 
-Usage: connect [options] [mode] host port
+Usage: connect [options] host port [mode]
 
 Options:
   -s, --secure        Establish a secure connection (SSL/TSL)
@@ -54,8 +54,8 @@ Options:
   -t, --timeout NUM   Set connection timeout in seconds
 
 Arguments:
-  [mode]              Optional connection mode (active or passive)
   host                The target host to connect to (e.g., example.com)
   port                The target port to connect to (e.g., 80)
+  [mode]              Optional connection mode (active or passive)
 ```
 

data/lib/options_by_example/commandline_parser.rb

@@ -17,6 +17,7 @@ class OptionsByExample
     def initialize(usage)
       @argument_names = usage.argument_names
       @default_values = usage.default_values
+      @ends_with_optional_vararg = usage.ends_with_optional_vararg
       @option_names = usage.option_names
 
       @argument_values = @default_values.dup
@@ -36,25 +37,34 @@ class OptionsByExample
         current << each
       end
 
-      raise_if_help_option
+      exit_if_help_option
       unpack_combined_shorthand_options
       expand_dash_number_to_dash_n_option
       raise_if_unknown_options
       parse_options
+      coerce_num_date_time_etc
 
       validate_number_of_arguments
-      parse_required_arguments
-      parse_optional_arguments
+      parse_positional_arguments
+      special_case_if_ends_with_optional_vararg
 
-      raise "Internal error: unreachable state" unless @remainder.empty?
+      # :nocov:
+      raise %{unreachable given we check number of arguments} unless @remainder.empty?
+      # :nocov:
     end
 
     private
 
-    def raise_if_help_option
+    def exit_if_help_option
       @slices.each do |option, *args|
         case option
         when '-h', '--help'
+          if args.first == 'debug!'
+            puts "@argument_names = #{@argument_names.inspect}"
+            puts "@default_values = #{@default_values.inspect}"
+            puts "@ends_with_optional_vararg = #{@ends_with_optional_vararg}"
+            puts "@option_names = #{@option_names.inspect}"
+          end
           raise PrintUsageMessage
         end
       end
@@ -114,25 +124,7 @@ class OptionsByExample
 
         if argument_name
           raise "Expected argument for option '#{option}', got none" if args.empty?
-          value = args.shift
-
-          begin
-            case argument_name
-            when 'NUM'
-              expected_type = 'an integer value'
-              value = Integer value
-            when 'DATE'
-              expected_type = 'a date (e.g. YYYY-MM-DD)'
-              value = Date.parse value
-            when 'TIME'
-              expected_type = 'a timestamp (e.g. HH:MM:SS)'
-              value = Time.parse value
-            end
-          rescue ArgumentError
-            raise "Invalid argument \"#{value}\" for option '#{option}', please provide #{expected_type}"
-          end
-
-          @argument_values[option_name] = value
+          @argument_values[option_name] = args.shift
           @option_took_argument = option
         else
           @option_took_argument = nil
@@ -142,57 +134,99 @@ class OptionsByExample
       end
     end
 
+    def coerce_num_date_time_etc
+      @option_names.each do |option, (each, argument_name)|
+        next unless value = @argument_values[each]
+        begin
+          case argument_name
+          when 'NUM'
+            expected_type = 'an integer value'
+            @argument_values[each] = Integer value
+          when 'DATE'
+            expected_type = 'a date (e.g. YYYY-MM-DD)'
+            @argument_values[each]  = Date.parse value
+          when 'TIME'
+            expected_type = 'a timestamp (e.g. HH:MM:SS)'
+            @argument_values[each]  = Time.parse value
+          end
+        rescue ArgumentError
+          raise "Invalid argument \"#{value}\" for option '#{option}', please provide #{expected_type}"
+        end
+      end
+    end
+
     def validate_number_of_arguments
-      count_optional_arguments = @argument_names.values.count(:optional)
-      count_required_arguments = @argument_names.values.count(:required)
-      count_vararg_arguments = @argument_names.values.count(:vararg)
+      # ASSUME: either varargs or optional arguments, never both. That
+      # constraint is guaranteed upstream. Here, we just count
 
-      min_length = count_required_arguments + count_vararg_arguments
-      max_length = count_required_arguments + count_optional_arguments
+      count_required = @argument_names.values.count(:required)
+      count_vararg = @argument_names.values.count(:vararg)
+      count_optional = @argument_names.values.count(:optional)
 
-      if @remainder.size > max_length && count_vararg_arguments == 0
-        range = [min_length, max_length].uniq.join(?-)
-        raise "Expected #{range} arguments, but received too many"
-      end
+      min_length = count_required + count_vararg
+      max_length = count_required + count_optional
+      max_length = nil if @ends_with_optional_vararg
+      max_length = nil if count_vararg > 0
 
-      if @remainder.size < min_length
-        too_few = @remainder.empty? ? 'none' : (@remainder.size == 1 ? 'only one' : 'too few')
-        remark = " (considering #{@option_took_argument} takes an argument)" if @option_took_argument
-        raise "Expected #{min_length} required arguments, but received #{too_few}#{remark}"
-      end
-    end
+      unless (min_length..max_length) === @remainder.size
 
-    def parse_required_arguments
-      if @argument_names.values.include?(:vararg)
-        remaining_arguments = @argument_names.length
-        @argument_names.each do |argument_name, arity|
-          raise "unreachable" if @remainder.empty?
-          remaining_arguments -= 1
-          case arity
-          when :required
-            @argument_values[argument_name] = @remainder.shift
-          when :vararg
-            @argument_values[argument_name] = @remainder.shift(@remainder.length - remaining_arguments)
-          else
-            raise "unreachable"
-          end
+        if max_length.nil?
+          msg = "Expected #{min_length} or more arguments,"
+        elsif max_length > min_length
+          msg = "Expected #{min_length}-#{max_length} arguments,"
+        else
+          msg = "Expected #{min_length} arguments,"
+        end
+
+        if @remainder.empty?
+          msg += " but received none"
+        elsif @remainder.size == 1 && min_length > 1
+          msg += " but received only one"
+        elsif @remainder.size < min_length
+          msg += " but received too few"
+        elsif max_length && @remainder.size > max_length
+          msg += " but received too many"
+        # :nocov:
+        else
+          raise %{unreachable given the range check above}
+        # :nocov:
         end
-        return
-      end
 
-      @argument_names.reverse_each do |argument_name, arity|
-        break if arity == :optional
-        raise "unreachable" if @remainder.empty?
-        @argument_values[argument_name] = @remainder.pop
+        if @option_took_argument
+          msg += " (considering #{@option_took_argument} takes an argument)"
+        end
+
+        raise msg
       end
     end
 
-    def parse_optional_arguments
+    def parse_positional_arguments
+      remaining_arguments = @argument_names.length
       @argument_names.each do |argument_name, arity|
-        break unless arity == :optional
-        break if @remainder.empty?
-        @argument_values[argument_name] = @remainder.shift
+        remaining_arguments -= 1
+        case arity
+        when :required
+          @argument_values[argument_name] = @remainder.shift
+        when :vararg
+          @argument_values[argument_name] = @remainder.shift(@remainder.length - remaining_arguments)
+        when :optional
+          break if @remainder.empty?
+          @argument_values[argument_name] = @remainder.shift
+        # :nocov:
+        else
+          raise %{unreachable given these are all possible values}
+        # :nocov:
+        end
       end
     end
+
+    def special_case_if_ends_with_optional_vararg
+      return unless @ends_with_optional_vararg
+      final_argument_name = @argument_names.keys.last
+      @argument_values[final_argument_name] = [
+        *@argument_values[final_argument_name],
+        *@remainder.shift(@remainder.length),
+      ]
+    end
   end
 end

data/lib/options_by_example/usage_specification.rb

@@ -7,6 +7,7 @@ class OptionsByExample
     attr_reader :message
     attr_reader :argument_names
     attr_reader :default_values
+    attr_reader :ends_with_optional_vararg
     attr_reader :option_names
 
     def initialize(text)
@@ -34,14 +35,20 @@ class OptionsByExample
         tokens.shift
       end
 
+      while /^(\w+)( ?\.\.\.)?$/ === tokens.first
+        vararg_if_dotted = $2 ? :vararg : :required
+        @argument_names[sanitize $1] = vararg_if_dotted
+        tokens.shift
+      end
+
       while /^\[(\w+)\]$/ === tokens.first
         @argument_names[sanitize $1] = :optional
         tokens.shift
       end
 
-      while /^(\w+)( ?\.\.\.)?$/ === tokens.first
-        vararg_if_dotted = $2 ? :vararg : :required
-        @argument_names[sanitize $1] = vararg_if_dotted
+      if /^\[(\w+) ?\.\.\.\]$/ === tokens.first
+        @argument_names[sanitize $1] = :optional
+        @ends_with_optional_vararg = true
         tokens.shift
       end
 

data/lib/options_by_example/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class OptionsByExample
-  VERSION = '3.3.0'
+  VERSION = '4.0.0'
 end
 
 
@@ -11,6 +11,17 @@ __END__
 # Minor version bump when backward-compatible changes or enhancements
 # Patch version bump when backward-compatible bug fixes, security updates etc
 
+4.0.0
+  - Remove support for leading optional arguments (breaking change)
+  - Add support for trailing optional arguments
+  - Add support for optional vararg argument
+
+3.4.0
+  - Ensure default values are coerced too
+  - Print error message to stdout
+  - New method #expect_at_most_one_except (experimental)
+  - New method #expect_at_most_one_of (experimental)
+
 3.3.0
   - Expand dash-number to dash-n option
   - Complete support for inline specification of options

data/lib/options_by_example.rb

@@ -28,8 +28,18 @@ class OptionsByExample
     puts @usage_spec.message
     exit 0
   rescue RuntimeError => err
-    puts "ERROR: #{err.message}"
-    exit 1
+    abort "ERR: #{err.message}"
+  end
+
+  def expect_at_most_one_except(*extra_options)
+    expect_at_most_one_of *(@options.keys - extra_options)
+  end
+
+  def expect_at_most_one_of(*mutually_exclusive_options)
+    provided_options = @options.keys & mutually_exclusive_options
+    if provided_options.length > 1
+      abort "ERR: Found more than one mutually-exclusive option {#{provided_options.join ', '}}"
+    end
   end
 
   def fetch(*args, &block)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: options_by_example
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Adrian Kuhn
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-02-01 00:00:00.000000000 Z
+date: 2026-03-16 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: