options_by_example 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5533bd626a90e56af73f7fe32cbd2c0a79630da399242c98abce184ac084dd9
-  data.tar.gz: 4583a92414c1e10544ffb42b4e45da0d1c0eac1adc1d38748bd31e24e791337e
+  metadata.gz: beeaa2ae22a04cfe49102108f616bad5d3fb63b00156bb34647774ba07c8def0
+  data.tar.gz: e2af434e1812a6244c276bea7b00b52b97411927ccc207e843f4866e64356d08
 SHA512:
-  metadata.gz: cd7df1507d066462d1031d71dc054fa886764dddca9fe17b4d6f7310f9e17f75673a6a6709e6ef1636d863dd35a537918d9e6838a04981cd947174d402569480
-  data.tar.gz: 9f11d4fdae24faefc1069435683e65c648635568d54d19e3e8197040b721db3630be4aa779781403d26b5c2e04dd23b3b6bcc0e3bef11d405855ac07e89a0630
+  metadata.gz: fca827e7190634ca8382ff90d074a276fd4367a609fad77b3d58a8488f85b97e3e8493fe2a717fd9a9aff3fefdde4315058c1512addaf4b1d7663f1a2dc201db
+  data.tar.gz: a2ce56d793153540e2c9c4959dc7af5aff0e73a4c32037a738a368f06128d4f35730411f8cce8875e5e1a3c153e6e4a4344de006171ca1b70d1b24737eeaf819

data/lib/options_by_example/commandline_parser.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+
+class OptionsByExample
+
+  class PrintUsageMessage < StandardError
+  end
+
+  class CommandlineParser
+
+    attr_reader :option_values
+    attr_reader :argument_values
+
+    def initialize(usage)
+      @argument_names = usage.argument_names
+      @default_values = usage.default_values
+      @option_names = usage.option_names
+
+      @argument_values = @default_values.dup
+      @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
+
+      raise_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
+
+      raise "Internal error: unreachable state" unless @remainder.empty?
+    end
+
+    private
+
+    def raise_if_help_option
+      @slices.each do |option, *args|
+        case option
+        when '-h', '--help'
+          raise PrintUsageMessage
+        end
+      end
+    end
+
+    def unpack_combined_shorthand_options
+
+      # Expand any combined shorthand options like -svt into their
+      # separate components (-s, -v, and -t) and assigns any arguments
+      # to the last component. If an unknown shorthand is found, raise
+      # a helpful error message with suggestion if possible.
+
+      list = []
+      @slices.each do |option, *args|
+        if option =~ /^-([a-zA-Z]{2,})$/
+          shorthands = $1.each_char.map { |char| "-#{char}" }
+
+          shorthands.each do |each|
+            if not @option_names.include?(each)
+              did_you_mean = ", did you mean '-#{option}'?" if @option_names.include?("-#{option}")
+              raise "Found unknown option #{each} inside '#{option}'#{did_you_mean}"
+            end
+          end
+
+          list.concat shorthands.map { |each| [each] }
+          list.last.concat args
+        else
+          list << [option, *args]
+        end
+      end
+
+      @slices = list
+    end
+
+    def expand_dash_number_to_dash_n_option
+      @slices.each do |each|
+        if each.first =~ /^-(\d+)$/
+          each[0..0] = ['-n', $1]
+        end
+      end
+    end
+
+    def raise_if_unknown_options
+      @slices.each do |option, *args|
+        raise "Found unknown option '#{option}'" unless @option_names.include?(option)
+      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"
+        end
+
+        option_name, argument_name = @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
+        end
+
+        @remainder = args
+      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)
+
+      min_length = count_required_arguments + count_vararg_arguments
+      max_length = count_required_arguments + count_optional_arguments
+
+      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
+
+      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
+
+    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
+        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
+      end
+    end
+
+    def parse_optional_arguments
+      @argument_names.each do |argument_name, arity|
+        break unless arity == :optional
+        break if @remainder.empty?
+        @argument_values[argument_name] = @remainder.shift
+      end
+    end
+  end
+end

data/lib/options_by_example/usage_specification.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+class OptionsByExample
+
+  class UsageSpecification
+
+    attr_reader :message
+    attr_reader :argument_names
+    attr_reader :default_values
+    attr_reader :option_names
+
+    def initialize(text)
+      @message = text.gsub('$0', File.basename($0)).gsub(/\n+\Z/, "\n\n")
+
+      # --- 1) Parse argument names -------------------------------------
+      #
+      # Parse the usage string and extract both optional argument names
+      # and required argument names, for example:
+      #
+      # Usage: connect [options] [mode] host port
+
+      @argument_names = {}
+      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
+      tokens.shift if tokens.first == '[options]'
+
+      while /^\[(--?\w.*)\]$/ === tokens.first
+        inline_options << $1
+        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
+        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)
+
+      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
+
+      # --- 2) Parse option names ---------------------------------------
+      #
+      # Parse the usage message and extract option names, their short and
+      # long forms, and the associated argument name (if any), eg:
+      #
+      # Options:
+      #   -s, --secure        Use secure connection
+      #   -v, --verbose       Enable verbose output
+      #   -r, --retries NUM   Number of connection retries (default 3)
+      #   -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+/)
+
+        short_form = nil
+        long_form = nil
+        option_name = nil
+        argument_name = nil
+        default_value = nil
+
+        if /^-(\w)( \w+)?$/ === tokens.first
+          short_form, argument_name = tokens.shift.split
+          option_name = sanitize $1
+          tokens.shift if ',' === tokens.first
+        end
+
+        if /^--([\w-]+)( \w+)?$/ === tokens.first
+          long_form, argument_name = tokens.shift.split
+          option_name = sanitize $1
+        end
+
+        if /^\(default (\S+)\)$/ === tokens.last
+          default_value = $1
+        end
+
+        [short_form, long_form].compact.each do |each|
+          @option_names[each] = [option_name, argument_name]
+        end
+
+        @default_values[option_name] = default_value if default_value
+      end
+    end
+
+    private
+
+    def sanitize(string)
+      string.tr('^a-zA-Z0-9', '_').downcase.to_sym
+    end
+  end
+end

data/lib/options_by_example/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class OptionsByExample
-  VERSION = '3.2.0'
+  VERSION = '3.4.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
 
+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
+  - Support repeated arguments using dot-dot-dot
+
 3.2.0
 
   - New method #get returns argument value or nil

data/lib/options_by_example.rb

@@ -1,52 +1,22 @@
 # frozen_string_literal: true
 
 require 'options_by_example/version'
-require 'options_by_example/parser'
+require 'options_by_example/commandline_parser'
+require 'options_by_example/usage_specification'
 
 
 class OptionsByExample
 
   attr_reader :arguments
   attr_reader :options
-  attr_reader :usage_message
+  attr_reader :usage_spec
 
   def self.read(data)
     return new data.read
   end
 
   def initialize(text)
-    @usage_message = text.gsub('$0', File.basename($0)).gsub(/\n+\Z/, "\n\n")
-
-    # --- 1) Parse argument names -------------------------------------
-    #
-    # Parse the usage string and extract both optional argument names
-    # and required argument names, for example:
-    #
-    # Usage: connect [options] [mode] host port
-
-    text =~ /Usage: (\$0|\w+)(?: \[options\])?((?: \[\w+\])*)((?: \w+)*)/
-    raise RuntimeError, "Expected usage string, got none" unless $1
-    @argument_names_optional = $2.to_s.split.map { |match| sanitize match.tr('[]', '') }
-    @argument_names_required = $3.to_s.split.map { |match| sanitize match }
-
-    # --- 2) Parse option names ---------------------------------------
-    #
-    # Parse the usage message and extract option names, their short and
-    # long forms, and the associated argument name (if any), eg:
-    #
-    # Options:
-    #   -s, --secure        Use secure connection
-    #   -v, --verbose       Enable verbose output
-    #   -r, --retries NUM   Number of connection retries (default 3)
-    #   -t, --timeout NUM   Set connection timeout in seconds
-
-    @option_names = {}
-    @default_values = {}
-    text.scan(/(?:(-\w), ?)?(--([\w-]+))(?: (\w+))?(?:.*\(default:? (\w+)\))?/) do
-      flags = [$1, $2].compact
-      flags.each { |each| @option_names[each] = [(sanitize $3), $4] }
-      @default_values[sanitize $3] = $5 if $5
-    end
+    @usage_spec = UsageSpecification.new(text)
 
     initialize_argument_accessors
     initialize_option_accessors
@@ -55,11 +25,21 @@ class OptionsByExample
   def parse(argv)
     parse_without_exit argv
   rescue PrintUsageMessage
-    puts @usage_message
+    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)
@@ -84,25 +64,19 @@ class OptionsByExample
   private
 
   def parse_without_exit(argv)
-    parser = Parser.new(
-      @argument_names_required,
-      @argument_names_optional,
-      @default_values,
-      @option_names,
-    )
+    parser = CommandlineParser.new(@usage_spec)
+    parser.parse(argv)
 
-    parser.parse argv
-    @arguments = parser.arguments
-    @options = parser.options
+    @arguments = parser.argument_values
+    @options = parser.option_values
 
     return self
   end
 
   def initialize_argument_accessors
     [
-      *@argument_names_required,
-      *@argument_names_optional,
-      *@option_names.values.select(&:last).map(&:first),
+      *@usage_spec.argument_names.keys,
+      *@usage_spec.option_names.values.select(&:last).map(&:first),
     ].each do |argument_name|
       instance_eval %{
         def argument_#{argument_name}
@@ -114,7 +88,7 @@ class OptionsByExample
   end
 
   def initialize_option_accessors
-    @option_names.each_value do |option_name, _|
+    @usage_spec.option_names.each_value do |option_name, _|
       instance_eval %{
         def include_#{option_name}?
           @options.include? :#{option_name}
@@ -122,9 +96,5 @@ class OptionsByExample
       }
     end
   end
-
-  def sanitize(string)
-    string.tr('^a-zA-Z0-9', '_').downcase.to_sym
-  end
 end
 

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: options_by_example
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Adrian Kuhn
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-17 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies: []
-description:
+description: 
 email:
 - akuhn@iam.unibe.ch
 executables: []
@@ -19,7 +19,8 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/options_by_example.rb
-- lib/options_by_example/parser.rb
+- lib/options_by_example/commandline_parser.rb
+- lib/options_by_example/usage_specification.rb
 - lib/options_by_example/version.rb
 homepage: https://github.com/akuhn/options_by_example
 licenses:
@@ -28,7 +29,7 @@ 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:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -43,8 +44,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: No-code options parser that extracts arguments directly from usage text.
 test_files: []

data/lib/options_by_example/parser.rb

@@ -1,168 +0,0 @@
-# frozen_string_literal: true
-
-require 'date'
-require 'time'
-
-
-class OptionsByExample
-
-  class PrintUsageMessage < StandardError
-  end
-
-  class Parser
-
-    attr_reader :options
-    attr_reader :arguments
-
-    def initialize(argument_names_required, argument_names_optional, default_values, option_names)
-      @argument_names_required = argument_names_required
-      @argument_names_optional = argument_names_optional
-      @default_values = default_values
-      @option_names = option_names
-
-      @arguments = @default_values.dup
-      @options = {}
-    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.
-
-      @chunks = []
-      @remainder = current = []
-      array.each do |each|
-        @chunks << current = [] if each.start_with?(?-)
-        current << each
-      end
-
-      detect_help_option
-      flatten_stacked_shorthand_options
-      detect_unknown_options
-      parse_options
-
-      validate_number_of_arguments
-      parse_required_arguments
-      parse_optional_arguments
-
-      raise "Internal error: unreachable state" unless @remainder.empty?
-    end
-
-    private
-
-    def detect_help_option
-      @chunks.each do |option, *args|
-        case option
-        when '-h', '--help'
-          raise PrintUsageMessage
-        end
-      end
-    end
-
-    def flatten_stacked_shorthand_options
-
-      # Expand any combined shorthand options like -svt into their
-      # separate components (-s, -v, and -t) and assigns any arguments
-      # to the last component. If an unknown shorthand is found, raise
-      # a helpful error message with suggestion if possible.
-
-      list = []
-      @chunks.each do |option, *args|
-        if option =~ /^-([a-zA-Z]{2,})$/
-          shorthands = $1.each_char.map { |char| "-#{char}" }
-
-          shorthands.each do |each|
-            if not @option_names.include?(each)
-              did_you_mean = ", did you mean '-#{option}'?" if @option_names.include?("-#{option}")
-              raise "Found unknown option #{each} inside '#{option}'#{did_you_mean}"
-            end
-          end
-
-          list.concat shorthands.map { |each| [each] }
-          list.last.concat args
-        else
-          list << [option, *args]
-        end
-      end
-
-      @chunks = list
-    end
-
-    def detect_unknown_options
-      @chunks.each do |option, *args|
-        raise "Found unknown option '#{option}'" unless @option_names.include?(option)
-      end
-    end
-
-    def parse_options
-      @chunks.each do |option, *args|
-        if @remainder.any?
-          raise "Unexpected arguments found before option '#{option}', please provide all options before arguments"
-        end
-
-        option_name, argument_name = @option_names[option]
-        @options[option_name] = true
-
-        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
-
-          @arguments[option_name] = value
-          @option_took_argument = option
-        else
-          @option_took_argument = nil
-        end
-
-        @remainder = args
-      end
-    end
-
-    def validate_number_of_arguments
-      min_length = @argument_names_required.size
-      max_length = @argument_names_optional.size + min_length
-
-      if @remainder.size > max_length
-        range = [min_length, max_length].uniq.join(?-)
-        raise "Expected #{range} arguments, but received too many"
-      end
-
-      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
-
-    def parse_required_arguments
-      stash = @remainder.pop(@argument_names_required.length)
-      @argument_names_required.each do |argument_name|
-        raise "Missing required argument '#{argument_name}'" if stash.empty?
-        @arguments[argument_name] = stash.shift
-      end
-    end
-
-    def parse_optional_arguments
-      @argument_names_optional.each do |argument_name|
-        break if @remainder.empty?
-        @arguments[argument_name] = @remainder.shift
-      end
-    end
-  end
-end