consoler 1.0.1 → 1.2.1

data/lib/consoler/arguments.rb

@@ -3,7 +3,6 @@
 require_relative 'matcher'
 
 module Consoler
-
   # Arguments
   #
   # @attr_reader [Array<String>] args Raw arguments

data/lib/consoler/command.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Consoler
-
   # Consoler command
   #
   # Basically a named hash

data/lib/consoler/matcher.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 module Consoler
-
   # Argument/Options matcher
   #
   # Given a list of arguments and a list option try to match them
   class Matcher
-
     # Create a matcher
     #
     # @param [Consoler::Arguments] arguments List of arguments
@@ -26,13 +24,15 @@ module Consoler
     def match
       parse_options = true
 
-      loop_args do |arg|
-        unless parse_options then
+      _loop_args do |arg|
+        unless parse_options
           @argument_values.push arg
           next
         end
 
-        if arg == '--' then
+        # when "argument" is --, then stop parsing the rest of the arguments
+        # and treat the rest as regular arguments
+        if arg == '--'
           parse_options = false
           next
         end
@@ -47,126 +47,189 @@ module Consoler
       remaining = _match_arguments
       _fill_defaults
 
-      if @matched_options.size == @options.size then
+      if @matched_options.size == @options.size
         @matched_options['remaining'] = remaining
+
+        # make sure all aliases are also filled
+        @options.each do |option|
+          option.aliases.each do |alias_|
+            @matched_options[alias_.name] = @matched_options[option.name]
+          end
+        end
+
         return @matched_options
       end
 
-      return nil
+      nil
     end
 
     private
 
+    # Analyze a single argument
+    #
+    # @param [String] arg Single argument
+    # @return [true, nil] true on success, nil on failure
     def _analyze(arg)
       is_long = false
       is_short = false
       name = nil
 
-      if arg[0..1] == '--' then
+      if arg[0..1] == '--'
         is_long = true
         name = arg[2..-1]
-      elsif arg[0] == '-' then
+      elsif arg[0] == '-'
         is_short = true
         name = arg[1..-1]
       end
 
-      if name.nil?
+      # arg is not a long/short option, add to arguments values
+      unless is_long || is_short
         @argument_values.push arg
         return true
       end
 
-      unless name.nil? then
-        option_name = if is_short then
+      unless name.nil?
+        # get the name of the option, short options use the first character
+        option_name = if is_short
                         name[0]
                       else
                         name
                       end
 
-        option = @options.get option_name
+        option, matched = @options.get_with_alias option_name
 
+        # no option by this name in options
         return nil if option.nil?
 
-        needs_short = option.is_short
-        needs_long = option.is_long
-
-        if needs_long and not is_long then
+        # see if the type if right, short or long
+        if matched.is_long && !is_long
           return nil
-        elsif needs_short and not is_short then
+        elsif matched.is_short && !is_short
           return nil
         end
 
-        if is_long then
-          if option.is_value then
-            return nil if peek_next.nil?
-            @matched_options[name] = peek_next
-            skip
+        if is_long
+          if option.is_value
+            # is_value needs a next argument for its value
+            return nil if _peek_next.nil?
+
+            @matched_options[option.name] = _peek_next
+            _skip_next
           else
-            @matched_options[name] = true
+            option_value! option
           end
         end
 
-        if is_short then
-          if name.size == 1 and option.is_value then
-            return nil if peek_next.nil?
-            @matched_options[name] = peek_next
-            skip
+        if is_short
+          if name.size == 1 && option.is_value
+            # is_value needs a next argument for its value
+            return nil if _peek_next.nil?
+
+            @matched_options[option.name] = _peek_next
+            _skip_next
           else
+            # for every character (short option) increment the option value
             name.split('').each do |n|
-              if @matched_options[n].nil? then
-                @matched_options[n] = 0
-              end
+              short_option = @options.get n
+              return nil if short_option.nil?
 
-              @matched_options[n] += 1
+              option_value! short_option
             end
           end
         end
       end
 
-      return true
+      true
     end
 
-    def current
-      @arguments.args[@index]
-    end
+    # Set the value of an option
+    #
+    # Long or short option needed
+    #
+    # @param [Consoler::Option]
+    def option_value!(option)
+      if option.is_short
+        if @matched_options[option.name].nil?
+          @matched_options[option.name] = 0
+        end
 
-    def peek_next
-      @arguments.args[@index + 1]
+        @matched_options[option.name] += 1
+      else
+        @matched_options[option.name] = true
+      end
     end
 
-    def loop_args
+    # Loop through the arguments
+    #
+    # @yield [String] An argument
+    # @return [Consoler::Matcher]
+    def _loop_args
       @index = 0
       size = @arguments.args.size
 
-      while @index < size do
-        yield current
+      # use an incrementing index, to be able to peek to the next in the list
+      # and to skip an item
+      while @index < size
+        yield @arguments.args[@index]
 
-        skip
+        _skip_next
       end
+
+      self
+    end
+
+    # Peek at the next argument
+    #
+    # Only useful inside {Consoler::Matcher#_loop_args}
+    #
+    # @return [String, nil]
+    def _peek_next
+      @arguments.args[@index + 1]
     end
 
-    def skip
+    # Skip to the next argument
+    #
+    # Useful if you use a peeked argument
+    #
+    # @return [nil]
+    # @return [Consoler::Matcher]
+    def _skip_next
       @index += 1
+
+      self
     end
 
+    # Match arguments to defined option arguments
+    #
+    # @return [Array<String>, nil] The remaining args,
+    #                              or <tt>nil</tt> if there are not enough arguments
     def _match_arguments
       @optionals_before = {}
       @optionals_before_has_remaining = false
 
+      total_argument_values = @argument_values.size
       argument_values_index = 0
 
       _match_arguments_optionals_before
 
       @optionals_before.each do |mandatory_arg_name, optionals|
+        # fill the optional argument option with a value if there are enough
+        # arguments supplied (info available from optionals map)
         optionals.each do |_, optional|
           optional.each do |before|
-            if before[:included] then
+            if before[:included]
+              return nil if argument_values_index >= total_argument_values
+
               @matched_options[before[:name]] = @argument_values[argument_values_index]
               argument_values_index += 1
             end
           end
         end
 
-        if mandatory_arg_name != :REMAINING then
+        # only fill mandatory argument if its not the :REMAINING key
+        if mandatory_arg_name != :REMAINING
+          return nil if argument_values_index >= total_argument_values
+
           @matched_options[mandatory_arg_name] = @argument_values[argument_values_index]
           argument_values_index += 1
         end
@@ -174,7 +237,8 @@ module Consoler
 
       remaining = []
 
-      while argument_values_index < @argument_values.size do
+      # left over arguments
+      while argument_values_index < @argument_values.size
         remaining.push @argument_values[argument_values_index]
         argument_values_index += 1
       end
@@ -182,78 +246,108 @@ module Consoler
       remaining
     end
 
+    # Create a map of all optionals and before which mandatory argument they appear
+    #
+    # @return [Consoler::Matcher]
     def _match_arguments_optionals_before
       @optionals_before = {}
       tracker = {}
 
-      @options.each do |option, key|
+      @options.each do |option, _key|
         next unless option.is_argument
 
-        if option.is_optional then
+        if option.is_optional
+          # setup tracker for optional group
           tracker[option.is_optional] = [] if tracker[option.is_optional].nil?
 
-          tracker[option.is_optional].push({
+          # mark all optionals as not-included
+          tracker[option.is_optional].push(
             included: false,
             name: option.name,
-          })
+          )
         else
           @optionals_before[option.name] = tracker
           tracker = {}
         end
       end
 
-      if tracker != {} then
+      # make sure all optionals are accounted for in the map
+      if tracker != {}
+        # use a special key so we can handle it differently in the filling process
         @optionals_before[:REMAINING] = tracker
         @optionals_before_has_remaining = true
       end
 
-      _match_arguments_optoins_before_matcher
+      _match_arguments_options_before_matcher
+
+      self
     end
 
-    def _match_arguments_optoins_before_matcher
+    # Match remaining args against the optionals map
+    #
+    # @return [Consoler::Matcher]
+    def _match_arguments_options_before_matcher
+      # number of arguments that are needed to fill our mandatory argument options
       mandatories_matched = @optionals_before.size
 
-      if @optionals_before_has_remaining then
+      # there are optionals at the end of the options, don't match the void
+      if @optionals_before_has_remaining
         mandatories_matched -= 1
       end
 
       total = 0
 
+      # loop through optional map
       _each_optional_before_sorted do |before|
-        if (total + before.size + mandatories_matched) <= @argument_values.size then
+        # are there enough arguments left to fill this optional group
+        if (total + before.size + mandatories_matched) <= @argument_values.size
           total += before.size
 
           before.each do |val|
-            val[:included] = true;
+            val[:included] = true
           end
         end
       end
+
+      self
     end
 
+    # Give all unmatched optional options there default value
+    #
+    # @return [Consoler::Matcher]
     def _fill_defaults
       @options.each do |option|
-        if option.is_optional then
-          unless @matched_options.has_key? option.name then
-            @matched_options[option.name] = option.default_value
-          end
+        next unless option.is_optional
+
+        unless @matched_options.key? option.name
+          @matched_options[option.name] = option.default_value
         end
       end
+
+      self
     end
 
+    # Loop through the optionals before map
+    #
+    # Sorted by number of optionals in a group
+    #
+    # @return [Consoler::Matcher]
     def _each_optional_before_sorted
       @optionals_before.each do |_, optionals|
         tmp = []
         optionals.each do |optional_index, before|
-          tmp.push({
+          tmp.push(
             count: before.size,
             index: optional_index,
-          })
+          )
         end
 
         tmp.sort! { |a, b| b[:count] - a[:count] }.each do |item|
           yield optionals[item[:index]]
         end
       end
+
+      self
     end
   end
 end

data/lib/consoler/option.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Consoler
-
   # Represents an option
   #
   # @attr_reader [String] name Name of the options
@@ -10,6 +9,7 @@ module Consoler
   # @attr_reader [Boolean] is_argument Is the option an argument
   # @attr_reader [Boolean] is_value Does the option need a value (<tt>--option=</tt>)
   # @attr_reader [Integer] is_optional Is the option optional (> 0) (<tt>[option]</tt>)
+  # @attr_reader [Array] aliases List of aliases of option (<tt>-v|--verbose</tt>)
   class Option
     attr_reader :name
     attr_reader :is_long
@@ -17,6 +17,7 @@ module Consoler
     attr_reader :is_argument
     attr_reader :is_value
     attr_reader :is_optional
+    attr_reader :aliases
 
     # Create a option
     #
@@ -27,11 +28,14 @@ module Consoler
     def self.create(option_def, tracker)
       option = Option.new option_def, tracker
 
-      if option.is_short and option.name.size > 1 then
+      # split short options with more than 1 char in multiple options
+      if option.is_short && option.name.size > 1
+        # remember state
         old_tracking = tracker.is_tracking
         old_is_value = option.is_value
 
-        if option.is_optional then
+        # if the complete option is optional, fake the tracker
+        if option.is_optional
           tracker.is_tracking = true
         end
 
@@ -40,13 +44,15 @@ module Consoler
         names.each_with_index do |name, i|
           new_name = "-#{name}"
 
-          if old_is_value and i == names.count - 1 then
+          # if the short option should have a value, this only counts for the last option
+          if old_is_value && i == names.count - 1
             new_name = "#{new_name}="
           end
 
           yield Option.new new_name, tracker
         end
 
+        # reset to saved state
         tracker.is_tracking = old_tracking
       else
         yield option
@@ -62,14 +68,20 @@ module Consoler
     def to_definition
       definition = name
 
-      if is_long then
+      if is_long
         definition = "--#{definition}"
-      elsif is_short then
+      elsif is_short
         definition = "-#{definition}"
       end
 
-      if is_value then
+      if is_value
         definition = "#{definition}="
+      elsif is_argument
+        definition = "<#{definition}>"
+      end
+
+      aliases.each do |alias_|
+        definition = "#{definition}|#{alias_.to_definition}"
       end
 
       definition
@@ -83,7 +95,7 @@ module Consoler
       return 0 if is_short
       return false if is_long
 
-      return nil
+      nil
     end
 
     protected
@@ -92,29 +104,61 @@ module Consoler
     #
     # @param [String] option_def Definition of the option
     # @param [Consoler::Tracker] tracker tracker
+    # @raise [RuntimeError] if the option name is empty
+    # @raise [RuntimeError] if the option is long _and_ short
     def initialize(option_def, tracker)
-      option, @is_optional = _is_optional option_def, tracker
+      # Check for multiple attributes in the option definition till we got the
+      # final name and all of its attributes
+
+      # make sure we don't wrongly process any alias
+      alias_defs = option_def.split '|'
+      option = alias_defs.shift || ''
+
+      option, @is_optional = _is_optional option, tracker
       option, @is_long = _is_long option
       option, @is_short = _is_short option
-      @is_argument = (not @is_long and not @is_short)
+      @is_argument = (!@is_long && !@is_short)
       option, @is_value = _value option, @is_argument
+      option, @aliases = _aliases option, alias_defs, tracker
+
+      if option[0] == '<'
+        raise 'Invalid <, missing >' if option[-1] != '>'
+        raise 'Only arguments support <, > around name' unless @is_argument
+
+        option = option[1..-2]
+      end
+
+      raise 'Missing starting <' if option[-1] == '>'
 
       @name = option
 
-      if @name.empty? then
+      if @name.empty?
         raise 'Option must have a name'
       end
 
-      if @is_long and @is_short
+      if @is_long && @is_short
         raise 'Option can not be a long and a short option'
       end
     end
 
     private
 
+    # Check optional definition
+    #
+    # Does it open an optional group
+    # Does it close an optional group (can be both)
+    # Updates the tracker
+    # Removes leading [ and trailing ]
+    #
+    # @param [String] option Option definition
+    # @param [Consoler::Tracker] tracker Optional tracker
+    # @raise [RuntimeError] if you try to nest optional groups
+    # @raise [RuntimeError] if you try to close an unopened optional
+    # @return [(String, Integer|nil)] Remaining option definition, and, optional group if available
     def _is_optional(option, tracker)
-      if option[0] == '[' then
-        if !tracker.is_tracking then
+      if option[0] == '['
+        if !tracker.is_tracking
+          # mark tracker as tracking
           tracker.is_tracking = true
           tracker.index += 1
           option = option[1..-1]
@@ -123,14 +167,14 @@ module Consoler
         end
       end
 
-      optional = if tracker.is_tracking then
+      # get optional group index from tracking, if tracking
+      optional = if tracker.is_tracking
                    tracker.index
-                 else
-                   nil
                  end
 
-      if option[-1] == ']' then
-        if tracker.is_tracking then
+      if option[-1] == ']'
+        if tracker.is_tracking
+          # mark tracker as non-tracking
           tracker.is_tracking = false
           option = option[0..-2]
         else
@@ -138,34 +182,47 @@ module Consoler
         end
       end
 
-      return option, optional
+      [option, optional]
     end
 
+    # Check long definition
+    #
+    # @param [String] option Option definition
+    # @return [(String, Boolean)]
     def _is_long(option)
-      if option[0..1] == '--' then
+      if option[0..1] == '--'
         long = true
         option = option[2..-1]
       else
         long = false
       end
 
-      return option, long
+      [option, long]
     end
 
+    # Check short definition
+    #
+    # @param [String] option Option definition
+    # @return [(String, Boolean)]
     def _is_short(option)
-      if option[0] == '-' then
+      if option[0] == '-'
         short = true
         option = option[1..-1]
       else
         short = false
       end
 
-      return option, short
+      [option, short]
     end
 
+    # Check value definition
+    #
+    # @param [String] option Option definition
+    # @raise [RuntimeError] if you try to assign a value to an argument
+    # @return [(String, Boolean)]
     def _value(option, argument)
-      if option[-1] == '=' then
-        if argument then
+      if option[-1] == '='
+        if argument
           raise 'Arguments can\'t have a value'
         end
 
@@ -175,7 +232,36 @@ module Consoler
         value = false
       end
 
-      return option, value
+      [option, value]
+    end
+
+    # Parse all possible aliases
+    #
+    # @param [String] option Option definition
+    # @param [Consoler::Tracker] tracker Optional tracker
+    # @raise [RuntimeError] On all kinds of occasions
+    # @return [(String, Array)] Remaining option definition, and, aliases if available
+    def _aliases(option, alias_defs, tracker)
+      return option, [] if alias_defs.empty?
+
+      raise 'Argument can\'t have aliases' if is_argument
+      raise 'Aliases are not allowed for multiple short options' if is_short && option.size > 1
+
+      aliases_ = []
+      alias_names = []
+
+      while (alias_def = alias_defs.shift)
+        Consoler::Option.create alias_def, tracker do |alias_|
+          raise "Duplicate alias name: #{alias_.name}" if alias_names.include? alias_.name
+          raise "Alias must have a value: #{alias_.name}" if is_value && !alias_.is_value
+          raise "Alias can't have a value: #{alias_.name}" if !is_value && alias_.is_value
+
+          aliases_.push alias_
+          alias_names.push alias_.name
+        end
+      end
+
+      [option, aliases_]
     end
   end
 end