options_by_example 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27abecec1f4038208d60c4a623de4664241e4b88db67b8e15918ba8d2e8c4ad3
-  data.tar.gz: e57931971bc3f57ac7a59fd9233f338530afc60d2a1f507a9a2344e10d9f5ab9
+  metadata.gz: 59f737886cd6b035ebefb01b6d513d6a4cd66957858d9c3f9d4b489058fe5725
+  data.tar.gz: d3f6f2d559a4f5c077f878dec4e8fb8c8f9cf9e4daaeebaba8b5611f343ac86b
 SHA512:
-  metadata.gz: 7513e6747f9269e9618e4a4e277560fcbb7741663cc01a3c5767b0a30c52277cd67590c19b21e2eb79d42bc6678ad329d465b1d0b75f2da6079d12cc9978fe52
-  data.tar.gz: 1a4bfc340b15a0f63115e9025e4be96f37fa0d5a0808bbe81d44438c97648159154b41dc8380b94fe8aeb1a4ab5d5d7b6448572e6741ecf8a5e8bdf3d75166a3
+  metadata.gz: ad0b05e43b8ec21c9bbc434085896082fe0a956190d255c5ef24382f3f0ec8faf5f05b32f3acda272ca8d0fbbb63e736d9a5db4860e6bd750be26f7601a263c6
+  data.tar.gz: e2008e435bbfc129170599f7e28626ede57501b078e65684c436fea0644d69b8a564c388da1bd197a60332c4c34404d60424541dd9912307c0b2316ad069a811

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..-1] = [@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,85 @@ 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, argument_arity, _, _ = @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
-          @option_took_argument = option
-        else
-          @option_took_argument = nil
+        if argument_arity == :required
+          raise "Expected argument for option '#{option}', got none" unless current.first
+
+          if pending.length == 1
+            minimum_count = count_arguments(:required) + count_arguments(:vararg)
+            if current.length <= minimum_count
+              raise "Ambiguous argument for option '#{option}', not enough remaining positional arguments"
+            end
+          end
+
+          @argument_values[option_name] = current.shift
+        elsif argument_arity == :optional && current.first
+          if pending.length == 1
+            required_count = count_arguments(:required)
+            if current.length <= required_count and required_count == @argument_names.length
+              return current
+            end
+            if current.length <= required_count or required_count != @argument_names.length
+              raise "Ambiguous argument for option '#{option}', please use -- before positional arguments"
+            end
+          end
+
+          @argument_values[option_name] = current.shift
         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_type, default_value)|
+        value = @argument_values.fetch(each, default_value)
+        next unless value
+
         begin
-          case argument_name
+          case argument_type
           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 +186,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
 
@@ -192,10 +214,6 @@ class OptionsByExample
         # :nocov:
         end
 
-        if @option_took_argument
-          msg += " (considering #{@option_took_argument} takes an argument)"
-        end
-
         raise msg
       end
     end
@@ -207,10 +225,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 +238,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
-      tokens = usage_line.scan(/\[.*?\]|\w+ \.\.\.|\S+/)
-      raise unless tokens.shift == 'Usage:'
-      raise unless tokens.shift
+      raise "Expected usage string, got none" unless usage_line
+      tokens = usage_line.split(/(\[.*?\]?\]|\w+ \.\.\.)|\s+/).reject(&:empty?)
+      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,38 +71,48 @@ 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|
-        tokens = string.scan(/--?\w[\w-]*(?: \w+)?|,|\(default \S+\)|\S+/)
+        tokens = string.strip.split(/(\s+)|(,)\s*/)
 
         short_form = nil
         long_form = nil
         option_name = nil
-        argument_name = nil
+        argument_arity = nil
+        argument_type = nil
         default_value = nil
 
-        if /^-(\w)( \w+)?$/ === tokens.first
-          short_form, argument_name = tokens.shift.split
+        if /^-(\w)$/ === tokens.first
+          short_form = tokens.shift
           option_name = sanitize $1
-          tokens.shift if ',' === tokens.first
+          tokens.shift if tokens.first == ','
         end
 
-        if /^--([\w-]+)( \w+)?$/ === tokens.first
-          long_form, argument_name = tokens.shift.split
+        if /^--([\w-]+)$/ === tokens.first
+          long_form = tokens.shift
           option_name = sanitize $1
         end
 
-        if /^\(default (\S+)\)$/ === tokens.last
-          default_value = $1
+        if tokens.shift == ' '
+          if /^(\[(.+)\]|(.+)\?)$/ === tokens.first
+            argument_type = $2 || $3
+            argument_arity = :optional
+            tokens.shift
+          else
+            argument_type = tokens.shift
+            argument_arity = :required
+          end
         end
 
-        [short_form, long_form].compact.each do |each|
-          @option_names[each] = [option_name, argument_name]
+        if /\(default\s+(\S+)\)$/ === tokens.join
+          default_value = $1
         end
 
-        @default_values[option_name] = default_value if default_value
+        ary = [option_name, argument_arity, argument_type, default_value]
+        [short_form, long_form].each do |each|
+          @option_names[each] = ary if each
+        end
       end
     end
 
@@ -112,5 +121,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.2.0'
 end
 
 
@@ -11,6 +11,19 @@ __END__
 # Minor version bump when backward-compatible changes or enhancements
 # Patch version bump when backward-compatible bug fixes, security updates etc
 
+4.2.0
+  - Generate #get_NAME methods for arguments
+  - Keep #argument_NAME as backwards-compatible aliases
+  - New method #get_at_most_one returns the provided option or nil
+  - New method #get_mutually_exclusive aliases #get_at_most_one
+  - Deprecate #expect_at_most_one_of in favor of #expect_at_most_one
+  - Support optional option arguments, eg '--compress [NUM]'
+
+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

@@ -32,16 +32,24 @@ class OptionsByExample
   end
 
   def expect_at_most_one_except(*extra_options)
-    expect_at_most_one_of *(@options.keys - extra_options)
+    expect_at_most_one *(@options.keys - extra_options)
   end
 
   def expect_at_most_one_of(*mutually_exclusive_options)
+    expect_at_most_one *mutually_exclusive_options
+  end
+
+  def get_at_most_one(*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
+    provided_options.first
   end
 
+  alias expect_at_most_one get_at_most_one
+  alias get_mutually_exclusive get_at_most_one
+
   def fetch(*args, &block)
     @arguments.fetch(*args, &block)
   end
@@ -76,13 +84,17 @@ 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, argument_arity| option_name if argument_arity }
+        .compact,
     ].each do |argument_name|
       instance_eval %{
-        def argument_#{argument_name}
+        def get_#{argument_name}
           val = @arguments[:#{argument_name}]
           val && block_given? ? (yield val) : val
         end
+
+        alias argument_#{argument_name} get_#{argument_name}
       }
     end
   end
@@ -97,4 +109,3 @@ class OptionsByExample
     end
   end
 end
-

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: options_by_example
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Adrian Kuhn
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 
 email:
 - akuhn@iam.unibe.ch
 executables: []
@@ -29,7 +27,6 @@ metadata:
   homepage_uri: https://github.com/akuhn/options_by_example
   source_code_uri: https://github.com/akuhn/options_by_example
   changelog_uri: https://github.com/akuhn/options_by_example/blob/master/lib/options_by_example/version.rb
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -44,8 +41,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: No-code options parser that extracts arguments directly from usage text.
 test_files: []