claide 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c401c5a5be0c7e2652c31c9cc82a46dca6a8b4b2
-  data.tar.gz: 76dc8118415015daf186720e9c188f86bd37c512
+  metadata.gz: fa421ae80f05ff7766c67d15049c75363ea796ca
+  data.tar.gz: 6c85d3c205a7f365992cb83913663e923eaf89e0
 SHA512:
-  metadata.gz: 0b38f9c3ef3e9a08dc2b6f52002aa928e48216f3b1fe3997d1613499c1f1716566e6f865a498c4f2e3854aaf4db9e2308a5b02549d884fd115ec5477da7a1077
-  data.tar.gz: 636d2249e8aacb1a0cfe05f88131c7aa46b4fb9904c45075ad51647c5f801442ac7ed312b0b58eefc8997089dd233f130ea125956d32c4af088197d420d65ae5
+  metadata.gz: 125926a5f8beb325d3e5a8a8b834de3db972cf402d62dab2c7afcfba52dd8738f152c30dceb02ce41a42a5ed5715d135b49d155e0ecfd2c021a8f64c9dd3b5ab
+  data.tar.gz: 99bf6357be57b12289b94501bd708c558b4ac45c9ada4321f0927b4e9f087e39c971bdfbdf20ed7cb0530ae42522c245d8fc70f0a853a00bbc71cba995d6f90a

data/lib/claide/ansi.rb

@@ -43,7 +43,7 @@ module CLAide
       :underline  => 4,
       :blink      => 5,
       :reverse    => 7,
-      :hidden     => 8
+      :hidden     => 8,
     }
 
     # @return [Hash{Symbol => Fixnum}] The codes to disable a text attribute by
@@ -54,7 +54,7 @@ module CLAide
       :underline  => 24,
       :blink      => 25,
       :reverse    => 27,
-      :hidden     => 28
+      :hidden     => 28,
     }
 
     # Return [String] The escape sequence to reset the graphics.
@@ -71,7 +71,7 @@ module CLAide
       :blue       => 4,
       :magenta    => 5,
       :cyan       => 6,
-      :white      => 7
+      :white      => 7,
     }
 
     # Return [String] The escape sequence for the default foreground color.

data/lib/claide/argument.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+module CLAide
+  # This class is used to represent individual arguments to present to
+  # the command help banner
+  #
+  class Argument
+    # The string used for ellipsis / repeatable arguments in the banner
+    #
+    ELLIPSIS = '...'
+
+    # @return [Array<String>]
+    #         List of alternate names for the parameters
+    attr_reader :names
+
+    # @return [Boolean]
+    #         Indicates if the argument is required (not optional)
+    #
+    attr_accessor :required
+    alias_method :required?, :required
+
+    # @return [Boolean]
+    #         Indicates if the argument is repeatable (= can appear multiple
+    #         times in the command, which is indicated by '...' in the banner)
+    #
+    attr_accessor :repeatable
+    alias_method :repeatable?, :repeatable
+
+    # @param [String,Array<String>] names
+    #        List of the names of each parameter alternatives.
+    #        For convenience, if there is only one alternative for that
+    #        parameter, we can use a String instead of a 1-item Array
+    #
+    # @param [Boolean] required
+    #        true if the parameter is required, false if it is optional
+    #
+    # @param [Boolean] repeatable
+    #        If true, the argument can appear multiple times in the command.
+    #        In that case, an ellipsis will be appended after the argument
+    #        in the help banner.
+    #
+    # @example
+    #
+    #   # A required parameter that can be either a NAME or URL
+    #   Argument.new(%(NAME URL), true)
+    #
+    def initialize(names, required, repeatable = false)
+      @names = Array(names)
+      @required = required
+      @repeatable = repeatable
+    end
+
+    # @return [Boolean] true on equality
+    #
+    # @param [Argument] other the Argument compared against
+    #
+    def ==(other)
+      other.is_a?(Argument) &&
+      names == other.names && required == other.required
+    end
+  end
+end

data/lib/claide/command/banner/prettifier.rb

@@ -18,11 +18,11 @@ module CLAide
           components = [
             [command, :green],
             [subcommand, :green],
-            [argument, :magenta]
+            [argument, :magenta],
           ]
           components.reduce('') do |memo, (string, ansi_key)|
-            memo << ' ' << string.ansi.apply(ansi_key) unless string.empty?
-            memo
+            next memo if !string || string.empty?
+            memo << ' ' << string.ansi.apply(ansi_key)
           end.lstrip
         end
 
@@ -30,12 +30,14 @@ module CLAide
         #
         def self.prettify_message(command, message)
           message = message.dup
-          [[command.arguments, :magenta],
-           [command.options, :blue]].each do |(list, ansi_key)|
-            list.map(&:first).each do |name|
-              message.gsub!(/`#{name}`/, "`#{name}`".ansi.apply(ansi_key))
+          command.arguments.each do |arg|
+            arg.names.each do |name|
+              message.gsub!("`#{name.gsub(/\.{3}$/, '')}`", '\0'.ansi.magenta)
             end
           end
+          command.options.each do |(name, _description)|
+            message.gsub!("`#{name}`", '\0'.ansi.blue)
+          end
           message
         end
 

data/lib/claide/command/banner.rb

@@ -24,7 +24,7 @@ module CLAide
         sections = [
           ['Usage',    formatted_usage_description],
           ['Commands', formatted_subcommand_summaries],
-          ['Options',  formatted_options_description]
+          ['Options',  formatted_options_description],
         ]
         banner = sections.map do |(title, body)|
           [prettify_title("#{title}:"), body] unless body.empty?
@@ -65,8 +65,10 @@ module CLAide
       # @return [String] The signature of the command.
       #
       def signature
-        result = prettify_signature(
-          command.full_command, signature_sub_command, signature_arguments)
+        full_command = command.full_command
+        sub_command = signature_sub_command
+        arguments = signature_arguments
+        result = prettify_signature(full_command, sub_command, arguments)
         result.insert(0, '$ ')
         result.insert(0, ' ' * (TEXT_INDENT - '$ '.size))
       end
@@ -74,19 +76,18 @@ module CLAide
       # @return [String] The subcommand indicator of the signature.
       #
       def signature_sub_command
-        if command.subcommands.any?
-          command.default_subcommand ? '[COMMAND]' : 'COMMAND'
-        end
-        ''
+        return '[COMMAND]' if command.default_subcommand
+        return 'COMMAND' if command.subcommands.any?
       end
 
       # @return [String] The arguments of the signature.
       #
       def signature_arguments
-        command.arguments.reduce('') do |memo, (name, type)|
-          name = "[#{name}]" if type == :optional
-          memo << ' ' << name
-        end.lstrip
+        command.arguments.map do |arg|
+          names = arg.names.join('|')
+          names.concat(' ' + Argument::ELLIPSIS) if arg.repeatable?
+          arg.required? ? names : "[#{names}]"
+        end.join(' ')
       end
 
       # @return [String] The section describing the subcommands of the command.

data/lib/claide/command/options.rb

@@ -10,7 +10,7 @@ module CLAide
       #
       DEFAULT_ROOT_OPTIONS = [
         ['--completion-script', 'Print the auto-completion script'],
-        ['--version',           'Show the version of the tool']
+        ['--version',           'Show the version of the tool'],
       ]
 
       # @return [Array<Array<String, String>>] The default options implemented
@@ -19,7 +19,7 @@ module CLAide
       DEFAULT_OPTIONS = [
         ['--verbose', 'Show more debugging information'],
         ['--no-ansi', 'Show output without ANSI codes'],
-        ['--help',    'Show help banner of specified command']
+        ['--help',    'Show help banner of specified command'],
       ]
 
       # @return [Array<Array<String, String>>] The list of the default
@@ -67,9 +67,8 @@ module CLAide
       def self.print_version(command)
         puts command.class.version
         if command.verbose?
-          prefix = command.class.plugin_prefix
-          PluginsHelper.plugin_load_paths(prefix).each do |path|
-            puts PluginsHelper.plugin_info(path)
+          PluginsHelper.specifications.each do |spec|
+            puts "#{spec.name}: #{spec.version}"
           end
         end
       end

data/lib/claide/command/plugins_helper.rb

@@ -2,72 +2,77 @@
 
 module CLAide
   class Command
-    module PluginsHelper
-      # Loads additional plugins via rubygems looking for files named after the
-      # `PLUGIN_PREFIX_plugin`.
+    # Handles plugin related logic logic for the `Command` class.
+    #
+    # Plugins are loaded the first time a command run and are identified by the
+    # prefix specified in the command class. Plugins must adopt the following
+    # conventions:
+    #
+    # - Support being loaded by a file located under the
+    # `lib/#{plugin_prefix}_plugin` relative path.
+    # - Be stored in a folder named after the plugin.
+    #
+    class PluginsHelper
+      class << self
+        # @return [Array<Pathname>] The list of the root directories of the
+        #         loaded plugins.
+        #
+        attr_reader :plugin_paths
+      end
+
+      # @return [Array<String>] Loads plugins via RubyGems looking for files
+      #         named after the `PLUGIN_PREFIX_plugin` and returns the paths of
+      #         the gems loaded successfully. Plugins are required safely.
       #
       def self.load_plugins(plugin_prefix)
+        return if plugin_paths
         paths = PluginsHelper.plugin_load_paths(plugin_prefix)
-        loaded_paths = []
+        plugin_paths = []
         paths.each do |path|
-          if PluginsHelper.safe_require(path)
-            loaded_paths << path
+          if PluginsHelper.safe_require(path.to_s)
+            plugin_paths << Pathname(path + './../../').cleanpath
           end
         end
-        loaded_paths
+
+        @plugin_paths = plugin_paths
       end
 
-      # Returns the name and the version of the plugin with the given path.
-      #
-      # @param  [String] path
-      #         The load path of the plugin.
-      #
-      # @return [String] A string including the name and the version or a
-      #         failure message.
+      # @return [Array<Specification>] The RubyGems specifications for the
+      #         loaded plugins.
       #
-      def self.plugin_info(path)
-        if gemspec = find_gemspec(path)
-          spec = Gem::Specification.load(gemspec)
-        end
-
-        if spec
-          "#{spec.name}: #{spec.version}"
-        else
-          "[!] Unable to load a specification for `#{path}`"
-        end
+      def self.specifications
+        PluginsHelper.plugin_paths.map do |path|
+          specification(path)
+        end.compact
       end
 
-      # @return [String] Finds the path of the gemspec of a path. The path is
-      # iterated upwards until a dir with a single gemspec is found.
+      # @return [Array<Specification>] The RubyGems specifications for the
+      #         plugin with the given root path.
       #
-      # @param  [String] path
-      #         The load path of a plugin.
+      # @param  [#to_s] path
+      #         The root path of the plugin.
       #
-      def self.find_gemspec(path)
-        reverse_ascending_paths(path).find do |candidate_path|
-          glob = Dir.glob("#{candidate_path}/*.gemspec")
-          if glob.count == 1
-            return glob.first
-          end
+      def self.specification(path)
+        glob = Dir.glob("#{path}/*.gemspec")
+        spec = Gem::Specification.load(glob.first) if glob.count == 1
+        unless spec
+          warn '[!] Unable to load a specification for the plugin ' \
+            "`#{path}`".ansi.yellow
         end
-        nil
+        spec
       end
 
-      # @return [String] Returns the list of the parents paths of a path.
+      # @return [Array<String>] The list of the plugins whose root path appears
+      #         in the backtrace of an exception.
       #
-      # @param  [String] path
-      #         The path for which the list is needed.
+      # @param  [Exception] exception
+      #         The exception to analyze.
       #
-      def self.reverse_ascending_paths(path)
-        components = path.split('/')[0...-1]
-        progress = nil
-        components.map do |component|
-          if progress
-            progress = progress + '/' + component
-          else
-            progress = component
-          end
-        end.reverse
+      def self.plugins_involved_in_exception(exception)
+        paths = plugin_paths.select do |plugin_path|
+          exception.backtrace.any? { |line| line.include?(plugin_path.to_s) }
+        end
+        paths.map { |path| path.to_s.split('/').last }
       end
 
       # Returns the paths of the files to require to load the available
@@ -77,10 +82,11 @@ module CLAide
       #
       def self.plugin_load_paths(plugin_prefix)
         if plugin_prefix && !plugin_prefix.empty?
+          pattern = "#{plugin_prefix}_plugin"
           if Gem.respond_to? :find_latest_files
-            Gem.find_latest_files("#{plugin_prefix}_plugin")
+            Gem.find_latest_files(pattern)
           else
-            Gem.find_files("#{plugin_prefix}_plugin")
+            Gem.find_files(pattern)
           end
         else
           []

data/lib/claide/command/validation_helper.rb

@@ -18,10 +18,7 @@ module CLAide
         type = ARGV::Parser.argument_type(string)
         list = suggestion_list(command_class, type)
         suggestion = ValidationHelper.suggestion(string, list)
-        pretty_suggestion = prettify_validation_suggestion(suggestion, type)
-        string_type = type == :arg ? 'command' : 'option'
-        "Unknown #{string_type}: `#{string}`\n" \
-          "Did you mean: #{pretty_suggestion}"
+        suggestion_message(suggestion, type, string)
       end
 
       # @return [Array<String>] The list of the valid arguments for a command
@@ -58,6 +55,29 @@ module CLAide
         sorted.first
       end
 
+      # @return [String] Returns a message including a suggestion for the given
+      #         suggestion.
+      #
+      # @param  [String, Nil] suggestion
+      #         The suggestion.
+      #
+      # @param  [Symbol] type
+      #         The type of the suggestion.
+      #
+      # @param  [String] string
+      #         The unrecognized string.
+      #
+      def self.suggestion_message(suggestion, type, string)
+        string_type = type == :arg ? 'command' : 'option'
+        if suggestion
+          pretty_suggestion = prettify_validation_suggestion(suggestion, type)
+          "Unknown #{string_type}: `#{string}`\n" \
+            "Did you mean: #{pretty_suggestion}"
+        else
+          "Unknown #{string_type}: `#{string}`"
+        end
+      end
+
       # Prettifies the given validation suggestion according to the type.
       #
       # @param  [String] suggestion

data/lib/claide/command.rb

@@ -89,44 +89,34 @@ module CLAide
       #
       attr_accessor :plugin_prefix
 
-      # @return [Array<Array<String,Symbol>>]
+      # @return [Array<Argument>]
       #         A list of arguments the command handles. This is shown
       #         in the usage section of the command’s help banner.
-      #         Each Array<String,Symbol> tuple in the array represents an
-      #         argument using the form [name, type] where:
-      #          - name is a String containing the argument
-      #          - type is either :optional or :required
+      #         Each Argument in the array represents an argument by its name
+      #         (or list of alternatives) and whether it's required or optional
       #
-      # @todo   Remove deprecation
-      #
-      attr_accessor :arguments
       def arguments
         @arguments ||= []
       end
 
-      # @param [Array<Array<String,Symbol>>] 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
+      # @param [Array<Argument>] arguments
+      #        An array listing the command arguments.
+      #        Each Argument object describe the argument by its name
+      #        (or list of alternatives) and whether it's required or optional
+      #
+      # @todo   Remove deprecation
       #
-      # rubocop:disable MethodLength
       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
+          if arguments.empty? || arguments[0].is_a?(Argument)
+            @arguments = arguments
+          else
+            self.arguments_array = arguments
           end
+        else
+          self.arguments_string = arguments
         end
       end
-      # rubocop:enable MethodLength
 
       # @return [Boolean] The default value for {Command#ansi_output}. This
       #         defaults to `true` if `STDOUT` is connected to a TTY and
@@ -326,6 +316,11 @@ module CLAide
     # @return [void]
     #
     def self.report_error(exception)
+      plugins = PluginsHelper.plugins_involved_in_exception(exception)
+      unless plugins.empty?
+        puts '[!] The exception involves the following plugins:' \
+          "\n -  #{plugins.join("\n -  ")}\n".ansi.yellow
+      end
       raise exception
     end
 
@@ -361,6 +356,19 @@ module CLAide
       banner_class.new(self).formatted_banner
     end
 
+    # @visibility private
+    #
+    # Print banner and exit
+    #
+    # @note Calling this method exits the current process.
+    #
+    # @return [void]
+    #
+    def self.banner!
+      puts banner
+      exit 0
+    end
+
     #-------------------------------------------------------------------------#
 
     # Set to `true` if the user specifies the `--verbose` option.
@@ -431,7 +439,7 @@ module CLAide
     # @return [void]
     #
     def validate!
-      help! if @argv.flag?('help')
+      banner! if @argv.flag?('help')
       unless @argv.empty?
         help! ValidationHelper.argument_suggestion(@argv.remainder, self.class)
       end
@@ -450,6 +458,21 @@ module CLAide
 
     protected
 
+    # Returns the class of the invoked command
+    #
+    # @return [Command]
+    #
+    def invoked_command_class
+      if invoked_as_default?
+        self.class.superclass
+      else
+        self.class
+      end
+    end
+
+    # @param  [String] error_message
+    #         A custom optional error message
+    #
     # @raise [Help]
     #
     #   Signals CLAide that a help banner for this command should be shown,
@@ -458,14 +481,54 @@ module CLAide
     # @return [void]
     #
     def help!(error_message = nil)
-      if invoked_as_default?
-        command = self.class.superclass
-      else
-        command = self.class
-      end
-      command.help!(error_message)
+      invoked_command_class.help!(error_message)
+    end
+
+    # Print banner and exit
+    #
+    # @note Calling this method exits the current process.
+    #
+    # @return [void]
+    #
+    def banner!
+      invoked_command_class.banner!
     end
 
     #-------------------------------------------------------------------------#
+
+    # Handle deprecated form of self.arguments as an
+    # Array<Array<(String, Symbol)>> like in:
+    #
+    #   self.arguments = [ ['NAME', :required], ['QUERY', :optional] ]
+    #
+    # @todo Remove deprecated format support
+    #
+    def self.arguments_array=(arguments)
+      warn '[!] The signature of CLAide#arguments has changed. ' \
+        "Use CLAide::Argument (#{self}: `#{arguments}`)".ansi.yellow
+      @arguments = arguments.map do |(name_str, type)|
+        names = name_str.split('|')
+        required = (type == :required)
+        Argument.new(names, required)
+      end
+    end
+
+    # Handle deprecated form of self.arguments as a String, like in:
+    #
+    #   self.arguments = 'NAME [QUERY]'
+    #
+    # @todo Remove deprecated format support
+    #
+    def self.arguments_string=(arguments)
+      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.new(argument.sub(/\[(.*)\]/, '\1').split('|'), false)
+        else
+          Argument.new(argument.split('|'), true)
+        end
+      end
+    end
   end
 end

data/lib/claide/helper.rb

@@ -33,9 +33,10 @@ module CLAide
     def self.format_markdown(string, indent = 0, max_width = 80)
       paragraphs = Helper.strip_heredoc(string).split("\n\n")
       paragraphs = paragraphs.map do |paragraph|
-        unless paragraph.start_with?(' ' * 4)
-          full_line = paragraph.gsub("\n", ' ')
-          paragraph = wrap_with_indent(full_line, indent, max_width)
+        if paragraph.start_with?(' ' * 4)
+          paragraph.gsub!(/\n/, "\n#{' ' * indent}")
+        else
+          paragraph = wrap_with_indent(paragraph, indent, max_width)
         end
         paragraph.insert(0, ' ' * indent).rstrip
       end
@@ -62,9 +63,10 @@ module CLAide
         width = [terminal_width, max_width].min
       end
 
+      full_line = string.gsub("\n", ' ')
       available_width = width - indent
       space = ' ' * indent
-      word_wrap(string, available_width).split("\n").join("\n#{space}")
+      word_wrap(full_line, available_width).split("\n").join("\n#{space}")
     end
 
     # @return [String] Lifted straight from ActionView. Thanks guys!

data/lib/claide.rb

@@ -8,9 +8,10 @@ module CLAide
   #
   #   CLAide’s version, following [semver](http://semver.org).
   #
-  VERSION = '0.6.1'
+  VERSION = '0.7.0'
 
   require 'claide/ansi'
+  require 'claide/argument'
   require 'claide/argv'
   require 'claide/command'
   require 'claide/help'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claide
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Eloy Duran
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-20 00:00:00.000000000 Z
+date: 2014-09-11 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -19,28 +19,29 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE
-- README.markdown
-- lib/claide.rb
-- lib/claide/ansi.rb
 - lib/claide/ansi/cursor.rb
 - lib/claide/ansi/graphics.rb
 - lib/claide/ansi/string_escaper.rb
-- lib/claide/argv.rb
+- lib/claide/ansi.rb
+- lib/claide/argument.rb
 - lib/claide/argv/parser.rb
-- lib/claide/command.rb
-- lib/claide/command/banner.rb
+- lib/claide/argv.rb
 - lib/claide/command/banner/prettifier.rb
+- lib/claide/command/banner.rb
 - lib/claide/command/options.rb
 - lib/claide/command/parser.rb
 - lib/claide/command/plugins_helper.rb
-- lib/claide/command/shell_completion_helper.rb
 - lib/claide/command/shell_completion_helper/zsh_completion_generator.rb
+- lib/claide/command/shell_completion_helper.rb
 - lib/claide/command/validation_helper.rb
+- lib/claide/command.rb
 - lib/claide/help.rb
 - lib/claide/helper.rb
 - lib/claide/informative_error.rb
 - lib/claide/mixins.rb
+- lib/claide.rb
+- README.markdown
+- LICENSE
 homepage: https://github.com/CocoaPods/CLAide
 licenses:
 - MIT
@@ -51,17 +52,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 3
 summary: A small command-line interface framework.