visionmedia-commander 3.1.8 → 3.2.0

data/History.rdoc

@@ -1,4 +1,17 @@
 
+=== 3.2.0 / 2009-03-26
+
+* Added implied small switches so they appear in help (-h, -v, etc)
+* Added #inspect back to Commander::Command::Options [#1]
+* Added inheritance of global options for sub-commands [#7]
+* Added #require_valid_command 
+* Renamed #call_active_command to #run_active_command
+* Changed; using same option format as sub-command options for globals [#18]
+* Changed; program :name is now optional, and is auto-defined when not specified [#21]
+* Moved #switch_to_sym from Command to Commander::Runner
+* Moved #seperate_switches_from_description into Commander::Runner [#22]
+* Removed program :name from commander init template since its not required anymore
+
 === 3.1.8 / 2009-03-25
 
 * Utilizing abort and $stderr instead of using #say [#16]

data/README.rdoc

@@ -27,6 +27,7 @@ as well as an object, specifying a method to call, so view the RDoc for more inf
    require 'rubygems'
    require 'commander'
 
+   # :name is optional, otherwise uses the basename of this executable
    program :name, 'Foo Bar'
    program :version, '1.0.0'
    program :description, 'Stupid command that prints foo or bar.'
@@ -221,6 +222,32 @@ you can add additional global options:
 
 This method accepts the same syntax as Commander::Command#option so check it out for documentation.
 
+All global options regardless of providing a block are accessable at the sub-command level. This
+means that instead of the following:
+
+  global_option('--verbose') { $verbose = true }
+  ...
+  c.when_called do |args, options|
+    say 'foo' if $verbose
+  ...
+
+You may:
+
+  global_option '--verbose'
+  ...
+  c.when_called do |args, options|
+    say 'foo' if options.verbose
+  ...
+
+== Tips
+
+When adding a global or sub-command option, OptionParser implicitly adds a small
+switch even when not explicitly created, for example -c will be the same as --config
+in both examples:
+
+  global_option '-c', '--config FILE'
+  global_option '--config FILE'
+
 == ASCII Tables
 
 For feature rich ASCII tables for your terminal app check out visionmedia's terminal-table gem at

data/bin/commander

@@ -27,7 +27,6 @@ command :init do |c|
           require 'commander'
           require '#{name}'
           
-          program :name, '#{name}'
           program :version, #{name.capitalize}::VERSION
           program :description, '#{description}'
            

data/commander.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{commander}
-  s.version = "3.1.8"
+  s.version = "3.2.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-25}
+  s.date = %q{2009-03-26}
   s.default_executable = %q{commander}
   s.description = %q{The complete solution for Ruby command-line executables}
   s.email = %q{tj@vision-media.ca}

data/lib/commander/command.rb

@@ -4,8 +4,8 @@ require 'optparse'
 module Commander
   class Command
     
-    attr_reader :name, :examples, :options, :proxy_options
-    attr_accessor :syntax, :description, :summary
+    attr_accessor :name, :examples, :syntax, :description
+    attr_accessor :summary, :proxy_options, :options
     
     ##
     # Options struct.
@@ -28,6 +28,10 @@ module Commander
       def default defaults = {}
         @table = defaults.merge! @table
       end
+      
+      def inspect
+        "<Commander::Command::Options #{ __hash__.map { |k,v| "#{k}=#{v.inspect}" }.join(', ') }>"
+      end
     end
         
     ##
@@ -103,7 +107,7 @@ module Commander
     #
     
     def option *args, &block
-      switches, description = seperate_switches_from_description *args
+      switches, description = Runner.seperate_switches_from_description *args
       proc = block || option_proc(switches)
       @options << {
         :args => args,
@@ -176,36 +180,12 @@ module Commander
       end 
     end
     
-    ##
-    # Attempts to generate a method name symbol from +switch+.
-    # For example:
-    # 
-    #   -h                 # => :h
-    #   --trace            # => :trace
-    #   --some-switch      # => :some_switch
-    #   --[no-]feature     # => :feature
-    #   --file FILE        # => :file
-    #   --list of,things   # => :list
-    
-    def switch_to_sym switch
-      switch.scan(/[\-\]](\w+)/).join('_').to_sym rescue nil
-    end
-    
-    ##
-    # Return switches and description seperated from the +args+ passed.
-
-    def seperate_switches_from_description *args
-      switches = args.find_all { |arg| arg.to_s =~ /^-/ } 
-      description = args.last unless !args.last.is_a? String or args.last.match(/^-/)
-      return switches, description
-    end
-        
     ##
     # Creates an Options instance populated with the option values
     # collected by the #option_proc.
     
     def proxy_option_struct
-      @proxy_options.inject Options.new do |options, (option, value)|
+      proxy_options.inject Options.new do |options, (option, value)|
         options.__send__ :"#{option}=", value
         options
       end
@@ -217,9 +197,7 @@ module Commander
     # and work with option values.
     
     def option_proc switches
-      Proc.new do |value|
-        @proxy_options << [switch_to_sym(switches.last), value]
-      end 
+      lambda { |value| proxy_options << [Runner.switch_to_sym(switches.last), value] } 
     end
     
     def inspect #:nodoc:

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

@@ -21,10 +21,12 @@
 <% end %>
 <% unless @options.empty? -%>
   <%= $terminal.color "GLOBAL OPTIONS", :bold %>:
-  <% @options.each do |(args, proc)| %>
-    <%= "%-20s %s" % [args.shift, args.last.is_a?(String) ? args.last : ''] -%>
-  <% end -%>
-<% end %>
+	<% @options.each do |option| -%>
+
+    <%= option[:switches].join ', ' %> 
+        <%= option[:description] %>
+	<% end -%>
+<% end -%>
 <% if program :help -%>
   <% program(:help).each_pair do |title, body| %>
   <%= $terminal.color title.to_s.upcase, :bold %>:

data/lib/commander/runner.rb

@@ -36,18 +36,18 @@ module Commander
     
     def run!
       trace = false
-      require_program :name, :version, :description
+      require_program :version, :description
       trap('INT') { abort program(:int_message) }
-      global_option('--help', 'Display help documentation') { command(:help).run *@args[1..-1]; return }
-      global_option('--version', 'Display version information') { say version; return } 
-      global_option('--trace', 'Display backtrace when an error occurs') { trace = true }
+      global_option('-h', '--help', 'Display help documentation') { command(:help).run *@args[1..-1]; return }
+      global_option('-v', '--version', 'Display version information') { say version; return } 
+      global_option('-t', '--trace', 'Display backtrace when an error occurs') { trace = true }
       parse_global_options
       remove_global_options
       unless trace
         begin
-          call_active_command
-        rescue InvalidCommandError
-          abort 'invalid command. Use --help for more information'
+          run_active_command
+        rescue InvalidCommandError => e
+          abort "#{e}. Use --help for more information"
         rescue \
           OptionParser::InvalidOption, 
           OptionParser::InvalidArgument,
@@ -57,7 +57,7 @@ module Commander
           abort "error: #{e}. Use --trace to view backtrace"
         end
       else
-        call_active_command
+        run_active_command
       end
     end
     
@@ -69,9 +69,10 @@ module Commander
     end
     
     ##
-    # Invoke the active command.
+    # Run the active command.
     
-    def call_active_command
+    def run_active_command
+      require_valid_command
       if alias? command_name_from_args
         active_command.run *(@aliases[command_name_from_args.to_s] + args_without_command_name)
       else
@@ -131,16 +132,21 @@ module Commander
     
     def command name, &block
       yield add_command(Commander::Command.new(name)) if block
-      @commands[name.to_s] or raise InvalidCommandError, "invalid command '#{ name || 'nil' }'", caller
+      @commands[name.to_s]
     end
     
     ##
-    # Add a global option; follows the same syntax as
-    # Command#option. This would be used for switches such
-    # as --version, --trace, etc.
+    # Add a global option; follows the same syntax as Command#option
+    # This would be used for switches such as --version, --trace, etc.
     
     def global_option *args, &block
-      @options << [args, block]
+      switches, description = Runner.seperate_switches_from_description *args
+      @options << {
+        :args => args,
+        :proc => block,
+        :switches => switches,
+        :description => description,
+      }
     end
     
     ##
@@ -228,7 +234,9 @@ module Commander
     # Returns hash of program defaults.
     
     def program_defaults
-      return :help_formatter => HelpFormatter::Terminal, :int_message => "\nProcess interrupted"
+      return :help_formatter => HelpFormatter::Terminal, 
+             :int_message => "\nProcess interrupted",
+             :name => File.basename($0)
     end
     
     ##
@@ -246,12 +254,21 @@ module Commander
           if args.empty?
             say help_formatter.render 
           else
-            say help_formatter.render_command(command(args.join(' ')))
+            command = command args.join(' ')
+            require_valid_command command
+            say help_formatter.render_command(command)
           end
         end
       end
     end
     
+    ##
+    # Raises InvalidCommandError when a +command+ is not found.
+    
+    def require_valid_command command = active_command
+      raise InvalidCommandError, 'invalid command', caller if command.nil?
+    end
+    
     ##
     # Removes global options from args. This prevents an invalid
     # option error from ocurring when options are parsed
@@ -259,8 +276,8 @@ module Commander
     
     def remove_global_options
       # TODO: refactor with flipflop
-      options.each do |(args, proc)|
-        switch, has_arg = args.first.split
+      options.each do |option|
+        switch, has_arg = option[:args].first.split
         past_switch, arg_removed = false, false
         @args.delete_if do |arg|
           if arg == switch
@@ -280,14 +297,29 @@ module Commander
     # Parse global command options.
     
     def parse_global_options
-      options.inject OptionParser.new do |options, (args, proc)|
-        options.on *args, &proc
+      options.inject OptionParser.new do |options, option|
+        options.on *option[:args], &global_option_proc(option[:switches], &option[:proc])
       end.parse! @args.dup
     rescue OptionParser::InvalidOption
       # Ignore invalid options since options will be further 
       # parsed by our sub commands.
     end
     
+    ##
+    # Returns a proc allowing for sub-commands to inherit global options.
+    # This functionality works weither a block is present for the global
+    # option or not, so simple switches such as --verbose can be used
+    # without a block, and used throughout all sub-commands.
+    
+    def global_option_proc switches, &block
+      lambda do |value|
+        unless active_command.nil?
+          active_command.proxy_options << [Runner.switch_to_sym(switches.last), value]
+        end
+        yield value if block and !value.nil?
+      end
+    end
+    
     ##
     # Raises a CommandError when the program any of the +keys+ are not present, or empty.
         
@@ -297,6 +329,30 @@ module Commander
       end
     end
     
+    ##
+    # Return switches and description seperated from the +args+ passed.
+
+    def self.seperate_switches_from_description *args
+      switches = args.find_all { |arg| arg.to_s =~ /^-/ } 
+      description = args.last unless !args.last.is_a? String or args.last.match(/^-/)
+      return switches, description
+    end
+    
+    ##
+    # Attempts to generate a method name symbol from +switch+.
+    # For example:
+    # 
+    #   -h                 # => :h
+    #   --trace            # => :trace
+    #   --some-switch      # => :some_switch
+    #   --[no-]feature     # => :feature
+    #   --file FILE        # => :file
+    #   --list of,things   # => :list
+    
+    def self.switch_to_sym switch
+      switch.scan(/[\-\]](\w+)/).join('_').to_sym rescue nil
+    end
+    
     private
     
     def say *args #:nodoc: 

data/lib/commander/version.rb

@@ -1,4 +1,4 @@
 
 module Commander
-  VERSION = '3.1.8'
+  VERSION = '3.2.0'
 end

data/spec/command_spec.rb

@@ -24,14 +24,6 @@ describe Commander::Command do
     end
   end
   
-  describe "#seperate_switches_from_description" do
-    it "should seperate switches and description returning both" do
-      switches, description = *@command.seperate_switches_from_description('-h', '--help', 'display help')
-      switches.should == ['-h', '--help']
-      description.should == 'display help'
-    end
-  end
-    
   describe "#option" do
     it "should add options" do
       lambda { @command.option '--recursive' }.should change(@command.options, :length).from(1).to(2)
@@ -49,17 +41,6 @@ describe Commander::Command do
     end
   end
   
-  describe "#switch_to_sym" do
-    it "should return a symbol based on the switch name" do
-      @command.switch_to_sym('--trace').should == :trace
-      @command.switch_to_sym('--foo-bar').should == :foo_bar
-      @command.switch_to_sym('--[no-]feature"').should == :feature
-      @command.switch_to_sym('--[no-]feature ARG').should == :feature
-      @command.switch_to_sym('--file [ARG]').should == :file
-      @command.switch_to_sym('--colors colors').should == :colors
-    end
-  end
-  
   describe "#run" do
     describe "should invoke #when_called" do
       it "with arguments seperated from options" do

data/spec/runner_spec.rb

@@ -20,7 +20,7 @@ describe Commander do
     
     it "should raise an error when required info has not been set" do
       new_command_runner '--help'
-  	  program :name, ''
+  	  program :version, ''
       lambda { run! }.should raise_error(Commander::Runner::CommandError)
     end
   end
@@ -30,8 +30,27 @@ describe Commander do
   	  command(:test).should be_instance_of(Commander::Command)
   	end
     
-    it "should raise InvalidCommandError when the command does not exist" do
-      lambda { command(:im_not_real) }.should raise_error(Commander::Runner::InvalidCommandError)
+    it "should return nil when the command does not exist" do
+      command(:im_not_real).should be_nil
+    end
+  end
+  
+  describe "#seperate_switches_from_description" do
+    it "should seperate switches and description returning both" do
+      switches, description = *Commander::Runner.seperate_switches_from_description('-h', '--help', 'display help')
+      switches.should == ['-h', '--help']
+      description.should == 'display help'
+    end
+  end
+  
+  describe "#switch_to_sym" do
+    it "should return a symbol based on the switch name" do
+     Commander::Runner.switch_to_sym('--trace').should == :trace
+     Commander::Runner.switch_to_sym('--foo-bar').should == :foo_bar
+     Commander::Runner.switch_to_sym('--[no-]feature"').should == :feature
+     Commander::Runner.switch_to_sym('--[no-]feature ARG').should == :feature
+     Commander::Runner.switch_to_sym('--file [ARG]').should == :file
+     Commander::Runner.switch_to_sym('--colors colors').should == :colors
     end
   end
   
@@ -42,14 +61,15 @@ describe Commander do
     end
     
     it "should pass arguments passed to the alias when called" do
+      gem_name = ''
       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' }
+          c.when_called { |_, options| gem_name = options.gem_name }
         end 
         alias_command :'install gem', :install, '--gem-name'
-        command(:install).should_receive(:run).once
       end.run!
+      gem_name.should == 'commander'
     end
   end
   
@@ -61,6 +81,28 @@ describe Commander do
       end.run!
       file.should == 'foo'
     end
+    
+    it "should be inherited by sub-commands" do
+      quiet = nil
+      new_command_runner 'foo', '--quiet' do
+        global_option('--quiet', 'Suppress output')
+        command :foo do |c|
+          c.when_called { |_, options| quiet = options.quiet } 
+        end
+      end.run!
+      quiet.should be_true
+    end
+    
+    it "should be inherited by sub-commands even when a block is present" do
+      quiet = nil
+      new_command_runner 'foo', '--quiet' do
+        global_option('--quiet', 'Suppress output') {}
+        command :foo do |c|
+          c.when_called { |_, options| quiet = options.quiet } 
+        end
+      end.run!
+      quiet.should be_true      
+    end
   end
   
   describe "--trace" do
@@ -165,9 +207,9 @@ describe Commander do
       command_runner.active_command.should be_instance_of(Commander::Command)
     end
     
-    it "should raise invalid command error when the command is not found" do
+    it "should return nil when the command is not found" do
       new_command_runner 'foo'
-      lambda { command_runner.active_command }.should raise_error(Commander::Runner::InvalidCommandError)
+      command_runner.active_command.should be_nil
     end
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: visionmedia-commander
 version: !ruby/object:Gem::Version 
-  version: 3.1.8
+  version: 3.2.0
 platform: ruby
 authors: 
 - TJ Holowaychuk
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-25 00:00:00 -07:00
+date: 2009-03-26 00:00:00 -07:00
 default_executable: commander
 dependencies: 
 - !ruby/object:Gem::Dependency