toys-core 0.7.0 → 0.8.0

data/lib/toys/alias.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Copyright 2019 Daniel Azuma
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+;
+
+module Toys
+  ##
+  # An alias is a name that refers to another name.
+  #
+  class Alias
+    ##
+    # Create a new alias.
+    # Should be created only from the DSL via the Loader.
+    # @private
+    #
+    def initialize(loader, full_name, target, priority)
+      @target_name =
+        if target.is_a?(::Array)
+          target.map(&:to_s)
+        else
+          full_name[0..-2] + [target.to_s]
+        end
+      @target_name.freeze
+      @full_name = full_name.map(&:to_s).freeze
+      @priority = priority
+      @tool_class = DSL::Tool.new_class(@full_name, priority, loader)
+    end
+
+    ##
+    # The tool class.
+    #
+    # @return [Class]
+    #
+    attr_reader :tool_class
+
+    ##
+    # The name of the tool as an array of strings.
+    # This array may not be modified.
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :full_name
+
+    ##
+    # The priority of this alias.
+    #
+    # @return [Integer]
+    #
+    attr_reader :priority
+
+    ##
+    # The name of the target as an array of strings.
+    # This array may not be modified.
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :target_name
+
+    ##
+    # The local name of this alias, i.e. the last element of the full name.
+    #
+    # @return [String]
+    #
+    def simple_name
+      full_name.last
+    end
+
+    ##
+    # A displayable name of this alias, generally the full name delimited by
+    # spaces.
+    #
+    # @return [String]
+    #
+    def display_name
+      full_name.join(" ")
+    end
+
+    ##
+    # A displayable name of the target, generally the full name delimited by
+    # spaces.
+    #
+    # @return [String]
+    #
+    def display_target
+      target_name.join(" ")
+    end
+  end
+end

data/lib/toys/arg_parser.rb

@@ -0,0 +1,624 @@
+# frozen_string_literal: true
+
+# Copyright 2019 Daniel Azuma
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+;
+
+module Toys
+  ##
+  # An internal class that parses command line arguments for a tool.
+  #
+  # Generally, you should not need to use this class directly. It is called
+  # from {Toys::CLI}.
+  #
+  class ArgParser
+    ##
+    # Base representation of a usage error reported by the ArgParser.
+    #
+    # This functions similarly to an exception, but is not raised. Rather, it
+    # is returned in the {Toys::ArgParser#errors} array.
+    #
+    class UsageError
+      ##
+      # Create a UsageError given a message and common data
+      #
+      # @param message [String] The basic error message.
+      # @param name [String,nil] The name of the element (normally flag or
+      #     positional argument) that reported the error, or nil if there is
+      #     no definite element.
+      # @param value [String,nil] The value that was rejected, or nil if not
+      #     applicable.
+      # @param suggestions [Array<String>,nil] An array of suggestions from
+      #     DidYouMean, or nil if not applicable.
+      #
+      def initialize(message, name: nil, value: nil, suggestions: nil)
+        @message = message
+        @name = name
+        @value = value
+        @suggestions = suggestions
+      end
+
+      ##
+      # The basic error message. Does not include suggestions, if any.
+      #
+      # @return [String]
+      #
+      attr_reader :message
+
+      ##
+      # The name of the element (normally a flag or positional argument) that
+      # reported the error.
+      #
+      # @return [String] The element name.
+      # @return [nil] if there is no definite element source.
+      #
+      attr_reader :name
+
+      ##
+      # The value that was rejected.
+      #
+      # @return [String] the value string
+      # @return [nil] if a value is not applicable to this error.
+      #
+      attr_reader :value
+
+      ##
+      # An array of suggestions from DidYouMean.
+      #
+      # @return [Array<String>] array of suggestions.
+      # @return [nil] if suggestions are not applicable to this error.
+      #
+      attr_reader :suggestions
+
+      ##
+      # A fully formatted error message including suggestions.
+      #
+      # @return [String]
+      #
+      def full_message
+        if suggestions && !suggestions.empty?
+          alts_str = suggestions.join("\n                 ")
+          "#{message}\nDid you mean...  #{alts_str}"
+        else
+          message
+        end
+      end
+      alias to_s full_message
+    end
+
+    ##
+    # A UsageError indicating a value was provided for a flag that does not
+    # take a value.
+    #
+    class FlagValueNotAllowedError < UsageError
+      ##
+      # Create a FlagValueNotAllowedError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param name [String] The name of the flag. Normally required.
+      #
+      def initialize(message = nil, name: nil)
+        super(message || "Flag \"#{name}\" should not take an argument.", name: name)
+      end
+    end
+
+    ##
+    # A UsageError indicating a value was not provided for a flag that requires
+    # a value.
+    #
+    class FlagValueMissingError < UsageError
+      ##
+      # Create a FlagValueMissingError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param name [String] The name of the flag. Normally required.
+      #
+      def initialize(message = nil, name: nil)
+        super(message || "Flag \"#{name}\" is missing a value.", name: name)
+      end
+    end
+
+    ##
+    # A UsageError indicating a flag name was not recognized.
+    #
+    class FlagUnrecognizedError < UsageError
+      ##
+      # Create a FlagUnrecognizedError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param value [String] The requested flag name. Normally required.
+      # @param suggestions [Array<String>] An array of suggestions to present
+      #     to the user. Optional.
+      #
+      def initialize(message = nil, value: nil, suggestions: nil)
+        super(message || "Flag \"#{value}\" is not recognized.",
+              value: value, suggestions: suggestions)
+      end
+    end
+
+    ##
+    # A UsageError indicating a flag name prefix was given that matched
+    # multiple flags.
+    #
+    class FlagAmbiguousError < UsageError
+      ##
+      # Create a FlagAmbiguousError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param value [String] The requested flag name. Normally required.
+      # @param suggestions [Array<String>] An array of suggestions to present
+      #     to the user. Optional.
+      #
+      def initialize(message = nil, value: nil, suggestions: nil)
+        super(message || "Flag prefix \"#{value}\" is ambiguous.",
+              value: value, suggestions: suggestions)
+      end
+    end
+
+    ##
+    # A UsageError indicating a flag did not accept the value given it.
+    #
+    class FlagValueUnacceptableError < UsageError
+      ##
+      # Create a FlagValueUnacceptableError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param name [String] The name of the flag. Normally required.
+      # @param value [String] The value given. Normally required.
+      # @param suggestions [Array<String>] An array of suggestions to present
+      #     to the user. Optional.
+      #
+      def initialize(message = nil, name: nil, value: nil, suggestions: nil)
+        super(message || "Unacceptable value \"#{value}\" for flag \"#{name}\".",
+              name: name, suggestions: suggestions)
+      end
+    end
+
+    ##
+    # A UsageError indicating a positional argument did not accept the value
+    # given it.
+    #
+    class ArgValueUnacceptableError < UsageError
+      ##
+      # Create an ArgValueUnacceptableError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param name [String] The name of the argument. Normally required.
+      # @param value [String] The value given. Normally required.
+      # @param suggestions [Array<String>] An array of suggestions to present
+      #     to the user. Optional.
+      #
+      def initialize(message = nil, name: nil, value: nil, suggestions: nil)
+        super(message || "Unacceptable value \"#{value}\" for positional argument \"#{name}\".",
+              name: name, suggestions: suggestions)
+      end
+    end
+
+    ##
+    # A UsageError indicating a required positional argument was not fulfilled.
+    #
+    class ArgMissingError < UsageError
+      ##
+      # Create an ArgMissingError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param name [String] The name of the argument. Normally required.
+      #
+      def initialize(message = nil, name: nil)
+        super(message || "Required positional argument \"#{name}\" is missing.", name: name)
+      end
+    end
+
+    ##
+    # A UsageError indicating extra arguments were supplied.
+    #
+    class ExtraArgumentsError < UsageError
+      ##
+      # Create an ExtraArgumentsError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param value [String] The first extra argument. Normally required.
+      # @param values [Array<String>] All extra arguments. Normally required.
+      #
+      def initialize(message = nil, value: nil, values: nil)
+        super(message || "Extra arguments: \"#{Array(values).join(' ')}\".", value: value)
+      end
+    end
+
+    ##
+    # A UsageError indicating the given subtool name does not exist.
+    #
+    class ToolUnrecognizedError < UsageError
+      ##
+      # Create a ToolUnrecognizedError.
+      #
+      # @param message [String,nil] A custom message. Normally omitted, in
+      #     which case an appropriate default is supplied.
+      # @param value [String] The requested subtool. Normally required.
+      # @param values [Array<String>] The full path of the requested tool.
+      #     Normally required.
+      # @param suggestions [Array<String>] An array of suggestions to present
+      #     to the user. Optional.
+      #
+      def initialize(message = nil, value: nil, values: nil, suggestions: nil)
+        super(message || "Tool not found: \"#{Array(values).join(' ')}\".",
+              value: value, suggestions: suggestions)
+        @name = name
+      end
+    end
+
+    ##
+    # A UsageError indicating a flag group constraint was not fulfilled.
+    #
+    class FlagGroupConstraintError < UsageError
+      ##
+      # Create a FlagGroupConstraintError.
+      #
+      # @param message [String] The message. Required.
+      #
+      def initialize(message)
+        super(message)
+      end
+    end
+
+    ##
+    # Create an argument parser for a particular tool.
+    #
+    # @param cli [Toys::CLI] The CLI in effect.
+    # @param tool [Toys::Tool] The tool defining the argument format.
+    # @param verbosity [Integer] The initial verbosity level (default is 0).
+    # @param require_exact_flag_match [Boolean] Whether to require flag matches
+    #     be exact (not partial). Default is false.
+    #
+    def initialize(cli, tool, verbosity: 0, require_exact_flag_match: false)
+      @require_exact_flag_match = require_exact_flag_match
+      @loader = cli.loader
+      @data = initial_data(cli, tool, verbosity)
+      @tool = tool
+      @seen_flag_keys = []
+      @errors = []
+      @unmatched_args = []
+      @unmatched_positional = []
+      @unmatched_flags = []
+      @parsed_args = []
+      @active_flag_def = nil
+      @active_flag_arg = nil
+      @arg_defs = tool.positional_args
+      @arg_def_index = 0
+      @flags_allowed = true
+      @finished = false
+    end
+
+    ##
+    # The tool definition governing this parser.
+    # @return [Toys::Tool]
+    #
+    attr_reader :tool
+
+    ##
+    # All command line arguments that have been parsed.
+    # @return [Array<String>]
+    #
+    attr_reader :parsed_args
+
+    ##
+    # Extra positional args that were not matched.
+    # @return [Array<String>]
+    #
+    attr_reader :unmatched_positional
+
+    ##
+    # Flags that were not matched.
+    # @return [Array<String>]
+    #
+    attr_reader :unmatched_flags
+
+    ##
+    # All args that were not matched.
+    # @return [Array<String>]
+    #
+    attr_reader :unmatched_args
+
+    ##
+    # The collected tool data from parsed arguments.
+    # @return [Hash]
+    #
+    attr_reader :data
+
+    ##
+    # An array of parse error messages.
+    # @return [Array<Toys::ArgParser::UsageError>]
+    #
+    attr_reader :errors
+
+    ##
+    # The current flag definition whose value is still pending
+    #
+    # @return [Toys::Flag] The pending flag definition
+    # @return [nil] if there is no pending flag
+    #
+    attr_reader :active_flag_def
+
+    ##
+    # Whether flags are currently allowed. Returns false after `--` is received.
+    # @return [Boolean]
+    #
+    def flags_allowed?
+      @flags_allowed
+    end
+
+    ##
+    # Determine if this parser is finished
+    # @return [Boolean]
+    #
+    def finished?
+      @finished
+    end
+
+    ##
+    # The argument definition that will be applied to the next argument.
+    #
+    # @return [Toys::PositionalArg] The next argument definition.
+    # @return [nil] if all arguments have been filled.
+    #
+    def next_arg_def
+      @arg_defs[@arg_def_index]
+    end
+
+    ##
+    # Incrementally parse a single string or an array of strings
+    #
+    # @param args [String,Array<String>]
+    # @return [self]
+    #
+    def parse(args)
+      raise "Parser has finished" if @finished
+      Array(args).each do |arg|
+        @parsed_args << arg
+        unless @tool.argument_parsing_disabled?
+          check_flag_value(arg) || check_flag(arg) || handle_positional(arg)
+        end
+      end
+      self
+    end
+
+    ##
+    # Complete parsing. This should be called after all arguments have been
+    # processed. It does a final check for any errors, including:
+    #
+    #  *  The arguments ended with a flag that was expecting a value but wasn't
+    #     provided.
+    #  *  One or more required arguments were never given a value.
+    #  *  One or more extra arguments were provided.
+    #  *  Restrictions defined in one or more flag groups were not fulfilled.
+    #
+    # Any errors are added to the errors array. It also fills in final values
+    # for `Context::Key::USAGE_ERRORS` and `Context::Key::ARGS`.
+    #
+    # After this method is called, this object is locked down, and no
+    # additional arguments may be parsed.
+    #
+    # @return [self]
+    #
+    def finish
+      finish_active_flag
+      finish_arg_defs
+      finish_flag_groups
+      finish_special_data
+      @finished = true
+      self
+    end
+
+    private
+
+    REMAINING_HANDLER = ->(val, prev) { prev.is_a?(::Array) ? prev << val : [val] }
+    ARG_HANDLER = ->(val, _prev) { val }
+
+    def initial_data(cli, tool, verbosity)
+      data = {
+        Context::Key::ARGS => nil,
+        Context::Key::CLI => cli,
+        Context::Key::CONTEXT_DIRECTORY => tool.context_directory,
+        Context::Key::LOGGER => cli.logger,
+        Context::Key::TOOL => tool,
+        Context::Key::TOOL_SOURCE => tool.source_info,
+        Context::Key::TOOL_NAME => tool.full_name,
+        Context::Key::USAGE_ERRORS => [],
+      }
+      Compat.merge_clones(data, tool.default_data)
+      data[Context::Key::VERBOSITY] ||= verbosity
+      data
+    end
+
+    def check_flag_value(arg)
+      return false unless @active_flag_def
+      result = @active_flag_def.value_type == :required || !arg.start_with?("-")
+      add_data(@active_flag_def.key, @active_flag_def.handler, @active_flag_def.acceptor,
+               result ? arg : nil, :flag, @active_flag_arg)
+      @seen_flag_keys << @active_flag_def.key
+      @active_flag_def = nil
+      @active_flag_arg = nil
+      result
+    end
+
+    def check_flag(arg)
+      return false unless @flags_allowed
+      case arg
+      when "--"
+        @flags_allowed = false
+      when /\A(--\w[\?\w-]*)=(.*)\z/
+        handle_valued_flag(::Regexp.last_match(1), ::Regexp.last_match(2))
+      when /\A--.+\z/
+        handle_plain_flag(arg)
+      when /\A-(.+)\z/
+        handle_single_flags(::Regexp.last_match(1))
+      else
+        return false
+      end
+      true
+    end
+
+    def handle_single_flags(str)
+      until str.empty?
+        str = handle_plain_flag("-#{str[0]}", str[1..-1])
+      end
+    end
+
+    def handle_plain_flag(name, following = "")
+      flag_result = find_flag(name)
+      flag_def = flag_result&.unique_flag
+      return "" unless flag_def
+      @seen_flag_keys << flag_def.key
+      if flag_def.flag_type == :boolean
+        add_data(flag_def.key, flag_def.handler, nil, !flag_result.unique_flag_negative?,
+                 :flag, name)
+      elsif following.empty?
+        if flag_def.value_type == :required || flag_result.unique_flag_syntax.value_delim == " "
+          @active_flag_def = flag_def
+          @active_flag_arg = name
+        else
+          add_data(flag_def.key, flag_def.handler, flag_def.acceptor, nil, :flag, name)
+        end
+      else
+        add_data(flag_def.key, flag_def.handler, flag_def.acceptor, following, :flag, name)
+        following = ""
+      end
+      following
+    end
+
+    def handle_valued_flag(name, value)
+      flag_result = find_flag(name)
+      flag_def = flag_result&.unique_flag
+      return unless flag_def
+      @seen_flag_keys << flag_def.key
+      if flag_def.flag_type == :value
+        add_data(flag_def.key, flag_def.handler, flag_def.acceptor, value, :flag, name)
+      else
+        add_data(flag_def.key, flag_def.handler, nil, !flag_result.unique_flag_negative?,
+                 :flag, name)
+        @errors << FlagValueNotAllowedError.new(name: name)
+      end
+    end
+
+    def handle_positional(arg)
+      if @tool.flags_before_args_enforced?
+        @flags_allowed = false
+      end
+      arg_def = next_arg_def
+      unless arg_def
+        @unmatched_positional << arg
+        @unmatched_args << arg
+        return
+      end
+      @arg_def_index += 1 unless arg_def.type == :remaining
+      handler = arg_def.type == :remaining ? REMAINING_HANDLER : ARG_HANDLER
+      add_data(arg_def.key, handler, arg_def.acceptor, arg, :arg, arg_def.display_name)
+    end
+
+    def find_flag(name)
+      flag_result = @tool.resolve_flag(name)
+      if flag_result.not_found? || @require_exact_flag_match && !flag_result.found_exact?
+        @errors << FlagUnrecognizedError.new(
+          value: name, suggestions: Compat.suggestions(name, @tool.used_flags)
+        )
+        @unmatched_flags << name
+        @unmatched_args << name
+        flag_result = nil
+      elsif flag_result.found_multiple?
+        @errors << FlagAmbiguousError.new(
+          value: name, suggestions: flag_result.matching_flag_strings
+        )
+        @unmatched_flags << name
+        @unmatched_args << name
+        flag_result = nil
+      end
+      flag_result
+    end
+
+    def add_data(key, handler, accept, value, type_name, display_name)
+      if accept
+        match = accept.match(value)
+        unless match
+          error_class = type_name == :flag ? FlagValueUnacceptableError : ArgValueUnacceptableError
+          suggestions = accept.respond_to?(:suggestions) ? accept.suggestions(value) : nil
+          @errors << error_class.new(value: value, name: display_name, suggestions: suggestions)
+          return
+        end
+        value = accept.convert(*Array(match))
+      end
+      if handler
+        value = handler.call(value, @data[key])
+      end
+      @data[key] = value
+    end
+
+    def finish_active_flag
+      if @active_flag_def
+        if @active_flag_def.value_type == :required
+          @errors << FlagValueMissingError.new(name: @active_flag_arg)
+        else
+          add_data(@active_flag_def.key, @active_flag_def.handler, @active_flag_def.acceptor,
+                   nil, :flag, @active_flag_arg)
+        end
+      end
+    end
+
+    def finish_arg_defs
+      arg_def = @arg_defs[@arg_def_index]
+      if arg_def && arg_def.type == :required
+        @errors << ArgMissingError.new(name: arg_def.display_name)
+      end
+      unless @unmatched_positional.empty?
+        first_arg = @unmatched_positional.first
+        @errors <<
+          if @tool.runnable? || !@seen_flag_keys.empty?
+            ExtraArgumentsError.new(values: @unmatched_positional, value: first_arg)
+          else
+            dictionary = @loader.list_subtools(@tool.full_name).map(&:simple_name)
+            ToolUnrecognizedError.new(values: @tool.full_name + [first_arg],
+                                      value: first_arg,
+                                      suggestions: Compat.suggestions(first_arg, dictionary))
+          end
+      end
+    end
+
+    def finish_flag_groups
+      @tool.flag_groups.each do |group|
+        @errors += Array(group.validation_errors(@seen_flag_keys))
+      end
+    end
+
+    def finish_special_data
+      @data[Context::Key::USAGE_ERRORS] = @errors
+      @data[Context::Key::ARGS] = @parsed_args
+      @data[Context::Key::UNMATCHED_ARGS] = @unmatched_args
+      @data[Context::Key::UNMATCHED_POSITIONAL] = @unmatched_positional
+      @data[Context::Key::UNMATCHED_FLAGS] = @unmatched_flags
+    end
+  end
+end