options_by_example 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb87e6b0c01a7f99d70d600c6adc142d96cae3fc18b122c2259c926504fb198b
-  data.tar.gz: e21e7dd4f0a4a77fb7e2a84b4edc77293023730388e0fcbf4abe2d0e5344d5c5
+  metadata.gz: f90dee5b19415bddb809efe80e4fc2c6f39daf7b82259a0c247caa789d21ff23
+  data.tar.gz: b74ece7699aee6f785e9a2fa5149f2a2ee6f2c7f5a4365a429e958d676e9aaf1
 SHA512:
-  metadata.gz: 7e5b59dc4a4b9ad41edeaadaf98fa3ee23abe4f262cfbb9ba93752dba66ff5868b704024a3d534b43386977caefe6a4eecea4a5e80c22f5c351f679ec2488bc3
-  data.tar.gz: 7ecce96f859a83e3dc702740c3d5e72c957d44a42387dff4a70db249bc54fc1df45484bf5ff099e9bbd66d9dae06a548d179f107aa5f6cb87395a36a54551bc0
+  metadata.gz: c4e235ad68624c57e3efe1915a31c006128351f6c870fa5aefa8f6b2856ec0bab33c24107c1d99b308d9b5fa54cabdff901d3669413e4021c839d7778ecb9cb7
+  data.tar.gz: a5c7213462bc16e1b88411b92c28c9be5b71cf9838bcad217316586b28318398441e1cc69acf56e223812c7c0fb51dcf381403158a35283f58ea2b0ce6f777bc

data/README.md

@@ -9,6 +9,19 @@ Features
 - Parses those arguments and options from the command line (ARGV)
 - Raises errors for unknown options or missing required arguments
 
+Installation
+
+To use options_by_example, first install the gem by running:
+
+```
+gem install options_by_example
+```
+
+Alternatively, add this line to your Gemfile and run bundle install:
+
+```
+gem 'options_by_example'
+```
 
 Example
 

data/lib/options_by_example/parser.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'date'
+require 'time'
+
 
 class OptionsByExample
 
@@ -11,19 +14,20 @@ class OptionsByExample
     attr_reader :options
     attr_reader :arguments
 
-    def initialize(argument_names_required, argument_names_optional, option_names)
+    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 = {}
+      @arguments = @default_values.dup
       @options = {}
     end
 
     def parse(array)
 
       # Separate command-line options and their respective arguments into
-      # chunks plus handling any remaining arguments. This organization
+      # chunks, plus tracking leading excess arguments. This organization
       # facilitates further processing and validation of the input.
 
       @chunks = []
@@ -33,8 +37,9 @@ class OptionsByExample
         current << each
       end
 
-      find_help_option
-      find_unknown_options
+      detect_help_option
+      flatten_stacked_shorthand_options
+      detect_unknown_options
       parse_options
 
       validate_number_of_arguments
@@ -46,7 +51,7 @@ class OptionsByExample
 
     private
 
-    def find_help_option
+    def detect_help_option
       @chunks.each do |option, *args|
         case option
         when '-h', '--help'
@@ -55,7 +60,36 @@ class OptionsByExample
       end
     end
 
-    def find_unknown_options
+    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
@@ -72,7 +106,28 @@ class OptionsByExample
 
         if argument_name
           raise "Expected argument for option '#{option}', got none" if args.empty?
-          @arguments[option_name] = args.shift
+          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
@@ -82,10 +137,17 @@ class OptionsByExample
     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

data/lib/options_by_example/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class OptionsByExample
-  VERSION = '2.0.0'
+  VERSION = '3.1.0'
 end
 
 
@@ -11,6 +11,20 @@ __END__
 # Minor version bump when backward-compatible changes or enhancements
 # Patch version bump when backward-compatible bug fixes, security updates etc
 
+3.1.0
+
+  - Support dash in argument and option names
+  - Method #if_present passes argument to block if present
+  - Method #include? return true if option is present
+
+3.0.0
+
+  - Support options with default values
+  - Improved support for one-line usage messages
+  - Expand combined shorthand options into their separate components
+  - Shorthand options must be single letter only
+  - Support options with typed arguments
+
 2.0.0
 
   - Replaced dynamic methods with explicit methods for options and arguments

data/lib/options_by_example.rb

@@ -23,10 +23,10 @@ class OptionsByExample
     #
     # Usage: connect [options] [mode] host port
 
-    text =~ /Usage: (\w+|\$0)( \[options\])?(( \[\w+\])*)(( \w+)*)/
+    text =~ /Usage: (\$0|\w+)(?: \[options\])?((?: \[\w+\])*)((?: \w+)*)/
     raise RuntimeError, "Expected usage string, got none" unless $1
-    @argument_names_optional = $3.to_s.split.map { |match| match.tr('[]', '').downcase }
-    @argument_names_required = $5.to_s.split.map(&:downcase)
+    @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 ---------------------------------------
     #
@@ -37,12 +37,14 @@ class OptionsByExample
     #   -s, --secure        Use secure connection
     #   -v, --verbose       Enable verbose output
     #   -r, --retries NUM   Number of connection retries (default 3)
-    #   -t, --timeout NUM   Connection timeout in seconds (default 10)
+    #   -t, --timeout NUM   Set connection timeout in seconds
 
     @option_names = {}
-    text.scan(/((--?\w+)(, --?\w+)*) ?(\w+)?/) do
-      opts = $1.split(", ")
-      opts.each { |each| @option_names[each] = [opts.last.tr('-', ''), $4] }
+    @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
 
     initialize_argument_accessors
@@ -63,6 +65,7 @@ class OptionsByExample
     parser = Parser.new(
       @argument_names_required,
       @argument_names_optional,
+      @default_values,
       @option_names,
     )
 
@@ -73,6 +76,17 @@ class OptionsByExample
     return self
   end
 
+  def if_present(name)
+    raise ArgumentError, 'block missing' unless block_given?
+
+    value = @arguments[name]
+    value.nil? ? value : (yield value)
+  end
+
+  def include?(name)
+    @options.include?(name)
+  end
+
   private
 
   def initialize_argument_accessors
@@ -83,7 +97,7 @@ class OptionsByExample
     ].each do |argument_name|
       instance_eval %{
         def argument_#{argument_name}
-          val = @arguments["#{argument_name}"]
+          val = @arguments[:#{argument_name}]
           val && block_given? ? (yield val) : val
         end
       }
@@ -94,10 +108,14 @@ class OptionsByExample
     @option_names.each_value do |option_name, _|
       instance_eval %{
         def include_#{option_name}?
-          @options.include? "#{option_name}"
+          @options.include? :#{option_name}
         end
       }
     end
   end
+
+  def sanitize(string)
+    string.tr('^a-zA-Z0-9', '_').downcase.to_sym
+  end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: options_by_example
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Adrian Kuhn
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-30 00:00:00.000000000 Z
+date: 2023-05-25 00:00:00.000000000 Z
 dependencies: []
 description:
 email: