Current project news: see the blog.

Trollop is a commandline option parser for Ruby that gets out of your way. One line of code per option is all you need to write. For that, you get a nice automatically-generated help page (fit to your screen size!), robust option parsing, command subcompletion, and sensible defaults for everything you don't specify.

Reasons to use Trollop:

  1. It requires fewer lines of code than any other option out there.
  2. It doesn't require you to subclass some shit just to use a damn option parser.
  3. It's a single file. You don't even need to make it a dependency. Just throw it in lib/.
  4. This gradient-free webpage. Fight the candy!

To install, you have three options:

To hack, command your computer to git clone git://, or see the Trollop Gitorious page.

To understand, read the examples below, the FAQ, and the API docs.



require 'trollop'
opts = Trollop::options do
  opt :monkey, "Use monkey mode"                     # a flag --monkey, defaulting to false
  opt :goat, "Use goat mode", :default => true       # a flag --goat, defaulting to true
  opt :num_limbs, "Number of limbs", :default => 4   # an integer --num-limbs <i>, defaulting to 4
  opt :num_thumbs, "Number of thumbs", :type => :int # an integer --num-thumbs <i>, defaulting to nil

p opts # a hash: { :monkey => false, :goat => true, :num_limbs => 4, :num_thumbs => nil }


require 'trollop'
opts = Trollop::options do
  version "test 1.2.3 (c) 2008 William Morgan"
  banner <<-EOS
Test is an awesome program that does something very, very important.

       test [options] <filenames>+
where [options] are:

  opt :ignore, "Ignore incorrect values"
  opt :file, "Extra data filename to read in, with a very long option description like this one", :type => String
  opt :volume, "Volume level", :default => 3.0
  opt :iters, "Number of iterations", :default => 5
Trollop::die :volume, "must be non-negative" if opts[:volume] < 0
Trollop::die :file, "must exist" unless File.exist?(opts[:file]) if opts[:file]

Sub-commands, a la SVN and Git

require 'trollop'

## Here's a program called "magic". We want this behavior:
##   magic delete <fn> => deletes a file
##   magic copy <fn>   => copies a file
## So 'delete' and 'copy' are subcommands.
## There are some global options, which appear to the left of the subcommand.
## There are some subcommand options, which appear to the right.
## Subcommand options can be specific to the subcommand. 'delete' might take
## different options from 'copy'.
## We do this by calling Trollop twice; one for the global options and once for
## the subcommand options. We need to tell Trollop what the subcommands are, so
## that it stops processing the global options when it encounters one of them.

SUB_COMMANDS = %w(delete copy)
global_opts = Trollop::options do
  banner "magic file deleting and copying utility"
  opt :dry_run, "Don't actually do anything", :short => "-n"
  stop_on SUB_COMMANDS

cmd = ARGV.shift # get the subcommand
cmd_opts = case cmd
  when "delete" # parse delete options
    Trollop::options do
      opt :force, "Force deletion"
  when "copy"  # parse copy options
    Trollop::options do
      opt :double, "Copy twice for safety's sake"
    Trollop::die "unknown subcommand #{cmd.inspect}"

puts "Global options: #{global_opts.inspect}"
puts "Subcommand: #{cmd.inspect}"
puts "Subcommand options: #{cmd_opts.inspect}"
puts "Remaining arguments: #{ARGV.inspect}"


Trollop is brought to you by William Morgan and by: