Home

Thor is a simple and efficient tool for building self-documenting command line utilities. It removes the pain of parsing command line options, writing "USAGE:" banners, and can also be used as an alternative to the Rake build tool. The syntax is Rake-like, so it should be familiar to most Rake users.

Installation

$ gem install thor

or

$ gem install wycats-thor -s http://gems.github.com

Basic Usage

Map options to a class. Simply create a class with the appropriate annotations and have options automatically map to functions and parameters.

Example:

class App < Thor                                                 # [1]
  map "-L" => :list                                              # [2]
  
  desc "install APP_NAME", "install one of the available apps"   # [3]
  method_options :force => :boolean, :alias => :string           # [4]
  def install(name)
    user_alias = options[:alias]
    if options.force?
      # do something
    end
    # other code
  end
  
  desc "list [SEARCH]", "list all of the available apps, limited by SEARCH"
  def list(search="")
    # list everything
  end
end

Thor automatically maps commands as such:

thor app:install myname --force

That gets converted to:

App.new.install("myname")
# with {'force' => true} as options hash

1. Inherit from Thor to turn a class into an option mapper.
2. Map additional non-valid identifiers to specific methods. In this case, convert -L to :list
3. Describe the method immediately below. The first parameter is the usage information, and the second parameter is the description.
4. Provide any additional options that will be available the instance method options.

Further Reading

Thor offers many scripting possibilities beyond these examples. Be sure to read through the documentation and specs to get a better understanding of the options available.