cmd 0.7.0

data/Rakefile

@@ -0,0 +1,141 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/contrib/sshpublisher'
+
+require 'date'
+require 'rbconfig'
+
+PKG_NAME         = 'cmd'
+PKG_VERSION      = '0.7.0'
+PKG_FILE_NAME    = "#{PKG_NAME}-#{PKG_VERSION}"
+PKG_DESTINATION  = "../#{PKG_NAME}"
+PKG_AUTHOR       = 'Marcel Molina Jr.' 
+PKG_AUTHOR_EMAIL = 'marcel@vernix.org'
+PKG_HOMEPAGE     = 'http://cmd.rubyforge.org'
+PKG_REMOTE_PATH  = "www/code/#{PKG_NAME}"
+PKG_REMOTE_HOST  = 'vernix.org' 
+PKG_REMOTE_USER  = 'marcel'
+PKG_ARCHIVES_DIR = 'download'
+PKG_DOC_DIR      = 'rdoc'
+
+BASE_DIRS   = %w( lib example test )
+
+desc "Default Task"
+task :default => [ :test ]
+
+desc "Run unit tests"
+task :test do
+  # Rake's TestTask seems to mess with my IO streams so I'm doing this the lame
+  # way.
+  system 'ruby test/tc_*.rb'
+end
+
+# Generate documentation ------------------------------------------------------
+
+RDOC_FILES = [
+  'AUTHORS',
+  'CHANGELOG',  
+  'INSTALL',  
+  'README',  
+  'THANKS',  
+  'TODO', 
+  'lib/cmd.rb'
+] 
+
+desc "Generate documentation"
+Rake::RDocTask.new do |rd|
+  rd.main = 'README'
+  rd.title = PKG_NAME
+  rd.rdoc_dir = PKG_DOC_DIR
+  rd.rdoc_files.include(RDOC_FILES)
+  rd.options << '--inline-source'
+  rd.options << '--line-numbers'
+end
+
+
+# Generate GEM ----------------------------------------------------------------
+
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'lib/**', 
+  'test/**', 
+  'example/**'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name    = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "A generic class to build line-oriented command interpreters."
+  s.description = s.summary 
+
+  s.files = PKG_FILES.to_a.delete_if {|f| f.include?('.svn')}
+  s.require_path = 'lib'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = RDOC_FILES 
+  s.rdoc_options << '--main'  << 'README' << 
+                    '--title' << PKG_NAME << 
+                    '--line-numbers'      <<
+                    '--inline-source'
+
+  s.test_files = Dir.glob('test/tc_*.rb')
+
+  s.author   = PKG_AUTHOR 
+  s.email    = PKG_AUTHOR_EMAIL 
+  s.homepage = PKG_HOMEPAGE 
+  s.rubyforge_project = PKG_NAME
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip     = true
+  pkg.need_tar_gz  = true
+  pkg.need_tar_bz2 = true
+  pkg.package_dir  = PKG_ARCHIVES_DIR 
+end
+
+# Support Tasks ---------------------------------------------------------------
+
+def egrep(pattern)
+  Dir['**/*.rb'].each do |fn|
+    count = 0
+    open(fn) do |f|
+      while line = f.gets
+  count += 1
+  if line =~ pattern
+    puts "#{fn}:#{count}:#{line}"
+  end
+      end
+    end
+  end
+end
+
+desc "Look for TODO and FIXME tags in the code"
+task :todo do
+  egrep /#.*(FIXME|TODO|XXX)/
+end
+
+# Push Release ----------------------------------------------------------------
+
+desc "Push current archives to release server"
+task :push_package => [ :package ] do 
+  Rake::SshDirPublisher.new(
+    "#{PKG_REMOTE_USER}@#{PKG_REMOTE_HOST}",
+    "#{PKG_REMOTE_PATH}/#{PKG_ARCHIVES_DIR}",
+    PKG_ARCHIVES_DIR
+  ).upload
+end
+
+desc "Push current rdoc to release server"
+task :push_rdoc => [ :rdoc ] do
+  Rake::SshDirPublisher.new(
+    "#{PKG_REMOTE_USER}@#{PKG_REMOTE_HOST}",
+    "#{PKG_REMOTE_PATH}/#{PKG_DOC_DIR}",
+    PKG_DOC_DIR
+  ).upload
+end
+
+desc "Push current version up to release server"
+task :push_release => [ :push_rdoc, :push_package ] 

data/THANKS

@@ -0,0 +1,12 @@
+Sam Stephenson (http://conio.net/) was gracious enough to take a close look at
+cmd.rb's API early on. If you find yourself pleased or impressed with a feature
+of cmd.rb it's most likely something that was his idea. He also supplied me
+with an excellent example of cmd.rb's usage with his calc.rb that you can find
+in the example directory.
+
+Jamis Buck (http://jamis.jamisbuck.org/) who enriched Cmd's domain language
+with his suggestion for a 'handle' macro.
+
+Mikael Brockman (http://www.phubuh.org/) 
+
+Scott Barron (http://scott.elitists.net/)

data/TODO

@@ -0,0 +1,124 @@
+= Cmd Todo list
+
+Send suggestions for this list to marcel@vernix.org.
+
+== Todo list
+
+* Writing a complete_(command name) is enough to have the completion results be
+  displayed, but not enough to actually complete. In order to complete as well
+  there must be additional logic such as what complete_grep does. So right now
+  to do a completion method for a command you really have to do something like:
+
+    def complete_find(line)
+      completion_grep(@numbers.keys.sort, line)
+    end
+
+  Where the first argument is the collection to complete against and line is
+  what is passed in. This API should be simplified and it should have a better
+  name than completion_grep. Also the subclass has to remember that the
+  complete method has to take an argument. It would be better to not have them
+  have to do that. Perhaps introduce (another macro) class method that just
+  takes a collection, or a method reference that returns a collection that then
+  is operated on internally. 
+
+    complete :find, :with => :phonebook_names
+
+    # ...
+
+    def phonebook_names
+      @nubers.keys.sort
+    end
+
+  or
+
+    complete :some_command, :some_other_command, :with => { # Some Proc }
+
+* Add a Documentation class (or some such) which collects list of subcommands
+  and shortcuts so that the default help command can be more helpful and
+  complete.
+
+* Make it so that doc allows one to document arguments for commands that take
+  arguments so that rather than just:
+
+    add  -- Add a number into the phonebook.
+
+  You'd get something more like
+
+    add name number [phone type]  -- Add a number into the phonebook.
+
+* Have doc work like the 'desc' method for rake where it preceeds the task to
+  which it describes rather than specifying the task excplicitly as args.
+
+* Get rid of do_ method naming convention and define a 'command' method to
+  replace the naming convention.
+
+    def do_subtract
+      # ...
+    end
+
+  would become
+
+    command subtract do
+      # ...
+    end
+
+  How to deal with method arguments? Perhaps doing:
+
+    command subtract do |arg|
+      # ...
+    end
+
+  Sam suggests command being the death of the doc macro:
+
+    command :add, 'Add an entry' do |name, number|
+      @numbers[name.strip] = number
+    end
+
+  I think that's pretty nice.
+
+* Take another shot at having more objects (e.g. Command, Subcommand,
+  Documentation, etc)
+
+* Provide a means of documenting subcommands
+
+* When passing arguments to do_ methods do a better job of just checking if the
+  method takes arguments and then passing them all in with *args. Do all the
+  arity checks and then pass it as many args as the do_ method takes. Raise
+  some client catchable exception if nothing can be done with the passed args
+  to satisfy the method signature of the do_ method. Basically make the do_
+  command methods as much like ruby methods as possible so that the arguments
+  are handed to the command so that it can access them directly rather than
+  having to fish them out.
+
+  So get rid of tokenize_args...it's a busted idea. Instead have
+
+    e.g.
+
+      def do_add(name, number)
+        # ...
+      end
+
+  If the method that takes care of passing a command the appropriate number of
+  arguments can't do its job based on the input given then the default could be
+  something like announcing that there was an argument error (perhaps
+  formalized using handle) and then the help for that command should be
+  displayed.
+
+* Implement rudimentary interaction with the underlying shell using the
+  standard | pipe notation and > redirection notation so that someone could do:
+
+    prompt> command | sort
+    
+    or
+
+    prompt> command > commands-output.txt
+
+    and maybe
+
+    prompt> command | sort > sorted-command-output.txt
+
+  Though I don't really want to write anything too fancy or complicated. I
+  think the most basic functionality of pipes and redirects would be useful
+  though.
+
+* Perhaps allow subclasses to override the tab as the completion key.

data/example/calc.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'cmd'
+rescue LoadError
+  require File.dirname(__FILE__) + '/../lib/cmd'
+end
+require 'mathn'
+
+class StackUnderflowError < StandardError; end
+
+class Calculator < Cmd
+  VALUE = /^-?\d+(\/\d+)?$/
+
+  prompt_with     :prompt_command
+
+  shortcut  '.',  :pop
+  shortcut  'x',  :swap
+
+  shortcut  '+',  :add
+  shortcut  '*',  :multiply
+  shortcut  '-',  :subtract
+  shortcut  '/',  :divide
+
+  doc :clear,     "Clears the contents of the stack"
+  doc :dup,       "Pushes the value of the stack's top item"
+  doc :pop,       "Removes the top item from the stack and displays its value"
+  doc :push,      "Pushes the values passed onto the stack"
+  doc :swap,      "Swaps the order of the stack's top 2 items"
+
+  doc :add,       "Pops 2 items, adds them, and pushes the result"
+  doc :multiply,  "Pops 2 items, multiplies them, and pushes the result"
+  doc :subtract,  "Pops 2 items, subtracts the topmost, and pushes the result"
+  doc :divide,    "Pops 2 items, divides by the topmost, and pushes the result"
+
+  handle StackUnderflowError, 'Stack underflow'
+  handle ZeroDivisionError,   'Division by zero'
+
+  def do_clear;       setup                     end
+  def do_dup;         push peek                 end
+  def do_pop;         print_value pop           end
+  def do_push(values) push *values              end
+  def do_swap;        swap                      end
+
+  def do_add;         push pop + pop            end
+  def do_multiply;    push pop * pop            end
+  def do_subtract;    swap; push pop - pop      end
+  def do_divide;      swap; push pop / pop      end
+
+protected
+
+  def setup;          @stack = []               end
+  def peek;           @stack.last or underflow  end
+  def pop;            @stack.pop  or underflow  end
+  def push(*values)   @stack += values          end
+  def swap;           top = pop; push top, pop  end
+  def underflow;      raise StackUnderflowError end
+
+  def print_value(value)
+    puts "=> #{value.inspect}"
+  end
+
+  def contents
+    return "(empty)" if @stack.empty?
+    @stack.inspect
+  end
+  
+  def command_missing(command, values)
+    return super unless command =~ VALUE
+    do_push values.unshift(eval(command))
+  end
+
+  def prompt_command
+    "#{self.class.name}#{contents}> "
+  end
+
+  def tokenize_args(args)
+    return args unless current_command =~ VALUE or current_command == "push"
+    args.to_s.split(/ +/).inject([]) do |a, v|
+      raise ArgumentError, "bad integer value #{v}" unless v =~ VALUE
+      a << eval(v)
+    end
+  end
+end
+
+Calculator.run

data/example/phonebook.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'cmd'
+rescue LoadError
+  require File.dirname(__FILE__) + '/../lib/cmd'
+end
+require 'yaml'
+
+class PhoneBook < Cmd
+  PHONEBOOK_FILE = File.expand_path('~/.phonebook')
+
+  doc :add, 'Add an entry (ex: add Sam, 312-555-1212)'
+  def do_add(args)
+    name, number = args.to_s.split(/, +/)
+    @numbers[name.strip] = number
+  end
+  shortcut '+', :add
+  
+  doc :find, 'Look up an entry (ex: find Sam)'
+  def do_find(name)
+    name.to_s.strip!
+    if @numbers[name]
+      print_name_and_number(name, @numbers[name])
+    else
+      puts "#{name} isn't in the phone book"
+    end
+  end
+
+  doc :list, 'List all entries'
+  def do_list
+    @numbers.sort.each do |name, number|
+      print_name_and_number(name, number)
+    end
+  end
+
+  doc :delete, 'Remove an entry'
+  def do_delete(name)
+    @numbers.delete(name) || write("No entry for '#{name}'")
+  end
+  
+protected
+
+  def setup
+    @numbers = get_store || {}
+  end
+
+  def complete_find(line)
+    completion_grep(@numbers.keys.sort, line)
+  end
+  
+  def print_name_and_number(*args)
+    puts "%-25s %s" % args
+  end
+
+  def postloop
+    File.open(PHONEBOOK_FILE, 'w') {|store| store.write YAML.dump(@numbers)}
+  end
+
+  def get_store
+    File.open(PHONEBOOK_FILE) {|store| YAML.load(store)} rescue nil 
+  end
+
+  def command_missing(command, args)
+    do_find(command)
+  end
+end
+
+PhoneBook.run

data/lib/cmd.rb

@@ -0,0 +1,557 @@
+READLINE_SUPPORTED = begin require 'readline' or true rescue LoadError end
+require 'abbrev'
+
+# A simple framework for writing line-oriented command interpreters, based 
+# heavily on Python's {cmd.py}[http://docs.python.org/lib/module-cmd.html].
+# 
+# These are often useful for test harnesses, administrative tools, and
+# prototypes that will later be wrapped in a more sophisticated interface.
+# 
+# A Cmd instance or subclass instance is a line-oriented interpreter
+# framework.  There is no good reason to instantiate Cmd itself; rather,
+# it's useful as a superclass of an interpreter class you define yourself
+# in order to inherit Cmd's methods and encapsulate action methods.
+class Cmd
+
+  module ClassMethods
+    @@docs      = {}
+    @@shortcuts = {}
+    @@handlers  = {}
+    @@prompt    = '> '
+    @@shortcut_table = {}
+    
+    # Set documentation for a command
+    #
+    #   doc :help, 'Display this help.'
+    #   def do_help
+    #     # etc
+    #   end
+    def doc(command, docstring = nil)
+      docstring = docstring ? docstring : yield
+      @@docs[command.to_s] = docstring
+    end
+
+    def docs
+      @@docs
+    end
+    module_function :docs
+
+    # Set what to do in the event that the given exception is raised.
+    #
+    #   handle StackOverflowError, :handle_stack_overflow
+    #
+    def handle(exception, handler)
+      @@handlers[exception.to_s] = handler
+    end
+    module_function :handle
+
+    # Sets what the prompt is. Accepts a String, a block or a Symbol.
+    #
+    # == Block 
+    #
+    #   prompt_with { Time.now }
+    #
+    # == Symbol
+    #
+    #   prompt_with :set_prompt
+    #
+    # == String
+    #
+    #   prompt_with "#{self.class.name}> "
+    #
+    def prompt_with(*p, &block)
+      @@prompt = block_given? ? block : p.first
+    end
+
+    # Returns the evaluation of expression passed to prompt_with. Result has
+    # +to_s+ called on it as Readline expects a String for its prompt.
+    # XXX This could probably be more robust
+    def prompt
+      case @@prompt
+      when Symbol: self.send @@prompt
+      when Proc:   @@prompt.call
+      else         @@prompt
+      end.to_s
+    end
+    module_function :prompt
+
+    # Create a command short cut
+    #
+    #   shortcut '?', 'help'
+    #   def do_help
+    #     # etc
+    #   end
+    def shortcut(short, command)
+      (@@shortcuts[command.to_s] ||= []).push short
+      @@shortcut_table[short] = command.to_s
+    end
+
+    def shortcut_table
+      @@shortcut_table
+    end
+    module_function :shortcut_table
+
+    def shortcuts
+      @@shortcuts
+    end
+    module_function :shortcuts
+
+    def custom_exception_handlers
+      @@handlers
+    end
+    module_function :custom_exception_handlers
+
+    # Defines a method which returns all defined methods which start with the
+    # passed in prefix followed by an underscore. Used to define methods to
+    # collect things such as all defined 'complete' and 'do' methods.
+    def define_collect_method(prefix)
+      method = 'collect_' + prefix
+      unless self.respond_to?(method) 
+        define_method(method) do
+          self.methods.grep(/^#{prefix}_/).map {|meth| meth[prefix.size + 1..-1]}
+        end
+      end
+    end
+  end
+  extend  ClassMethods
+  include ClassMethods
+
+  @hide_undocumented_commands = nil
+  class << self
+    # Flag that sets whether undocumented commands are listed in the help
+    attr_accessor :hide_undocumented_commands
+
+    def run(intro = nil)
+      new.cmdloop(intro)
+    end
+  end
+
+  # STDIN stream used
+  attr_writer :stdin
+
+  # STDOUT stream used
+  attr_writer :stdout
+
+  # The current command
+  attr_writer :current_command
+
+  prompt_with :default_prompt
+
+  def initialize
+    @stdin, @stdout = STDIN, STDOUT
+    @stop = false
+    setup
+  end 
+
+  # Starts up the command loop
+  def cmdloop(intro = nil)
+    preloop
+    write intro if intro
+    begin
+      set_completion_proc(:complete)
+      begin
+        execute_command
+      # Catch ^C
+      rescue Interrupt
+        user_interrupt
+      # I don't know why ZeroDivisionError isn't caught below...
+      rescue ZeroDivisionError
+        handle_all_remaining_exceptions(ZeroDivisionError)
+      rescue => exception
+        handle_all_remaining_exceptions(exception)
+      end
+    end until @stop
+    postloop
+  end
+  alias :run :cmdloop
+
+  shortcut '?', 'help'
+  doc :help,  'This help message.' 
+  def do_help(command = nil)
+    if command
+      command = translate_shortcut(command)
+      docs.include?(command) ? print_help(command) : no_help(command)
+    else
+      documented_commands.each {|cmd| print_help cmd}
+      print_undocumented_commands if undocumented_commands?
+    end
+  end
+
+  # Called when the +command+ has no associated documentation, this could
+  # potentially mean that the command is non existant
+  def no_help(command)
+    write "No help for command '#{command}'"
+  end
+
+  doc :exit,  'Terminate the program.' 
+  def do_exit; stoploop end
+
+  # Turns off readline even if it is supported
+  def turn_off_readline
+    @readline_supported = false
+    self
+  end
+
+  protected
+
+    def execute_command
+      unless ARGV.empty?
+        stoploop
+        execute_line(ARGV * ' ')
+      else
+        execute_line(display_prompt(prompt, true))
+      end
+    end
+
+    def handle_all_remaining_exceptions(exception)
+      if exception_is_handled?(exception) 
+        run_custom_exception_handling(exception) 
+      else
+        handle_exception(exception)
+      end
+    end
+
+    def execute_line(command)
+      postcmd(run_command(precmd(command)))
+    end
+
+    def stoploop
+      @stop = true
+    end
+
+    # Indicates whether readline support is enabled
+    def readline_supported?
+      @readline_supported = READLINE_SUPPORTED if @readline_supported.nil?
+      @readline_supported
+    end
+
+    # Determines if the given exception has a custome handler.
+    def exception_is_handled?(exception)
+      custom_exception_handler(exception)
+    end
+
+    # Runs the customized exception handler for the given exception.
+    def run_custom_exception_handling(exception)
+      case handler = custom_exception_handler(exception)
+      when String: write handler 
+      when Symbol: self.send(custom_exception_handler(exception))
+      end
+    end
+
+    # Returns the customized handler for the exception
+    def custom_exception_handler(exception)
+      custom_exception_handlers[exception.to_s]
+    end
+
+
+    # Called at object creation. This can be treated like 'initialize' for sub
+    # classes.
+    def setup
+    end
+
+    # Exceptions in the cmdloop are caught and passed to +handle_exception+.
+    # Custom exception classes must inherit from StandardError to be 
+    # passed to +handle_exception+.
+    def handle_exception(exception)
+      raise exception
+    end
+
+    # Displays the prompt. 
+    def display_prompt(prompt, with_history = true)
+      line = if readline_supported?
+        Readline::readline(prompt, with_history)
+      else
+        print prompt
+        @stdin.gets
+      end
+      line.respond_to?(:strip) ? line.strip : line
+    end
+
+    # The current command.
+    def current_command
+      translate_shortcut @current_command
+    end
+
+    # Called when the user hits ctrl-C or ctrl-D. Terminates execution by default.
+    def user_interrupt
+      write 'Terminating' # XXX get rid of this
+      stoploop
+    end
+
+    # XXX Not implementd yet. Called when a do_ method that takes arguments doesn't get any
+    def arguments_missing
+      write 'Invalid arguments'
+      do_help(current_command) if docs.include?(current_command)
+    end
+
+    # A bit of a hack I'm afraid. Since subclasses will be potentially
+    # overriding user_interrupt we want to ensure that it returns true so that
+    # it can be called with 'and return'
+    def interrupt
+      user_interrupt or true
+    end
+
+    # Displays the help for the passed in command.
+    def print_help(cmd)
+      offset = docs.keys.longest_string_length
+      write "#{cmd.ljust(offset)} -- #{docs[cmd]}"            + 
+      (has_shortcuts?(cmd) ? " #{display_shortcuts(cmd)}" : '')
+    end
+
+    def display_shortcuts(cmd)
+      "(aliases: #{shortcuts[cmd].join(', ')})"
+    end
+
+    # The method name that corresponds to the passed in command.
+    def command(cmd)
+      "do_#{cmd}".intern
+    end
+
+    # The method name that corresponds to the complete command for the pass in
+    # command.
+    def complete_method(cmd)
+      "complete_#{cmd}".intern
+    end
+
+    # Call back executed at the start of the cmdloop.
+    def preloop
+    end
+    
+    # Call back executed at the end of the cmdloop.
+    def postloop
+    end
+
+    # Receives line submitted at prompt and passes it along to the command
+    # being called.
+    def precmd(line)
+      line
+    end
+    
+    # Receives the returned value of the called command.
+    def postcmd(line)
+      line
+    end
+    
+    # Called when an empty line is entered in response to the prompt.
+    def empty_line
+    end
+
+    define_collect_method('do')
+    define_collect_method('complete')
+
+    # The default completor. Looks up all do_* methods.
+    def complete(command)
+      commands = completion_grep(command_list, command)
+      if commands.size == 1
+        cmd = commands.first
+        set_completion_proc(complete_method(cmd)) if collect_complete.include?(cmd)
+      end
+      commands
+    end
+
+    # Lists of commands (i.e. do_* methods minus the 'do_' part).
+    def command_list
+      collect_do - subcommand_list
+    end
+
+    # Definitive list of shortcuts and abbreviations of a command.
+    def command_lookup_table 
+      return @command_lookup_table if @command_lookup_table
+      @command_lookup_table = command_abbreviations.merge(shortcut_table)
+    end
+
+    # Returns lookup table of unambiguous identifiers for commands.
+    def command_abbreviations
+      return @command_abbreviations if @command_abbreviations
+      @command_abbreviations = Abbrev::abbrev(command_list)
+    end
+
+    # List of all subcommands.
+    def subcommand_list
+      with_underscore, without_underscore = collect_do.partition {|command| command.include?('_')}
+      with_underscore.find_all {|do_method| without_underscore.include?(do_method[/^[^_]+/])}
+    end
+
+    # Lists all subcommands of a given command.
+    def subcommands(command)
+      completion_grep(subcommand_list, translate_shortcut(command) + '_')
+    end
+
+    # Indicates whether a given command has any subcommands.
+    def has_subcommands?(command)
+      !subcommands(command).empty?
+    end
+
+    # List of commands which are documented.
+    def documented_commands
+      docs.keys.sort
+    end
+
+    # Indicates whether undocummented commands will be listed by the help
+    # command (they are listed by default).
+    def undocumented_commands_hidden?
+      self.class.hide_undocumented_commands  
+    end
+
+    def print_undocumented_commands
+      return if undocumented_commands_hidden?
+      # TODO perhaps do some fancy stuff so that if the number of undocumented
+      # commands is greater than 80 cols or some such passed in number it
+      # presents them in a columnar fashion much the way readline does by default
+      write ' '
+      write 'Undocumented commands'
+      write '====================='
+      write undocumented_commands.join(' ' * 4)
+    end
+
+    # Returns list of undocumented commands.
+    def undocumented_commands
+      command_list - documented_commands
+    end
+
+    # Indicates if any commands are undocumeted.
+    def undocumented_commands?
+      !undocumented_commands.empty?
+    end
+
+    # Completor for the help command.
+    def complete_help(command)
+      completion_grep(documented_commands, command)
+    end
+
+    def completion_grep(collection, pattern)
+      collection.grep(/^#{Regexp.escape(pattern)}/)
+    end
+
+    # Writes out a message with newline.
+    def write(*strings)
+      # We want newlines at the end of every line, so don't join with "\n"
+      strings.each do |string|
+        @stdout.write string
+        @stdout.write "\n"
+      end
+    end
+    alias :puts :write
+
+    # Writes out a message without newlines appended.
+    def print(*strings)
+      strings.each {|string| @stdout.write string}
+    end
+
+    shortcut '!', 'shell'
+    doc :shell, 'Executes a shell.'
+    # Executes a shell, perhaps should only be defined by subclasses.
+    def do_shell(line)
+      shell = ENV['SHELL']
+      line ? write(%x(#{line}).strip) : system(shell)
+    end
+
+    # Takes care of collecting the current command and its arguments if any and
+    # dispatching the appropriate command.
+    def run_command(line)
+      cmd, args = parse_line(line)
+      sanitize_readline_history(line) if line
+      unless cmd then empty_line; return end
+
+      cmd = translate_shortcut(cmd)
+      self.current_command = cmd
+      set_completion_proc(complete_method(cmd)) if collect_complete.include?(complete_method(cmd))
+      cmd_method = command(cmd)
+      if self.respond_to?(cmd_method) 
+        # Perhaps just catch exceptions here (related to arity) and call a
+        # method that reports a generic error like 'invalid arguments'
+        self.method(cmd_method).arity.zero? ? self.send(cmd_method) : self.send(cmd_method, tokenize_args(args)) 
+      else                              
+        command_missing(current_command, tokenize_args(args))
+      end
+    end
+
+    # Receives the line as it was passed from the prompt (barring modification
+    # in precmd) and splits it into a command section and an args section. The
+    # args are by default set to nil if they are boolean false or empty then
+    # joined with spaces. The tokenize method can be used to further alter the
+    # args.
+    def parse_line(line)
+      # line will be nil if ctr-D was pressed
+      user_interrupt and return if line.nil? 
+
+      cmd, *args = line.split
+      args = args.to_s.empty? ? nil : args * ' '
+      if args and has_subcommands?(cmd)
+        if cmd = find_subcommand_in_args(subcommands(cmd), line.split)
+          # XXX Completion proc should be passed array of subcommands somewhere
+          args = line.split.join('_').match(/^#{cmd}/).post_match.gsub('_', ' ').strip
+          args = nil if args.empty?
+        end
+      end
+      [cmd, args]
+    end
+
+    # Extracts a subcommand if there is one from the command line submitted. I guess this is a hack. 
+    def find_subcommand_in_args(subcommands, args)
+      (subcommands & (1..args.size).to_a.map {|num_elems| args.first(num_elems).join('_')}).max
+    end
+
+    # Looks up command shortcuts (e.g. '?' is a shortcut for 'help'). Short
+    # cuts can be added by using the shortcut class method.
+    def translate_shortcut(cmd)
+      command_lookup_table[cmd] || cmd
+    end
+
+    # Indicates if the passed in command has any registerd shortcuts.
+    def has_shortcuts?(cmd)
+      command_shortcuts(cmd)
+    end
+
+    # Returns the set of registered shortcuts for a command, or nil if none.
+    def command_shortcuts(cmd)
+      shortcuts[cmd]  
+    end
+
+    # Called on command arguments as they are passed into the command.
+    def tokenize_args(args)
+      args
+    end
+
+    # Cleans up the readline history buffer by performing tasks such as
+    # removing empty lines and piggy-backed duplicates. Only executed if
+    # running with readline support.
+    def sanitize_readline_history(line)
+      return unless readline_supported? 
+      # Strip out empty lines
+      Readline::HISTORY.pop if line.match(/^\s*$/)
+      # Remove duplicates
+      Readline::HISTORY.pop if Readline::HISTORY[-2] == line rescue IndexError
+    end
+
+    # Readline completion uses a procedure that takes the current readline
+    # buffer and returns an array of possible matches against the current
+    # buffer. This method sets the current procedure to use. Commands can
+    # specify customized completion procs by defining a method following the
+    # naming convetion complet_{command_name}.
+    def set_completion_proc(cmd)
+      return unless readline_supported?
+      Readline.completion_proc = self.method(cmd)
+    end
+
+    # Called when the line entered at the prompt does not map to any of the
+    # defined commands. By default it reports that there is no such command.
+    def command_missing(command, args)
+      write "No such command '#{command}'"
+    end
+
+    def default_prompt
+      "#{self.class.name}> "
+    end
+
+end
+
+module Enumerable #:nodoc:
+  def longest_string_length
+    inject(0) {|longest, item| longest >= item.size ? longest : item.size}
+  end
+end
+
+if __FILE__ == $0
+  Cmd.run
+end