options_by_example 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f90dee5b19415bddb809efe80e4fc2c6f39daf7b82259a0c247caa789d21ff23
-  data.tar.gz: b74ece7699aee6f785e9a2fa5149f2a2ee6f2c7f5a4365a429e958d676e9aaf1
+  metadata.gz: 8ced46483d8abae62122bb45cd0d4753408c4d93e08405a3409583ec9fcfb477
+  data.tar.gz: e8484baa8976c72154fb2da2509482d985501c08960e7e67fdf04731e307787b
 SHA512:
-  metadata.gz: c4e235ad68624c57e3efe1915a31c006128351f6c870fa5aefa8f6b2856ec0bab33c24107c1d99b308d9b5fa54cabdff901d3669413e4021c839d7778ecb9cb7
-  data.tar.gz: a5c7213462bc16e1b88411b92c28c9be5b71cf9838bcad217316586b28318398441e1cc69acf56e223812c7c0fb51dcf381403158a35283f58ea2b0ce6f777bc
+  metadata.gz: 22f691bf1fc36e14868996b32b15de17a1760add666aa046e6dc57fb0e09f8dad75c7c18260255930c88ea3e56a1c994285dd320a659e6c9ee92fc4ae45d3f10
+  data.tar.gz: 1d54dca36e9829f2018af7493586e18ca7d590819d112e28482c93684212adc4ccd53e5c5183d49885c927f4ddb9e23c0654874ddbceb0e617f95c6fc6b96258

data/README.md

@@ -30,15 +30,15 @@ require 'options_by_example'
 
 Options = OptionsByExample.read(DATA).parse(ARGV)
 
-puts Options.include_secure?
-puts Options.include_verbose?
-puts Options.include_retries?
-puts Options.include_timeout?
-puts Options.argument_retries
-puts Options.argument_timeout
-puts Options.argument_mode
-puts Options.argument_host
-puts Options.argument_port
+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
 
 
 __END__
@@ -50,8 +50,8 @@ Usage: connect [options] [mode] host port
 Options:
   -s, --secure        Establish a secure connection (SSL/TSL)
   -v, --verbose       Enable verbose output for detailed information
-  -r, --retries NUM   Specify the number of connection retries (default 3)
-  -t, --timeout NUM   Set the connection timeout in seconds (default 10)
+  -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)

data/lib/options_by_example/{parser.rb → commandline_parser.rb}

@@ -9,19 +9,18 @@ class OptionsByExample
   class PrintUsageMessage < StandardError
   end
 
-  class Parser
+  class CommandlineParser
 
-    attr_reader :options
-    attr_reader :arguments
+    attr_reader :option_values
+    attr_reader :argument_values
 
-    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
+    def initialize(usage)
+      @argument_names = usage.argument_names
+      @default_values = usage.default_values
+      @option_names = usage.option_names
 
-      @arguments = @default_values.dup
-      @options = {}
+      @argument_values = @default_values.dup
+      @option_values = {}
     end
 
     def parse(array)
@@ -30,16 +29,17 @@ class OptionsByExample
       # chunks, plus tracking leading excess arguments. This organization
       # facilitates further processing and validation of the input.
 
-      @chunks = []
+      @slices = []
       @remainder = current = []
       array.each do |each|
-        @chunks << current = [] if each.start_with?(?-)
+        @slices << current = [] if each.start_with?(?-)
         current << each
       end
 
-      detect_help_option
-      flatten_stacked_shorthand_options
-      detect_unknown_options
+      raise_if_help_option
+      unpack_combined_shorthand_options
+      expand_dash_number_to_dash_n_option
+      raise_if_unknown_options
       parse_options
 
       validate_number_of_arguments
@@ -51,8 +51,8 @@ class OptionsByExample
 
     private
 
-    def detect_help_option
-      @chunks.each do |option, *args|
+    def raise_if_help_option
+      @slices.each do |option, *args|
         case option
         when '-h', '--help'
           raise PrintUsageMessage
@@ -60,7 +60,7 @@ class OptionsByExample
       end
     end
 
-    def flatten_stacked_shorthand_options
+    def unpack_combined_shorthand_options
 
       # Expand any combined shorthand options like -svt into their
       # separate components (-s, -v, and -t) and assigns any arguments
@@ -68,7 +68,7 @@ class OptionsByExample
       # a helpful error message with suggestion if possible.
 
       list = []
-      @chunks.each do |option, *args|
+      @slices.each do |option, *args|
         if option =~ /^-([a-zA-Z]{2,})$/
           shorthands = $1.each_char.map { |char| "-#{char}" }
 
@@ -86,23 +86,31 @@ class OptionsByExample
         end
       end
 
-      @chunks = list
+      @slices = list
     end
 
-    def detect_unknown_options
-      @chunks.each do |option, *args|
+    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
-      @chunks.each do |option, *args|
+      @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]
-        @options[option_name] = true
+        @option_values[option_name] = true
 
         if argument_name
           raise "Expected argument for option '#{option}', got none" if args.empty?
@@ -124,7 +132,7 @@ class OptionsByExample
             raise "Invalid argument \"#{value}\" for option '#{option}', please provide #{expected_type}"
           end
 
-          @arguments[option_name] = value
+          @argument_values[option_name] = value
           @option_took_argument = option
         else
           @option_took_argument = nil
@@ -135,10 +143,14 @@ class OptionsByExample
     end
 
     def validate_number_of_arguments
-      min_length = @argument_names_required.size
-      max_length = @argument_names_optional.size + min_length
+      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
+      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
@@ -151,17 +163,35 @@ class OptionsByExample
     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
+      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_optional.each do |argument_name|
+      @argument_names.each do |argument_name, arity|
+        break unless arity == :optional
         break if @remainder.empty?
-        @arguments[argument_name] = @remainder.shift
+        @argument_values[argument_name] = @remainder.shift
       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.1.0'
+  VERSION = '3.3.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.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
+  - New method #fetch returns argument value or raises error
+  - Changed internal method #parse_without_exit to private
+
 3.1.0
 
   - Support dash in argument and option names

data/lib/options_by_example.rb

@@ -1,51 +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_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
@@ -54,26 +25,19 @@ 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
   end
 
-  def parse_without_exit(argv)
-    parser = Parser.new(
-      @argument_names_required,
-      @argument_names_optional,
-      @default_values,
-      @option_names,
-    )
-
-    parser.parse argv
-    @arguments = parser.arguments
-    @options = parser.options
+  def fetch(*args, &block)
+    @arguments.fetch(*args, &block)
+  end
 
-    return self
+  def get(name)
+    @arguments[name]
   end
 
   def if_present(name)
@@ -89,11 +53,20 @@ class OptionsByExample
 
   private
 
+  def parse_without_exit(argv)
+    parser = CommandlineParser.new(@usage_spec)
+    parser.parse(argv)
+
+    @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}
@@ -105,7 +78,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}
@@ -113,9 +86,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.1.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Adrian Kuhn
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-25 00:00:00.000000000 Z
+date: 2026-02-01 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: []