commander 4.1.5 → 4.1.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 89c316cbb98922c1aa25063c184fe3214dc33f03
+  data.tar.gz: 5222385e2c3e6f4d59b4b748315b429173d95435
+SHA512:
+  metadata.gz: 1d88c3df61b540cfa7e5bf58f83891393f331f0844a031619692a5429417471f3aacd1910fb7fdfb52bcaa8aa0ca469b050cd301b2323e3cd9220851d36bce2e
+  data.tar.gz: 5534ce249d8211b77c8c8112d9793e122137ec0513146bef96cf6ad1fcca4610f0bdf8a83856a1288bcca8e4f0818e537263df017263ba2709943ff0b290fd46

data/.travis.yml

@@ -2,10 +2,9 @@ language: ruby
 before_install: gem update --system
 rvm:
   - 1.8.7
-  - 1.9.2
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - jruby-18mode
   - jruby-19mode
-  - rbx-18mode
-  - rbx-19mode
+  - rbx

data/History.rdoc

@@ -1,3 +1,8 @@
+=== 4.1.6 / 2014-02-11
+
+* Respect environment setting for $LESS (@ellemenno)
+* Add ability to hide trace flags and globally enable tracing (#16, #17) (@jamesrwhite)
+
 === 4.1.5 / 2013-08-11
 
 * Prevent deprecation warning when loaded in a Rails 4 environment (#58)

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2008-2013 TJ Holowaychuk <tj@vision-media.ca>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,406 @@
+[<img src="https://secure.travis-ci.org/ggilder/commander.png?branch=master" alt="Build Status" />](http://travis-ci.org/ggilder/commander)
+
+# Commander
+
+The complete solution for Ruby command-line executables.
+Commander bridges the gap between other terminal related libraries
+you know and love (OptionParser, HighLine), while providing many new
+features, and an elegant API.
+
+## Features
+
+* Easier than baking cookies
+* Parses options using OptionParser
+* Auto-populates struct with options ( no more `{ |v| options[:recursive] = v }` )
+* Auto-generates help documentation via pluggable help formatters
+* Optional default command when none is present
+* Global / Command level options
+* Packaged with two help formatters (Terminal, TerminalCompact)
+* Imports the highline gem for interacting with the terminal
+* Adds additional user interaction functionality
+* Highly customizable progress bar with intuitive, simple usage
+* Multi-word command name support such as `drupal module install MOD`, rather than `drupal module_install MOD`
+* Sexy paging for long bodies of text
+* Support for MacOS text-to-speech
+* Command aliasing (very powerful, as both switches and arguments can be used)
+* Growl notification support for MacOS
+* Use the `commander` executable to initialize a commander driven program
+
+## Installation
+
+    $ gem install commander
+
+## Quick Start
+
+To generate a quick template for a commander app, run:
+
+    $ commander init yourfile.rb
+
+## Example
+
+For more option examples view the `Commander::Command#option` method. Also
+an important feature to note is that action may be a class to instantiate,
+as well as an object, specifying a method to call, so view the RDoc for more information.
+
+```ruby
+require 'rubygems'
+require 'commander/import'
+
+# :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.'
+
+command :foo do |c|
+  c.syntax = 'foobar foo'
+  c.description = 'Displays foo'
+  c.action do |args, options|
+    say 'foo'
+  end
+end
+
+command :bar do |c|
+  c.syntax = 'foobar bar [options]'
+  c.description = 'Display bar with optional prefix and suffix'
+  c.option '--prefix STRING', String, 'Adds a prefix to bar'
+  c.option '--suffix STRING', String, 'Adds a suffix to bar'
+  c.action do |args, options|
+    options.default :prefix => '(', :suffix => ')'
+    say "#{options.prefix}bar#{options.suffix}"
+  end
+end
+```
+
+Example output:
+```
+$ foobar bar
+# => (bar)
+
+$ foobar bar --suffix '}' --prefix '{'
+# => {bar}
+```
+
+## HighLine
+
+As mentioned above, the highline gem is imported into the global scope. Here
+are some quick examples for how to utilize highline in your commands:
+
+```ruby
+# Ask for password masked with '*' character
+ask("Password:  ") { |q| q.echo = "*" }
+
+# Ask for password
+ask("Password:  ") { |q| q.echo = false }
+
+# Ask if the user agrees (yes or no)
+agree("Do something?")
+
+# Asks on a single line (note the space after ':')
+ask("Name: ")
+
+# Asks with new line after "Description:"
+ask("Description:")
+
+# Calls Date#parse to parse the date string passed
+ask("Birthday? ", Date)
+
+# Ensures Integer is within the range specified
+ask("Age? ", Integer) { |q| q.in = 0..105 }
+
+# Asks for a list of strings, converts to array
+ask("Fav colors?", Array)
+```
+
+## HighLine & Interaction Additions
+
+In addition to highline's fantastic choice of methods, commander adds the
+following methods to simplify common tasks:
+
+```ruby
+# Ask for password
+password
+
+# Ask for password with specific message and mask character
+password "Enter your password please:", '-'
+
+# Ask for CLASS, which may be any valid class responding to #parse. Date, Time, Array, etc
+names = ask_for_array 'Names: '
+bday = ask_for_date 'Birthday?: '
+
+# Simple progress bar (Commander::UI::ProgressBar)
+uris = %w[
+  http://vision-media.ca
+  http://google.com
+  http://yahoo.com
+]
+progress uris do |uri|
+  res = open uri
+  # Do something with response
+end
+
+# 'Log' action to stdout
+log "create", "path/to/file.rb"
+
+# Enable paging of output after this point
+enable_paging
+
+# Ask editor for input (EDITOR environment variable or whichever is available: TextMate, vim, vi, emacs, nano, pico)
+ask_editor
+
+# Ask editor, supplying initial text
+ask_editor 'previous data to update'
+
+# Ask editor, preferring a specific editor
+ask_editor 'previous data', 'vim'
+
+# Choose from an array of elements
+choice = choose("Favorite language?", :ruby, :perl, :js)
+
+# Alter IO for the duration of the block
+io new_input, new_output do
+  new_input_contents = $stdin.read
+  puts new_input_contents # outputs to new_output stream
+end
+# $stdin / $stdout reset back to original streams
+
+# Speech synthesis
+speak 'What is your favorite food? '
+food = ask 'favorite food?: '
+speak "Wow, I like #{food} too. We have so much in common."
+speak "I like #{food} as well!", "Victoria", 190
+
+# Execute arbitrary applescript
+applescript 'foo'
+
+# Converse with speech recognition server
+case converse 'What is the best food?', :cookies => 'Cookies', :unknown => 'Nothing'
+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'
+  when :yes
+    speak 'Well you see, cookies are just fantastic, they melt in your mouth.'
+  else
+    speak 'Ok then, bye.'
+  end
+end
+```
+
+## Growl Notifications
+
+Commander provides methods for displaying Growl notifications. To use these
+methods you need to install http://github.com/visionmedia/growl which utilizes
+the [growlnotify](http://growl.info/extras.php#growlnotify) executable. Note that
+growl is auto-imported by Commander when available, no need to require.
+
+```ruby
+# Display a generic Growl notification
+notify 'Something happened'
+
+# Display an 'info' status notification
+notify_info 'You have #{emails.length} new email(s)'
+
+# Display an 'ok' status notification
+notify_ok 'Gems updated'
+
+# Display a 'warning' status notification
+notify_warning '1 gem failed installation'
+
+# Display an 'error' status notification
+notify_error "Gem #{name} failed"
+```
+
+## Commander Goodies
+
+### Option Defaults
+
+The options struct passed to `#action` provides a `#default` method, allowing you
+to set defaults in a clean manner for options which have not been set.
+
+```ruby
+command :foo do |c|
+  c.option '--interval SECONDS', Integer, 'Interval in seconds'
+  c.option '--timeout SECONDS', Integer, 'Timeout in seconds'
+  c.action do |args, options|
+    options.default \
+      :interval => 2,
+      :timeout  => 60
+  end
+end
+```
+
+### Command Aliasing
+
+Aliases can be created using the `#alias_command` method like below:
+
+```ruby
+command :'install gem' do |c|
+  c.action { 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:
+
+```ruby
+command :'install gem' do |c|
+  c.syntax = 'install gem <name> [options]'
+  c.option '--dest DIR', String, 'Destination directory'
+  c.action { |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 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:
+
+```ruby
+default_command :update
+```
+
+```
+$ foo
+# => installing rubygems to some_path
+```
+
+Keeping in mind that commander searches for the longest possible match
+when considering a 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:
+
+```ruby
+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>
+
+### Global Options
+
+Although most switches will be at the command level, several are available by
+default at the global level, such as `--version`, and `--help`. Using
+`#global_option` you can add additional global options:
+
+```ruby
+global_option('-c', '--config FILE', 'Load config data for your commands to use') { |file| ... }
+```
+
+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 command level. This
+means that instead of the following:
+
+```ruby
+global_option('--verbose') { $verbose = true }
+...
+c.action do |args, options|
+  say 'foo' if $verbose
+...
+```
+
+You may:
+
+```ruby
+global_option '--verbose'
+...
+c.action do |args, options|
+  say 'foo' if options.verbose
+...
+```
+
+### Formatters
+
+Two core formatters are currently available, the default `Terminal` formatter
+as well as `TerminalCompact`. To utilize a different formatter simply use
+`:help_formatter` like below:
+
+```ruby
+program :help_formatter, Commander::HelpFormatter::TerminalCompact
+```
+
+Or utilize the help formatter aliases:
+
+```ruby
+program :help_formatter, :compact
+```
+
+This abstraction could be utilized to generate HTML documentation for your executable.
+
+### Tracing
+
+By default the `-t` and `--trace` global options are provided to allow users to get a backtrace to aid debugging.
+
+You can disable these options:
+
+```ruby
+never_trace!
+```
+
+Or make it always on:
+
+```ruby
+always_trace!
+```
+
+## Tips
+
+When adding a global or 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, however `-c` will only appear in the documentation
+when explicitly assigning it.
+
+```ruby
+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 http://github.com/visionmedia/terminal-table
+
+    +----------+-------+----+--------+-----------------------+
+    | Terminal | Table | Is | Wicked | Awesome               |
+    +----------+-------+----+--------+-----------------------+
+    |          |       |    |        | get it while its hot! |
+    +----------+-------+----+--------+-----------------------+
+
+## Running Specifications
+
+    $ rake spec
+
+OR
+
+    $ spec --color spec
+
+## Contrib
+
+Feel free to fork and request a pull, or submit a ticket
+http://github.com/visionmedia/commander/issues
+
+## License
+
+This project is available under the MIT license. See LICENSE for details.

data/commander.gemspec

@@ -7,6 +7,7 @@ Gem::Specification.new do |s|
   s.version     = Commander::VERSION
   s.authors     = ["TJ Holowaychuk", "Gabriel Gilder"]
   s.email       = ["ggilder@tractionco.com"]
+  s.license     = "MIT"
   s.homepage    = "http://visionmedia.github.com/commander"
   s.summary     = "The complete solution for Ruby command-line executables"
   s.description = "The complete solution for Ruby command-line executables. Commander bridges the gap between other terminal related libraries you know and love (OptionParser, HighLine), while providing many new features, and an elegant API."
@@ -23,4 +24,4 @@ Gem::Specification.new do |s|
   s.add_development_dependency("rspec", "~> 2")
   s.add_development_dependency("rake")
   s.add_development_dependency("simplecov")
-end
+end

data/lib/commander/delegates.rb

@@ -1,8 +1,9 @@
 
 module Commander
   module Delegates
-    %w( add_command command program run! global_option 
-        commands alias_command default_command ).each do |meth|
+    %w( add_command command program run! global_option
+        commands 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
@@ -10,4 +11,4 @@ module Commander
       END
     end
   end
-end
+end

data/lib/commander/runner.rb

@@ -48,7 +48,7 @@ module Commander
     # Run command parsing and execution process.
     
     def run!
-      trace = false
+      trace = @always_trace || false
       require_program :version, :description
       trap('INT') { abort program(:int_message) } if program(:int_message)
       trap('INT') { program(:int_block).call } if program(:int_block)
@@ -58,7 +58,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 }
+      global_option('-t', '--trace', 'Display backtrace when an error occurs') { trace = true } unless @never_trace
       parse_global_options
       remove_global_options options, @args
       unless trace
@@ -72,7 +72,11 @@ module Commander
           OptionParser::MissingArgument => e
           abort e.to_s
         rescue => e
-          abort "error: #{e}. Use --trace to view backtrace"
+          if @never_trace
+            abort "error: #{e}."
+          else
+            abort "error: #{e}. Use --trace to view backtrace"
+          end
         end
       else
         run_active_command
@@ -85,7 +89,23 @@ module Commander
     def version
       '%s %s' % [program(:name), program(:version)]
     end
-    
+
+    ##
+    # Enable tracing on all executions (bypasses --trace)
+
+    def always_trace!
+      @always_trace = true
+      @never_trace = false
+    end
+
+    ##
+    # Hide the trace option from the help menus and don't add it as a global option
+
+    def never_trace!
+      @never_trace = true
+      @always_trace = false
+    end
+
     ##
     # Assign program information.
     #

data/lib/commander/user_interaction.rb

@@ -284,7 +284,7 @@ module Commander
         $stdin.reopen read
         write.close; read.close
         Kernel.select [$stdin]
-        ENV['LESS'] = 'FSRX'
+        ENV['LESS'] = 'FSRX' unless ENV.key? 'LESS'
         pager = ENV['PAGER'] || 'less'
         exec pager rescue exec '/bin/sh', '-c', pager
       else

data/lib/commander/version.rb

@@ -1,3 +1,3 @@
 module Commander
-  VERSION = '4.1.5'
+  VERSION = '4.1.6'
 end

data/spec/command_spec.rb

@@ -50,21 +50,21 @@ describe Commander::Command do
       end
       
       it "calling the #call method by default when an object is called" do
-        object = mock 'Object'
+        object = double 'Object'
         object.should_receive(:call).once
         @command.when_called object
         @command.run 'foo'        
       end
       
       it "should allow #action as an alias to #when_called" do
-        object = mock 'Object'
+        object = double 'Object'
         object.should_receive(:call).once
         @command.action object
         @command.run 'foo'
       end
             
       it "calling an arbitrary method when an object is called" do
-        object = mock 'Object'
+        object = double 'Object'
         object.should_receive(:foo).once
         @command.when_called object, :foo
         @command.run 'foo'        

data/spec/runner_spec.rb

@@ -280,7 +280,7 @@ describe Commander do
         end.run!
       }.should raise_error(SystemExit, /error: cookies!. Use --trace/)
     end
-    
+
     it "should display callstack when using this switch" do
       lambda {
         new_command_runner 'foo', '--trace' do
@@ -289,7 +289,54 @@ describe Commander do
       }.should raise_error(RuntimeError)
     end
   end
-  
+
+  describe "#always_trace!" do
+    it "should enable tracing globally, regardless of whether --trace was passed or not" do
+      lambda {
+        new_command_runner 'foo' do
+          always_trace!
+          command(:foo) { |c| c.when_called { raise 'cookies!' } }
+        end.run!
+      }.should raise_error(RuntimeError)
+    end
+  end
+
+  describe "#never_trace!" do
+    it "should disable tracing globally, regardless of whether --trace was passed or not" do
+      lambda {
+        new_command_runner 'help', '--trace' do
+          never_trace!
+        end.run!
+      }.should raise_error(SystemExit, /invalid option: --trace/)
+    end
+
+    it "should not prompt to use --trace switch on errors" do
+      msg = nil
+      begin
+        new_command_runner 'foo' do
+          never_trace!
+          command(:foo) { |c| c.when_called { raise 'cookies!' } }
+        end.run!
+      rescue SystemExit => e
+        msg = e.message
+      end
+      msg.should match(/error: cookies!/)
+      msg.should_not match(/--trace/)
+    end
+  end
+
+  context "conflict between #always_trace! and #never_trace!" do
+    it "respects the last used command" do
+      lambda {
+        new_command_runner 'foo' do
+          never_trace!
+          always_trace!
+          command(:foo) { |c| c.when_called { raise 'cookies!' } }
+        end.run!
+      }.should raise_error(RuntimeError)
+    end
+  end
+
   describe "--version" do
     it "should output program version" do
       run('--version').should eq("test 1.2.3\n")

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: commander
 version: !ruby/object:Gem::Version
-  version: 4.1.5
-  prerelease: 
+  version: 4.1.6
 platform: ruby
 authors:
 - TJ Holowaychuk
@@ -10,12 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-11 00:00:00.000000000 Z
+date: 2014-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -23,7 +21,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -31,7 +28,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -39,7 +35,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -47,33 +42,29 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: The complete solution for Ruby command-line executables. Commander bridges
@@ -91,8 +82,9 @@ files:
 - DEVELOPMENT
 - Gemfile
 - History.rdoc
+- LICENSE
 - Manifest
-- README.rdoc
+- README.md
 - Rakefile
 - bin/commander
 - commander.gemspec
@@ -124,28 +116,28 @@ files:
 - spec/spec_helper.rb
 - spec/ui_spec.rb
 homepage: http://visionmedia.github.com/commander
-licenses: []
+licenses:
+- MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: commander
-rubygems_version: 1.8.22
+rubygems_version: 2.2.1
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: The complete solution for Ruby command-line executables
 test_files:
 - spec/command_spec.rb

data/README.rdoc

@@ -1,372 +0,0 @@
-{<img src="https://secure.travis-ci.org/ggilder/commander.png?branch=master" alt="Build Status" />}[http://travis-ci.org/ggilder/commander]
-
-= Commander
-
-The complete solution for Ruby command-line executables. 
-Commander bridges the gap between other terminal related libraries
-you know and love (OptionParser, HighLine), while providing many new
-features, and an elegant API.
-
-== Features
-
-* Easier than baking cookies
-* Parses options using OptionParser
-* Auto-populates struct with options ( no more { |v| options[:recursive] = v } )
-* Auto-generates help documentation via pluggable help formatters
-* Optional default command when none is present
-* Global / Command level options
-* Packaged with two help formatters (Terminal, TerminalCompact)
-* Imports the highline gem for interacting with the terminal
-* Adds additional user interaction functionality
-* Highly customizable progress bar with intuitive, simple usage
-* Multi-word command name support such as 'drupal module install MOD', rather than 'drupal module_install MOD'
-* Sexy paging for long bodies of text
-* Support for MacOS text-to-speech
-* Command aliasing (very powerful, as both switches and arguments can be used)
-* Growl notification support for MacOS
-* Use the 'commander' executable to initialize a commander driven program
-
-== Installation
-
-  $ gem install commander
-
-== Quick Start
-
-To generate a quick template for a commander app, run:
-
-  $ commander init yourfile.rb
-
-== Example
-
-For more option examples view the Commander::Command#option method. Also
-an important feature to note is that action may be a class to instantiate,
-as well as an object, specifying a method to call, so view the RDoc for more information.
-
-   require 'rubygems'
-   require 'commander/import'
-
-   # :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.'
-
-   command :foo do |c|
-     c.syntax = 'foobar foo'
-     c.description = 'Displays foo'
-     c.action do |args, options|
-       say 'foo'
-     end
-   end
-
-   command :bar do |c|
-     c.syntax = 'foobar bar [options]'
-     c.description = 'Display bar with optional prefix and suffix'
-     c.option '--prefix STRING', String, 'Adds a prefix to bar'
-     c.option '--suffix STRING', String, 'Adds a suffix to bar'
-     c.action do |args, options|
-       options.default :prefix => '(', :suffix => ')'
-       say "#{options.prefix}bar#{options.suffix}"
-     end
-   end
-
-   $ foobar bar
-   # => (bar)
-
-   $ foobar bar --suffix '}' --prefix '{'
-   # => {bar}
-
-== HighLine
-
-As mentioned above the highline gem is imported into 'global scope', below
-are some quick examples for how to utilize highline in your command(s):
-   
-   # Ask for password masked with '*' character
-   ask("Password:  ") { |q| q.echo = "*" }
-  
-   # Ask for password 
-   ask("Password:  ") { |q| q.echo = false }
-
-   # Ask if the user agrees (yes or no)
-   agree("Do something?")
-
-   # Asks on a single line (note the space after ':')
-   ask("Name: ")
-
-   # Asks with new line after "Description:"
-   ask("Description:")
-
-   # Calls Date#parse to parse the date string passed
-   ask("Birthday? ", Date)
-
-   # Ensures Integer is within the range specified
-   ask("Age? ", Integer) { |q| q.in = 0..105 }
-
-   # Asks for a list of strings, converts to array
-   ask("Fav colors?", Array)
-
-== HighLine & Interaction Additions
-
-In addition to highline's fantastic choice of methods, commander adds the 
-following methods to simplify common tasks:
-
-   # Ask for password 
-   password
-   
-   # Ask for password with specific message and mask character
-   password "Enter your password please:", '-'
-
-   # Ask for CLASS, which may be any valid class responding to #parse. Date, Time, Array, etc
-   names = ask_for_array 'Names: '
-   bday = ask_for_date 'Birthday?: '
-
-   # Simple progress bar (Commander::UI::ProgressBar)
-   uris = %w[ 
-     http://vision-media.ca 
-     http://google.com 
-     http://yahoo.com
-     ]
-   progress uris do |uri|
-     res = open uri
-     # Do something with response
-   end
-
-  # 'Log' action to stdout
-  log "create", "path/to/file.rb"
-
-  # Enable paging of output after this point
-  enable_paging
-
-  # Ask editor for input (EDITOR environment variable or whichever is available: TextMate, vim, vi, emacs, nano, pico)
-  ask_editor
-
-  # Ask editor, supplying initial text
-  ask_editor 'previous data to update'
-  
-  # Ask editor, preferring a specific editor
-  ask_editor 'previous data', 'vim'
-
-  # Choose from an array of elements
-  choice = choose("Favorite language?", :ruby, :perl, :js)
-
-  # Alter IO for the duration of the block
-  io new_input, new_output do
-    new_input_contents = $stdin.read
-    puts new_input_contents # outputs to new_output stream
-  end
-  # $stdin / $stdout reset back to original streams
-
-  # Speech synthesis 
-  speak 'What is your favorite food? '
-  food = ask 'favorite food?: '
-  speak "Wow, I like #{food} too. We have so much in common." 
-  speak "I like #{food} as well!", "Victoria", 190
-
-  # Execute arbitrary applescript
-  applescript 'foo'
-
-  # Converse with speech recognition server
-  case converse 'What is the best food?', :cookies => 'Cookies', :unknown => 'Nothing'
-  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'
-    when :yes
-      speak 'Well you see, cookies are just fantastic, they melt in your mouth.'
-    else
-      speak 'Ok then, bye.'
-    end
-  end
-
-== Growl Notifications
-
-Commander provides methods for displaying Growl notifications. To use these
-methods you need to install http://github.com/visionmedia/growl which utilizes
-the growlnotify[http://growl.info/extras.php#growlnotify] executable. Note that
-growl is auto-imported by Commander when available, no need to require.
-
-  # Display a generic Growl notification
-  notify 'Something happened'
-
-  # Display an 'info' status notification
-  notify_info 'You have #{emails.length} new email(s)'
-
-  # Display an 'ok' status notification
-  notify_ok 'Gems updated'
-
-  # Display a 'warning' status notification
-  notify_warning '1 gem failed installation'
-
-  # Display an 'error' status notification
-  notify_error "Gem #{name} failed"
-
-== Commander Goodies
-
-=== Option Defaults
-
-The options struct passed to #action provides a #default method, allowing you
-to set defaults in a clean manner for 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.action 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.action { 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.action { |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 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 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>
-
-=== Global Options
-
-Although most switches will be at the command level, several are available
-by default at the global level, such as --version, and --help. Using #global_option
-you can add additional global options:
-
-  global_option('-c', '--config FILE', 'Load config data for your commands to use') { |file| ... }
-
-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 command level. This
-means that instead of the following:
-
-  global_option('--verbose') { $verbose = true }
-  ...
-  c.action do |args, options|
-    say 'foo' if $verbose
-  ...
-
-You may:
-
-  global_option '--verbose'
-  ...
-  c.action do |args, options|
-    say 'foo' if options.verbose
-  ...
-
-=== Formatters
-
-Two core formatters are currently available, the default Terminal formatter as well
-as TerminalCompact. To utilize a different formatter simply use :help_formatter like below:
-
-  program :help_formatter, Commander::HelpFormatter::TerminalCompact
-
-Or utilize the help formatter aliases:
-
-  program :help_formatter, :compact
-
-This abstraction could be utilized to generate HTML documentation for your executable.
-
-== Tips
-
-When adding a global or 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, however '-c' will only appear in the documentation when explicitly
-assigning it.
-
-  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
-http://github.com/visionmedia/terminal-table
-
-   +----------+-------+----+--------+-----------------------+
-   | Terminal | Table | Is | Wicked | Awesome               |
-   +----------+-------+----+--------+-----------------------+
-   |          |       |    |        | get it while its hot! |
-   +----------+-------+----+--------+-----------------------+
-
-== Running Specifications
-
-  $ rake spec
-  
-OR 
-
-  $ spec --color spec
-
-== Contrib
-
-Feel free to fork and request a pull, or submit a ticket
-http://github.com/visionmedia/commander/issues
-
-== License
-
-(The MIT License)
-
-Copyright (c) 2008-2009 TJ Holowaychuk <tj@vision-media.ca>
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.