claide 0.5.0 → 0.6.0

data/lib/claide/argv/parser.rb

@@ -0,0 +1,83 @@
+module CLAide
+  class ARGV
+    module Parser
+      # @return [Array<Array<Symbol, String, Array>>] A list of tuples for each
+      #         parameter, where the first entry is the `type` and the second
+      #         entry the actual parsed parameter.
+      #
+      # @example
+      #
+      #   list = parse(['tea', '--no-milk', '--sweetner=honey'])
+      #   list # => [[:arg, "tea"],
+      #              [:flag, ["milk", false]],
+      #              [:option, ["sweetner", "honey"]]]
+      #
+      def self.parse(argv)
+        entries = []
+        copy = argv.map(&:to_s)
+        while argument = copy.shift
+          type = argument_type(argument)
+          parameter = argument_parameter(type, argument)
+          entries << [type, parameter]
+        end
+        entries
+      end
+
+      # @return [Symbol] Returns the type of an argument. The types can be
+      #         either: `:arg`, `:flag`, `:option`.
+      #
+      # @param  [String] argument
+      #         The argument to check.
+      #
+      def self.argument_type(argument)
+        if argument.start_with?('--')
+          if argument.include?('=')
+            :option
+          else
+            :flag
+          end
+        else
+          :arg
+        end
+      end
+
+      # @return [String, Array<String, String>] Returns argument itself for
+      #         normal arguments (like commands) and a tuple with they key and
+      #         the value for options and flags.
+      #
+      # @param  [Symbol] type
+      #         The type of the argument.
+      #
+      # @param  [String] argument
+      #         The argument to check.
+      #
+      def self.argument_parameter(type, argument)
+        case type
+        when :arg
+          return argument
+        when :flag
+          return flag_paramenter(argument)
+        when :option
+          return argument[2..-1].split('=', 2)
+        end
+      end
+
+      # @return [String, Array<String, String>] Returns the parameter
+      #         describing a flag arguments.
+      #
+      # @param  [String] argument
+      #         The flag argument to check.
+      #
+      def self.flag_paramenter(argument)
+        if argument.start_with?('--no-')
+          key = argument[5..-1]
+          value = false
+        else
+          key = argument[2..-1]
+          value = true
+        end
+        [key, value]
+      end
+    end
+  end
+end

data/lib/claide/command.rb

@@ -1,9 +1,13 @@
 # encoding: utf-8
 
 require 'claide/command/banner'
+require 'claide/command/parser'
+require 'claide/command/plugins_helper'
+require 'claide/command/options'
+require 'claide/command/shell_completion_helper'
+require 'claide/command/validation_helper'
 
 module CLAide
-
   # This class is used to build a command-line interface
   #
   # Each command is represented by a subclass of this class, which may be
@@ -44,11 +48,7 @@ module CLAide
   # defaults to {Command.summary}.
   #
   class Command
-
-    #-------------------------------------------------------------------------#
-
     class << self
-
       # @return [Boolean] Indicates whether or not this command can actually
       #         perform work of itself, or that it only contains subcommands.
       #
@@ -60,6 +60,7 @@ module CLAide
       #         help banner or to show its subcommands instead.
       #
       #         Setting this to `true` implies it’s an abstract command.
+      #
       attr_reader :ignore_in_command_lookup
       alias_method :ignore_in_command_lookup?, :ignore_in_command_lookup
       def ignore_in_command_lookup=(flag)
@@ -88,10 +89,43 @@ module CLAide
       #
       attr_accessor :plugin_prefix
 
-      # @return [String] A list of arguments the command handles. This is shown
-      #         in the usage section of the command’s help banner.
+      # @return [Array<Tuple>] A list of arguments the command handles. This
+      #         is shown in the usage section of the command’s help banner.
+      #         Each tuple in the array represents an argument using
+      #         [name, type] where:
+      #          - name is a String containing the argument
+      #          - type is either :optional or :required
       #
+      # @TODO   Remove deprecation
+      #
+      # rubocop:disable all
       attr_accessor :arguments
+      def arguments
+        @arguments ||= []
+      end
+
+      # @param [Array<Tuple>] arguments
+      #        An array containing arguments, each described by a tuple of
+      #        the form [name, type], where:
+      #          - name is a String containing the argument
+      #          - type is either :optional or :required
+      #
+      def arguments=(arguments)
+        if arguments.is_a?(Array)
+          @arguments = arguments
+        else
+          warn '[!] The specification of arguments as a string has been' \
+            " deprecated #{self}: `#{arguments}`".ansi.yellow
+          @arguments = arguments.split(' ').map do |argument|
+            if argument.start_with?('[')
+              [argument.sub(/\[(.*)\]/, '\1'), :optional]
+            else
+              [argument, :required]
+            end
+          end
+        end
+      end
+      # rubocop:enable all
 
       # @return [Boolean] The default value for {Command#ansi_output}. This
       #         defaults to `true` if `STDOUT` is connected to a TTY and
@@ -101,31 +135,13 @@ module CLAide
       #
       def ansi_output
         if @ansi_output.nil?
-          @ansi_output = STDOUT.tty? &&
-                           String.method_defined?(:red) &&
-                             String.method_defined?(:green) &&
-                               String.method_defined?(:yellow)
+          @ansi_output = STDOUT.tty?
         end
         @ansi_output
       end
       attr_writer :ansi_output
       alias_method :ansi_output?, :ansi_output
 
-      def colorize_output
-        warn "[!] The use of `CLAide::Command.colorize_output` has been " \
-             "deprecated. Use `CLAide::Command.ansi_output` instead. " \
-             "(Called from: #{caller.first})"
-        ansi_output
-      end
-      alias_method :colorize_output?, :colorize_output
-
-      def colorize_output=(flag)
-        warn "[!] The use of `CLAide::Command.colorize_output=` has been " \
-             "deprecated. Use `CLAide::Command.ansi_output=` instead. " \
-             "(Called from: #{caller.first})"
-        self.ansi_output = flag
-      end
-
       # @return [String] The name of the command. Defaults to a snake-cased
       #         version of the class’ name.
       #
@@ -136,265 +152,215 @@ module CLAide
       end
       attr_writer :command
 
-      # @return [String] The full command up-to this command, as it would be
-      #         looked up during parsing.
-      #
-      # @note (see #ignore_in_command_lookup)
-      #
-      # @example
+      # @return [String] The version of the command. This value will be printed
+      #         by the `--version` flag if used for the root command.
       #
-      #   BevarageMaker::Tea.full_command # => "beverage-maker tea"
-      #
-      def full_command
-        if superclass == Command
-          ignore_in_command_lookup? ? '' : command
+      attr_accessor :version
+    end
+
+    #-------------------------------------------------------------------------#
+
+    # @return [String] The full command up-to this command, as it would be
+    #         looked up during parsing.
+    #
+    # @note (see #ignore_in_command_lookup)
+    #
+    # @example
+    #
+    #   BevarageMaker::Tea.full_command # => "beverage-maker tea"
+    #
+    def self.full_command
+      if superclass == Command
+        ignore_in_command_lookup? ? '' : command
+      else
+        if ignore_in_command_lookup?
+          superclass.full_command
         else
-          if ignore_in_command_lookup?
-            superclass.full_command
-          else
-            "#{superclass.full_command} #{command}"
-          end
+          "#{superclass.full_command} #{command}"
         end
       end
+    end
 
-      # @return [Array<Class>] A list of all command classes that are nested
-      #         under this command.
-      #
-      def subcommands
-        @subcommands ||= []
-      end
+    # @return [Bool] Whether this is the root command class
+    #
+    def self.root_command?
+      superclass == CLAide::Command
+    end
 
-      # @return [Array<Class>] A list of command classes that are nested under
-      #         this command _or_ the subcommands of those command classes in
-      #         case the command class should be ignored in command lookup.
-      #
-      def subcommands_for_command_lookup
-        subcommands.map do |subcommand|
-          if subcommand.ignore_in_command_lookup?
-            subcommand.subcommands_for_command_lookup
-          else
-            subcommand
-          end
-        end.flatten
-      end
+    # @return [Array<Class>] A list of all command classes that are nested
+    #         under this command.
+    #
+    def self.subcommands
+      @subcommands ||= []
+    end
 
-      # Searches the list of subcommands that should not be ignored for command
-      # lookup for a subcommand with the given `name`.
-      #
-      # @param  [String] name
-      #         The name of the subcommand to be found.
-      #
-      # @return [CLAide::Command, nil] The subcommand, if found.
-      #
-      def find_subcommand(name)
-        subcommands_for_command_lookup.find { |sc| sc.command == name }
-      end
+    # @return [Array<Class>] A list of command classes that are nested under
+    #         this command _or_ the subcommands of those command classes in
+    #         case the command class should be ignored in command lookup.
+    #
+    def self.subcommands_for_command_lookup
+      subcommands.map do |subcommand|
+        if subcommand.ignore_in_command_lookup?
+          subcommand.subcommands_for_command_lookup
+        else
+          subcommand
+        end
+      end.flatten
+    end
 
-      # @visibility private
-      #
-      # Automatically registers a subclass as a subcommand.
-      #
-      def inherited(subcommand)
-        subcommands << subcommand
-      end
+    # Searches the list of subcommands that should not be ignored for command
+    # lookup for a subcommand with the given `name`.
+    #
+    # @param  [String] name
+    #         The name of the subcommand to be found.
+    #
+    # @return [CLAide::Command, nil] The subcommand, if found.
+    #
+    def self.find_subcommand(name)
+      subcommands_for_command_lookup.find { |sc| sc.command == name }
+    end
 
-      # Should be overridden by a subclass if it handles any options.
-      #
-      # The subclass has to combine the result of calling `super` and its own
-      # list of options. The recommended way of doing this is by concatenating
-      # concatenating to this classes’ own options.
-      #
-      # @return [Array<Array>]
-      #
-      #   A list of option name and description tuples.
-      #
-      # @example
-      #
-      #   def self.options
-      #     [
-      #       ['--verbose', 'Print more info'],
-      #       ['--help',    'Print help banner'],
-      #     ].concat(super)
-      #   end
-      #
-      def options
-        options = [
-          ['--verbose', 'Show more debugging information'],
-          ['--help',    'Show help banner of specified command'],
-        ]
-        if Command.ansi_output?
-          options.unshift(['--no-ansi', 'Show output without ANSI codes'])
-        end
-        options
-      end
+    # @visibility private
+    #
+    # Automatically registers a subclass as a subcommand.
+    #
+    def self.inherited(subcommand)
+      subcommands << subcommand
+    end
 
-      # @param  [Array, ARGV] argv
-      #         A list of (remaining) parameters.
-      #
-      # @return [Command] An instance of the command class that was matched by
-      #         going through the arguments in the parameters and drilling down
-      #         command classes.
-      #
-      def parse(argv)
-        argv = ARGV.new(argv) unless argv.is_a?(ARGV)
-        cmd = argv.arguments.first
-        if cmd && subcommand = find_subcommand(cmd)
-          argv.shift_argument
-          subcommand.parse(argv)
-        elsif abstract_command? && default_subcommand
-          subcommand = find_subcommand(default_subcommand)
-          unless subcommand
-            raise "Unable to find the default subcommand " \
-                  "`#{default_subcommand}` for command `#{self}`."
-          end
-          result = subcommand.parse(argv)
-          result.invoked_as_default = true
-          result
-        else
-          new(argv)
-        end
-      end
+    # Should be overridden by a subclass if it handles any options.
+    #
+    # The subclass has to combine the result of calling `super` and its own
+    # list of options. The recommended way of doing this is by concatenating
+    # concatenating to this classes’ own options.
+    #
+    # @return [Array<Array>]
+    #
+    #   A list of option name and description tuples.
+    #
+    # @example
+    #
+    #   def self.options
+    #     [
+    #       ['--verbose', 'Print more info'],
+    #       ['--help',    'Print help banner'],
+    #     ].concat(super)
+    #   end
+    #
+    def self.options
+      Options.default_options(self)
+    end
 
-      # Instantiates the command class matching the parameters through
-      # {Command.parse}, validates it through {Command#validate!}, and runs it
-      # through {Command#run}.
-      #
-      # @note
-      #
-      #   You should normally call this on
-      #
-      # @param [Array, ARGV] argv
-      #
-      #   A list of parameters. For instance, the standard `ARGV` constant,
-      #   which contains the parameters passed to the program.
-      #
-      # @return [void]
-      #
-      def run(argv)
-        load_plugins
-        command = parse(argv)
+    # Instantiates the command class matching the parameters through
+    # {Command.parse}, validates it through {Command#validate!}, and runs it
+    # through {Command#run}.
+    #
+    # @note   You should normally call this on
+    #
+    # @note   The ANSI support is configured before running a command to allow
+    #         the same process to run multiple commands with different
+    #         settings.  For example a process with ANSI output enabled might
+    #         want to programmatically invoke another command with the output
+    #         enabled.
+    #
+    # @param [Array, ARGV] argv
+    #        A list of parameters. For instance, the standard `ARGV` constant,
+    #        which contains the parameters passed to the program.
+    #
+    # @return [void]
+    #
+    def self.run(argv = [])
+      argv = ARGV.coherce(argv)
+      PluginsHelper.load_plugins(plugin_prefix)
+      command = parse(argv)
+
+      unless Options.handle_root_option(command, argv)
+        ANSI.disabled = !ansi_output?
         command.validate!
         command.run
-        rescue Exception => exception
-          if exception.is_a?(InformativeError)
-            puts exception.message
-            if command.verbose?
-              puts
-              puts(*exception.backtrace)
-            end
-            exit exception.exit_status
-          else
-            report_error(exception)
-          end
-      end
-
-      # Allows the application to perform custom error reporting, by overriding
-      # this method.
-      #
-      # @param [Exception] exception
-      #
-      #   An exception that occurred while running a command through
-      #   {Command.run}.
-      #
-      # @raise
-      #
-      #   By default re-raises the specified exception.
-      #
-      # @return [void]
-      #
-      def report_error(exception)
-        raise exception
       end
+    rescue Object => exception
+      handle_exception(command, exception)
+    end
 
-      # @visibility private
-      #
-      # @param  [String] error_message
-      #         The error message to show to the user.
-      #
-      # @param  [Boolean] ansi_output
-      #         Whether or not to use ANSI codes to prettify output.
-      #
-      # @param  [Class] help_class
-      #         The class to use to raise a ‘help’ error.
-      #
-      # @raise  [Help]
-      #
-      #   Signals CLAide that a help banner for this command should be shown,
-      #   with an optional error message.
-      #
-      # @return [void]
-      #
-      def help!(error_message = nil, ansi_output = false, help_class = Help)
-        raise help_class.new(banner(ansi_output), error_message, ansi_output)
-      end
+    def self.parse(argv)
+      Parser.parse(self, argv)
+    end
 
-      # @visibility private
-      #
-      # Returns the banner for the command.
-      #
-      # @param  [Boolean] ansi
-      #         Whether the banner should use ANSI codes to prettify output.
-      #
-      # @param  [Class] banner_class
-      #         The class to use to format help banners.
-      #
-      # @return [String] The banner for the command.
-      #
-      def banner(ansi_output = false, banner_class = Banner)
-        banner_class.new(self, ansi_output).formatted_banner
+    # Presents an exception to the user according to class of the .
+    #
+    # @param  [Command] command
+    #         The command which originated the exception.
+    #
+    # @param  [Object] exception
+    #         The exception to present.
+    #
+    # @return [void]
+    #
+    def self.handle_exception(command, exception)
+      if exception.is_a?(InformativeError)
+        puts exception.message
+        if command.verbose?
+          puts
+          puts(*exception.backtrace)
+        end
+        exit exception.exit_status
+      else
+        report_error(exception)
       end
+    end
 
-      # Load additional plugins via rubygems looking for:
-      #
-      # <command-path>/plugin.rb
-      #
-      # where <command-path> is the namespace of the Command converted to a
-      # path, for example:
-      #
-      # Pod::Command
-      #
-      # maps to
-      #
-      # pod/command
-      #
-      def load_plugins
-        return unless plugin_prefix
-        files_to_require = if Gem.respond_to? :find_latest_files
-                             Gem.find_latest_files("#{plugin_prefix}_plugin")
-                           else
-                             Gem.find_files("#{plugin_prefix}_plugin")
-                           end
-        files_to_require.each { |path| require_plugin_path(path) }
-      end
+    # Allows the application to perform custom error reporting, by overriding
+    # this method.
+    #
+    # @param [Exception] exception
+    #
+    #   An exception that occurred while running a command through
+    #   {Command.run}.
+    #
+    # @raise
+    #
+    #   By default re-raises the specified exception.
+    #
+    # @return [void]
+    #
+    def self.report_error(exception)
+      raise exception
+    end
 
-      # Loads the plugin file at the given path, catching any failure.
-      #
-      # @param [String] path
-      #        The path to load.
-      #
-      def require_plugin_path(path)
-        require path
-      rescue Exception => exception
-        message = "\n---------------------------------------------"
-        message << "\nError loading the plugin with path `#{path}`.\n"
-        message << "\n#{exception.class} - #{exception.message}"
-        message << "\n#{exception.backtrace.join("\n")}"
-        message << "\n---------------------------------------------\n"
-        puts prettify_plugin_load_error(message)
-      end
+    # @visibility private
+    #
+    # @param  [String] error_message
+    #         The error message to show to the user.
+    #
+    # @param  [Class] help_class
+    #         The class to use to raise a ‘help’ error.
+    #
+    # @raise  [Help]
+    #
+    #   Signals CLAide that a help banner for this command should be shown,
+    #   with an optional error message.
+    #
+    # @return [void]
+    #
+    def self.help!(error_message = nil, help_class = Help)
+      raise help_class.new(banner, error_message)
+    end
 
-      # Override to control how to print the warning that’s shown when an
-      # exception occurs during plugin loading.
-      #
-      # By default this will be displayed in yellow if `#ansi_output?` returns
-      # `true`.
-      #
-      # @param [String] message
-      #        The plugin load error message.
-      #
-      def prettify_plugin_load_error(message)
-        ansi_output? ? message.yellow : message
-      end
+    # @visibility private
+    #
+    # Returns the banner for the command.
+    #
+    # @param  [Boolean] ansi
+    #         Whether the banner should use ANSI codes to prettify output.
+    #
+    # @param  [Class] banner_class
+    #         The class to use to format help banners.
+    #
+    # @return [String] The banner for the command.
+    #
+    def self.banner(banner_class = Banner)
+      banner_class.new(self).formatted_banner
     end
 
     #-------------------------------------------------------------------------#
@@ -429,27 +395,6 @@ module CLAide
     attr_accessor :ansi_output
     alias_method :ansi_output?, :ansi_output
 
-    def colorize_output
-      warn "[!] The use of `CLAide::Command#colorize_output` has been " \
-           "deprecated. Use `CLAide::Command#ansi_output` instead. " \
-           "(Called from: #{caller.first})"
-      ansi_output
-    end
-    alias_method :colorize_output?, :colorize_output
-
-    def colorize_output=(flag)
-      warn "[!] The use of `CLAide::Command#colorize_output=` has been " \
-           "deprecated. Use `CLAide::Command#ansi_output=` instead. " \
-           "(Called from: #{caller.first})"
-      self.ansi_output = flag
-    end
-
-    # @return [Bool] Whether the command was invoked by an abstract command by
-    #         default.
-    #
-    attr_accessor :invoked_as_default
-    alias_method :invoked_as_default?, :invoked_as_default
-
     # Subclasses should override this method to remove the arguments/options
     # they support from `argv` _before_ calling `super`.
     #
@@ -466,17 +411,15 @@ module CLAide
       argv = ARGV.new(argv) unless argv.is_a?(ARGV)
       @verbose = argv.flag?('verbose')
       @ansi_output = argv.flag?('ansi', Command.ansi_output?)
-
-      color = argv.flag?('color')
-      unless color.nil?
-        warn "[!] The use of the `--color`/`--no-color` flag has been " \
-             "deprecated. Use `--ansi`/`--no-ansi` instead."
-        @ansi_output = color
-      end
-
       @argv = argv
     end
 
+    # @return [Bool] Whether the command was invoked by an abstract command by
+    #         default.
+    #
+    attr_accessor :invoked_as_default
+    alias_method :invoked_as_default?, :invoked_as_default
+
     # Raises a Help exception if the `--help` option is specified, if `argv`
     # still contains remaining arguments/options by the time it reaches this
     # implementation, or when called on an ‘abstract command’.
@@ -491,17 +434,20 @@ module CLAide
     #
     def validate!
       help! if @argv.flag?('help')
-      help! "Unknown arguments: #{@argv.remainder.join(' ')}" if !@argv.empty?
+      unless @argv.empty?
+        help! ValidationHelper.argument_suggestion(@argv.remainder, self.class)
+      end
       help! if self.class.abstract_command?
     end
 
-    # This method should be overridden by the command class to perform its work.
+    # This method should be overridden by the command class to perform its
+    # work.
     #
     # @return [void
     #
     def run
-      raise "A subclass should override the `CLAide::Command#run` method to " \
-            "actually perform some work."
+      raise 'A subclass should override the `CLAide::Command#run` method to ' \
+        'actually perform some work.'
     end
 
     protected
@@ -519,10 +465,9 @@ module CLAide
       else
         command = self.class
       end
-      command = command.help!(error_message, ansi_output?)
+      command.help!(error_message)
     end
 
     #-------------------------------------------------------------------------#
-
   end
 end