visionmedia-commander 2.5.7 → 3.0.0

data/lib/commander/core_ext.rb

@@ -1,5 +1,4 @@
 
-require 'commander/core_ext/kernel'
 require 'commander/core_ext/array'
 require 'commander/core_ext/object'
 require 'commander/core_ext/string'

data/lib/commander/core_ext/array.rb

@@ -2,23 +2,28 @@
 class Array 
   
   ##
-  # Split +string+ into an array. 
+  # Split +string+ into an array. Used in
+  # conjunection with Highline's ask, or ask_for_array
+  # methods, which must respond to #parse.
   #
   # === Highline example:
   #  
   #   # ask invokes Array#parse
   #   list = ask 'Favorite cookies:', Array
   #
+  #   # or use ask_for_CLASS
+  #   list = ask_for_array 'Favorite cookies: '
+  #
   
   def self.parse string
-    string.split
+    eval "%w(#{string})"
   end
   
   ##
-  # Delete switches such as -h or --help.
+  # Delete switches such as -h or --help. Mutative.
   
   def delete_switches
-    self.dup.delete_if { |v| v.to_s =~ /^-/ } 
+    self.delete_if { |value| value.to_s =~ /^-/ } 
   end
   
 end

data/lib/commander/core_ext/object.rb

@@ -1,13 +1,48 @@
 
+require 'forwardable'
+
+##
+# Delegates the following methods:
+#
+# * Commander::Runner#add_command
+# * Commander::Runner#command
+# * Commander::Runner#commands
+# * Commander::Runner#program
+# * Commander::UI::ProgressBar#progress
+#
+
 class Object
   
+  extend Forwardable
   include Commander::UI
   
+  def_delegators :$command_runner, :add_command, :command, :program, :run!, :commands
+  def_delegators Commander::UI::ProgressBar, :progress
+
   ##
-  # Used with ERB in Commander::HelpFormatter::Base.
+  # Return the current binding.
   
   def get_binding
     binding
   end
+
+  ##
+  # Return the current command runner.
   
-end
+  def command_runner
+    $command_runner
+  end
+    
+  ##
+  # Implement #ask_for_CLASS.
+  
+  include Module.new {
+    def method_missing meth, *args, &block
+      case meth.to_s
+      when /^ask_for_([\w]+)/ ; $terminal.ask(args.first, eval($1.capitalize))
+      else super
+      end
+    end
+  }
+
+end

data/lib/commander/core_ext/string.rb

@@ -2,10 +2,10 @@
 class String
     
   ##
-  # Replace +hash+ keys with associated values. Mutative.
+  # Replace +hash+ keys with associated values.
   
   def tokenize! hash = {}
-    hash.each { |k, v| gsub! /:#{k}/, v.to_s }
+    hash.each { |key, value| gsub! /:#{key}/, value.to_s }
     self
   end
     
@@ -16,16 +16,4 @@ class String
     self.dup.tokenize! hash
   end
   
-  ##
-  # Converts a string to camelcase.
-  
-  def camelcase upcase_first_letter = true
-    up = upcase_first_letter
-    s = dup
-    s.gsub!(/\/(.?)/){ "::#{$1.upcase}" }
-    s.gsub!(/(?:_+|-+)([a-z])/){ $1.upcase }
-    s.gsub!(/(\A|\s)([a-z])/){ $1 + $2.upcase } if up
-    s
-  end
-    
 end

data/lib/commander/help_formatters.rb

@@ -1,6 +1,8 @@
 
 require 'commander/help_formatters/base'
 
-module Commander::HelpFormatter
-  autoload :Terminal, 'commander/help_formatters/terminal'
+module Commander
+  module HelpFormatter
+    autoload :Terminal, 'commander/help_formatters/terminal'
+  end
 end

data/lib/commander/help_formatters/base.rb

@@ -9,30 +9,10 @@ module Commander
   # The default formatter is Commander::HelpFormatter::Terminal.
   
   module HelpFormatter
-    
     class Base 
-      
-      ##
-      # Access the current command runner via +@runner+.
-
-      def initialize runner
-        @runner = runner
-      end
-      
-      ##
-      # Renders global help.
-      
-      def render
-        "Implement global help here"
-      end
-      
-      ##
-      # Renders +command+ specific help.
-      
-      def render_command command
-        "Implement help for #{command.name} here"
-      end
-      
+      def initialize runner; @runner = runner  end
+      def render; 'Implement global help here' end
+      def render_command command; "Implement help for #{command.name} here" end
     end
   end
 end

data/lib/commander/help_formatters/terminal.rb

@@ -3,13 +3,6 @@ require 'erb'
 
 module Commander
   module HelpFormatter
-    
-    ##
-    # = Terminal
-    #
-    # Outputs help in a terminal friendly format,
-    # utilizing asni formatting via the highline gem.
-    
     class Terminal < Base
       def render
         template(:help).result @runner.get_binding
@@ -20,7 +13,7 @@ module Commander
       end
       
       def template name
-        ERB.new(File.read(File.expand_path(File.dirname(__FILE__)) + "/terminal/#{name}.erb"), nil, "-")
+        ERB.new(File.read(File.expand_path(File.dirname(__FILE__)) + "/terminal/#{name}.erb"), nil, '-')
       end
     end
   end

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

@@ -1,31 +1,31 @@
 
-  <%= color "NAME", :bold %>:
+  <%= $terminal.color "NAME", :bold %>:
 
     <%= @name %>
 
-  <%= color "DESCRIPTION", :bold %>:
+  <%= $terminal.color "DESCRIPTION", :bold %>:
 
     <%= @description || @summary || 'No description.' -%>
 
 <% if @syntax -%>
 
-  <%= color "SYNOPSIS", :bold %>:
+  <%= $terminal.color "SYNOPSIS", :bold %>:
 
     <%= @syntax -%>
 
 <% end -%>
 <% unless @examples.empty? -%>
 
-  <%= color "EXAMPLES", :bold %>:
-	<% @examples.each do |example| -%>
+  <%= $terminal.color "EXAMPLES", :bold %>:
+	<% @examples.each do |description, command| -%>
 
-    # <%= example[:description] %>
-    <%= example[:command] %>
+    # <%= description %>
+    <%= command %>
 	<% end -%>
 <% end -%>
 <% unless @options.empty? -%>
 
-  <%= color "OPTIONS", :bold %>:
+  <%= $terminal.color "OPTIONS", :bold %>:
 	<% @options.each do |option| -%>
 
     <%= option[:switches].join ', ' %> 

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

@@ -1,19 +1,19 @@
 
-  <%= color "NAME", :bold %>:
+  <%= $terminal.color "NAME", :bold %>:
 
     <%= program :name %>
 
-  <%= color "DESCRIPTION", :bold %>:
+  <%= $terminal.color "DESCRIPTION", :bold %>:
 
     <%= program :description %>
 
-  <%= color "SUB-COMMANDS", :bold %>:
+  <%= $terminal.color "SUB-COMMANDS", :bold %>:
 <% @commands.each_pair do |name, command| %>
     <%= "%-20s %s" % [command.name, command.summary || command.description] -%>
 <% end %>
 <% if program :help -%>
   <% program(:help).each_pair do |title, body| %>
-  <%= color title.to_s.upcase, :bold %>:
+  <%= $terminal.color title.to_s.upcase, :bold %>:
 	
     <%= body %>
   <% end %>

data/lib/commander/runner.rb

@@ -22,31 +22,30 @@ module Commander
     attr_reader :options
     
     ##
-    # Initialize a new command runner.
+    # Initialize a new command runner. Optionally
+    # supplying +args+ for mocking, or arbitrary usage.
     
     def initialize args = ARGV
-      @args = args
-      @commands, @options, @program = {}, {}, { 
-        :help_formatter => Commander::HelpFormatter::Terminal,
-        :int_message => "\nProcess interrupted",
-      }
+      @args, @commands, @options = args, {}, {}
+      @program = program_defaults
       create_default_commands
       parse_global_options
     end
     
     ##
-    # Run the command parsing and execution process immediately.
+    # Run command parsing and execution process.
     
     def run!
-      %w[ name version description ].each { |k| ensure_program_key_set k.to_sym }
+      require_program :name, :version, :description
       case 
-      when options[:version] : $terminal.say "#{@program[:name]} #{@program[:version]}" 
-      when options[:help] : get_command(:help).run
-      else active_command.run args_without_command
+      when options[:version] ; $terminal.say "#{program(:name)} #{program(:version)}" 
+      when options[:help]    ; command(:help).run(*@args[1..@args.length])
+      else                     active_command.run *args_without_command_name
       end
     rescue InvalidCommandError
-      $terminal.say "invalid command. Use --help for more information"
-    rescue OptionParser::InvalidOption, 
+      $terminal.say 'invalid command. Use --help for more information'
+    rescue \
+      OptionParser::InvalidOption, 
       OptionParser::InvalidArgument,
       OptionParser::MissingArgument => e
       $terminal.say e
@@ -57,25 +56,25 @@ module Commander
     #
     # === Examples:
     #    
-    #    # Set data
-    #    program :name, 'Commander'
-    #    program :version, Commander::VERSION
-    #    program :description, 'Commander utility program.'
-    #    program :help, 'Copyright', '2008 TJ Holowaychuk'
-    #    program :help, 'Anything', 'You want'
-    #    program :int_message 'Bye bye!'
-    #
-    #    # Get data
-    #    program :name # => 'Commander'
+    #   # Set data
+    #   program :name, 'Commander'
+    #   program :version, Commander::VERSION
+    #   program :description, 'Commander utility program.'
+    #   program :help, 'Copyright', '2008 TJ Holowaychuk'
+    #   program :help, 'Anything', 'You want'
+    #   program :int_message 'Bye bye!'
+    #   
+    #   # Get data
+    #   program :name # => 'Commander'
     #
     # === Keys:
     #
-    #    :name            (required) Program name
-    #    :version         (required) Program version triple, ex: '0.0.1'
-    #    :description     (required) Program description
-    #    :help_formatter  Defaults to Commander::HelpFormatter::Terminal
-    #    :help            Allows addition of arbitrary global help blocks
-    #    :int_message     Message to display when interrupted (CTRL + C)
+    #   :name            (required) Program name
+    #   :version         (required) Program version triple, ex: '0.0.1'
+    #   :description     (required) Program description
+    #   :help_formatter  Defaults to Commander::HelpFormatter::Terminal
+    #   :help            Allows addition of arbitrary global help blocks
+    #   :int_message     Message to display when interrupted (CTRL + C)
     #
     
     def program key, *args
@@ -84,31 +83,30 @@ module Commander
         @program[:help][args.first] = args[1]
       else
         @program[key] = *args unless args.empty?
-        @program[key] if args.empty?
+        @program[key]
       end
     end
     
     ##
-    # Generate a command object instance using a block
-    # evaluated with the command as its scope.
+    # Creates and yields a command instance when a block is passed.
+    # Otherise attempts to return the command, raising InvalidCommandError when
+    # it does not exist.
     #
     # === Examples:
     #    
-    #    command :my_command do |c|
-    #      c.when_called do |args|
-    #        # Code
-    #      end
-    #    end
-    #
-    # === See:
-    #
-    # * Commander::Command
-    # * Commander::Runner#add_command
+    #   command :my_command do |c|
+    #     c.when_called do |args|
+    #       # Code
+    #     end
+    #   end
     #
     
     def command name, &block
-      command = Commander::Command.new(name) and yield command
-      add_command command
+      if block
+        yield add_command(Commander::Command.new(name))
+      else
+        @commands[name.to_s] or raise InvalidCommandError, "invalid command '#{ name || 'nil' }'", caller
+      end
     end
     
     ##
@@ -119,14 +117,7 @@ module Commander
     end
     
     ##
-    # Get a command object if available or nil.
-    
-    def get_command name
-      @commands[name.to_s] or raise InvalidCommandError, "invalid command '#{ name || 'nil' }'", caller
-    end
-    
-    ##
-    # Check if a command exists.
+    # Check if a command +name+ exists.
     
     def command_exists? name
       @commands[name.to_s]
@@ -134,60 +125,70 @@ module Commander
     
     ##
     # Get active command within arguments passed to this runner.
-    #
-    # === See:
-    #
-    # * Commander::Runner#parse_global_options
-    #
     
     def active_command
-      @_active_command ||= get_command(command_name_from_args)
+      @__active_command ||= command(command_name_from_args)
     end
     
     ##
-    # Attemps to locate command from @args. Supports multi-word
-    # command names. 
+    # Attemps to locate a command name from within the arguments.
+    # Supports multi-word commands, using the largest possible match.
     
     def command_name_from_args
-      @_command_name_from_args ||= @args.delete_switches.inject do |name, arg|
-        return name if command_exists? name
-        name += " #{arg}"
-      end
+      @__command_name_from_args ||= valid_command_names_from(*@args.dup).last
+    end
+    
+    ##
+    # Returns array of valid command names found within +args+.
+    
+    def valid_command_names_from *args
+      arg_string = args.delete_switches.join ' '
+      commands.keys.map { |key| key if arg_string.include? key }.compact
     end
     
     ##
     # Help formatter instance.
     
     def help_formatter
-      @_help_formatter ||= @program[:help_formatter].new self
+      @__help_formatter ||= program(:help_formatter).new self
     end
     
     ##
     # Return arguments without the command name.
     
-    def args_without_command
-      @args.dup - command_name_from_args.split
+    def args_without_command_name
+      removed = []
+      parts = command_name_from_args.split
+      @args.dup.delete_if do |arg|
+        removed << arg if parts.include?(arg) and not removed.include?(arg)
+      end
     end
             
     private
     
+    ##
+    # Returns hash of program defaults.
+    
+    def program_defaults
+      return :help_formatter => HelpFormatter::Terminal, :int_message => "\nProcess interrupted"
+    end
+    
     ##
     # Creates default commands such as 'help' which is 
     # essentially the same as using the --help switch.
     
     def create_default_commands
       command :help do |c|
-        c.syntax = "command help <sub_command>"
-        c.summary = "Display help documentation for <sub_command>"
-        c.description = "Display help documentation for the global or sub commands"
-        c.example "Display global help", "command help"
-        c.example "Display help for 'foo'", "command help foo"
+        c.syntax = 'command help <sub_command>'
+        c.summary = 'Display help documentation for <sub_command>'
+        c.description = 'Display help documentation for the global or sub commands'
+        c.example 'Display global help', 'command help'
+        c.example "Display help for 'foo'", 'command help foo'
         c.when_called do |args, options|
-          gen = help_formatter
           if args.empty?
-            $terminal.say gen.render 
+            $terminal.say help_formatter.render 
           else
-            $terminal.say gen.render_command(get_command(args.join(' ')))
+            $terminal.say help_formatter.render_command(command(args.join(' ')))
           end
         end
       end
@@ -199,14 +200,11 @@ module Commander
     # These options are used by commander itself 
     # as well as allowing your program to specify 
     # global commands such as '--verbose'.
-    #
-    # TODO: allow 'option' method for global program
-    #
     
     def parse_global_options
       opts = OptionParser.new
-      opts.on("--help") { @options[:help] = true }
-      opts.on("--version") { @options[:version] = true }
+      opts.on('--help') { @options[:help] = true }
+      opts.on('--version') { @options[:version] = true }
       opts.parse! @args.dup
     rescue OptionParser::InvalidOption
       # Ignore invalid options since options will be further 
@@ -214,10 +212,12 @@ module Commander
     end
     
     ##
-    # Raises a CommandError when the program +key+ is not present, or is empty.
+    # Raises a CommandError when the program any of the +keys+ are not present, or empty.
         
-    def ensure_program_key_set key 
-      raise CommandError, "Program #{key} required (use #program method)" if (@program[key].nil? || @program[key].empty?)
+    def require_program *keys
+      keys.each do |key|
+        raise CommandError, "program #{key} required" if program(key).nil? or program(key).empty?
+      end
     end
     
   end