commander 3.3.0

data/History.rdoc

@@ -0,0 +1,275 @@
+
+=== 3.3.0 / 2009-05-12
+
+* Added #choose
+* Added aliasing for help formatters [#24]
+* Added UI.replace_tokens
+* Added #converse
+* Added #speak
+* Added #applescript
+* Added #reset_io
+* Added #io
+* Removed String#tokenize
+* Removed #delete_switches
+
+=== 3.2.9 / 2009-04-09
+
+* Fixed bug in removal of global options
+
+=== 3.2.8 / 2009-04-09
+
+* Added auto-loading support of visionmedia-growl convenience methods when the gem is available
+* Changed; growl related methods are now part of visionmedia-growl
+* Fixed doc typos
+
+=== 3.2.7 / 2009-04-08
+
+* Added #notify, #notify_ok, #notify_warning, #notify_info and #notify_error
+  These methods all utilize the MacOS growlnotify binary, very cool stuff check it out!
+
+=== 3.2.6 / 2009-04-08
+
+* Added Commander::UI::AskForClass
+* Added support to #remove_global_options for options with arguments
+* Removed .re directory used for visionmedia-release
+* Fixed bug preventing --trace from working
+
+=== 3.2.5 / 2009-04-02
+
+* Added #ask_editor
+
+=== 3.2.4 / 2009-04-02
+
+* Added #enable_paging [#9]
+
+=== 3.2.3 / 2009-04-01
+
+* Added new pager using less [#9]
+
+=== 3.2.2 / 2009-04-01
+
+* Github's gem builder timed out ? ...
+
+=== 3.2.1 / 2009-04-01
+
+* Added Commander::HelpFormatter::TerminalCompact
+* Fix; updated gemspec / manifest removing test/* causing issue [#26]
+
+=== 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 commands [#7]
+* Added #require_valid_command 
+* Renamed #call_active_command to #run_active_command
+* Changed; using same option format as 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 #separate_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]
+* Fixed INT trapping issue (purely cosmetic) [#14]
+* Removed todo, use lighthouse now for commander at:
+  http://visionmedia.lighthouseapp.com/projects/27643-commander/overview
+
+=== 3.1.7 / 2009-03-24
+
+* Added global --trace option
+
+=== 3.1.6 / 2009-03-22
+
+* Changed Options struct to always use symbols
+
+=== 3.1.5 / 2009-03-22
+
+* Added Options#__hash__ to access the internal hash table
+* Refactored Options struct to function much like an OpenStruct
+* Updated commander exec init help description
+
+=== 3.1.4 / 2009-03-20
+
+* Gemspec typo
+
+=== 3.1.3 / 2009-03-20
+
+* Added #remove_global_options
+* Added core global option descriptions
+* Added display of global options
+* Removed small core switches (-v, -h) because they are implicitly set
+* Fixed issue with option switchs failing when named as common methods like --send, or --password
+* Fixed bug causing InvalidOption error when global options do not abort the process.
+  This was due to these options remaining in the arguments array, in turn being parsed
+  by the command's option parser, issuing the error. This is fixed by #remove_global_options.
+
+=== 3.1.2 / 2009-03-16
+
+* Added support for global options via #global_option
+* Added #call_active_command and #say to clean things up internally
+* Misc refactoring
+
+=== 3.1.1 / 2009-03-13
+
+* Fixed some terminal formatter spacing issues
+
+=== 3.1.0 / 2009-03-13
+
+* Added Command#inspect
+* Added displaying of aliases in global help
+* Added support for alias args
+* Added #default_command
+
+=== 3.0.3 / 2009-03-12
+
+* Added #alias_command
+
+=== 3.0.2 / 2009-03-12
+
+* Added terminal formatter specs
+* Fixed bug preventing command names passed to help from working
+
+=== 3.0.1 / 2009-03-12
+
+* Fixed bug in #command_name_from_args preventing the left-most match for a command name to be used
+* Fixed bug in Command#example preventing the formatter from outputting them correctly
+
+=== 3.0.0 / 2009-03-12
+
+* Added sub command help support when using the --help switch
+* #delete_switches is now mutative
+* Added #valid_command_names_from
+* #when_called now raises argument error when neither a block, object, or class is passed
+* Added options#default method and specs
+* Added support for multi-word list parsing in Array#parse
+* Added summary to commander template
+* Added optional block param for #new_command_runner spec helper
+* Added .re (metadata for visionmedia-release gem)
+* Moved delgation of Kernel methods to Object
+* Refactored multi-word command name specs
+* Refactored Object#method_missing; using call chain to implement
+* Refactored all specs
+* Change #color calls in formatters to $terminal#color for now
+* Using highlines $terminal.output for IO stream with the progressbar
+* Replaced #ensure_program_key_set with #require_program, taking an array of keys
+* Renamed #args_without_command to #args_without_command_name
+* Renamed #populate_options_to_when_called to #option_proc
+* Renamed #sym_from_switch to #switch_to_sym
+* Removed #get_command, use #command without supplying a block
+* Removed Command#inspect
+* Removed command description aliases of short_description, long_description. Use description / summary
+* Removed VerboseFileUtils
+* Removed String#camelcase as its not really needed (was only used in commander's executable for creating templates)
+* Removed commander/import for now
+* Removed LOG_FORMAT
+* Removed Kernel ext which only had #color
+
+=== 2.5.7 / 2009-03-11
+
+* Fixed paren warnings in import spec
+* Fixed Kernel#method_missing to preserve its original behavior (Raise errors for missing methods or variables)
+
+=== 2.5.6 / 2009-03-06
+
+* Replaced Commander::VERSION::STRING with Commander::VERSION (for release gem)
+* Refactored progress bar
+* Fixed String#tokenize
+
+=== 2.4.5 / 2009-03-03
+
+* Fixed bug which was not allowing switch arguments which are strings
+  such as --eval 'something here'
+
+=== 2.4.4 / 2009-01-15
+
+* Fixed bug which was not allowing multi-word commands to view help
+
+=== 2.4.3 / 2009-01-15
+
+* Fixed bug in command_name_from_args, preventing multi-word commands
+
+=== 2.4.2 / 2009-01-12
+
+* Github! build me!
+
+=== 2.4.1 / 2009-01-11
+
+* Added ask_for_CLASS, which may be any class name such as ask_for_date, ask_for_array, etc
+* Changed doc to *.rdoc for pretty markup on github
+
+=== 2.3.0 / 2008-12-16
+
+* Removed input, output in favour of HighLines $terminal
+* Autoloading terminal formatter since it may not always be used
+* Added wrapping of text with 10 padding, defaults to 80
+* Added friendly interruption message by default, overridable with trap or int_message
+* Fixed description now showing as summary when no summary is available
+
+=== 2.2.1 / 2008-12-09
+
+* Fixed typo in String#tokenize, preventing progress bar from working
+* Fixed some small formatting issues with help output
+
+=== 2.2.0 / 2008-12-09
+
+* Additional documentation
+* Added support for arbitrary help 'blocks' using program :help, 'Your block', 'Your blocks contents'
+* Added support for description, summary, short_description, and large_description, which are displaying conditionally within help docs
+* Allowing uncaught exceptions to reach stderr, for debugging purposes
+
+=== 2.1.1 / 2008-12-01
+
+* Changed #password, now requires that the user must enter a non-empty? value
+
+=== 2.1.0 / 2008-12-01
+
+* Added progress bar
+* Added auto-inclusion of FileUtils module
+* Added stdout logging method
+* Fixed issue with options placed before command
+
+=== 2.0.1 / 2008-11-24
+
+* Fixed new line after command options
+* Fixed padding for command list
+
+=== 2.0.0 / 2008-11-24
+
+* Rewrite of entire gem
+* Added auto-parsing and struct population of options
+* Added better documentation
+
+=== 1.2.2 / 2008-11-06
+
+* Forgot to add array.rb
+
+=== 1.2.0 / 2008-11-06
+
+* Added paging ability (similar to 'less')
+* Added coloring to default help generator
+
+=== 1.1.0 / 2008-11-06
+
+* Added dependency for Highline gem, which replaces Commander's user interaction lib
+
+=== 1.0.4 / 2008-11-04
+
+* Added support for --help and --version flags
+
+=== 1.0.3 / 2008-11-01
+
+* Typo causing the gem to fail build on github
+
+=== 1.0.2 / 2008-11-01
+
+* Added gemspec for github
+
+=== 1.0.1 / 2008-10-31
+
+* Added shebang line to commander init
+* Added require 'rubygems' 
+
+=== 1.0.0 / 2008-10-31
+
+* Initial release

data/Manifest

@@ -0,0 +1,36 @@
+History.rdoc
+Manifest
+README.rdoc
+Rakefile
+bin/commander
+commander.gemspec
+lib/commander.rb
+lib/commander/blank.rb
+lib/commander/command.rb
+lib/commander/core_ext.rb
+lib/commander/core_ext/array.rb
+lib/commander/core_ext/object.rb
+lib/commander/delegates.rb
+lib/commander/help_formatters.rb
+lib/commander/help_formatters/base.rb
+lib/commander/help_formatters/terminal.rb
+lib/commander/help_formatters/terminal/command_help.erb
+lib/commander/help_formatters/terminal/help.erb
+lib/commander/help_formatters/terminal_compact.rb
+lib/commander/help_formatters/terminal_compact/command_help.erb
+lib/commander/help_formatters/terminal_compact/help.erb
+lib/commander/import.rb
+lib/commander/runner.rb
+lib/commander/user_interaction.rb
+lib/commander/version.rb
+spec/command_spec.rb
+spec/core_ext/array_spec.rb
+spec/core_ext/object_spec.rb
+spec/help_formatters/base_spec.rb
+spec/help_formatters/terminal_spec.rb
+spec/runner_spec.rb
+spec/spec_helper.rb
+spec/ui_spec.rb
+tasks/docs.rake
+tasks/gemspec.rake
+tasks/spec.rake

data/README.rdoc

@@ -0,0 +1,357 @@
+
+= 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 intuative, 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
+
+Due to issues with Github and supporting previous releases, until 4.0 you must:
+  sudo gem install visionmedia-commander --version 3.2.9
+
+== Example
+
+For more option examples view the Commander::Command#option method. Also
+an important feature to note is that when_called 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.when_called 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.when_called 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 we will continue to
+simplify common tasks using the following methods:
+
+   # 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 or TextMate by default)
+  ask_editor
+
+  # Ask editor, supplying initial text
+  ask_editor 'previous data to update'
+
+  # 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"
+
+  # 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 alike." 
+
+  # 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
+
+== Commander Goodies
+
+=== Option Defaults
+
+The options struct passed to #when_called provides a #default method, allowing you
+to set defaults in a clean manor to options which have not been set.
+
+  command :foo do |c|
+    c.option '--interval SECONDS', Integer, 'Interval in seconds'
+    c.option '--timeout SECONDS', Integer, 'Timeout in seconds'
+    c.when_called do |args, options|
+      options.default \
+        :interval => 2,
+        :timeout  => 60
+    end
+  end
+
+=== Command Aliasing
+
+Aliases can be created using the #alias_command method like below:
+
+  command :'install gem' do |c|
+    c.when_called { puts 'foo' }
+  end
+  alias_command :'gem install', :'install gem'
+
+Or more complicated aliases can be made, passing any arguments
+as if it was invoked via the command line:
+
+  command :'install gem' do |c|
+    c.syntax = 'install gem <name> [options]'
+    c.option '--dest DIR', String, 'Destination directory'
+    c.when_called { |args, options| puts "installing #{args.first} to #{options.dest}" }
+  end
+  alias_command :update, :'install gem', 'rubygems', '--dest', 'some_path'
+
+  $ foo update
+  # => installing rubygems to some_path
+
+=== Command Defaults
+
+Although working with a 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.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
+  ...
+
+=== 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! |
+   +----------+-------+----+--------+-----------------------+
+
+== Growl Notifications
+
+To utilize the #notify and #notify_STATUS methods you need to install
+http://github.com/visionmedia/growl which utilizes the 'growlnotify' executable.
+Note that growl is auto-imported by Commander when available, no need to require.
+
+== Contrib
+
+Feel free to fork and request a pull, or submit a ticket
+http://visionmedia.lighthouseapp.com/projects/27643-commander
+
+== Known Issues
+ 
+* ask_editor has been tested with TextMate only
+
+== 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.