claide 0.5.0 → 0.6.0

data/lib/claide/command/banner.rb

@@ -1,177 +1,193 @@
 # encoding: utf-8
 
+require 'claide/command/banner/prettifier'
+
 module CLAide
   class Command
-
     # Creates the formatted banner to present as help of the provided command
     # class.
     #
     class Banner
-
-      # @return [Class]
+      # @return [Class] The command for which the banner should be created.
       #
       attr_accessor :command
 
-      # @return [Bool]
-      #
-      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] ansi_output @see ansi_output
       #
-      def initialize(command, ansi_output = false)
+      def initialize(command)
         @command = command
-        @ansi_output = ansi_output
       end
 
-      # @return [String]
+      # @return [String] The banner for the command.
       #
       def formatted_banner
-        banner = []
-        if command.abstract_command?
-          banner << command.description if command.description
-        elsif usage = formatted_usage_description
-          banner << 'Usage:'
-          banner << usage
-        end
-        if commands = formatted_subcommand_summaries
-          banner << 'Commands:'
-          banner << commands
-        end
-        banner << 'Options:'
-        banner << formatted_options_description
-        banner.join("\n\n")
+        sections = [
+          ['Usage',    formatted_usage_description],
+          ['Commands', formatted_subcommand_summaries],
+          ['Options',  formatted_options_description]
+        ]
+        banner = sections.map do |(title, body)|
+          ["#{prettify_title(title)}:", body] unless body.empty?
+        end.compact.join("\n\n")
+        banner
       end
 
       private
 
       # @!group Banner sections
-
       #-----------------------------------------------------------------------#
 
-      # @return [String]
+      # @return [String] The indentation of the text.
       #
-      def formatted_options_description
-        opts = command.options
-        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")
+      TEXT_INDENT = 6
+
+      # @return [Fixnum] The maximum width of the text.
+      #
+      MAX_WIDTH = TEXT_INDENT + 80
+
+      # @return [Fixnum] The minimum between a name and its description.
+      #
+      DESCRIPTION_SPACES = 3
+
+      # @return [Fixnum] The minimum between a name and its description.
+      #
+      SUBCOMMAND_BULLET_SIZE = 2
+
+      # @return [String] The section describing the usage of the command.
+      #
+      def formatted_usage_description
+        message = command.description || command.summary || ''
+        message = Helper.format_markdown(message, TEXT_INDENT, MAX_WIDTH)
+        message = prettify_message(command, message)
+        "#{signature}\n\n#{message}"
       end
 
-      # @return [String]
+      # @return [String] The signature of the command.
       #
-      def prettify_option_name(name)
-        name
+      def signature
+        result = prettify_signature(
+          command.full_command, signature_sub_command, signature_arguments)
+        result.insert(0, '$ ')
+        result.insert(0, ' ' * (TEXT_INDENT - '$ '.size))
       end
 
-      # @return [String]
+      # @return [String] The subcommand indicator of the signature.
       #
-      def formatted_usage_description
-        if message = command.description || command.summary
-          message = strip_heredoc(message)
-          message = message.split("\n").map { |line| "      #{line}" }.join("\n")
-          args = " #{command.arguments}" if command.arguments
-          cmd = "$ #{command.full_command}#{args}"
-          "    #{prettify_command_in_usage_description(cmd)}\n\n#{message}"
+      def signature_sub_command
+        if command.subcommands.any?
+          command.default_subcommand ? '[COMMAND]' : 'COMMAND'
         end
+        ''
       end
 
-      # @return [String]
+      # @return [String] The arguments of the signature.
       #
-      def prettify_command_in_usage_description(command)
-        command
+      def signature_arguments
+        command.arguments.reduce('') do |memo, (name, type)|
+          name = "[#{name}]" if type == :optional
+          memo << ' ' << name
+        end.lstrip
       end
 
-      # @return [String]
+      # @return [String] The section describing the subcommands of the command.
+      #
+      # @note   The plus sign emphasizes the that the subcommands are added to
+      #         the command. The square brackets conveys a sense of direction
+      #         and indicates the gravitational force towards the default
+      #         command.
       #
       def formatted_subcommand_summaries
-        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 = prettify_subcommand_name(subcommand_string)
-            is_default = subcommand.command == command.default_subcommand
-            if is_default
-              bullet_point = '-'
-            else
-              bullet_point = '*'
-            end
-            "    #{bullet_point} #{subcommand_string}   #{subcommand.summary}"
-          end.join("\n")
-        end
+        subcommands = subcommands_for_banner
+        subcommands.map do |subcommand|
+          name = subcommand.command
+          bullet = (name == command.default_subcommand) ? '>' : '+'
+          name = "#{bullet} #{name}"
+          pretty_name = prettify_subcommand(name)
+          entry_description(pretty_name, subcommand.summary, name.size)
+        end.join("\n")
       end
 
-      # @return [String]
+      # @return [String] The section describing the options of the command.
       #
-      def prettify_subcommand_name(name)
-        ansi_output? ? name.green : name
+      def formatted_options_description
+        options = command.options
+        options.map do |name, description|
+          pretty_name = prettify_option_name(name)
+          entry_description(pretty_name, description, name.size)
+        end.join("\n")
       end
 
-      private
-
-      # @!group Private helpers
+      # @return [String] The line describing a single entry (subcommand or
+      #         option).
+      #
+      def entry_description(name, description, name_width)
+        max_name_width = compute_max_name_width
+        desc_start = max_name_width + (TEXT_INDENT - 2) + DESCRIPTION_SPACES
+        result = ' ' * (TEXT_INDENT - 2)
+        result << name
+        result << ' ' * DESCRIPTION_SPACES
+        result << ' ' * (max_name_width - name_width)
+        result << Helper.wrap_with_indent(description, desc_start, MAX_WIDTH)
+      end
 
+      # @!group Overrides
       #-----------------------------------------------------------------------#
 
-      # @return [String] Lifted straight from ActiveSupport. Thanks guys!
+      # @return [String] A decorated title.
       #
-      def strip_heredoc(string)
-        if min = string.scan(/^[ \t]*(?=\S)/).min
-          string.gsub(/^[ \t]{#{min.size}}/, '')
-        else
-          string
-        end
+      def prettify_title(title)
+        Prettifier.prettify_title(title)
       end
 
-      # @return [String] Lifted straight from ActionView. Thanks guys!
+      # @return [String] A decorated textual representation of the command.
       #
-      def word_wrap(line, line_width)
-        line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip
+      def prettify_signature(command, subcommand, argument)
+        Prettifier.prettify_signature(command, subcommand, argument)
       end
 
-      # @return [Fixnum] The width of the current terminal, unless being piped.
+      # @return [String] A decorated command description.
       #
-      def terminal_width
-        @terminal_width ||= begin
-          if STDOUT.tty? && system('which tput > /dev/null 2>&1')
-            `tput cols`.to_i
-          else
-            0
-          end
-        end
+      def prettify_message(command, message)
+        Prettifier.prettify_message(command, message)
+      end
+
+      # @return [String] A decorated textual representation of the subcommand
+      #         name.
+      #
+      def prettify_subcommand(name)
+        Prettifier.prettify_subcommand(name)
+      end
+
+      # @return [String] A decorated textual representation of the option name.
+      #
+      #
+      def prettify_option_name(name)
+        Prettifier.prettify_option_name(name)
+      end
+
+      # @!group Private helpers
+      #-----------------------------------------------------------------------#
+
+      # @return [Array<String>] The list of the subcommands to use in the
+      #         banner.
+      #
+      def subcommands_for_banner
+        command.subcommands_for_command_lookup.reject do |subcommand|
+          subcommand.summary.nil?
+        end.sort_by(&:command)
       end
 
+      # @return [Fixnum] The width of the largest command name or of the
+      #         largest option name. Used to align all the descriptions.
+      #
+      def compute_max_name_width
+        widths = []
+        widths << command.options.map { |option| option.first.size }
+        widths << subcommands_for_banner.map do |cmd|
+          cmd.command.size + SUBCOMMAND_BULLET_SIZE
+        end.max
+        widths.flatten.compact.max || 1
+      end
     end
   end
 end

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

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+module CLAide
+  class Command
+    class Banner
+      # Implements the default logic to prettify the Banner.
+      #
+      module Prettifier
+        # @return [String] A decorated title.
+        #
+        def self.prettify_title(title)
+          title.ansi.underline
+        end
+
+        # @return [String] A decorated textual representation of the command.
+        #
+        def self.prettify_signature(command, subcommand, argument)
+          components = [
+            [command, :green],
+            [subcommand, :green],
+            [argument, :magenta]
+          ]
+          components.reduce('') do |memo, (string, ansi_key)|
+            memo << ' ' << string.ansi.apply(ansi_key) unless string.empty?
+            memo
+          end.lstrip
+        end
+
+        # @return [String] A decorated command description.
+        #
+        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))
+            end
+          end
+          message
+        end
+
+        # @return [String] A decorated textual representation of the subcommand
+        #         name.
+        #
+        def self.prettify_subcommand(name)
+          name.chomp.ansi.green
+        end
+
+        # @return [String] A decorated textual representation of the option
+        #         name.
+        #
+        #
+        def self.prettify_option_name(name)
+          name.chomp.ansi.blue
+        end
+      end
+    end
+  end
+end

data/lib/claide/command/options.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+
+module CLAide
+  class Command
+    # Provides support for the default options.
+    #
+    module Options
+      # @return [Array<Array<String, String>>] The default options for a root
+      #         command implemented by CLAide.
+      #
+      DEFAULT_ROOT_OPTIONS = [
+        ['--completion-script', 'Print the auto-completion script'],
+        ['--version',           'Show the version of the tool']
+      ]
+
+      # @return [Array<Array<String, String>>] The default options implemented
+      #         by CLAide.
+      #
+      DEFAULT_OPTIONS = [
+        ['--verbose', 'Show more debugging information'],
+        ['--no-ansi', 'Show output without ANSI codes'],
+        ['--help',    'Show help banner of specified command']
+      ]
+
+      # @return [Array<Array<String, String>>] The list of the default
+      #         options for the given command.
+      #
+      # @param  [Class] command_class
+      #         The command class for which the options are needed.
+      #
+      def self.default_options(command_class)
+        if command_class.root_command?
+          Options::DEFAULT_ROOT_OPTIONS + Options::DEFAULT_OPTIONS
+        else
+          Options::DEFAULT_OPTIONS
+        end
+      end
+
+      # Handles root commands options if appropriate.
+      #
+      # @param  [Command] command
+      #         The invoked command.
+      #
+      # @param  [ARGV] argv
+      #         The parameters of the command.
+      #
+      # @return [Bool] Whether any root command option was handled.
+      #
+      def self.handle_root_option(command, argv)
+        argv = ARGV.coherce(argv)
+        return false unless command.class.root_command?
+        if argv.flag?('version')
+          print_version(command)
+          return true
+        elsif argv.flag?('completion-script')
+          print_completion_template(command)
+          return true
+        end
+        false
+      end
+
+      # Prints the version of the command optionally including plugins.
+      #
+      # @param  [Command] command
+      #         The invoked command.
+      #
+      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)
+          end
+        end
+      end
+
+      # Prints an auto-completion script according to the user shell.
+      #
+      # @param  [Command] command
+      #         The invoked command.#
+      #
+      def self.print_completion_template(command)
+        puts ShellCompletionHelper.completion_template(command.class)
+      end
+    end
+  end
+end