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, all packed in one simple, 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 sub-command when none is present
Global / Sub-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
Growl notification support for MacOS
Sub-command aliasing (very powerful, as both switches and arguments can be used)
Use the 'commander' executable to initialize a commander driven program

Example


      require 'rubygems'
      require 'commander'
      
      # :name is optional, otherwise uses the basename of this executable
      program :name, 'Foo Bar'
      program :version, '1.0.0'
      program :description, 'Stupid command that prints foo or bar.'
      
      command :foodo|c|
        c.syntax = 'foobar foo'
        c.description = 'Displays foo'
        c.when_calleddo|args, options|
          say 'foo'
       endend
      
      command :bardo|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_calleddo|args, options|
          options.default :prefix => '(', :suffix => ')'
          say "#{options.prefix}bar#{options.suffix}"
       endend
      
      $ foobar bar
      # => (bar)
      
      $ foobar bar --suffix '{' --prefix '}'
      # => {bar}

User Interaction


      # 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)
      
      # 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?: '
      
      # 'Log' action to stdout
      log "create", "path/to/file.rb"
      
      # Simple progress bar (Commander::UI::ProgressBar)
      uris = %w( vision-media.ca google.com yahoo.com )
      progress urisdo|uri|
       res = open "http://#{uri}"
       # Do something with response
      end
      
      # 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"

API Documentation

Click to view the most recent SDoc generated. For a more up-to-date look at what the Commander gem has to offer view the README.