claide 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa421ae80f05ff7766c67d15049c75363ea796ca
-  data.tar.gz: 6c85d3c205a7f365992cb83913663e923eaf89e0
+  metadata.gz: 39fe6340165dbe39cd732747424e3360f6fde1ca
+  data.tar.gz: 96a7229736da06c1c4ec61c9a2fc1a9a972fe1b2
 SHA512:
-  metadata.gz: 125926a5f8beb325d3e5a8a8b834de3db972cf402d62dab2c7afcfba52dd8738f152c30dceb02ce41a42a5ed5715d135b49d155e0ecfd2c021a8f64c9dd3b5ab
-  data.tar.gz: 99bf6357be57b12289b94501bd708c558b4ac45c9ada4321f0927b4e9f087e39c971bdfbdf20ed7cb0530ae42522c245d8fc70f0a853a00bbc71cba995d6f90a
+  metadata.gz: 4cbd2c94407f1083a03629754892b8acbda7c2c5335f004c26e59f7040fb3532a161f082b7171a15f89f05db1cc80f2d447c645a35ff4fd5c45cb034126e6c25
+  data.tar.gz: c9af023661f85713f91b4fb2b4480b73599c2506272ad1362fa6fa5a3feb110066c02e5479926890151bb16bb95ca2d890e46875f7c87471dc1697819e0f95c2

data/lib/claide.rb

@@ -8,14 +8,12 @@ module CLAide
   #
   #   CLAide’s version, following [semver](http://semver.org).
   #
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 
   require 'claide/ansi'
   require 'claide/argument'
   require 'claide/argv'
   require 'claide/command'
   require 'claide/help'
-  require 'claide/helper'
   require 'claide/informative_error'
-  require 'claide/mixins'
 end

data/lib/claide/argument.rb

@@ -56,7 +56,7 @@ module CLAide
     #
     def ==(other)
       other.is_a?(Argument) &&
-      names == other.names && required == other.required
+        names == other.names && required == other.required
     end
   end
 end

data/lib/claide/argv.rb

@@ -1,19 +1,17 @@
 # encoding: utf-8
 
-require 'claide/argv/parser'
-
 module CLAide
   # This class is responsible for parsing the parameters specified by the user,
   # accessing individual parameters, and keep state by removing handled
   # parameters.
   #
   class ARGV
-    # @return [ARGV] Coherces an object to the ARGV class if needed.
+    # @return [ARGV] Coerces an object to the ARGV class if needed.
     #
     # @param  [Object] argv
     #         The object which should be converted to the ARGV class.
     #
-    def self.coherce(argv)
+    def self.coerce(argv)
       if argv.is_a?(ARGV)
         argv
       else
@@ -203,5 +201,85 @@ module CLAide
       end
       result.nil? ? default : result
     end
+
+    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)
+          parsed_argument = parse_argument(type, argument)
+          entries << [type, parsed_argument]
+        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 the argument itself for
+      #         normal arguments (like commands) and a tuple with the 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.parse_argument(type, argument)
+        case type
+        when :arg
+          return argument
+        when :flag
+          return parse_flag(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.parse_flag(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,11 +1,8 @@
 # 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'
+require 'claide/command/plugin_manager'
+require 'claide/command/argument_suggester'
 
 module CLAide
   # This class is used to build a command-line interface
@@ -83,11 +80,14 @@ module CLAide
       #
       attr_accessor :description
 
-      # @return [String] The prefix for loading CLAide plugins for this
-      #         command. Plugins are loaded via their
-      #         <plugin_prefix>_plugin.rb file.
+      # @return [Array<String>] The prefixes used t osearch for CLAide plugins.
+      #         Plugins are loaded via their `<plugin_prefix>_plugin.rb` file.
+      #         Defaults to search for `claide` plugins.
       #
-      attr_accessor :plugin_prefix
+      def plugin_prefixes
+        @plugin_prefixes ||= ['claide']
+      end
+      attr_writer :plugin_prefixes
 
       # @return [Array<Argument>]
       #         A list of arguments the command handles. This is shown
@@ -219,6 +219,16 @@ module CLAide
       subcommands << subcommand
     end
 
+    DEFAULT_ROOT_OPTIONS = [
+      ['--version', 'Show the version of the tool'],
+    ]
+
+    DEFAULT_OPTIONS = [
+      ['--verbose', 'Show more debugging information'],
+      ['--no-ansi', 'Show output without ANSI codes'],
+      ['--help',    'Show help banner of specified command'],
+    ]
+
     # Should be overridden by a subclass if it handles any options.
     #
     # The subclass has to combine the result of calling `super` and its own
@@ -239,15 +249,44 @@ module CLAide
     #   end
     #
     def self.options
-      Options.default_options(self)
+      if root_command?
+        DEFAULT_ROOT_OPTIONS + DEFAULT_OPTIONS
+      else
+        DEFAULT_OPTIONS
+      end
+    end
+
+    # Handles root commands options if appropriate.
+    #
+    # @param  [ARGV] argv
+    #         The parameters of the command.
+    #
+    # @return [Bool] Whether any root command option was handled.
+    #
+    def handle_root_options(argv)
+      return false unless self.class.root_command?
+      if argv.flag?('version')
+        print_version
+        return true
+      end
+      false
+    end
+
+    # Prints the version of the command optionally including plugins.
+    #
+    def print_version
+      puts self.class.version
+      if verbose?
+        PluginManager.specifications.each do |spec|
+          puts "#{spec.name}: #{spec.version}"
+        end
+      end
     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
-    #
     # @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
@@ -261,12 +300,14 @@ module CLAide
     # @return [void]
     #
     def self.run(argv = [])
-      argv = ARGV.coherce(argv)
-      PluginsHelper.load_plugins(plugin_prefix)
-      command = parse(argv)
+      plugin_prefixes.each do |plugin_prefix|
+        PluginManager.load_plugins(plugin_prefix)
+      end
 
+      argv = ARGV.coerce(argv)
+      command = parse(argv)
       ANSI.disabled = !command.ansi_output?
-      unless Options.handle_root_option(command, argv)
+      unless command.handle_root_options(argv)
         command.validate!
         command.run
       end
@@ -274,14 +315,47 @@ module CLAide
       handle_exception(command, exception)
     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 self.parse(argv)
-      Parser.parse(self, argv)
+      argv = ARGV.coerce(argv)
+      cmd = argv.arguments.first
+      if cmd && subcommand = find_subcommand(cmd)
+        argv.shift_argument
+        subcommand.parse(argv)
+      elsif abstract_command? && default_subcommand
+        load_default_subcommand(argv)
+      else
+        new(argv)
+      end
+    end
+
+    # @param  [Array, ARGV] argv
+    #         A list of (remaining) parameters.
+    #
+    # @return [Command] Returns the default subcommand initialized with the
+    #         given arguments.
+    #
+    def self.load_default_subcommand(argv)
+      unless subcommand = find_subcommand(default_subcommand)
+        raise 'Unable to find the default subcommand ' \
+          "`#{default_subcommand}` for command `#{self}`."
+      end
+      result = subcommand.parse(argv)
+      result.invoked_as_default = true
+      result
     end
 
-    # Presents an exception to the user according to class of the .
+    # Presents an exception to the user in a short manner in case of an
+    # `InformativeError` or in long form in other cases,
     #
-    # @param  [Command] command
-    #         The command which originated the exception.
+    # @param  [Command, nil] command
+    #         The command from where the exception originated.
     #
     # @param  [Object] exception
     #         The exception to present.
@@ -291,7 +365,7 @@ module CLAide
     def self.handle_exception(command, exception)
       if exception.is_a?(InformativeError)
         puts exception.message
-        if command.verbose?
+        if command.nil? || command.verbose?
           puts
           puts(*exception.backtrace)
         end
@@ -316,7 +390,7 @@ module CLAide
     # @return [void]
     #
     def self.report_error(exception)
-      plugins = PluginsHelper.plugins_involved_in_exception(exception)
+      plugins = PluginManager.plugins_involved_in_exception(exception)
       unless plugins.empty?
         puts '[!] The exception involves the following plugins:' \
           "\n -  #{plugins.join("\n -  ")}\n".ansi.yellow
@@ -414,12 +488,30 @@ module CLAide
     #   A list of (user-supplied) params that should be handled.
     #
     def initialize(argv)
-      argv = ARGV.new(argv) unless argv.is_a?(ARGV)
+      argv = ARGV.coerce(argv)
       @verbose = argv.flag?('verbose')
       @ansi_output = argv.flag?('ansi', Command.ansi_output?)
       @argv = argv
     end
 
+    # Convenience method.
+    # Instantiate the command and run it with the provided arguments at once.
+    #
+    # @note This method validate! the command before running it, but contrary to
+    # CLAide::Command::run, it does not load plugins nor exit on failure.
+    # It is up to the caller to rescue any possible exception raised.
+    #
+    # @param [String..., Array<String>] args
+    #        The arguments to initialize the command with
+    #
+    # @raise [Help] If validate! fails
+    #
+    def self.invoke(*args)
+      command = new(ARGV.new(args.flatten))
+      command.validate!
+      command.run
+    end
+
     # @return [Bool] Whether the command was invoked by an abstract command by
     #         default.
     #
@@ -441,7 +533,8 @@ module CLAide
     def validate!
       banner! if @argv.flag?('help')
       unless @argv.empty?
-        help! ValidationHelper.argument_suggestion(@argv.remainder, self.class)
+        argument = @argv.remainder.first
+        help! ArgumentSuggester.new(argument, self.class).suggestion
       end
       help! if self.class.abstract_command?
     end
@@ -530,5 +623,15 @@ module CLAide
         end
       end
     end
+
+    # Handle depracted form of assigning a plugin prefix.
+    #
+    # @todo Remove deprecated form.
+    #
+    def self.plugin_prefix=(prefix)
+      warn '[!] The specification of a singular plugin prefix has been ' \
+           "deprecated. Use `#{self}::plugin_prefixes` instead."
+      plugin_prefixes << prefix
+    end
   end
 end

data/lib/claide/command/argument_suggester.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+module CLAide
+  class Command
+    class ArgumentSuggester
+      # @param  [String] argument
+      #         The unrecognized argument for which to make a suggestion.
+      #
+      # @param  [Class] command_class
+      #         The class of the command which encountered the unrecognized
+      #         arguments.
+      #
+      def initialize(argument, command_class)
+        @argument, @command_class = argument, command_class
+        @argument_type = ARGV::Parser.argument_type(@argument)
+      end
+
+      # @return [Array<String>] The list of the valid arguments for a command
+      #         according to the type of the argument.
+      #
+      def possibilities
+        case @argument_type
+        when :option, :flag
+          @command_class.options.map(&:first)
+        when :arg
+          @command_class.subcommands_for_command_lookup.map(&:command)
+        end
+      end
+
+      # @return [String] Returns a suggested argument from `possibilities` based
+      #         on the `levenshtein_distance` score.
+      #
+      def suggested_argument
+        possibilities.sort_by do |element|
+          self.class.levenshtein_distance(@argument, element)
+        end.first
+      end
+
+      # @return [String] Returns a message including a suggestion for the given
+      #         suggestion.
+      #
+      def suggestion
+        argument_description = @argument_type == :arg ? 'command' : 'option'
+        if suggestion = suggested_argument
+          pretty_suggestion = self.class.prettify_suggestion(suggestion,
+                                                             @argument_type)
+          "Unknown #{argument_description}: `#{@argument}`\n" \
+            "Did you mean: #{pretty_suggestion}"
+        else
+          "Unknown #{argument_description}: `#{@argument}`"
+        end
+      end
+
+      # Prettifies the given validation suggestion according to the type.
+      #
+      # @param  [String] suggestion
+      #         The suggestion to prettify.
+      #
+      # @param  [Type] argument_type
+      #         The type of the suggestion: either `:command` or `:option`.
+      #
+      # @return [String] A handsome suggestion.
+      #
+      def self.prettify_suggestion(suggestion, argument_type)
+        case argument_type
+        when :option, :flag
+          suggestion = "#{suggestion}"
+          suggestion.ansi.blue
+        when :arg
+          suggestion.ansi.green
+        end
+      end
+
+      # Returns the Levenshtein distance between the given strings.
+      # From: http://rosettacode.org/wiki/Levenshtein_distance#Ruby
+      #
+      # @param  [String] a
+      #         The first string to compare.
+      #
+      # @param  [String] b
+      #         The second string to compare.
+      #
+      # @return [Fixnum] The distance between the strings.
+      #
+      # rubocop:disable all
+      def self.levenshtein_distance(a, b)
+        a, b = a.downcase, b.downcase
+        costs = Array(0..b.length)
+        (1..a.length).each do |i|
+          costs[0], nw = i, i - 1
+          (1..b.length).each do |j|
+            costs[j], nw = [
+              costs[j] + 1, costs[j - 1] + 1, a[i - 1] == b[j - 1] ? nw : nw + 1
+            ].min, costs[j]
+          end
+        end
+        costs[b.length]
+      end
+      # rubocop:enable all
+    end
+  end
+end