options_by_example 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d803c63947acbb818c4fbf749cdb18084e6b0750678f9e600369ce543b78536
-  data.tar.gz: 21d6c8a4866627102f82d12a2805eb60850e6a24eb04d0ec064ea5af55dd87a2
+  metadata.gz: 26769b40ccdbee8bcb810e85755f7e3774145dda2ea8860edda1c99a65e168a5
+  data.tar.gz: 5d11ede203262af12bb65613ea5d153bb699188443453d82f8fb5bccb13068a1
 SHA512:
-  metadata.gz: a6e16dbd993f098415710aacd89e859ff9ac9403256a648a51fd4ab7754d91aa473e8c5b53f055ab0378d4acf1977e6b30f8826d1a626f6bcdeef4e0eb15e233
-  data.tar.gz: b9dcfa2249f316554b416f788109486caecefdc68c8d48890cc3e0033a3270509bea96fbe994931413bae7160c035e8968f63f855e59f522d67149d20e7fc15b
+  metadata.gz: 1cb7a3d1732b19543557ed113094204451f9d24e2fae91029aa19d3f2985482e5536cc8c185e1dbef15fd77d330dd7ea76e7d0a6c596f7e198278f4afdf3bc74
+  data.tar.gz: 61a4d2a408fbe795040f7963e6d9cdb82076872bf7118c7fbb633b940684bd5eed9884f2d4a3f73cc4f321eb4e976d9ff5b252a17694a6316c4849314a5aa586

data/lib/options_by_example/parser.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+
+class OptionsByExample
+  class Parser
+
+    attr_reader :options
+    attr_reader :arguments
+
+    def initialize(argument_names_required, argument_names_optional, option_names)
+      @argument_names_required = argument_names_required
+      @argument_names_optional = argument_names_optional
+      @option_names = option_names
+
+      @arguments = {}
+      @options = {}
+    end
+
+    def parse(array)
+
+      # Separate command-line options and their respective arguments into
+      # chunks plus handling any remaining 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
+
+      find_help_option
+      find_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 find_help_option
+      @chunks.each do |option, *args|
+        case option
+        when '-h', '--help'
+          raise "puts @usage_message"
+        end
+      end
+    end
+
+    def find_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?
+          @arguments[option_name] = args.shift
+        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
+    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

data/lib/options_by_example/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class OptionsByExample
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
 end
 
 
@@ -11,10 +11,20 @@ __END__
 # Minor version bump when backward-compatible changes or enhancements
 # Patch version bump when backward-compatible bug fixes, security updates etc
 
-1.0.1
+1.3.0
 
-  - Update readme file with features and an example
+  - Extract parsing functionality into class
+  - Better error messages
+
+1.2.0
+
+  - Ensure compatibility with Ruby versions 1.9.3 and newer
+
+1.1.0
+
+  - Renamed the gem from usage_by_example to options_by_example
   - Update the gemspec to include readme and ruby files only
+  - Update readme file with features and an example
 
 1.0.0
 

data/lib/options_by_example.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "options_by_example/version"
+require 'options_by_example/version'
+require 'options_by_example/parser'
 
 
 class OptionsByExample
@@ -18,21 +19,22 @@ class OptionsByExample
   end
 
   def initialize(text)
-    @usage = text.gsub('$0', File.basename($0)).gsub(/\n+\Z/, "\n\n")
+    @settings = {exit_on_error: true}
+    @usage_message = text.gsub('$0', File.basename($0)).gsub(/\n+\Z/, "\n\n")
 
-    # ---- 1) Parse argument names ------------------------------------
+    # --- 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: (\w+|\$0) \[options\](( \[\w+\])*)(( \w+)*)/
+    text =~ /Usage: (\w+|\$0)( \[options\])?(( \[\w+\])*)(( \w+)*)/
     raise RuntimeError, "Expected usage string, got none" unless $1
-    @argument_names_optional = $2.to_s.split.map { |match| match.tr('[]', '').downcase }
-    @argument_names_required = $4.to_s.split.map(&:downcase)
+    @argument_names_optional = $3.to_s.split.map { |match| match.tr('[]', '').downcase }
+    @argument_names_required = $5.to_s.split.map(&:downcase)
 
-    # ---- 2) Parse option names --------------------------------------
+    # --- 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:
@@ -46,81 +48,42 @@ class OptionsByExample
     @option_names = {}
     text.scan(/((--?\w+)(, --?\w+)*) ?(\w+)?/) do
       opts = $1.split(", ")
-      opts.each { |each| @option_names[each] = [opts.last.tr('-', ''), $4&.downcase] }
+      opts.each { |each| @option_names[each] = [opts.last.tr('-', ''), $4] }
     end
-
-    # ---- 3) Include help option by default --------------------------
-
-    @option_names.update("-h" => :help, "--help" => :help)
   end
 
-  def parse(argv, exit_on_error: true)
-    array = argv.dup
-    @arguments = {}
-    @options = {}
-
-    # --- 1) Parse options --------------------------------------------
-
-    most_recent_option = nil
-    until array.empty? do
-      break unless array.first.start_with?(?-)
-      most_recent_option = option = array.shift
-      option_name, argument_name = @option_names[option]
-      raise "Got unknown option #{option}" if option_name.nil?
-      raise if option_name == :help # Show usage without error message
-      @options[option_name] = true
-
-      # Consume argument, if expected by most recent option
-      if argument_name
-        argument = array.shift
-        raise "Expected argument for option #{option}" unless /^[^-]/ === argument
-        @arguments[option_name] = argument
-        most_recent_option = nil
-      end
-    end
-
-    # --- 2) Parse optional arguments ---------------------------------
+  def use(settings)
+    @settings.update settings
 
-    # Check any start with --, ie excess options
-    # Check min_length - max_length here
-
-    stash = array.pop(@argument_names_required.length)
-    @argument_names_optional.each do |argument_name|
-      break if array.empty?
-      argument = array.shift
-      raise "Expected more arguments, got option #{option}" unless /^[^-]/ === argument
-      @arguments[argument_name] = argument
-    end
-
-    # --- 3) Parse required arguments ---------------------------------
+    return self
+  end
 
-    @argument_names_required.each do |argument_name|
-      raise "Expected required argument #{argument_name.upcase}, got none" if stash.empty?
-      argument = stash.shift
-      raise "Expected more arguments, got option #{option}" unless /^[^-]/ === argument
-      @arguments[argument_name] = argument
-    end
+  def parse(argv)
+    parser = Parser.new(
+      @argument_names_required,
+      @argument_names_optional,
+      @option_names,
+    )
 
-    # --- 4) Expect to be done ----------------------------------------
+    parser.parse argv
 
-    if not array.empty?
-      # Custom error message if most recent option did not require argument
-      raise "Got unexpected argument for option #{most_recent_option}" if most_recent_option
-      raise "Expected #{min_length}#{"-#{max_length}" if max_length > min_length} arguments, got more"
-    end
+    @options = parser.options
+    @arguments = parser.arguments
 
     return self
-
   rescue RuntimeError => err
-    if exit_on_error
-      puts "ERROR: #{err.message}\n\n" unless err.message.empty?
-      puts @usage
-      exit
+    raise unless @settings[:exit_on_error]
+
+    if err.message == "puts @usage_message"
+      puts @usage_message
     else
-      raise # Reraise the same exception
+      puts "ERROR: #{err.message}"
     end
+
+    exit 1
   end
 
+
   def method_missing(sym, *args, &block)
     case sym
     when /^argument_(\w+)$/

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: options_by_example
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Adrian Kuhn
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-28 00:00:00.000000000 Z
+date: 2023-04-29 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/options_by_example.rb
+- lib/options_by_example/parser.rb
 - lib/options_by_example/version.rb
 homepage: https://github.com/akuhn/options_by_example
 licenses:
@@ -34,7 +35,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="