options_by_example 3.4.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beeaa2ae22a04cfe49102108f616bad5d3fb63b00156bb34647774ba07c8def0
-  data.tar.gz: e2af434e1812a6244c276bea7b00b52b97411927ccc207e843f4866e64356d08
+  metadata.gz: 3f146461611879c6934270f692e97391830d93f634b9300f7fa2883195bc0a22
+  data.tar.gz: 19ad57569defbb334404085af3248675cfa84000511bbf49b2803b5c6cb38dee
 SHA512:
-  metadata.gz: fca827e7190634ca8382ff90d074a276fd4367a609fad77b3d58a8488f85b97e3e8493fe2a717fd9a9aff3fefdde4315058c1512addaf4b1d7663f1a2dc201db
-  data.tar.gz: a2ce56d793153540e2c9c4959dc7af5aff0e73a4c32037a738a368f06128d4f35730411f8cce8875e5e1a3c153e6e4a4344de006171ca1b70d1b24737eeaf819
+  metadata.gz: 01146df8d0c06df84d2c093d0493219d6bd9d78ab5174f089b6b13b79b5fbb355ebd16f8bd5e3b65358670b44f6479e032e8967e57df52935328e5f151bfb4a1
+  data.tar.gz: fbfe47bf367329b63e3661c28b964118c9dd47e013dabcfabdf6ceae9bdad3a2af9cd0998a852d5e3ede7a22b07146d64ae85fb61727aac54e1ced139075f918

data/README.md

@@ -1,61 +1,48 @@
 # Options by Example
 
-No-code options parser that automatically detects command-line options from the usage text of your application. This intuitive parser identifies optional and required argument names as well as option names without requiring any additional code, making it easy to manage user input for your command-line applications.
+No-code options parser that automatically detects command-line options from the usage text.
 
 Features
 
-- Automatically detects optional and required argument names from usage text
-- Automatically detects option names and associated arguments (if any) from usage text
+- Automatically infers options and argument names from usage text
 - Parses those arguments and options from the command line (ARGV)
 - Raises errors for unknown options or missing required arguments
+- Supports typed arguments, eg `--lines NUM` or `--since DATE`
 
-Installation
+Example
 
-To use options_by_example, first install the gem by running:
+```ruby
+require %(options_by_example)
 
-```
-gem install options_by_example
-```
+flags = OptionsByExample.read(DATA).parse(ARGV)
 
-Alternatively, add this line to your Gemfile and run bundle install:
+puts 'Feeling verbose today' if flags.include?(:verbose)
+puts flags.get(:words).sample(flags.get(:num))
 
-```
-gem 'options_by_example'
-```
-
-Example
+__END__
+Choose at random from a list of provided words.
 
-```ruby
-require 'options_by_example'
+Usage: random.rb [options] words ...
 
-Options = OptionsByExample.read(DATA).parse(ARGV)
+Options:
+  -n, --num NUM     Number of choices (default 1)
+  --verbose         Enable verbose mode
+```
 
-puts Options.include? :secure
-puts Options.include? :verbose
-puts Options.include? :retries
-puts Options.include? :timeout
-puts Options.get :retries
-puts Options.get :timeout
-puts Options.get :mode
-puts Options.get :host
-puts Options.get :port
+And then call the program with eg
 
+    ruby random.rb -n 2 foo bar qux
 
-__END__
-Establishes a network connection to a designated host and port, enabling
-users to assess network connectivity and diagnose potential problems.
+### Installation
 
-Usage: connect [options] [mode] host port
+To use options_by_example, first install the gem by running:
 
-Options:
-  -s, --secure        Establish a secure connection (SSL/TSL)
-  -v, --verbose       Enable verbose output for detailed information
-  -r, --retries NUM   Number of connection retries (default 3)
-  -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)
 ```
+gem install options_by_example
+```
+
+Alternatively, add this line to your Gemfile and run bundle install:
 
+```
+gem 'options_by_example'
+```

data/lib/options_by_example/commandline_parser.rb

@@ -16,46 +16,47 @@ class OptionsByExample
 
     def initialize(usage)
       @argument_names = usage.argument_names
-      @default_values = usage.default_values
       @option_names = usage.option_names
 
-      @argument_values = @default_values.dup
+      @argument_values = {}
       @option_values = {}
     end
 
-    def parse(array)
+    def parse(argv)
+      @slices = argv.slice_before(/^-/).entries
+      treat_everything_after_double_dash_as_positionals
 
-      # Separate command-line options and their respective arguments into
-      # chunks, plus tracking leading excess arguments. This organization
-      # facilitates further processing and validation of the input.
-
-      @slices = []
-      @remainder = current = []
-      array.each do |each|
-        @slices << current = [] if each.start_with?(?-)
-        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
+
+      @remainder = parse_options_and_return_remainder
       coerce_num_date_time_etc
 
       validate_number_of_arguments
-      parse_required_arguments
-      parse_optional_arguments
+      parse_positional_arguments
 
-      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 treat_everything_after_double_dash_as_positionals
+      index = @slices.index { |head,| head == '--' }
+      @slices[index..] = [@slices.drop(index).flatten] if index
+    end
+
+    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 "@option_names = #{@option_names.inspect}"
+          end
           raise PrintUsageMessage
         end
       end
@@ -99,104 +100,135 @@ class OptionsByExample
     end
 
     def raise_if_unknown_options
-      @slices.each do |option, *args|
-        raise "Found unknown option '#{option}'" unless @option_names.include?(option)
+      @slices.each do |option,|
+        if option =~ /^--?\w/ and not @option_names.include?(option)
+          raise "Found unknown option '#{option}'"
+        end
       end
     end
 
-    def parse_options
-      @slices.each do |option, *args|
-        if @remainder.any?
-          raise "Unexpected arguments found before option '#{option}', please provide all options before arguments"
+    def parse_options_and_return_remainder
+      pending = @slices.dup
+
+      until pending.empty?
+        current = pending.first
+
+        unless current.first =~ /^--?\w/
+          current.shift if current.first == '--' # consume double-dash
+          return current if pending.length == 1
+          raise "Unexpected arguments found before option '#{pending[1].first}', please provide all options before arguments"
         end
 
-        option_name, argument_name = @option_names[option]
+        option = current.shift # consume the option/flag
+        option_name, has_argument, _ = @option_names[option]
         @option_values[option_name] = true
 
-        if argument_name
-          raise "Expected argument for option '#{option}', got none" if args.empty?
-          @argument_values[option_name] = args.shift
+        if has_argument
+          raise "Expected argument for option '#{option}', got none" unless current.first
+          @argument_values[option_name] = current.shift # consume the argument
           @option_took_argument = option
         else
           @option_took_argument = nil
         end
 
-        @remainder = args
+        pending.shift if current.empty?
       end
+
+      return []
     end
 
     def coerce_num_date_time_etc
-      @option_names.each do |option, (each, argument_name)|
-        next unless value = @argument_values[each]
+      @option_names.each do |option, (each, argument_name, default_value)|
+        value = @argument_values.fetch(each, default_value)
+        next unless value
+
         begin
           case argument_name
           when 'NUM'
             expected_type = 'an integer value'
-            @argument_values[each] = Integer value
+            value = Integer value
+          when 'FLOAT'
+            expected_type = 'a floating-point value'
+            value = Float value
           when 'DATE'
             expected_type = 'a date (e.g. YYYY-MM-DD)'
-            @argument_values[each]  = Date.parse value
+            value = Date.parse value
           when 'TIME'
             expected_type = 'a timestamp (e.g. HH:MM:SS)'
-            @argument_values[each]  = Time.parse value
+            value = Time.parse value
           end
         rescue ArgumentError
           raise "Invalid argument \"#{value}\" for option '#{option}', please provide #{expected_type}"
         end
+
+        @argument_values[each] = value
       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
+      min_length = count_arguments(:required) + count_arguments(:vararg)
+      max_length = count_arguments(:required) + count_arguments(/optional/)
+      max_length = nil if count_arguments(/vararg/) > 0
 
-      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
+      unless (min_length..max_length) === @remainder.size
 
-      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
+        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
 
-    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 @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, :optional_vararg
+          @argument_values[argument_name] = @remainder.shift(@remainder.length - remaining_arguments)
+        when :optional
+          next if @remainder.empty?
+          @argument_values[argument_name] = @remainder.shift
+        # :nocov:
+        else
+          raise %{unreachable given these are all possible values}
+        # :nocov:
+        end
       end
     end
+
+    private
+
+    def count_arguments(pattern)
+      @argument_names.values.grep(pattern).count
+    end
   end
 end

data/lib/options_by_example/usage_specification.rb

@@ -6,7 +6,6 @@ class OptionsByExample
 
     attr_reader :message
     attr_reader :argument_names
-    attr_reader :default_values
     attr_reader :option_names
 
     def initialize(text)
@@ -23,10 +22,10 @@ class OptionsByExample
       inline_options = []
 
       usage_line = text.lines.grep(/Usage:/).first
-      raise RuntimeError, "Expected usage string, got none" unless usage_line
+      raise "Expected usage string, got none" unless usage_line
       tokens = usage_line.scan(/\[.*?\]|\w+ \.\.\.|\S+/)
-      raise unless tokens.shift == 'Usage:'
-      raise unless tokens.shift
+      raise "Expected usage line to start with 'Usage:'" unless tokens.shift == 'Usage:'
+      raise "Expected command name on same line as 'Usage:'" unless tokens.shift
       tokens.shift if tokens.first == '[options]'
 
       while /^\[(--?\w.*)\]$/ === tokens.first
@@ -34,24 +33,31 @@ 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_vararg
         tokens.shift
       end
 
       raise "Found invalid usage token '#{tokens.first}'" unless tokens.empty?
 
-      count_optional_arguments = @argument_names.values.count(:optional)
-      count_vararg_arguments = @argument_names.values.count(:vararg)
+      if count_arguments(:vararg) > 0 && count_arguments(/optional/) > 0
+        raise "Cannot combine vararg and optional arguments"
+      end
 
-      raise "Cannot combine dotted and optional arguments" if count_optional_arguments > 0 && count_vararg_arguments > 0
-      raise "Found more than one dotted arguments" if count_vararg_arguments > 1
+      if count_arguments(/vararg/) > 1
+        raise "Found more than one vararg arguments"
+      end
 
       # --- 2) Parse option names ---------------------------------------
       #
@@ -65,7 +71,6 @@ class OptionsByExample
       #   -t, --timeout NUM   Set connection timeout in seconds
 
       @option_names = {}
-      @default_values = {}
 
       options = inline_options + text.lines.grep(/^\s*--?\w/)
       options.each do |string|
@@ -92,11 +97,10 @@ class OptionsByExample
           default_value = $1
         end
 
-        [short_form, long_form].compact.each do |each|
-          @option_names[each] = [option_name, argument_name]
+        ary = [option_name, argument_name, default_value]
+        [short_form, long_form].each do |each|
+          @option_names[each] = ary if each
         end
-
-        @default_values[option_name] = default_value if default_value
       end
     end
 
@@ -105,5 +109,9 @@ class OptionsByExample
     def sanitize(string)
       string.tr('^a-zA-Z0-9', '_').downcase.to_sym
     end
+
+    def count_arguments(pattern)
+      @argument_names.values.grep(pattern).count
+    end
   end
 end

data/lib/options_by_example/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class OptionsByExample
-  VERSION = '3.4.0'
+  VERSION = '4.1.0'
 end
 
 
@@ -11,6 +11,16 @@ __END__
 # Minor version bump when backward-compatible changes or enhancements
 # Patch version bump when backward-compatible bug fixes, security updates etc
 
+4.1.0
+  - Treat everything after double-dash as positional arguments
+  - Improve error message when usage is split across lines
+  - Add support for FLOAT arguments, eg `--ratio FLOAT`
+
+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

data/lib/options_by_example.rb

@@ -76,7 +76,9 @@ class OptionsByExample
   def initialize_argument_accessors
     [
       *@usage_spec.argument_names.keys,
-      *@usage_spec.option_names.values.select(&:last).map(&:first),
+      *@usage_spec.option_names.values
+        .map { |option_name, has_argument| option_name if has_argument }
+        .compact,
     ].each do |argument_name|
       instance_eval %{
         def argument_#{argument_name}

metadata

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