options_by_example 3.4.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beeaa2ae22a04cfe49102108f616bad5d3fb63b00156bb34647774ba07c8def0
-  data.tar.gz: e2af434e1812a6244c276bea7b00b52b97411927ccc207e843f4866e64356d08
+  metadata.gz: 27abecec1f4038208d60c4a623de4664241e4b88db67b8e15918ba8d2e8c4ad3
+  data.tar.gz: e57931971bc3f57ac7a59fd9233f338530afc60d2a1f507a9a2344e10d9f5ab9
 SHA512:
-  metadata.gz: fca827e7190634ca8382ff90d074a276fd4367a609fad77b3d58a8488f85b97e3e8493fe2a717fd9a9aff3fefdde4315058c1512addaf4b1d7663f1a2dc201db
-  data.tar.gz: a2ce56d793153540e2c9c4959dc7af5aff0e73a4c32037a738a368f06128d4f35730411f8cce8875e5e1a3c153e6e4a4344de006171ca1b70d1b24737eeaf819
+  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,7 +37,7 @@ 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
@@ -44,18 +45,26 @@ class OptionsByExample
       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
@@ -147,56 +156,77 @@ class OptionsByExample
     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
+
+        if @option_took_argument
+          msg += " (considering #{@option_took_argument} takes an argument)"
         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
+        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.4.0'
+  VERSION = '4.0.0'
 end
 
 
@@ -11,6 +11,11 @@ __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

metadata

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