options_by_example 1.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26769b40ccdbee8bcb810e85755f7e3774145dda2ea8860edda1c99a65e168a5
-  data.tar.gz: 5d11ede203262af12bb65613ea5d153bb699188443453d82f8fb5bccb13068a1
+  metadata.gz: 98c16609314706667d2b776fa71de92ca874b2fcc803ea8f80387fe4f0245d9a
+  data.tar.gz: 8cc7023f98016edaa5521d6184985fb4133135e902f0380f81e233b6f52bfb97
 SHA512:
-  metadata.gz: 1cb7a3d1732b19543557ed113094204451f9d24e2fae91029aa19d3f2985482e5536cc8c185e1dbef15fd77d330dd7ea76e7d0a6c596f7e198278f4afdf3bc74
-  data.tar.gz: 61a4d2a408fbe795040f7963e6d9cdb82076872bf7118c7fbb633b940684bd5eed9884f2d4a3f73cc4f321eb4e976d9ff5b252a17694a6316c4849314a5aa586
+  metadata.gz: a4e54eeb9f5beef88733ac4c70055570eeff930ccacd287f88b80905bd1760b6b1ec3513c5ea144d1c7cdc259af7d4991f81c5be82249cecb2f939d291d29032
+  data.tar.gz: 9126c11cba93c504fd41939dfa24c62578889b8546b9f472091a9463eed4cc6e3f409ff7e40a8219ce9a70913ae63872486745629431290e8f87dec6edf351be

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,25 +1,33 @@
 # 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, 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 = []
@@ -29,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
@@ -42,16 +51,45 @@ class OptionsByExample
 
     private
 
-    def find_help_option
+    def detect_help_option
       @chunks.each do |option, *args|
         case option
         when '-h', '--help'
-          raise "puts @usage_message"
+          raise PrintUsageMessage
         end
       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
@@ -68,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
@@ -78,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 = '1.3.0'
+  VERSION = '3.0.0'
 end
 
 
@@ -11,9 +11,21 @@ __END__
 # Minor version bump when backward-compatible changes or enhancements
 # Patch version bump when backward-compatible bug fixes, security updates etc
 
+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
+
+2.0.0
+
+  - Replaced dynamic methods with explicit methods for options and arguments
+  - Removed ability to call dynamic methods with undeclared names
+
 1.3.0
 
-  - Extract parsing functionality into class
+  - Extracted parsing functionality into class
   - Better error messages
 
 1.2.0

data/lib/options_by_example.rb

@@ -6,20 +6,14 @@ require 'options_by_example/parser'
 
 class OptionsByExample
 
-  attr_reader :argument_names_optional
-  attr_reader :argument_names_required
-  attr_reader :option_names
-
   attr_reader :arguments
   attr_reader :options
 
-
   def self.read(data)
     return new data.read
   end
 
   def initialize(text)
-    @settings = {exit_on_error: true}
     @usage_message = text.gsub('$0', File.basename($0)).gsub(/\n+\Z/, "\n\n")
 
     # --- 1) Parse argument names -------------------------------------
@@ -29,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| match.tr('[]', '').downcase }
+    @argument_names_required = $3.to_s.split.map(&:downcase)
 
     # --- 2) Parse option names ---------------------------------------
     #
@@ -43,56 +37,69 @@ 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] = [$3, $4] }
+      @default_values[$3] = $5 if $5
     end
-  end
 
-  def use(settings)
-    @settings.update settings
-
-    return self
+    initialize_argument_accessors
+    initialize_option_accessors
   end
 
   def parse(argv)
+    parse_without_exit argv
+  rescue PrintUsageMessage
+    puts @usage_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
-
-    @options = parser.options
     @arguments = parser.arguments
+    @options = parser.options
 
     return self
-  rescue RuntimeError => err
-    raise unless @settings[:exit_on_error]
+  end
 
-    if err.message == "puts @usage_message"
-      puts @usage_message
-    else
-      puts "ERROR: #{err.message}"
+  private
+
+  def initialize_argument_accessors
+    [
+      *@argument_names_required,
+      *@argument_names_optional,
+      *@option_names.values.select(&:last).map(&:first),
+    ].each do |argument_name|
+      instance_eval %{
+        def argument_#{argument_name}
+          val = @arguments["#{argument_name}"]
+          val && block_given? ? (yield val) : val
+        end
+      }
     end
-
-    exit 1
   end
 
-
-  def method_missing(sym, *args, &block)
-    case sym
-    when /^argument_(\w+)$/
-      val = @arguments[$1]
-      block && val ? block.call(val) : val
-    when /^include_(\w+)\?$/
-      @options[$1]
-    else
-      super
+  def initialize_option_accessors
+    @option_names.each_value do |option_name, _|
+      instance_eval %{
+        def include_#{option_name}?
+          @options.include? "#{option_name}"
+        end
+      }
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: options_by_example
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Adrian Kuhn
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-29 00:00:00.000000000 Z
+date: 2023-05-17 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -27,6 +27,7 @@ licenses:
 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: