commander 4.2.1 → 4.3.0

data/lib/commander/command.rb

@@ -3,45 +3,44 @@ require 'optparse'
 
 module Commander
   class Command
-    
     attr_accessor :name, :examples, :syntax, :description
     attr_accessor :summary, :proxy_options, :options
-    
+
     ##
     # Options struct.
 
     class Options
       include Blank
-      
+
       def initialize
         @table = {}
       end
-      
+
       def __hash__
         @table
       end
-      
-      def method_missing meth, *args, &block
+
+      def method_missing(meth, *args)
         meth.to_s =~ /=$/ ? @table[meth.to_s.chop.to_sym] = args.first : @table[meth]
       end
-      
-      def default defaults = {}
+
+      def default(defaults = {})
         @table = defaults.merge! @table
       end
-      
+
       def inspect
-        "<Commander::Command::Options #{ __hash__.map { |k,v| "#{k}=#{v.inspect}" }.join(', ') }>"
+        "<Commander::Command::Options #{ __hash__.map { |k, v| "#{k}=#{v.inspect}" }.join(', ') }>"
       end
     end
-        
+
     ##
     # Initialize new command with specified _name_.
-    
-    def initialize name
+
+    def initialize(name)
       @name, @examples, @when_called = name.to_s, [], []
       @options, @proxy_options = [], []
     end
-    
+
     ##
     # Add a usage example for this command.
     #
@@ -49,22 +48,22 @@ module Commander
     # created by the help formatters.
     #
     # === Examples
-    #    
+    #
     #   command :something do |c|
     #     c.example "Should do something", "my_command something"
     #   end
     #
-    
-    def example description, command 
+
+    def example(description, command)
       @examples << [description, command]
     end
-    
+
     ##
     # Add an option.
     #
     # Options are parsed via OptionParser so view it
     # for additional usage documentation. A block may optionally be
-    # passed to handle the option, otherwise the _options_ struct seen below 
+    # passed to handle the option, otherwise the _options_ struct seen below
     # contains the results of this option. This handles common formats such as:
     #
     #   -h, --help          options.help           # => bool
@@ -75,18 +74,18 @@ module Commander
     #   --date [DATE]       options.date           # => date or nil when optional argument not set
     #
     # === Examples
-    #    
+    #
     #   command :something do |c|
     #     c.option '--recursive', 'Do something recursively'
     #     c.option '--file FILE', 'Specify a file'
     #     c.option('--info', 'Display info') { puts "handle with block" }
     #     c.option '--[no-]feature', 'With or without feature'
     #     c.option '--list FILES', Array, 'List the files specified'
-    #   
+    #
     #     c.when_called do |args, options|
     #       do_something_recursively if options.recursive
     #       do_something_with_file options.file if options.file
-    #     end 
+    #     end
     #   end
     #
     # === Help Formatters
@@ -105,88 +104,88 @@ module Commander
     #   c.option '--time TIME', Time
     #   c.option '--date [DATE]', Date
     #
-    
-    def option *args, &block
+
+    def option(*args, &block)
       switches, description = Runner.separate_switches_from_description(*args)
       proc = block || option_proc(switches)
       @options << {
-        :args => args,
-        :proc => proc,
-        :switches => switches,
-        :description => description,
+        args: args,
+        proc: proc,
+        switches: switches,
+        description: description
       }
     end
-    
+
     ##
-    # Handle execution of command. The handler may be a class, 
+    # Handle execution of command. The handler may be a class,
     # object, or block (see examples below).
     #
     # === Examples
-    #    
+    #
     #   # Simple block handling
     #   c.when_called do |args, options|
     #      # do something
-    #   end 
-    #   
+    #   end
+    #
     #   # Create inst of Something and pass args / options
     #   c.when_called MyLib::Command::Something
-    #   
+    #
     #   # Create inst of Something and use arbitrary method
     #    c.when_called MyLib::Command::Something, :some_method
-    #   
+    #
     #   # Pass an object to handle callback (requires method symbol)
     #   c.when_called SomeObject, :some_method
     #
-    
-    def when_called *args, &block
-      raise ArgumentError, 'must pass an object, class, or block.' if args.empty? and !block
+
+    def when_called(*args, &block)
+      fail ArgumentError, 'must pass an object, class, or block.' if args.empty? && !block
       @when_called = block ? [block] : args
     end
-    alias :action :when_called
-    
+    alias_method :action, :when_called
+
     ##
     # Run the command with _args_.
     #
     # * parses options, call option blocks
     # * invokes when_called proc
     #
-    
-    def run *args
+
+    def run(*args)
       call parse_options_and_call_procs(*args)
     end
-    
+
     #:stopdoc:
-    
+
     ##
-    # Parses options and calls associated procs, 
+    # Parses options and calls associated procs,
     # returning the arguments remaining.
-    
-    def parse_options_and_call_procs *args
+
+    def parse_options_and_call_procs(*args)
       return args if args.empty?
-      @options.inject OptionParser.new do |opts, option| 
+      @options.inject OptionParser.new do |opts, option|
         opts.on(*option[:args], &option[:proc])
         opts
       end.parse! args
     end
-    
+
     ##
     # Call the commands when_called block with _args_.
-    
-    def call args = []
+
+    def call(args = [])
       object = @when_called.shift
       meth = @when_called.shift || :call
       options = proxy_option_struct
       case object
-      when Proc  ; object.call(args, options)
-      when Class ; meth != :call ? object.new.send(meth, args, options) : object.new(args, options)
-      else         object.send(meth, args, options) if object
-      end 
+      when Proc then object.call(args, options)
+      when Class then meth != :call ? object.new.send(meth, args, options) : object.new(args, options)
+      else object.send(meth, args, options) if object
+      end
     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)|
         # options that are present will evaluate to true
@@ -195,19 +194,18 @@ module Commander
         options
       end
     end
-    
+
     ##
     # Option proxy proc used when a block is not explicitly passed
     # via the #option method. This allows commander to auto-populate
     # and work with option values.
-    
-    def option_proc switches
-      lambda { |value| proxy_options << [Runner.switch_to_sym(switches.last), value] } 
+
+    def option_proc(switches)
+      lambda { |value| proxy_options << [Runner.switch_to_sym(switches.last), value] }
     end
-    
-    def inspect 
+
+    def inspect
       "<Commander::Command:#{name}>"
     end
-    
   end
-end
+end

data/lib/commander/configure.rb

@@ -5,7 +5,7 @@ module Commander
   def configure(*configuration_opts, &configuration_block)
     configuration_module = Module.new
     configuration_module.extend Commander::Methods
-    
+
     configuration_module.class_exec(*configuration_opts, &configuration_block)
 
     configuration_module.class_exec do
@@ -15,4 +15,3 @@ module Commander
 
   module_function :configure
 end
-

data/lib/commander/core_ext.rb

@@ -1,3 +1,3 @@
 
 require 'commander/core_ext/array'
-require 'commander/core_ext/object'
+require 'commander/core_ext/object'

data/lib/commander/core_ext/array.rb

@@ -1,6 +1,5 @@
 
 class Array
-
   ##
   # Split _string_ into an array. Used in
   # conjunction with Highline's #ask, or #ask_for_array
@@ -18,9 +17,9 @@ class Array
   #   list = ask_for_array 'Favorite cookies: '
   #
 
-  def self.parse string
+  def self.parse(string)
     # Using reverse + lookahead to work around Ruby 1.8's lack of lookbehind
+    # TODO: simplify now that we don't support Ruby 1.8
     string.reverse.split(/\s(?!\\)/).reverse.map { |s| s.reverse.gsub('\\ ', ' ') }
   end
-
 end

data/lib/commander/core_ext/object.rb

@@ -1,11 +1,9 @@
 
 class Object
-
   ##
   # Return the current binding.
-  
+
   def get_binding
     binding
   end
-
 end

data/lib/commander/delegates.rb

@@ -1,14 +1,25 @@
-
 module Commander
   module Delegates
-    %w( add_command command program run! global_option
-        commands alias_command default_command
-        always_trace! never_trace! ).each do |meth|
+    %w(
+      add_command
+      command
+      program
+      run!
+      global_option
+      alias_command
+      default_command
+      always_trace!
+      never_trace!
+    ).each do |meth|
       eval <<-END, binding, __FILE__, __LINE__
         def #{meth} *args, &block
           ::Commander::Runner.instance.#{meth} *args, &block
         end
       END
     end
+
+    def defined_commands(*args, &block)
+      ::Commander::Runner.instance.commands(*args, &block)
+    end
   end
 end

data/lib/commander/help_formatters.rb

@@ -6,7 +6,8 @@ module Commander
     autoload :TerminalCompact, 'commander/help_formatters/terminal_compact'
 
     module_function
-    def indent amount, text
+
+    def indent(amount, text)
       text.gsub("\n", "\n" + (' ' * amount))
     end
   end

data/lib/commander/help_formatters/base.rb

@@ -1,18 +1,25 @@
 
 module Commander
-  
   ##
   # = Help Formatter
   #
   # Commander's help formatters control the output when
   # either the help command, or --help switch are called.
   # The default formatter is Commander::HelpFormatter::Terminal.
-  
+
   module HelpFormatter
-    class Base 
-      def initialize runner; @runner = runner  end
-      def render; 'Implement global help here' end
-      def render_command command; "Implement help for #{command.name} here" end
+    class Base
+      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
+end

data/lib/commander/help_formatters/terminal.rb

@@ -7,14 +7,14 @@ module Commander
       def render
         template(:help).result @runner.get_binding
       end
-      
-      def render_command command
+
+      def render_command(command)
         template(:command_help).result command.get_binding
       end
-      
-      def template name
+
+      def template(name)
         ERB.new(File.read(File.join(File.dirname(__FILE__), 'terminal', "#{name}.erb")), nil, '-')
       end
     end
   end
-end
+end

data/lib/commander/help_formatters/terminal_compact.rb

@@ -4,9 +4,9 @@ require 'erb'
 module Commander
   module HelpFormatter
     class TerminalCompact < Terminal
-      def template name
+      def template(name)
         ERB.new(File.read(File.join(File.dirname(__FILE__), 'terminal_compact', "#{name}.erb")), nil, '-')
       end
     end
   end
-end
+end

data/lib/commander/methods.rb

@@ -8,4 +8,3 @@ module Commander::Methods
 
   $terminal.wrap_at = HighLine::SystemExtensions.terminal_size.first - 5 rescue 80 if $stdin.tty?
 end
-

data/lib/commander/runner.rb

@@ -57,7 +57,7 @@ module Commander
         return
       end
       global_option('-v', '--version', 'Display version information') { say version; return } 
-      global_option('-t', '--trace', 'Display backtrace when an error occurs') { trace = true } unless @never_trace
+      global_option('-t', '--trace', 'Display backtrace when an error occurs') { trace = true } unless @never_trace || @always_trace
       parse_global_options
       remove_global_options options, @args
       unless trace

data/lib/commander/user_interaction.rb

@@ -2,22 +2,20 @@ require 'tempfile'
 require 'shellwords'
 
 module Commander
-  
   ##
   # = User Interaction
   #
   # Commander's user interaction module mixes in common
-  # methods which extend HighLine's functionality such 
+  # methods which extend HighLine's functionality such
   # as a #password method rather than calling #ask directly.
-  
+
   module UI
-    
     module_function
-    
+
     #--
     # Auto include growl when available.
     #++
-    
+
     begin
       require 'growl'
     rescue LoadError
@@ -25,26 +23,26 @@ module Commander
     else
       include Growl
     end
-    
+
     ##
     # Ask the user for a password. Specify a custom
-    # _message_ other than 'Password: ' or override the 
+    # _message_ other than 'Password: ' or override the
     # default _mask_ of '*'.
-    
-    def password message = 'Password: ', mask = '*'
+
+    def password(message = 'Password: ', mask = '*')
       pass = ask(message) { |q| q.echo = mask }
       pass = password message, mask if pass.nil? || pass.empty?
       pass
     end
-    
+
     ##
     # Choose from a set array of _choices_.
-    
-    def choose message = nil, *choices, &block
+
+    def choose(message = nil, *choices, &block)
       say message if message
       super(*choices, &block)
     end
-    
+
     ##
     # 'Log' an _action_ to the terminal. This is typically used
     # for verbose output regarding actions performed. For example:
@@ -53,8 +51,8 @@ module Commander
     #   remove  path/to/old_file.rb
     #   remove  path/to/old_file2.rb
     #
-    
-    def log action, *args
+
+    def log(action, *args)
       say '%15s  %s' % [action, args.join(' ')]
     end
 
@@ -66,7 +64,7 @@ module Commander
     #   say_ok 'It is ok', 'This is ok too'
     #
 
-    def say_ok *args
+    def say_ok(*args)
       args.each do |arg|
         say $terminal.color(arg, :green)
       end
@@ -80,7 +78,7 @@ module Commander
     #   say_warning 'Be careful', 'Think about it'
     #
 
-    def say_warning *args
+    def say_warning(*args)
       args.each do |arg|
         say $terminal.color(arg, :yellow)
       end
@@ -94,7 +92,7 @@ module Commander
     #   say_error 'It is not ok', 'This is not ok too'
     #
 
-    def say_error *args
+    def say_error(*args)
       args.each do |arg|
         say $terminal.color(arg, :red)
       end
@@ -120,28 +118,28 @@ module Commander
 
     ##
     # Speak _message_ using _voice_ at a speaking rate of _rate_
-    # 
+    #
     # Voice defaults to 'Alex', which is one of the better voices.
     # Speaking rate defaults to 175 words per minute
     #
     # === Examples
-    #    
+    #
     #   speak 'What is your favorite food? '
     #   food = ask 'favorite food?: '
-    #   speak "Wow, I like #{food} too. We have so much in common." 
+    #   speak "Wow, I like #{food} too. We have so much in common."
     #   speak "I like #{food} as well!", "Victoria", 190
     #
     # === Notes
     #
     # * MacOS only
     #
-    
-    def speak message, voice = :Alex, rate = 175
+
+    def speak(message, voice = :Alex, rate = 175)
       Thread.new { applescript "say #{message.inspect} using #{voice.to_s.inspect} speaking rate #{rate}" }
     end
-    
+
     ##
-    # Converse with speech recognition. 
+    # Converse with speech recognition.
     #
     # Currently a "poorman's" DSL to utilize applescript and
     # the MacOS speech recognition server.
@@ -149,7 +147,7 @@ module Commander
     # === Examples
     #
     #   case converse 'What is the best food?', :cookies => 'Cookies', :unknown => 'Nothing'
-    #   when :cookies 
+    #   when :cookies
     #     speak 'o.m.g. you are awesome!'
     #   else
     #     case converse 'That is lame, shall I convince you cookies are the best?', :yes => 'Ok', :no => 'No', :maybe => 'Maybe another time'
@@ -164,31 +162,30 @@ module Commander
     #
     # * MacOS only
     #
-    
-    def converse prompt, responses = {}
-      i, commands = 0, responses.map { |key, value| value.inspect }.join(',')
+
+    def converse(prompt, responses = {})
+      i, commands = 0, responses.map { |_key, value| value.inspect }.join(',')
       statement = responses.inject '' do |statement, (key, value)|
-        statement << (((i += 1) == 1 ? 
-          %(if response is "#{value}" then\n):
-            %(else if response is "#{value}" then\n))) <<
-              %(do shell script "echo '#{key}'"\n)
+        statement << (((i += 1) == 1 ?
+          %(if response is "#{value}" then\n) : %(else if response is "#{value}" then\n))) <<
+          %(do shell script "echo '#{key}'"\n)
       end
       applescript(%(
-        tell application "SpeechRecognitionServer" 
+        tell application "SpeechRecognitionServer"
           set response to listen for {#{commands}} with prompt "#{prompt}"
           #{statement}
           end if
         end tell
       )).strip.to_sym
     end
-    
+
     ##
     # Execute apple _script_.
-    
-    def applescript script
+
+    def applescript(script)
       `osascript -e "#{ script.gsub('"', '\"') }"`
     end
-    
+
     ##
     # Normalize IO streams, allowing for redirection of
     # +input+ and/or +output+, for example:
@@ -213,8 +210,8 @@ module Commander
     #     end
     #   end
     #
-    
-    def io input = nil, output = nil, &block
+
+    def io(input = nil, output = nil, &block)
       $stdin = File.new(input) if input
       $stdout = File.new(output, 'r+') if output
       if block
@@ -222,10 +219,10 @@ module Commander
         reset_io
       end
     end
-    
+
     ##
     # Reset IO to initial constant streams.
-    
+
     def reset_io
       $stdin, $stdout = STDIN, STDOUT
     end
@@ -234,12 +231,12 @@ module Commander
     # Find an editor available in path. Optionally supply the _preferred_
     # editor. Returns the name as a string, nil if none is available.
 
-    def available_editor preferred = nil
-      [preferred, ENV['EDITOR'], 'mate -w', 'vim', 'vi', 'emacs', 'nano', 'pico'].
-        compact.
-        find {|name| system("hash #{name.split.first} 2>&-") }
+    def available_editor(preferred = nil)
+      [preferred, ENV['EDITOR'], 'mate -w', 'vim', 'vi', 'emacs', 'nano', 'pico']
+        .compact
+        .find { |name| system("hash #{name.split.first} 2>&-") }
     end
-    
+
     ##
     # Prompt an editor for input. Optionally supply initial
     # _input_ which is written to the editor.
@@ -252,8 +249,8 @@ module Commander
     #   ask_editor('foo')         # => prompts EDITOR with default text of 'foo'
     #   ask_editor('foo', 'mate -w')  # => prompts TextMate with default text of 'foo'
     #
-       
-    def ask_editor input = nil, preferred_editor = nil
+
+    def ask_editor(input = nil, preferred_editor = nil)
       editor = available_editor preferred_editor
       program = Commander::Runner.instance.program(:name).downcase rescue 'commander'
       tmpfile = Tempfile.new program
@@ -265,10 +262,10 @@ module Commander
         tmpfile.unlink
       end
     end
-    
+
     ##
     # Enable paging of output after called.
-    
+
     def enable_paging
       return unless $stdout.tty?
       return unless Process.respond_to? :fork
@@ -279,7 +276,7 @@ module Commander
       # configurations that don't support it, but versions before 1.9 don't
       # seem to do this reliably and instead raise a NotImplementedError
       # (which is rescued below).
-      
+
       if Kernel.fork
         $stdin.reopen read
         write.close; read.close
@@ -310,21 +307,22 @@ module Commander
     #   end
     #
 
-    def progress arr, options = {}, &block
+    def progress(arr, options = {})
       bar = ProgressBar.new arr.length, options
       bar.show
       arr.each { |v| bar.increment yield(v) }
     end
-        
+
     ##
     # Implements ask_for_CLASS methods.
-    
+
     module AskForClass
       # All special cases in HighLine::Question#convert, except those that implement #parse
       ([Float, Integer, String, Symbol, Regexp, Array, File, Pathname] +
       # All Classes that respond to #parse
       Object.constants.map do |const|
         # const_get(:Config) issues a deprecation warning on ruby 1.8.7
+        # TODO: clean up now that we're not supporting Ruby 1.8
         Object.const_get(const) unless const == :Config
       end.select do |const|
         const.class == Class && const.respond_to?(:parse)
@@ -334,16 +332,16 @@ module Commander
         end
       end
     end
-    
+
     ##
     # Substitute _hash_'s keys with their associated values in _str_.
-    
-    def replace_tokens str, hash #:nodoc:
+
+    def replace_tokens(str, hash) #:nodoc:
       hash.inject str do |str, (key, value)|
         str.gsub ":#{key}", value.to_s
       end
     end
-    
+
     ##
     # = Progress Bar
     #
@@ -352,12 +350,12 @@ module Commander
     # be incremented. Note that a hash of tokens may be passed to
     # #increment, (or returned when using Object#progress).
     #
-    #   uris = %w( 
+    #   uris = %w(
     #     http://vision-media.ca
     #     http://yahoo.com
     #     http://google.com
     #     )
-    #   
+    #
     #   bar = Commander::UI::ProgressBar.new uris.length, options
     #   threads = []
     #   uris.each do |uri|
@@ -381,12 +379,11 @@ module Commander
     #
 
     class ProgressBar
-
       ##
       # Creates a new progress bar.
       #
       # === Options
-      #    
+      #
       #   :title              Title, defaults to "Progress"
       #   :width              Width of :progress_bar
       #   :progress_str       Progress string, defaults to "="
@@ -397,7 +394,7 @@ module Commander
       #
       # === Tokens
       #
-      #   :title 
+      #   :title
       #   :percent_complete
       #   :progress_bar
       #   :step
@@ -407,7 +404,7 @@ module Commander
       #   :time_remaining
       #
 
-      def initialize total, options = {}
+      def initialize(total, options = {})
         @total_steps, @step, @start_time = total, 0, Time.now
         @title = options.fetch :title, 'Progress'
         @width = options.fetch :width, 25
@@ -417,10 +414,10 @@ module Commander
         @format = options.fetch :format, ':title |:progress_bar| :percent_complete% complete '
         @tokens = options.fetch :tokens, {}
       end
-      
+
       ##
       # Completion percentage.
-      
+
       def percent_complete
         if @total_steps.zero?
           100
@@ -428,50 +425,49 @@ module Commander
           @step * 100 / @total_steps
         end
       end
-      
+
       ##
       # Time that has elapsed since the operation started.
-      
+
       def time_elapsed
         Time.now - @start_time
       end
-      
+
       ##
       # Estimated time remaining.
-      
+
       def time_remaining
         (time_elapsed / @step) * steps_remaining
       end
-      
+
       ##
       # Number of steps left.
-      
+
       def steps_remaining
         @total_steps - @step
       end
-      
+
       ##
       # Formatted progress bar.
-      
+
       def progress_bar
         (@progress_str * (@width * percent_complete / 100)).ljust @width, @incomplete_str
       end
-      
+
       ##
       # Generates tokens for this step.
-      
+
       def generate_tokens
         {
-          :title => @title,
-          :percent_complete => percent_complete,
-          :progress_bar => progress_bar, 
-          :step => @step,
-          :steps_remaining => steps_remaining,
-          :total_steps => @total_steps, 
-          :time_elapsed => "%0.2fs" % time_elapsed,
-          :time_remaining => @step > 0 ? "%0.2fs" % time_remaining : '',
-        }.
-        merge! @tokens
+          title: @title,
+          percent_complete: percent_complete,
+          progress_bar: progress_bar,
+          step: @step,
+          steps_remaining: steps_remaining,
+          total_steps: @total_steps,
+          time_elapsed: '%0.2fs' % time_elapsed,
+          time_remaining: @step > 0 ? '%0.2fs' % time_remaining : ''
+        }.merge! @tokens
       end
 
       ##
@@ -487,10 +483,10 @@ module Commander
           end
         end
       end
-      
+
       ##
       # Whether or not the operation is complete, and we have finished.
-      
+
       def finished?
         @step == @total_steps + 1
       end
@@ -506,7 +502,7 @@ module Commander
       # Increment progress. Optionally pass _tokens_ which
       # can be displayed in the output format.
 
-      def increment tokens = {}
+      def increment(tokens = {})
         @step += 1
         @tokens.merge! tokens if tokens.is_a? Hash
         show