visionmedia-commander 3.0.3 → 3.1.0

data/History.rdoc

@@ -1,4 +1,11 @@
 
+=== 3.1.0 / 2009-03-13
+
+* Added Command#inspect
+* Added displaying of aliases in global help
+* Added support for alias args
+* Added #default_command
+
 === 3.0.3 / 2009-03-12
 
 * Added #alias_command

data/Manifest

@@ -29,6 +29,7 @@ spec/spec_helper.rb
 tasks/docs.rake
 tasks/gemspec.rake
 tasks/spec.rake
+test/foo
 test/pbar
 test/ui
 Todo.rdoc

data/README.rdoc

@@ -138,6 +138,79 @@ simplify common tasks using the following methods:
   # 'Log' action to stdout
   log "create", "path/to/file.rb"
 
+== Commander Goodies
+
+=== Option Defaults
+
+The options struct passed to #when_called provides a #default method, allowing you
+to set defaults in a clean manor to options which have not been set.
+
+  command :foo do |c|
+    c.option '--interval SECONDS', Integer, 'Interval in seconds'
+    c.option '--timeout SECONDS', Integer, 'Timeout in seconds'
+    c.when_called do |args, options|
+      options.default \
+        :interval => 2,
+        :timeout  => 60
+    end
+  end
+
+=== Command Aliasing
+
+Aliases can be created using the #alias_command method like below:
+
+  command :'install gem' do |c|
+    c.when_called { puts 'foo' }
+  end
+  alias_command :'gem install', :'install gem'
+
+Or more complicated aliases can be made, passing any arguments
+as if it was invoked via the command line:
+
+  command :'install gem' do |c|
+    c.syntax = 'install gem <name> [options]'
+    c.option '--dest DIR', String, 'Destination directory'
+    c.when_called { |args, options| puts "installing #{args.first} to #{options.dest}" }
+  end
+  alias_command :update, :'install gem', 'rubygems', '--dest', 'some_path'
+
+  $ foo update
+  # => installing rubygems to some_path
+
+=== Command Defaults
+
+Although working with a sub-command executable framework provides many 
+benefits over a single command implementation, sometimes you still
+want the ability to create a terse syntax for your command. With that
+in mind we may use #default_command to help with this. Considering
+our previous :'install gem' example:
+
+  default_command :update
+
+  $ foo
+  # => installing rubygems to some_path
+
+Keeping in mind that commander searches for the longest possible match
+when considering a sub-command, so if you were to pass arguments to foo
+like below, expecting them to be passed to :update, this would be incorrect,
+and would end up calling :'install gem', so be careful that the users do 
+not need to use command names within the arguments.
+
+  $ foo install gem
+  # => installing  to 
+
+=== Additional Global Help
+
+Arbitrary help can be added using the following #program symbol:
+
+  program :help, 'Author', 'TJ Holowaychuk <tj@vision-media.ca>'
+
+Which will output the rest of the help doc, along with:
+
+  AUTHOR:
+
+    TJ Holowaychuk <tj@vision-media.ca>
+
 == ASCII Tables
 
 For feature rich ASCII tables for your terminal app check out visionmedia's terminal-table gem at

data/Todo.rdoc

@@ -6,6 +6,8 @@
 
 == Minor
 
+* Add arbitrary help blocks to sub-commands as well
+* Spec for changing out formatters (mock formatter)
 * Add optional default command when none is present
 * Fix multi-word command template creation via `commander init`
 * Consider global #color method again

data/commander.gemspec

@@ -2,17 +2,17 @@
 
 Gem::Specification.new do |s|
   s.name = %q{commander}
-  s.version = "3.0.3"
+  s.version = "3.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["TJ Holowaychuk"]
-  s.date = %q{2009-03-12}
+  s.date = %q{2009-03-13}
   s.default_executable = %q{commander}
   s.description = %q{The complete solution for Ruby command-line executables}
   s.email = %q{tj@vision-media.ca}
   s.executables = ["commander"]
   s.extra_rdoc_files = ["bin/commander", "lib/commander/command.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/object.rb", "lib/commander/core_ext/string.rb", "lib/commander/core_ext.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "lib/commander.rb", "README.rdoc", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake"]
-  s.files = ["bin/commander", "commander.gemspec", "History.rdoc", "lib/commander/command.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/object.rb", "lib/commander/core_ext/string.rb", "lib/commander/core_ext.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "lib/commander.rb", "Manifest", "Rakefile", "README.rdoc", "spec/command_spec.rb", "spec/core_ext/array_spec.rb", "spec/core_ext/object_spec.rb", "spec/core_ext/string_spec.rb", "spec/help_formatters/base_spec.rb", "spec/help_formatters/terminal_spec.rb", "spec/runner_spec.rb", "spec/spec_helper.rb", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake", "test/pbar", "test/ui", "Todo.rdoc"]
+  s.files = ["bin/commander", "commander.gemspec", "History.rdoc", "lib/commander/command.rb", "lib/commander/core_ext/array.rb", "lib/commander/core_ext/object.rb", "lib/commander/core_ext/string.rb", "lib/commander/core_ext.rb", "lib/commander/help_formatters/base.rb", "lib/commander/help_formatters/terminal/command_help.erb", "lib/commander/help_formatters/terminal/help.erb", "lib/commander/help_formatters/terminal.rb", "lib/commander/help_formatters.rb", "lib/commander/runner.rb", "lib/commander/user_interaction.rb", "lib/commander/version.rb", "lib/commander.rb", "Manifest", "Rakefile", "README.rdoc", "spec/command_spec.rb", "spec/core_ext/array_spec.rb", "spec/core_ext/object_spec.rb", "spec/core_ext/string_spec.rb", "spec/help_formatters/base_spec.rb", "spec/help_formatters/terminal_spec.rb", "spec/runner_spec.rb", "spec/spec_helper.rb", "tasks/docs.rake", "tasks/gemspec.rake", "tasks/spec.rake", "test/foo", "test/pbar", "test/ui", "Todo.rdoc"]
   s.has_rdoc = true
   s.homepage = %q{http://github.com/visionmedia/commander}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Commander", "--main", "README.rdoc"]

data/lib/commander/command.rb

@@ -211,5 +211,9 @@ module Commander
       end 
     end
     
+    def inspect #:nodoc:
+      "<Commander::Command:#{name}>"
+    end
+    
   end
 end

data/lib/commander/core_ext/object.rb

@@ -16,7 +16,7 @@ class Object
   extend Forwardable
   include Commander::UI
   
-  def_delegators :$command_runner, :add_command, :command, :program, :run!, :commands, :alias_command
+  def_delegators :$command_runner, :add_command, :command, :program, :run!, :commands, :alias_command, :default_command
   def_delegators Commander::UI::ProgressBar, :progress
 
   ##

data/lib/commander/help_formatters/terminal/help.erb

@@ -8,14 +8,24 @@
     <%= program :description %>
 
   <%= $terminal.color "SUB-COMMANDS", :bold %>:
-<% @commands.each_pair do |name, command| %>
+<% @commands.each_pair do |name, command| -%>
+	<% unless alias? name %>
     <%= "%-20s %s" % [command.name, command.summary || command.description] -%>
-<% end %>
+	<% end -%>
+<% end -%>
+<% unless @aliases.empty? %>
+
+  <%= $terminal.color "ALIASES", :bold %>:
+  <% @aliases.each do |alias_name, args| %>
+    <%= "%-20s %s %s" % [alias_name, command(alias_name).name, args.join(' ')] -%>
+  <% end -%>
+<% end -%>
 <% if program :help -%>
+
   <% program(:help).each_pair do |title, body| %>
   <%= $terminal.color title.to_s.upcase, :bold %>:
-	
+
     <%= body %>
-  <% end %>
+  <% end -%>
 <% end -%>
 

data/lib/commander/runner.rb

@@ -26,7 +26,7 @@ module Commander
     # supplying +args+ for mocking, or arbitrary usage.
     
     def initialize args = ARGV
-      @args, @commands, @options = args, {}, {}
+      @args, @commands, @options, @aliases = args, {}, {}, {}
       @program = program_defaults
       create_default_commands
       parse_global_options
@@ -40,7 +40,12 @@ module Commander
       case 
       when options[:version] ; $terminal.say "#{program(:name)} #{program(:version)}" 
       when options[:help]    ; command(:help).run(*@args[1..-1])
-      else                     active_command.run *args_without_command_name
+      else
+        if alias? command_name_from_args
+          active_command.run *(@aliases[command_name_from_args.to_s] + args_without_command_name)
+        else
+          active_command.run *args_without_command_name
+        end              
       end
     rescue InvalidCommandError
       $terminal.say 'invalid command. Use --help for more information'
@@ -107,10 +112,20 @@ module Commander
     end
     
     ##
-    # Alias command +name+ with +alias_name+.
+    # Alias command +name+ with +alias_name+. Optionallry +args+ may be passed
+    # as if they were being passed straight to the original command via the command-line.
     
-    def alias_command alias_name, name
+    def alias_command alias_name, name, *args
       @commands[alias_name.to_s] = command name
+      @aliases[alias_name.to_s] = args
+    end
+    
+    ##
+    # Default command +name+ to be used when no other
+    # command is found in the arguments.
+    
+    def default_command name
+      @default_command = name
     end
     
     ##
@@ -120,6 +135,13 @@ module Commander
       @commands[command.name] = command
     end
     
+    ##
+    # Check if command +name+ is an alias.
+    
+    def alias? name
+      @aliases.include? name.to_s
+    end
+    
     ##
     # Check if a command +name+ exists.
     
@@ -139,7 +161,7 @@ module Commander
     # Supports multi-word commands, using the largest possible match.
     
     def command_name_from_args
-      @__command_name_from_args ||= valid_command_names_from(*@args.dup).sort.last
+      @__command_name_from_args ||= (valid_command_names_from(*@args.dup).sort.last || @default_command)
     end
     
     ##
@@ -162,7 +184,7 @@ module Commander
     
     def args_without_command_name
       removed = []
-      parts = command_name_from_args.split
+      parts = command_name_from_args.split rescue []
       @args.dup.delete_if do |arg|
         removed << arg if parts.include?(arg) and not removed.include?(arg)
       end

data/lib/commander/version.rb

@@ -1,4 +1,4 @@
 
 module Commander
-  VERSION = '3.0.3'
+  VERSION = '3.1.0'
 end

data/spec/help_formatters/base_spec.rb

@@ -5,13 +5,6 @@ describe Commander::HelpFormatter do
     mock_terminal
   end
   
-  def run *args
-    new_command_runner *args do
-      program :help_formatter, Commander::HelpFormatter::Base
-    end.run!    
-    @output.string
-  end
-  
   it "should display global help using --help switch" do
     run('--help').should == "Implement global help here\n"
   end

data/spec/runner_spec.rb

@@ -35,46 +35,50 @@ describe Commander do
   end
   
   describe "#alias_command" do
-    it "should allow aliasing of any command" do
+    it "should alias a command" do
       alias_command :foo, :test
       command(:foo).should == command(:test)
     end
+    
+    it "should pass arguments passed to the alias when called" do
+      new_command_runner 'install', 'gem', 'commander' do
+        command :install do |c|
+          c.option '--gem-name NAME', 'Install a gem'
+          c.when_called { |_, options| options.gem_name.should == 'commander' }
+        end 
+        alias_command :'install gem', :install, '--gem-name'
+        command(:install).should_receive(:run).once
+      end.run!
+    end
   end
   
   describe "--version" do
     it "should output program version" do
-      new_command_runner '--version' do
-        program :help_formatter, Commander::HelpFormatter::Base
-      end.run!
-      @output.string.should == "test 1.2.3\n"
+      run('--version').should == "test 1.2.3\n"
     end
   end
   
   describe "--help" do
     it "should not output an invalid command message" do
-      new_command_runner('--help').run!
-      @output.string.should_not == "invalid command. Use --help for more information\n"
+      run('--help').should_not == "invalid command. Use --help for more information\n"
     end
   end
   
   describe "with invalid options" do
     it "should output an invalid option message" do
-      new_command_runner('test', '--invalid-option').run!
-      @output.string.should == "invalid option: --invalid-option\n"
+      run('test', '--invalid-option').should == "invalid option: --invalid-option\n"
     end
   end
   
   describe "with invalid sub-command passed" do
     it "should output an invalid command message" do
-      new_command_runner('foo').run!
-      @output.string.should == "invalid command. Use --help for more information\n"
+      run('foo').should == "invalid command. Use --help for more information\n"
     end
   end
   
   describe "with invalid sub-command passed to help" do
     it "should output an invalid command message" do
-      new_command_runner('help', 'does_not_exist').run!
-      @output.string.should == "invalid command. Use --help for more information\n"
+      run('help', 'does_not_exist').should == "invalid command. Use --help for more information\n"
     end
   end
   
@@ -132,6 +136,41 @@ describe Commander do
     end
   end
   
+  describe "#default_command" do
+    it "should allow you to default any command when one is not explicitly passed" do
+      new_command_runner '--trace' do
+        default_command :test
+        command(:test).should_receive(:run).once
+        command_runner.active_command.should == command(:test)
+      end.run!
+    end
+    
+    it "should not prevent other commands from being called" do
+      new_command_runner 'foo', 'bar', '--trace' do
+        default_command :test
+        command(:'foo bar'){}
+        command(:'foo bar').should_receive(:run).once
+        command_runner.active_command.should == command(:'foo bar')
+      end.run!
+    end
+    
+    it "should not prevent longer commands to use the same words as the default" do
+      new_command_runner 'foo', 'bar', 'something'
+      default_command :'foo bar'
+      command(:'foo bar'){}
+      command(:'foo bar something'){}
+      command_runner.active_command.should == command(:'foo bar something')
+    end
+    
+    it "should allow defaulting of command aliases" do
+      new_command_runner '--trace' do
+        default_command :foobar
+        alias_command :foobar, :test
+        command(:test).should_receive(:run).once
+      end.run!
+    end
+  end
+  
   describe "should function correctly" do
     it "when options are passed before the command name" do
       new_command_runner '--trace', 'test', 'foo', 'bar' do
@@ -175,6 +214,15 @@ describe Commander do
         command_runner.args_without_command_name.should == ['--trace', 'something', 'my', 'command']
       end.run!
     end
+    
+    it "when using multi-word commands with other commands using the same words" do
+      new_command_runner '--trace', 'my', 'command', 'something', 'my', 'command' do
+        command('my command') {}
+        command('my command something') {}
+        command_runner.command_name_from_args.should == 'my command something'
+        command_runner.args_without_command_name.should == ['--trace', 'my', 'command']
+      end.run!
+    end
   end
   
 end

data/spec/spec_helper.rb

@@ -37,4 +37,11 @@ def new_command_runner *args, &block
   create_test_command
   yield if block
   command_runner
+end
+
+def run *args
+  new_command_runner *args do
+    program :help_formatter, Commander::HelpFormatter::Base
+  end.run!    
+  @output.string
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: visionmedia-commander
 version: !ruby/object:Gem::Version 
-  version: 3.0.3
+  version: 3.1.0
 platform: ruby
 authors: 
 - TJ Holowaychuk
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-12 00:00:00 -07:00
+date: 2009-03-13 00:00:00 -07:00
 default_executable: commander
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -80,6 +80,7 @@ files:
 - tasks/docs.rake
 - tasks/gemspec.rake
 - tasks/spec.rake
+- test/foo
 - test/pbar
 - test/ui
 - Todo.rdoc