rubycli 0.1.7 → 0.2.0

data/lib/rubycli/argument_parser.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 require 'did_you_mean'
+require 'ripper'
 
 require_relative 'type_utils'
 require_relative 'arguments/token_stream'
@@ -8,6 +11,8 @@ module Rubycli
   class ArgumentParser
     include TypeUtils
 
+    OPTION_TOKEN_PATTERN = /\A-{1,2}([a-zA-Z0-9_-]+)(?:=(.*))?\z/
+
     def initialize(environment:, documentation_registry:, json_coercer:, debug_logger:)
       @environment = environment
       @documentation_registry = documentation_registry
@@ -18,9 +23,11 @@ module Rubycli
 
     def parse(args, method = nil)
       pos_args = []
+      raw_pos_args = []
       kw_args = {}
 
       kw_param_names = extract_keyword_parameter_names(method)
+      required_kw_param_names = extract_required_keyword_parameter_names(method)
       debug_log "Available keyword parameters: #{kw_param_names.inspect}"
 
       metadata = method ? @documentation_registry.metadata_for(method) : { options: [], returns: [], summary: nil }
@@ -28,6 +35,9 @@ module Rubycli
       cli_aliases = build_cli_alias_map(option_defs)
       option_lookup = build_option_lookup(option_defs)
       type_converters = build_type_converter_map(option_defs)
+      known_option_names = (
+        kw_param_names + cli_aliases.keys + option_lookup.keys.map(&:to_s)
+      ).uniq
 
       stream = Arguments::TokenStream.new(args)
 
@@ -36,8 +46,9 @@ module Rubycli
 
         if token == '--'
           stream.advance
-          rest_tokens = stream.consume_remaining.map { |value| convert_arg(value) }
-          pos_args.concat(rest_tokens)
+          rest_tokens = stream.consume_remaining
+          raw_pos_args.concat(rest_tokens)
+          pos_args.concat(rest_tokens.map { |value| convert_arg(value) })
           break
         elsif option_token?(token)
           stream.advance
@@ -48,18 +59,21 @@ module Rubycli
             kw_args,
             cli_aliases,
             option_lookup,
-            type_converters
+            type_converters,
+            required_kw_param_names,
+            known_option_names
           )
-        elsif assignment_token?(token)
+        elsif assignment_token_for_method?(token, method, kw_param_names)
           stream.advance
-          process_assignment_token(token, kw_args)
+          process_assignment_token(token, kw_args, option_lookup, type_converters)
         else
+          raw_pos_args << token
           pos_args << convert_arg(token)
           stream.advance
         end
       end
 
-      pos_args = convert_positional_arguments(pos_args, method, metadata)
+      pos_args = convert_positional_arguments(pos_args, raw_pos_args, method, metadata)
       debug_log "Final parsed - pos_args: #{pos_args.inspect}, kw_args: #{kw_args.inspect}"
       [pos_args, kw_args]
     end
@@ -88,12 +102,27 @@ module Rubycli
             .map { |_, name| name.to_s }
     end
 
+    def extract_required_keyword_parameter_names(method)
+      return [] unless method
+
+      method.parameters
+            .select { |type, _| type == :keyreq }
+            .map { |_, name| name.to_s }
+    end
+
+    # Tokens such as -5, -1_000 and -0x10 match the option pattern, but no Ruby
+    # keyword can be named after a number, so they are values, not options.
     def option_token?(token)
-      token =~ /\A-{1,2}([a-zA-Z0-9_-]+)(?:=(.*))?\z/
+      token.match?(OPTION_TOKEN_PATTERN) && looks_like_option?(token)
     end
 
-    def assignment_token?(token)
-      !split_assignment_token(token).nil?
+    def assignment_token_for_method?(token, method, kw_param_names)
+      key, = split_assignment_token(token)
+      return false unless key
+      return true unless method
+      return true if kw_param_names.include?(key)
+
+      method.parameters.any? { |type, _| type == :keyrest }
     end
 
     def process_option_token(
@@ -103,9 +132,11 @@ module Rubycli
       kw_args,
       cli_aliases,
       option_lookup,
-      type_converters
+      type_converters,
+      required_kw_param_names,
+      known_option_names
     )
-      token =~ /\A-{1,2}([a-zA-Z0-9_-]+)(?:=(.*))?\z/
+      token =~ OPTION_TOKEN_PATTERN
       cli_key = Regexp.last_match(1).tr('-', '_')
       embedded_value = Regexp.last_match(2)
 
@@ -117,7 +148,11 @@ module Rubycli
       final_key_sym = final_key.to_sym
 
       option_meta = option_lookup[final_key_sym]
-      requires_value = option_meta ? option_meta[:requires_value] : nil
+      requires_value = if option_meta
+                         option_meta[:requires_value]
+                       else
+                         required_kw_param_names.include?(final_key)
+                       end
       option_label = option_meta&.long || "--#{final_key.tr('_', '-')}"
 
       value_capture = if embedded_value
@@ -126,17 +161,18 @@ module Rubycli
                         capture_option_value(
                           option_meta,
                           stream,
-                          requires_value
+                          requires_value,
+                          known_option_names
                         )
+                      elsif requires_value
+                        capture_required_option_value(option_label, stream, known_option_names)
                       elsif (next_token = stream.current) && !looks_like_option?(next_token)
                         stream.consume
                       else
                         'true'
                       end
 
-      if requires_value && (value_capture.nil? || value_capture == 'true')
-        raise ArgumentError, "Option '#{option_label}' requires a value"
-      end
+      raise ArgumentError, "Option '#{option_label}' requires a value" if requires_value && value_capture.nil?
 
       converted_value = convert_option_value(
         final_key_sym,
@@ -147,34 +183,62 @@ module Rubycli
 
       kw_args[final_key_sym] = converted_value
     end
-    def capture_option_value(option_meta, stream, requires_value)
+
+    def capture_required_option_value(option_label, stream, known_option_names)
+      next_token = stream.current
+      option_like_value = looks_like_option?(next_token) &&
+                          !valid_eval_option_value?(next_token, known_option_names)
+      raise ArgumentError, "Option '#{option_label}' requires a value" if next_token.nil? || option_like_value
+
+      stream.consume
+    end
+
+    def capture_option_value(option_meta, stream, requires_value, known_option_names)
       if option_meta[:boolean_flag]
         if (next_token = stream.current) && TypeUtils.boolean_string?(next_token)
           return stream.consume
         end
-        return 'true'
+
+        'true'
       elsif option_meta[:optional_value]
         if (next_token = stream.current) && !looks_like_option?(next_token)
           return stream.consume
         end
-        return true
+
+        true
       elsif requires_value == false
-        return 'true'
+        'true'
       elsif requires_value
-        next_token = stream.current
-        raise ArgumentError, "Option '#{option_meta.long}' requires a value" unless next_token
-
-        return stream.consume
+        capture_required_option_value(option_meta.long, stream, known_option_names)
       elsif (next_token = stream.current) && !looks_like_option?(next_token)
-        return stream.consume
+        stream.consume
       else
-        return 'true'
+        'true'
       end
     end
 
-    def process_assignment_token(token, kw_args)
+    def valid_eval_option_value?(token, known_option_names)
+      return false unless Rubycli.eval_mode?
+      return false if known_option_token?(token, known_option_names)
+
+      !Ripper.sexp(token).nil?
+    end
+
+    def known_option_token?(token, known_option_names)
+      match = token&.match(OPTION_TOKEN_PATTERN)
+      return false unless match
+
+      key = match[1].tr('-', '_')
+      return true if known_option_names.include?(key)
+
+      known_option_names.one? { |name| name.start_with?(key) }
+    end
+
+    def process_assignment_token(token, kw_args, option_lookup, type_converters)
       key, value = split_assignment_token(token)
-      kw_args[key.to_sym] = convert_arg(value)
+      keyword = key.to_sym
+      option_meta = option_lookup[keyword]
+      kw_args[keyword] = convert_option_value(keyword, value, option_meta, type_converters)
     end
 
     def split_assignment_token(token)
@@ -187,33 +251,103 @@ module Rubycli
       [key, value]
     end
 
-    def convert_positional_arguments(pos_args, method, metadata)
+    def convert_positional_arguments(pos_args, raw_pos_args, method, metadata)
       return pos_args unless method
+      return pos_args if Rubycli.eval_mode? || Rubycli.json_mode?
 
       positional_map = metadata[:positionals_map] || {}
       return pos_args if positional_map.empty?
 
       converted = pos_args.dup
-      method.parameters.each_with_index do |(type, name), index|
-        next unless %i[req opt].include?(type)
+      positional_argument_bindings(method, converted.size).each do |type, name, indexes|
         definition = positional_map[name]
         next unless definition
-        next if index >= converted.size
 
-        converter = converter_for_definition(definition)
-        next unless converter
+        case type
+        when :req, :opt
+          index = indexes.first
+          next unless index
+
+          converter = converter_for_definition(definition)
+          next unless converter
+
+          begin
+            converted[index] = converter.call(raw_pos_args[index])
+          rescue StandardError => e
+            label = definition.label || definition.placeholder || name.to_s.upcase
+            raise ArgumentError, "Value '#{converted[index]}' for #{label} is invalid: #{e.message}"
+          end
+        when :rest
+          next if indexes.empty?
+
+          converter = converter_for_rest_definition(definition)
+          next unless converter
 
-        begin
-          converted[index] = converter.call(converted[index])
-        rescue StandardError => e
           label = definition.label || definition.placeholder || name.to_s.upcase
-          raise ArgumentError, "Value '#{converted[index]}' for #{label} is invalid: #{e.message}"
+          indexes.each do |index|
+            value = raw_pos_args[index]
+            converted[index] = converter.call(value)
+          rescue StandardError => e
+            raise ArgumentError, "Value '#{value}' for #{label} is invalid: #{e.message}"
+          end
         end
       end
 
       converted
     end
 
+    def positional_argument_bindings(method_obj, argument_count)
+      parameters = method_obj.parameters.select { |type, _| %i[req opt rest].include?(type) }
+      first_flexible = parameters.index { |type, _| %i[opt rest].include?(type) }
+
+      unless first_flexible
+        return parameters.each_with_index.map do |(type, name), index|
+          [type, name, index < argument_count ? [index] : []]
+        end
+      end
+
+      last_flexible = parameters.rindex { |type, _| %i[opt rest].include?(type) }
+      bindings = []
+      cursor = 0
+
+      parameters[0...first_flexible].each do |type, name|
+        indexes = cursor < argument_count ? [cursor] : []
+        bindings << [type, name, indexes]
+        cursor += 1 unless indexes.empty?
+      end
+
+      trailing = parameters[(last_flexible + 1)..] || []
+      trailing_start = [argument_count - trailing.size, cursor].max
+      middle_end = [trailing_start, argument_count].min
+
+      parameters[first_flexible..last_flexible].each do |type, name|
+        indexes = if type == :rest
+                    (cursor...middle_end).to_a
+                  elsif cursor < middle_end
+                    [cursor]
+                  else
+                    []
+                  end
+        bindings << [type, name, indexes]
+        cursor += indexes.size
+      end
+
+      trailing.each_with_index do |(type, name), offset|
+        index = trailing_start + offset
+        bindings << [type, name, index < argument_count ? [index] : []]
+      end
+
+      bindings
+    end
+
+    def converter_for_rest_definition(definition)
+      scalar_types = Array(definition.types).compact.map do |type|
+        normalized = type.to_s.strip
+        array_inner_type(normalized) || normalized
+      end
+      build_converter_for_types(scalar_types)
+    end
+
     def converter_for_definition(definition)
       types = Array(definition.types).compact
       return nil if types.empty?
@@ -225,13 +359,29 @@ module Rubycli
         if normalized.start_with?('Array<') && normalized.end_with?('>')
           inner = normalized[6..-2].strip
           element_converter = converter_for_single_type(inner)
-          return ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+          return lambda { |value|
+            list_items(value).map do |item|
+              if inner == 'String' && item.is_a?(String)
+                item
+              else
+                (element_converter ? element_converter.call(item) : item)
+              end
+            end
+          }
         elsif normalized.end_with?('[]')
           inner = normalized[0..-3]
           element_converter = converter_for_single_type(inner)
-          return ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+          return lambda { |value|
+            list_items(value).map do |item|
+              if inner == 'String' && item.is_a?(String)
+                item
+              else
+                (element_converter ? element_converter.call(item) : item)
+              end
+            end
+          }
         elsif normalized.casecmp('Array').zero?
-          return ->(value) { TypeUtils.parse_list(value) }
+          return ->(value) { list_items(value) }
         else
           single = converter_for_single_type(normalized)
           return single if single
@@ -265,15 +415,24 @@ module Rubycli
       return if positional_args.nil? || positional_args.empty?
 
       positional_map = metadata[:positionals_map] || {}
-      ordered_params = method_obj.parameters.select { |type, _| %i[req opt].include?(type) }
-
-      ordered_params.each_with_index do |(_, name), index|
+      positional_argument_bindings(method_obj, positional_args.size).each do |type, name, indexes|
         definition = positional_map[name]
         next unless definition
-        next if index >= positional_args.size
 
         label = definition.label || definition.placeholder || name.to_s.upcase
-        enforce_value_against_definition(definition, positional_args[index], label)
+
+        case type
+        when :req, :opt
+          index = indexes.first
+          next unless index
+
+          enforce_value_against_definition(definition, positional_args[index], label)
+        when :rest
+          next if indexes.empty?
+
+          values = indexes.map { |index| positional_args[index] }
+          enforce_value_against_definition(definition, values, label)
+        end
       end
     end
 
@@ -309,10 +468,10 @@ module Rubycli
       formatted_value = format_literal_value(entry)
 
       message = if description
-        "#{label} must be #{description} (received #{formatted_value})"
-      else
-        "Value #{formatted_value} for #{label} is not allowed"
-      end
+                  "#{label} must be #{description} (received #{formatted_value})"
+                else
+                  "Value #{formatted_value} for #{label} is not allowed"
+                end
 
       suggestions = literal_suggestions(definition, entry)
       return message if suggestions.empty?
@@ -355,7 +514,9 @@ module Rubycli
     end
 
     def allowed_value_description(definition)
-      literal_descriptions = Array(definition.allowed_values).map { |entry| format_literal_value(entry[:value]) }.reject(&:empty?)
+      literal_descriptions = Array(definition.allowed_values).map do |entry|
+        format_literal_value(entry[:value])
+      end.reject(&:empty?)
       type_descriptions = Array(definition.types)
                           .map { |token| token.to_s.strip }
                           .reject { |token| token.empty? || literal_hint_token?(token) }
@@ -397,6 +558,7 @@ module Rubycli
 
       if (inner = array_inner_type(normalized))
         return false unless value.is_a?(Array)
+
         return value.all? { |element| matches_type_token?(inner, element) }
       end
 
@@ -420,8 +582,6 @@ module Rubycli
         token[0..-3]
       elsif token.start_with?('Array<') && token.end_with?('>')
         token[6..-2].strip
-      else
-        nil
       end
     end
 
@@ -466,6 +626,17 @@ module Rubycli
       safe_constant_lookup(normalized)
     end
 
+    # Type annotations may name a class from a library that is not installed
+    # (bigdecimal, for instance, is no longer a default gem). Report it as a
+    # user-facing error instead of letting the LoadError escape with a backtrace.
+    def require_optional_library(library, type_token)
+      require library
+    rescue LoadError
+      raise ArgumentError,
+            "Type '#{type_token}' needs the #{library} library, which is not installed. " \
+            "Install it with `gem install #{library}` (or add it to your Gemfile)."
+    end
+
     def format_literal_value(value)
       case value
       when Symbol
@@ -490,7 +661,6 @@ module Rubycli
       token.start_with?('%i[', '%I[', '%w[', '%W[')
     end
 
-
     def build_cli_alias_map(option_defs)
       option_defs.each_with_object({}) do |opt, memo|
         next unless opt.short
@@ -526,21 +696,17 @@ module Rubycli
       lambda do |value|
         return nil if value.nil? && allow_nil
 
-        if allow_nil && value.is_a?(String) && value.strip.casecmp('nil').zero?
-          next nil
-        end
+        next nil if allow_nil && value.is_a?(String) && value.strip.casecmp('nil').zero?
 
         if converters.empty?
           value
         else
           last_error = nil
           converters.each do |converter|
-            begin
-              result = converter.call(value)
-              return result
-            rescue StandardError => e
-              last_error = e
-            end
+            result = converter.call(value)
+            return result
+          rescue StandardError => e
+            last_error = e
           end
           raise last_error || ArgumentError.new("Could not convert value '#{value}'")
         end
@@ -564,10 +730,13 @@ module Rubycli
       when 'Boolean', 'TrueClass', 'FalseClass'
         ->(value) { TypeUtils.convert_boolean(value) }
       when 'Symbol'
-        ->(value) { value.to_sym }
+        lambda { |value|
+          converted_value = convert_arg(value)
+          converted_value.is_a?(Symbol) ? converted_value : value.to_sym
+        }
       when 'BigDecimal', 'Decimal'
-        require 'bigdecimal'
-        ->(value) {
+        require_optional_library('bigdecimal', normalized)
+        lambda { |value|
           return value if value.is_a?(BigDecimal)
 
           if value.is_a?(String)
@@ -577,20 +746,35 @@ module Rubycli
           end
         }
       when 'Date'
-        require 'date'
+        require_optional_library('date', normalized)
         ->(value) { Date.parse(value) }
-      when 'Time', 'DateTime'
-        require 'time'
+      when 'Time'
+        require_optional_library('time', normalized)
         ->(value) { Time.parse(value) }
-      when 'JSON', 'Hash'
-        ->(value) {
-          return value if value.is_a?(Hash)
+      when 'DateTime'
+        require_optional_library('date', normalized)
+        ->(value) { DateTime.parse(value) }
+      when 'JSON'
+        lambda { |value|
+          parsed_value = convert_arg(value)
+          parsed_value = JSON.parse(value) unless parsed_value.is_a?(Hash) || parsed_value.is_a?(Array)
+          unless parsed_value.is_a?(Hash) || parsed_value.is_a?(Array)
+            raise ::ArgumentError, 'JSON value must be an object or array'
+          end
 
-          JSON.parse(value)
+          parsed_value
+        }
+      when 'Hash'
+        lambda { |value|
+          parsed_value = convert_arg(value)
+          parsed_value = JSON.parse(value) unless parsed_value.is_a?(Hash)
+          raise ::ArgumentError, 'Hash value must be an object' unless parsed_value.is_a?(Hash)
+
+          parsed_value
         }
       when 'Pathname'
-        require 'pathname'
-        ->(value) {
+        require_optional_library('pathname', normalized)
+        lambda { |value|
           return value if value.is_a?(Pathname)
 
           Pathname.new(value.to_s)
@@ -599,39 +783,47 @@ module Rubycli
         if normalized.start_with?('Array<') && normalized.end_with?('>')
           inner = normalized[6..-2].strip
           element_converter = converter_for_single_type(inner)
-          ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+          lambda { |value|
+            list_items(value).map do |item|
+              if inner == 'String' && item.is_a?(String)
+                item
+              else
+                (element_converter ? element_converter.call(item) : item)
+              end
+            end
+          }
         elsif normalized.end_with?('[]')
           inner = normalized[0..-3]
           element_converter = converter_for_single_type(inner)
-          ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+          lambda { |value|
+            list_items(value).map do |item|
+              if inner == 'String' && item.is_a?(String)
+                item
+              else
+                (element_converter ? element_converter.call(item) : item)
+              end
+            end
+          }
         elsif normalized == 'Array'
-          ->(value) { TypeUtils.parse_list(value) }
-        else
-          nil
+          ->(value) { list_items(value) }
         end
       end
     end
 
+    def list_items(value)
+      converted_value = convert_arg(value)
+      source = converted_value.is_a?(Array) ? converted_value : value
+      TypeUtils.parse_list(source)
+    end
+
     def convert_option_value(keyword, value, option_meta, type_converters)
-      if Rubycli.eval_mode? || Rubycli.json_mode?
-        return convert_arg(value)
-      end
+      return convert_arg(value) if Rubycli.eval_mode? || Rubycli.json_mode?
 
       converter = type_converters[keyword]
       converted_value = convert_arg(value)
       return converted_value unless converter
 
-      original_input = value if value.is_a?(String)
-      expects_list = option_meta && option_meta.types.any? { |type|
-        type.to_s.end_with?('[]') || type.to_s.start_with?('Array<')
-      }
-
-      value_for_converter = converted_value
-      if expects_list && original_input && converted_value.is_a?(Numeric) && original_input.include?(',')
-        value_for_converter = original_input
-      end
-
-      converter.call(value_for_converter)
+      converter.call(value)
     rescue StandardError => e
       option_label = option_meta&.long || option_meta&.short || keyword
       raise ArgumentError, "Value '#{value}' for option '#{option_label}' is invalid: #{e.message}"
@@ -639,9 +831,16 @@ module Rubycli
 
     def looks_like_option?(token)
       return false unless token
-      return false if token == '--'
+      return false if ['--', '-'].include?(token)
 
-      token.start_with?('-') && !(token =~ /\A-?\d+(\.\d+)?\z/)
+      decimal_digits = '\d(?:_?\d)*'
+      negative_decimal = token.match?(
+        /\A-(?:#{decimal_digits}(?:\.(?:#{decimal_digits})?)?|\.#{decimal_digits})(?:[eE][+-]?#{decimal_digits})?\z/
+      )
+      negative_radix = token.match?(
+        /\A-0(?:[xX][0-9a-fA-F_]+|[bB][01_]+|[oO][0-7_]+|[dD][0-9_]+)\z/
+      )
+      token.start_with?('-') && !negative_decimal && !negative_radix
     end
   end
 end