claide 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 36f21c6747d3cf6f375f617e2e9a5dda06c6bf62
-  data.tar.gz: 8e127974a2cca76d6c727eed4f3c2afaf5bac18a
+  metadata.gz: c48ac46a6dd1a3d4b6e9b31d6e7e0a9b4697ecc7
+  data.tar.gz: aafaf22c16450580a41154a005103b321654fddf
 SHA512:
-  metadata.gz: b9a061458ebfb79695b865f757f09e6f46e775a2695612b810d7bdb813e4ef1a6c4e79346b89fcc69a4a3d9a855039a305a84bbe669c2f8baafc76ab96dc5688
-  data.tar.gz: 68f8dfc688c182c00ac906789c5cb74d89534b5b76c8d9bf8c5e8d4cea19b61af4c0778371be238c18aca1d50e47e7932439e4b4819d31633779ea0546c182b5
+  metadata.gz: 9f2a2db1a5e9632761d90bd3486376fe856b6f4012f69391ea093b810c3883cd1f8b9b1b271f42bec2b3b105ba2ef3a14adf1a07ec2fa45f97edb6785f0dedaf
+  data.tar.gz: ee607530bb899f4a376bcb6a262a9dbf8bd7790cf85a568f99234ad156249f23e38f5f2cd9f364da6c626ef9fba0501c0c8277b9508cce99cc34f835462288cc

data/lib/claide.rb

@@ -9,11 +9,11 @@ module CLAide
   #
   #   CLAide’s version, following [semver](http://semver.org).
   #
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 
-  require 'claide/argv.rb'
-  require 'claide/command.rb'
-  require 'claide/help.rb'
-  require 'claide/informative_error.rb'
+  require 'claide/argv'
+  require 'claide/command'
+  require 'claide/help'
+  require 'claide/informative_error'
 
 end

data/lib/claide/argv.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module CLAide
 
   # This class is responsible for parsing the parameters specified by the user,

data/lib/claide/command.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require 'claide/command/banner'
 
 module CLAide
@@ -53,6 +55,17 @@ module CLAide
       attr_accessor :abstract_command
       alias_method :abstract_command?, :abstract_command
 
+      # @return [Boolean] Indicates whether or not this command is used during
+      #         command parsing and whether or not it should be shown in the
+      #         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)
+        @ignore_in_command_lookup = self.abstract_command = flag
+      end
+
       # @return [String] The subcommand which an abstract command should invoke
       #         by default.
       #
@@ -80,21 +93,39 @@ module CLAide
       #
       attr_accessor :arguments
 
-      # @return [Boolean] The default value for {Command#colorize_output}. This
-      #         defaults to `true` if `String` has the instance methods
-      #         `#green` and `#red`.  Which are defined by, for instance, the
-      #         [colored](https://github.com/defunkt/colored) gem.
-      #
-      def colorize_output
-        if @colorize_output.nil?
-          @colorize_output = String.method_defined?(:red) &&
-                               String.method_defined?(:green)
+      # @return [Boolean] The default value for {Command#ansi_output}. This
+      #         defaults to `true` if `STDOUT` is connected to a TTY and
+      #         `String` has the instance methods `#red`, `#green`, and
+      #         `#yellow` (which are defined by, for instance, the
+      #         [colored](https://github.com/defunkt/colored) gem).
+      #
+      def ansi_output
+        if @ansi_output.nil?
+          @ansi_output = STDOUT.tty? &&
+                           String.method_defined?(:red) &&
+                             String.method_defined?(:green) &&
+                               String.method_defined?(:yellow)
         end
-        @colorize_output
+        @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
-      attr_writer :colorize_output
       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.
       #
@@ -105,7 +136,10 @@ module CLAide
       end
       attr_writer :command
 
-      # @return [String] The full command up-to this 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
       #
@@ -113,19 +147,49 @@ module CLAide
       #
       def full_command
         if superclass == Command
-          "#{command}"
+          ignore_in_command_lookup? ? '' : command
         else
-          "#{superclass.full_command} #{command}"
+          if ignore_in_command_lookup?
+            superclass.full_command
+          else
+            "#{superclass.full_command} #{command}"
+          end
         end
       end
 
-      # @return [Array<Class>] A list of command classes that are nested under
-      #         this command.
+      # @return [Array<Class>] A list of all command classes that are nested
+      #         under this command.
       #
       def subcommands
         @subcommands ||= []
       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
+
+      # 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
+
       # @visibility private
       #
       # Automatically registers a subclass as a subcommand.
@@ -158,8 +222,8 @@ module CLAide
           ['--verbose', 'Show more debugging information'],
           ['--help',    'Show help banner of specified command'],
         ]
-        if Command.colorize_output?
-          options.unshift(['--no-color', 'Show output without color'])
+        if Command.ansi_output?
+          options.unshift(['--no-ansi', 'Show output without ANSI codes'])
         end
         options
       end
@@ -174,14 +238,14 @@ module CLAide
       def parse(argv)
         argv = ARGV.new(argv) unless argv.is_a?(ARGV)
         cmd = argv.arguments.first
-        if cmd && subcommand = subcommands.find { |sc| sc.command == cmd }
+        if cmd && subcommand = find_subcommand(cmd)
           argv.shift_argument
           subcommand.parse(argv)
         elsif abstract_command? && default_subcommand
-          subcommand = subcommands.find { |sc| sc.command == default_subcommand }
+          subcommand = find_subcommand(default_subcommand)
           unless subcommand
-            raise "Unable to find the default subcommand `#{default_subcommand}` " \
-              "for command `#{self}`."
+            raise "Unable to find the default subcommand " \
+                  "`#{default_subcommand}` for command `#{self}`."
           end
           result = subcommand.parse(argv)
           result.invoked_as_default = true
@@ -244,28 +308,40 @@ module CLAide
 
       # @visibility private
       #
-      # @raise [Help]
+      # @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, colorize = false)
-        raise Help.new(banner(colorize), error_message, colorize)
+      def help!(error_message = nil, ansi_output = false, help_class = Help)
+        raise help_class.new(banner(ansi_output), error_message, ansi_output)
       end
 
       # @visibility private
       #
       # Returns the banner for the command.
       #
-      # @param  [Bool] colorize
-      #         Whether the banner should be returned colorized.
+      # @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(colorize = false)
-        Banner.new(self, colorize).formatted_banner
+      def banner(ansi_output = false, banner_class = Banner)
+        banner_class.new(self, ansi_output).formatted_banner
       end
 
       # Load additional plugins via rubygems looking for:
@@ -304,8 +380,20 @@ module CLAide
         message << "\n#{exception.class} - #{exception.message}"
         message << "\n#{exception.backtrace.join("\n")}"
         message << "\n---------------------------------------------\n"
-        message = colorize_output ? message.yellow : message
-        puts message
+        puts prettify_plugin_load_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
     end
 
@@ -327,19 +415,35 @@ module CLAide
     attr_accessor :verbose
     alias_method :verbose?, :verbose
 
-    # Set to `true` if {Command.colorize_output} returns `true` and the user
-    # did **not** specify the `--no-color` option.
+    # Set to `true` if {Command.ansi_output} returns `true` and the user
+    # did **not** specify the `--no-ansi` option.
     #
     # @note (see #verbose)
     #
     # @return [Boolean]
     #
-    #   Wether or not to color {InformativeError} exception messages red and
+    #   Whether or not to use ANSI codes to prettify output. For instance, by
+    #   default {InformativeError} exception messages will be colored red and
     #   subcommands in help banners green.
     #
-    attr_accessor :colorize_output
+    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.
     #
@@ -350,9 +454,9 @@ module CLAide
     # they support from `argv` _before_ calling `super`.
     #
     # The `super` implementation sets the {#verbose} attribute based on whether
-    # or not the `--verbose` option is specified; and the {#colorize_output}
-    # attribute to `false` if {Command.colorize_output} returns `true`, but the
-    # user specified the `--no-color` option.
+    # or not the `--verbose` option is specified; and the {#ansi_output}
+    # attribute to `false` if {Command.ansi_output} returns `true`, but the
+    # user specified the `--no-ansi` option.
     #
     # @param [ARGV, Array] argv
     #
@@ -361,7 +465,15 @@ module CLAide
     def initialize(argv)
       argv = ARGV.new(argv) unless argv.is_a?(ARGV)
       @verbose = argv.flag?('verbose')
-      @colorize_output = argv.flag?('color', Command.colorize_output?)
+      @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
 
@@ -388,8 +500,8 @@ module CLAide
     # @return [void
     #
     def run
-      raise "A subclass should override the 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
@@ -407,7 +519,7 @@ module CLAide
       else
         command = self.class
       end
-      command = command.help!(error_message, colorize_output?)
+      command = command.help!(error_message, ansi_output?)
     end
 
     #-------------------------------------------------------------------------#

data/lib/claide/command/banner.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module CLAide
   class Command
 
@@ -12,15 +14,30 @@ module CLAide
 
       # @return [Bool]
       #
-      attr_accessor :colorize_output
+      attr_accessor :ansi_output
+      alias_method :ansi_output?, :ansi_output
+
+      def colorize_output
+        warn "[!] The use of `CLAide::Command::Banner#colorize_output` has " \
+             "been deprecated. Use `CLAide::Command::Banner#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::Banner#colorize_output=` has " \
+             "been deprecated. Use `CLAide::Command::Banner#ansi_output=` " \
+             "instead. (Called from: #{caller.first})"
+        self.ansi_output = flag
+      end
+
       # @param [Class] command @see command
-      # @param [Class] colorize_output@see colorize_output
+      # @param [Class] ansi_output @see ansi_output
       #
-      def initialize(command, colorize_output = false)
+      def initialize(command, ansi_output = false)
         @command = command
-        @colorize_output = colorize_output
+        @ansi_output = ansi_output
       end
 
       # @return [String]
@@ -52,8 +69,27 @@ module CLAide
       #
       def formatted_options_description
         opts = command.options
-        size = opts.map { |opt| opt.first.size }.max
-        opts.map { |key, desc| "    #{key.ljust(size)}   #{desc}" }.join("\n")
+        max_key_size = opts.map { |opt| opt.first.size }.max
+
+        desc_start = max_key_size + 7 # fixed whitespace in `result` var
+        desc_width = terminal_width - desc_start
+
+        opts.map do |key, desc|
+          space = ' ' * (max_key_size - key.size)
+          result = "    #{prettify_option_name(key)}#{space}   "
+          if terminal_width == 0
+            result << desc
+          else
+            space = ' ' * desc_start
+            result << word_wrap(desc, desc_width).split("\n").join("\n#{space}")
+          end
+        end.join("\n")
+      end
+
+      # @return [String]
+      #
+      def prettify_option_name(name)
+        name
       end
 
       # @return [String]
@@ -63,21 +99,28 @@ module CLAide
           message = strip_heredoc(message)
           message = message.split("\n").map { |line| "      #{line}" }.join("\n")
           args = " #{command.arguments}" if command.arguments
-          "    $ #{command.full_command}#{args}\n\n#{message}"
+          cmd = "$ #{command.full_command}#{args}"
+          "    #{prettify_command_in_usage_description(cmd)}\n\n#{message}"
         end
       end
 
+      # @return [String]
+      #
+      def prettify_command_in_usage_description(command)
+        command
+      end
+
       # @return [String]
       #
       def formatted_subcommand_summaries
-        subcommands = command.subcommands.reject do |subcommand|
+        subcommands = command.subcommands_for_command_lookup.reject do |subcommand|
           subcommand.summary.nil?
         end.sort_by(&:command)
         unless subcommands.empty?
           command_size = subcommands.map { |cmd| cmd.command.size }.max
           subcommands.map do |subcommand|
             subcommand_string = subcommand.command.ljust(command_size)
-            subcommand_string = subcommand_string.green if colorize_output?
+            subcommand_string = prettify_subcommand_name(subcommand_string)
             is_default = subcommand.command == command.default_subcommand
             if is_default
               bullet_point = '-'
@@ -89,6 +132,12 @@ module CLAide
         end
       end
 
+      # @return [String]
+      #
+      def prettify_subcommand_name(name)
+        ansi_output? ? name.green : name
+      end
+
       private
 
       # @!group Private helpers
@@ -105,6 +154,24 @@ module CLAide
         end
       end
 
+      # @return [String] Lifted straight from ActionView. Thanks guys!
+      #
+      def word_wrap(line, line_width)
+        line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip
+      end
+
+      # @return [Fixnum] The width of the current terminal, unless being piped.
+      #
+      def terminal_width
+        @terminal_width ||= begin
+          if STDOUT.tty? && system('which tput > /dev/null 2>&1')
+            `tput cols`.to_i
+          else
+            0
+          end
+        end
+      end
+
     end
   end
 end

data/lib/claide/help.rb

@@ -1,6 +1,8 @@
+# encoding: utf-8
+
 module CLAide
 
-  require 'claide/informative_error.rb'
+  require 'claide/informative_error'
 
   # The exception class that is raised to indicate a help banner should be
   # shown while running {Command.run}.
@@ -18,9 +20,18 @@ module CLAide
     #
     attr_reader :error_message
 
-    # @return [Bool] Whether the error message should be colorized.
+    # @return [Bool] Whether the error message should use ANSI codes to
+    #         prettify output.
     #
-    attr_reader  :colorize
+    attr_reader  :ansi_output
+    alias_method :ansi_output?, :ansi_output
+
+    def colorize
+      warn "[!] The use of `CLAide::Help#colorize` has been " \
+           "deprecated. Use `CLAide::Help#ansi_output` instead. " \
+           "(Called from: #{caller.first})"
+      ansi_output
+    end
     alias_method :colorize?, :colorize
 
     # @param [String] banner @see banner
@@ -30,10 +41,10 @@ module CLAide
     #        terminate the program with, will be set to `1`, otherwise a {Help}
     #        exception is treated as not being a real error and exits with `0`.
     #
-    def initialize(banner, error_message = nil, colorize = false)
+    def initialize(banner, error_message = nil, ansi_output = false)
       @banner = banner
       @error_message = error_message
-      @colorize = colorize
+      @ansi_output = ansi_output
       @exit_status = @error_message.nil? ? 0 : 1
     end
 
@@ -43,10 +54,16 @@ module CLAide
     def formatted_error_message
       if error_message
         message = "[!] #{error_message}"
-        colorize? ? message.red : message
+        prettify_error_message(message)
       end
     end
 
+    # @return [String]
+    #
+    def prettify_error_message(message)
+      ansi_output? ? message.red : message
+    end
+
     # @return [String] The optional error message, combined with the help
     #         banner of the command.
     #

data/lib/claide/informative_error.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module CLAide
 
   # Including this module into an exception class will ensure that when raised,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claide
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Eloy Duran
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-14 00:00:00.000000000 Z
+date: 2014-03-26 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -19,14 +19,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.markdown
+- lib/claide.rb
 - lib/claide/argv.rb
-- lib/claide/command/banner.rb
 - lib/claide/command.rb
+- lib/claide/command/banner.rb
 - lib/claide/help.rb
 - lib/claide/informative_error.rb
-- lib/claide.rb
-- README.markdown
-- LICENSE
 homepage: https://github.com/CocoaPods/CLAide
 licenses:
 - MIT
@@ -37,17 +37,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.0.3
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 3
 summary: A small command-line interface framework.