cri 2.2.1 → 2.3.0

data/NEWS.md

@@ -1,6 +1,12 @@
 Cri News
 ========
 
+2.3.0
+-----
+
+* Added colors
+* Added support for marking commands as hidden
+
 2.2.1
 -----
 

data/cri.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |s|
                          [ 'cri.gemspec', '.gemtest' ]
   s.require_paths      = [ 'lib' ]
 
+  s.add_dependency('colored', '>= 1.2')
+
   s.rdoc_options     = [ '--main', 'README.md' ]
   s.extra_rdoc_files = [ 'ChangeLog', 'LICENSE', 'README.md', 'NEWS.md' ]
 end

data/lib/cri.rb

@@ -17,7 +17,7 @@ module Cri
   end
 
   # The current Cri version.
-  VERSION = '2.2.1'
+  VERSION = '2.3.0'
 
   autoload 'Command',           'cri/command'
   autoload 'CommandDSL',        'cri/command_dsl'

data/lib/cri/command.rb

@@ -70,6 +70,11 @@ module Cri
     #   supercommands’ names.
     attr_accessor :usage
 
+    # @return [Boolean] true if the command is hidden (e.g. because it is
+    #   deprecated), false otherwise
+    attr_accessor :hidden
+    alias_method :hidden?, :hidden
+
     # @return [Array<Hash>] The list of option definitions
     attr_accessor :option_definitions
 
@@ -292,46 +297,73 @@ module Cri
     end
 
     # @return [String] The help text for this command
-    def help
+    def help(params={})
+      is_verbose = params.fetch(:verbose, false)
+
       text = ''
 
+      # Append name and summary
+      if summary
+        text << "name".formatted_as_title << "\n"
+        text << "    #{name.formatted_as_command} - #{summary}" << "\n"
+        unless aliases.empty?
+          text << "    aliases: " << aliases.map { |a| a.formatted_as_command }.join(' ') << "\n"
+        end
+      end
+
       # Append usage
       if usage
         path = [ self.supercommand ]
         path.unshift(path[0].supercommand) until path[0].nil?
-        full_usage = path[1..-1].map { |c| c.name + ' ' }.join + usage
-        text << "usage: #{full_usage}\n"
-      end
+        formatted_usage = usage.gsub(/^([^\s]+)/) { |m| m.formatted_as_command }
+        full_usage = path[1..-1].map { |c| c.name.formatted_as_command + ' ' }.join + formatted_usage
 
-      # Append aliases
-      unless aliases.empty?
         text << "\n"
-        text << "aliases: #{aliases.join(' ')}\n"
-      end
-
-      # Append short description
-      if summary
-        text << "\n"
-        text << summary + "\n"
+        text << "usage".formatted_as_title << "\n"
+        text << full_usage.wrap_and_indent(78, 4) << "\n"
       end
 
       # Append long description
       if description
         text << "\n"
+        text << "description".formatted_as_title << "\n"
         text << description.wrap_and_indent(78, 4) + "\n"
       end
 
       # Append subcommands
-      unless self.commands.empty?
+      unless self.subcommands.empty?
         text << "\n"
-        text << (self.supercommand ? 'subcommands' : 'commands') << ":\n"
+        text << (self.supercommand ? 'subcommands' : 'commands').formatted_as_title
         text << "\n"
-        length = self.commands.inject(0) { |m,c| [ m, c.name.size ].max }
-        self.commands.sort_by { |cmd| cmd.name }.each do |cmd|
+
+        visible_cmds, invisible_cmds = self.subcommands.partition { |c| !c.hidden? }
+
+        commands_for_length = is_verbose ? self.subcommands : visible_cmds
+        length = commands_for_length.map { |c| c.name.formatted_as_command.size }.max
+
+        # Visible
+        visible_cmds.sort_by { |cmd| cmd.name }.each do |cmd|
           text << sprintf("    %-#{length+4}s %s\n",
-            cmd.name,
+            cmd.name.formatted_as_command,
             cmd.summary)
         end
+
+        # Invisible
+        if is_verbose
+          invisible_cmds.sort_by { |cmd| cmd.name }.each do |cmd|
+            text << sprintf("    %-#{length+4}s %s\n",
+              cmd.name.formatted_as_command,
+              cmd.summary)
+          end
+        else
+          case invisible_cmds.size
+          when 0
+          when 1
+            text << "    (1 hidden command ommitted; show it with --verbose)\n"
+          else
+            text << "    (#{invisible_cmds.size} hidden commands ommitted; show them with --verbose)\n"
+          end
+        end
       end
 
       # Append options
@@ -339,23 +371,23 @@ module Cri
       if self.supercommand
         groups["options for #{self.supercommand.name}"] = self.supercommand.global_option_definitions
       end
-      length = groups.values.inject(&:+).inject(0) { |m,o| [ m, o[:long].size ].max }
+      length = groups.values.inject(&:+).map { |o| o[:long].size }.max
       groups.each_pair do |name, defs|
         unless defs.empty?
           text << "\n"
-          text << "#{name}:\n"
+          text << "#{name}".formatted_as_title
           text << "\n"
           defs.sort { |x,y| x[:long] <=> y[:long] }.each do |opt_def|
             text << sprintf(
-              "    -%1s --%-#{length+4}s %s\n",
+              "    -%1s --%-#{length+4}s",
               opt_def[:short],
-              opt_def[:long],
-              opt_def[:desc])
+              opt_def[:long]).formatted_as_option
+
+            text << opt_def[:desc] << "\n"
           end
         end
       end
 
-      # Return text
       text
     end
 

data/lib/cri/command_dsl.rb

@@ -79,6 +79,16 @@ module Cri
       @command.usage = arg
     end
 
+    # Marks the command as hidden. Hidden commands do not show up in the list of
+    # subcommands of the parent command, unless --verbose is passed (or
+    # `:verbose => true` is passed to the {Cri::Command#help} method). This can
+    # be used to mark commands as deprecated.
+    #
+    # @return [void]
+    def be_hidden
+      @command.hidden = true
+    end
+
     # Adds a new option to the command. If a block is given, it will be
     # executed when the option is successfully parsed.
     #

data/lib/cri/commands/basic_help.rb

@@ -10,16 +10,20 @@ commandline options. When a command is given, a command description as well as
 command-specific commandline options are shown.
 EOS
 
+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"
   end
 
+  is_verbose = opts.fetch(:verbose, false)
+
   if args.empty?
-    puts cmd.supercommand.help
+    puts cmd.supercommand.help(:verbose => is_verbose)
   elsif args.size == 1
-    puts cmd.supercommand.command_named(args[0]).help
+    puts cmd.supercommand.command_named(args[0]).help(:verbose => is_verbose)
   else
     $stderr.puts cmd.usage
     exit 1

data/lib/cri/commands/basic_root.rb

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

data/lib/cri/core_ext/string.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+require 'colored'
 
 module Cri::CoreExtensions
 
@@ -59,6 +60,24 @@ module Cri::CoreExtensions
       end.join("\n\n")
     end
 
+    # @return [String] The string, formatted to be used as a title in a section
+    #   in the help
+    def formatted_as_title
+      self.upcase.red.bold
+    end
+
+    # @return [String] The string, formatted to be used as the name of a command
+    #   in the help
+    def formatted_as_command
+      self.green
+    end
+
+    # @return [String] The string, formatted to be used as an option definition
+    #   of a command in the help
+    def formatted_as_option
+      self.yellow
+    end
+
   end
 
 end

data/test/helper.rb

@@ -13,7 +13,7 @@ class Cri::TestCase < MiniTest::Unit::TestCase
   end
 
   def capture_io_while(&block)
-   orig_io = capture_io
+    orig_io = capture_io
     block.call
     [ $stdout.string, $stderr.string ]
   ensure
@@ -42,3 +42,6 @@ private
   end
 
 end
+
+# Unexpected system exit is unexpected
+::MiniTest::Unit::TestCase::PASSTHROUGH_EXCEPTIONS.delete(SystemExit)

data/test/test_basic_root.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+class Cri::BasicRootTestCase < Cri::TestCase
+
+  def test_run_with_help
+    cmd = Cri::Command.new_basic_root
+
+    stdout, stderr = capture_io_while do
+      assert_raises SystemExit do
+        cmd.run(%w( -h ))
+      end
+    end
+
+    assert stdout =~ /COMMANDS.*\n.*help.*show help/
+  end
+
+end

data/test/test_command.rb

@@ -5,7 +5,7 @@ class Cri::CommandTestCase < Cri::TestCase
   def simple_cmd
     Cri::Command.define do
       name        'moo'
-      usage       'dunno whatever'
+      usage       'moo [options] arg1 arg2 ...'
       summary     'does stuff'
       description 'This command does a lot of stuff.'
 
@@ -256,7 +256,7 @@ class Cri::CommandTestCase < Cri::TestCase
   def test_help_nested
     help = nested_cmd.subcommands.find { |cmd| cmd.name == 'sub' }.help
 
-    assert_match /^usage: super sub \[options\]/, help
+    assert help.include?("USAGE\e[0m\e[0m\n    \e[32msuper\e[0m \e[32msub\e[0m [options]\n")
   end
 
   def test_help_for_bare_cmd
@@ -346,4 +346,53 @@ class Cri::CommandTestCase < Cri::TestCase
     assert_match /mycommand.rb/, error.backtrace.join("\n")
   end
 
+  def test_hidden_commands_single
+    cmd    = nested_cmd
+    subcmd = simple_cmd
+    cmd.add_command subcmd
+    subcmd.modify do |c|
+      c.name    'old-and-deprecated'
+      c.summary 'does stuff the ancient, totally deprecated way'
+      c.be_hidden
+    end
+
+    refute cmd.help.include?('hidden commands ommitted')
+    assert cmd.help.include?('hidden command ommitted')
+    refute cmd.help.include?('old-and-deprecated')
+
+    refute cmd.help(:verbose => true).include?('hidden commands ommitted')
+    refute cmd.help(:verbose => true).include?('hidden command ommitted')
+    assert cmd.help(:verbose => true).include?('old-and-deprecated')
+  end
+
+  def test_hidden_commands_multiple
+    cmd    = nested_cmd
+
+    subcmd = simple_cmd
+    cmd.add_command subcmd
+    subcmd.modify do |c|
+      c.name    'old-and-deprecated'
+      c.summary 'does stuff the old, deprecated way'
+      c.be_hidden
+    end
+
+    subcmd = simple_cmd
+    cmd.add_command subcmd
+    subcmd.modify do |c|
+      c.name    'ancient-and-deprecated'
+      c.summary 'does stuff the ancient, reallydeprecated way'
+      c.be_hidden
+    end
+
+    assert cmd.help.include?('hidden commands ommitted')
+    refute cmd.help.include?('hidden command ommitted')
+    refute cmd.help.include?('old-and-deprecated')
+    refute cmd.help.include?('ancient-and-deprecated')
+
+    refute cmd.help(:verbose => true).include?('hidden commands ommitted')
+    refute cmd.help(:verbose => true).include?('hidden command ommitted')
+    assert cmd.help(:verbose => true).include?('old-and-deprecated')
+    assert cmd.help(:verbose => true).include?('ancient-and-deprecated')
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cri
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-17 00:00:00.000000000 Z
-dependencies: []
+date: 2012-06-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colored
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.2'
 description: Cri allows building easy-to-use commandline interfaces with support for
   subcommands.
 email: denis.defreyne@stoneship.org
@@ -39,6 +55,7 @@ files:
 - test/helper.rb
 - test/test_base.rb
 - test/test_basic_help.rb
+- test/test_basic_root.rb
 - test/test_command.rb
 - test/test_command_dsl.rb
 - test/test_core_ext.rb
@@ -67,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: a library for building easy-to-use commandline tools