cri 2.6.1 → 2.7.0

data/lib/cri/command_dsl.rb

@@ -1,10 +1,11 @@
 # encoding: utf-8
 
 module Cri
-
   # The command DSL is a class that is used for building and modifying
   # commands.
   class CommandDSL
+    # @return [Cri::Command] The built command
+    attr_reader :command
 
     # Creates a new DSL, intended to be used for building a single command. A
     # {CommandDSL} instance is not reusable; create a new instance if you want
@@ -12,15 +13,10 @@ module Cri
     #
     # @param [Cri::Command, nil] command The command to modify, or nil if a
     #   new command should be created
-    def initialize(command=nil)
+    def initialize(command = nil)
       @command = command || Cri::Command.new
     end
 
-    # @return [Cri::Command] The built command
-    def command
-      @command
-    end
-
     # Adds a subcommand to the current command. The command can either be
     # given explicitly, or a block can be given that defines the command.
     #
@@ -29,7 +25,7 @@ module Cri
     #   added as a subcommand
     #
     # @return [void]
-    def subcommand(command=nil, &block)
+    def subcommand(command = nil, &block)
       if command.nil?
         command = Cri::Command.define(&block)
       end
@@ -108,13 +104,17 @@ module Cri
     # @option params [Boolean] :multiple Whether or not the option should
     #   be multi-valued
     #
+    # @option params [Boolean] :hidden Whether or not the option should
+    #   be printed in the help output
+    #
     # @return [void]
-    def option(short, long, desc, params={}, &block)
+    def option(short, long, desc, params = {}, &block)
       requiredness = params.fetch(:argument, :forbidden)
       multiple = params.fetch(:multiple, false)
+      hidden = params.fetch(:hidden, false)
 
       if short.nil? && long.nil?
-        raise ArgumentError, "short and long options cannot both be nil"
+        fail ArgumentError, 'short and long options cannot both be nil'
       end
 
       @command.option_definitions << {
@@ -124,6 +124,7 @@ module Cri
         :argument => requiredness,
         :multiple => multiple,
         :block    => block,
+        :hidden   => hidden,
       }
     end
     alias_method :opt, :option
@@ -140,12 +141,15 @@ module Cri
     # @option params [Boolean] :multiple Whether or not the option should
     #   be multi-valued
     #
+    # @option params [Boolean] :hidden Whether or not the option should
+    #   be printed in the help output
+    #
     # @return [void]
     #
     # @see {#option}
-    def required(short, long, desc, params={}, &block)
+    def required(short, long, desc, params = {}, &block)
       params = params.merge(:argument => :required)
-      self.option(short, long, desc, params, &block)
+      option(short, long, desc, params, &block)
     end
 
     # Adds a new option with a forbidden argument to the command. If a block
@@ -160,12 +164,15 @@ module Cri
     # @option params [Boolean] :multiple Whether or not the option should
     #   be multi-valued
     #
+    # @option params [Boolean] :hidden Whether or not the option should
+    #   be printed in the help output
+    #
     # @return [void]
     #
     # @see {#option}
-    def flag(short, long, desc, params={}, &block)
+    def flag(short, long, desc, params = {}, &block)
       params = params.merge(:argument => :forbidden)
-      self.option(short, long, desc, params, &block)
+      option(short, long, desc, params, &block)
     end
     alias_method :forbidden, :flag
 
@@ -181,12 +188,15 @@ module Cri
     # @option params [Boolean] :multiple Whether or not the option should
     #   be multi-valued
     #
+    # @option params [Boolean] :hidden Whether or not the option should
+    #   be printed in the help output
+    #
     # @return [void]
     #
     # @see {#option}
-    def optional(short, long, desc, params={}, &block)
+    def optional(short, long, desc, params = {}, &block)
       params = params.merge(:argument => :optional)
-      self.option(short, long, desc, params, &block)
+      option(short, long, desc, params, &block)
     end
 
     # Sets the run block to the given block. The given block should have two
@@ -203,8 +213,8 @@ module Cri
     # @return [void]
     def run(&block)
       unless [2, 3].include?(block.arity)
-        raise ArgumentError,
-          "The block given to Cri::Command#run expects two or three args"
+        fail ArgumentError,
+             'The block given to Cri::Command#run expects two or three args'
       end
 
       @command.block = block

data/lib/cri/command_runner.rb

@@ -1,11 +1,9 @@
 # encoding: utf-8
 
 module Cri
-
   # A command runner is responsible for the execution of a command. Using it
   # is optional, but it is useful for commands whose execution block is large.
   class CommandRunner
-
     # @return [Hash] A hash contain the options and their values
     attr_reader :options
 
@@ -33,7 +31,7 @@ module Cri
     #
     # @return [void]
     def call
-      self.run
+      run
     end
 
     # Performs the actual execution of the command.
@@ -42,9 +40,7 @@ module Cri
     #
     # @abstract
     def run
-      raise NotImplementedError, 'Cri::CommandRunner subclasses must implement #run'
+      fail NotImplementedError, 'Cri::CommandRunner subclasses must implement #run'
     end
-
   end
-
 end

data/lib/cri/commands/basic_help.rb

@@ -14,8 +14,8 @@ flag :v, :verbose, 'show more detailed help'
 
 run do |opts, args, cmd|
   if cmd.supercommand.nil?
-    raise NoHelpAvailableError,
-      "No help available because the help command has no supercommand"
+    fail NoHelpAvailableError,
+         'No help available because the help command has no supercommand'
   end
 
   is_verbose = opts.fetch(:verbose, false)

data/lib/cri/commands/basic_root.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-flag :h, :help, 'show help for this command' do |value, cmd|
+flag :h, :help, 'show help for this command' do |_value, cmd|
   puts cmd.help
   exit 0
 end

data/lib/cri/core_ext.rb

@@ -1,6 +1,8 @@
 # encoding: utf-8
 
-module Cri::CoreExtensions
+module Cri
+  module CoreExtensions
+  end
 end
 
 require 'cri/core_ext/string'

data/lib/cri/core_ext/string.rb

@@ -2,36 +2,34 @@
 
 require 'colored'
 
-module Cri::CoreExtensions
-
-  # @deprecated
-  module String
-
-    # @see Cri::StringFormatter#to_paragraphs
-    def to_paragraphs
-      Cri::StringFormatter.new.to_paragraphs(self)
-    end
-
-    # @see Cri::StringFormatter#to_paragraphs
-    def wrap_and_indent(width, indentation)
-      Cri::StringFormatter.new.wrap_and_indent(self, width, indentation)
-    end
-
-    # @see Cri::StringFormatter#format_as_title
-    def formatted_as_title
-      Cri::StringFormatter.new.format_as_title(self)
+module Cri
+  module CoreExtensions
+    # @deprecated
+    module String
+      # @see Cri::StringFormatter#to_paragraphs
+      def to_paragraphs
+        Cri::StringFormatter.new.to_paragraphs(self)
+      end
+
+      # @see Cri::StringFormatter#to_paragraphs
+      def wrap_and_indent(width, indentation)
+        Cri::StringFormatter.new.wrap_and_indent(self, width, indentation)
+      end
+
+      # @see Cri::StringFormatter#format_as_title
+      def formatted_as_title
+        Cri::StringFormatter.new.format_as_title(self)
+      end
+
+      # @see Cri::StringFormatter#format_as_command
+      def formatted_as_command
+        Cri::StringFormatter.new.format_as_command(self)
+      end
+
+      # @see Cri::StringFormatter#format_as_option
+      def formatted_as_option
+        Cri::StringFormatter.new.format_as_option(self)
+      end
     end
-
-    # @see Cri::StringFormatter#format_as_command
-    def formatted_as_command
-      Cri::StringFormatter.new.format_as_command(self)
-    end
-
-    # @see Cri::StringFormatter#format_as_option
-    def formatted_as_option
-      Cri::StringFormatter.new.format_as_option(self)
-    end
-
   end
-
 end

data/lib/cri/help_renderer.rb

@@ -1,10 +1,17 @@
 # encoding: utf-8
 
 module Cri
-
   # The {HelpRenderer} class is responsible for generating a string containing
   # the help for a given command, intended to be printed on the command line.
   class HelpRenderer
+    # The line width of the help output
+    LINE_WIDTH = 78
+
+    # The indentation of descriptions
+    DESC_INDENT = 4
+
+    # The spacing between an option name and option description
+    OPT_DESC_SPACING = 6
 
     # Creates a new help renderer for the given command.
     #
@@ -12,7 +19,7 @@ module Cri
     #
     # @option params [Boolean] :verbose true if the help output should be
     #   verbose, false otherwise.
-    def initialize(cmd, params={})
+    def initialize(cmd, params = {})
       @cmd        = cmd
       @is_verbose = params.fetch(:verbose, false)
       @io         = params.fetch(:io, $stdout)
@@ -40,32 +47,32 @@ module Cri
     def append_summary(text)
       return if @cmd.summary.nil?
 
-      text << fmt.format_as_title("name", @io) << "\n"
+      text << fmt.format_as_title('name', @io) << "\n"
       text << "    #{fmt.format_as_command(@cmd.name, @io)} - #{@cmd.summary}" << "\n"
       unless @cmd.aliases.empty?
-        text << "    aliases: " << @cmd.aliases.map { |a| fmt.format_as_command(a, @io) }.join(' ') << "\n"
+        text << '    aliases: ' << @cmd.aliases.map { |a| fmt.format_as_command(a, @io) }.join(' ') << "\n"
       end
     end
 
     def append_usage(text)
       return if @cmd.usage.nil?
 
-      path = [ @cmd.supercommand ]
+      path = [@cmd.supercommand]
       path.unshift(path[0].supercommand) until path[0].nil?
       formatted_usage = @cmd.usage.gsub(/^([^\s]+)/) { |m| fmt.format_as_command(m, @io) }
       full_usage = path[1..-1].map { |c| fmt.format_as_command(c.name, @io) + ' ' }.join + formatted_usage
 
       text << "\n"
-      text << fmt.format_as_title("usage", @io) << "\n"
-      text << fmt.wrap_and_indent(full_usage, 78, 4) << "\n"
+      text << fmt.format_as_title('usage', @io) << "\n"
+      text << fmt.wrap_and_indent(full_usage, LINE_WIDTH, DESC_INDENT) << "\n"
     end
 
     def append_description(text)
       return if @cmd.description.nil?
 
       text << "\n"
-      text << fmt.format_as_title("description", @io) << "\n"
-      text << fmt.wrap_and_indent(@cmd.description, 78, 4) + "\n"
+      text << fmt.format_as_title('description', @io) << "\n"
+      text << fmt.wrap_and_indent(@cmd.description, LINE_WIDTH, DESC_INDENT) + "\n"
     end
 
     def append_subcommands(text)
@@ -80,13 +87,15 @@ module Cri
 
       # Command
       shown_subcommands.sort_by { |cmd| cmd.name }.each do |cmd|
-        text << sprintf("    %-#{length+4}s %s\n",
-          fmt.format_as_command(cmd.name, @io),
-          cmd.summary)
+        text <<
+          format(
+            "    %-#{length + DESC_INDENT}s %s\n",
+            fmt.format_as_command(cmd.name, @io),
+            cmd.summary)
       end
 
       # Hidden notice
-      if !@is_verbose
+      unless @is_verbose
         diff = @cmd.subcommands.size - shown_subcommands.size
         case diff
         when 0
@@ -98,12 +107,34 @@ module Cri
       end
     end
 
+    def length_for_opt_defs(opt_defs)
+      opt_defs.map do |opt_def|
+        string = ''
+
+        # Always pretend there is a short option
+        string << '-X'
+
+        if opt_def[:long]
+          string << ' --' + opt_def[:long]
+        end
+
+        case opt_def[:argument]
+        when :required
+          string << '=<value>'
+        when :optional
+          string << '=[<value>]'
+        end
+
+        string.size
+      end.max
+    end
+
     def append_options(text)
       groups = { 'options' => @cmd.option_definitions }
       if @cmd.supercommand
         groups["options for #{@cmd.supercommand.name}"] = @cmd.supercommand.global_option_definitions
       end
-      length = groups.values.inject(&:+).map { |o| o[:long].to_s.size }.max
+      length = length_for_opt_defs(groups.values.inject(&:+))
       groups.keys.sort.each do |name|
         defs = groups[name]
         append_option_group(text, name, defs, length)
@@ -119,19 +150,70 @@ module Cri
 
       ordered_defs = defs.sort_by { |x| x[:short] || x[:long] }
       ordered_defs.each do |opt_def|
-        text << format_opt_def(opt_def, length)
-        text << opt_def[:desc] << "\n"
+        unless opt_def[:hidden]
+          text << format_opt_def(opt_def, length)
+          text << fmt.wrap_and_indent(opt_def[:desc], LINE_WIDTH, length + OPT_DESC_SPACING + DESC_INDENT, true) << "\n"
+        end
       end
     end
 
-    def format_opt_def(opt_def, length)
-      opt_text = sprintf(
-          "    %-2s %-#{length+6}s",
-          opt_def[:short] ? ('-' + opt_def[:short]) : '',
-          opt_def[:long]  ? ('--' + opt_def[:long]) : '')
-      fmt.format_as_option(opt_text, @io)
+    def short_value_postfix_for(opt_def)
+      value_postfix =
+        case opt_def[:argument]
+        when :required
+          '<value>'
+        when :optional
+          '[<value>]'
+        else
+          nil
+        end
+
+      if value_postfix
+        opt_def[:long] ? '' : ' ' + value_postfix
+      else
+        ''
+      end
     end
 
-  end
+    def long_value_postfix_for(opt_def)
+      value_postfix =
+        case opt_def[:argument]
+        when :required
+          '=<value>'
+        when :optional
+          '[=<value>]'
+        else
+          nil
+        end
+
+      if value_postfix
+        opt_def[:long] ? value_postfix : ''
+      else
+        ''
+      end
+    end
 
+    def format_opt_def(opt_def, length)
+      short_value_postfix = short_value_postfix_for(opt_def)
+      long_value_postfix = long_value_postfix_for(opt_def)
+
+      opt_text = ''
+      opt_text_len = 0
+      if opt_def[:short]
+        opt_text << fmt.format_as_option('-' + opt_def[:short], @io)
+        opt_text << short_value_postfix
+        opt_text << ' '
+        opt_text_len += 1 + opt_def[:short].size + short_value_postfix.size + 1
+      else
+        opt_text << '   '
+        opt_text_len += 3
+      end
+      opt_text << fmt.format_as_option('--' + opt_def[:long], @io) if opt_def[:long]
+      opt_text << long_value_postfix
+      opt_text_len += 2 + opt_def[:long].size if opt_def[:long]
+      opt_text_len += long_value_postfix.size
+
+      '    ' + opt_text + ' ' * (length + OPT_DESC_SPACING - opt_text_len)
+    end
+  end
 end