options_by_example 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27abecec1f4038208d60c4a623de4664241e4b88db67b8e15918ba8d2e8c4ad3
-  data.tar.gz: e57931971bc3f57ac7a59fd9233f338530afc60d2a1f507a9a2344e10d9f5ab9
+  metadata.gz: 3f146461611879c6934270f692e97391830d93f634b9300f7fa2883195bc0a22
+  data.tar.gz: 19ad57569defbb334404085af3248675cfa84000511bbf49b2803b5c6cb38dee
 SHA512:
-  metadata.gz: 7513e6747f9269e9618e4a4e277560fcbb7741663cc01a3c5767b0a30c52277cd67590c19b21e2eb79d42bc6678ad329d465b1d0b75f2da6079d12cc9978fe52
-  data.tar.gz: 1a4bfc340b15a0f63115e9025e4be96f37fa0d5a0808bbe81d44438c97648159154b41dc8380b94fe8aeb1a4ab5d5d7b6448572e6741ecf8a5e8bdf3d75166a3
+  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] host port [mode]
+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:
-  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)
 ```
+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,37 +16,26 @@ 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
+      @argument_values = {}
       @option_values = {}
     end
 
-    def parse(array)
-
-      # 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
+    def parse(argv)
+      @slices = argv.slice_before(/^-/).entries
+      treat_everything_after_double_dash_as_positionals
 
       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_positional_arguments
-      special_case_if_ends_with_optional_vararg
 
       # :nocov:
       raise %{unreachable given we check number of arguments} unless @remainder.empty?
@@ -55,14 +44,17 @@ class OptionsByExample
 
     private
 
+    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 "@default_values = #{@default_values.inspect}"
-            puts "@ends_with_optional_vararg = #{@ends_with_optional_vararg}"
             puts "@option_names = #{@option_names.inspect}"
           end
           raise PrintUsageMessage
@@ -108,50 +100,68 @@ 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
 
@@ -159,14 +169,9 @@ class OptionsByExample
       # ASSUME: either varargs or optional arguments, never both. That
       # constraint is guaranteed upstream. Here, we just count
 
-      count_required = @argument_names.values.count(:required)
-      count_vararg = @argument_names.values.count(:vararg)
-      count_optional = @argument_names.values.count(:optional)
-
-      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
+      min_length = count_arguments(:required) + count_arguments(:vararg)
+      max_length = count_arguments(:required) + count_arguments(/optional/)
+      max_length = nil if count_arguments(/vararg/) > 0
 
       unless (min_length..max_length) === @remainder.size
 
@@ -207,10 +212,10 @@ class OptionsByExample
         case arity
         when :required
           @argument_values[argument_name] = @remainder.shift
-        when :vararg
+        when :vararg, :optional_vararg
           @argument_values[argument_name] = @remainder.shift(@remainder.length - remaining_arguments)
         when :optional
-          break if @remainder.empty?
+          next if @remainder.empty?
           @argument_values[argument_name] = @remainder.shift
         # :nocov:
         else
@@ -220,13 +225,10 @@ class OptionsByExample
       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),
-      ]
+    private
+
+    def count_arguments(pattern)
+      @argument_names.values.grep(pattern).count
     end
   end
 end

data/lib/options_by_example/usage_specification.rb

@@ -6,8 +6,6 @@ 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)
@@ -24,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
@@ -47,18 +45,19 @@ class OptionsByExample
       end
 
       if /^\[(\w+) ?\.\.\.\]$/ === tokens.first
-        @argument_names[sanitize $1] = :optional
-        @ends_with_optional_vararg = true
+        @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 ---------------------------------------
       #
@@ -72,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|
@@ -99,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
 
@@ -112,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 = '4.0.0'
+  VERSION = '4.1.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.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

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: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Adrian Kuhn
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: