Trollop

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:

• Trollop is a single file with no dependencies. You can just download it and throw it in your code directory.
• You can use rubygems and command your computer to gem install trollop.
• You can download the tarball from the Trollop Rubyforge page.

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

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

Examples

Simple

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

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

• Trollop::options returns a hash of values. That's all the output you get.
• Underscores are converted to dashes. opt :hello_there corresponds to an option --hello-there.
• All options are taken to be boolean flags, defaulting to false, unless you specify a default or a type. The type will be inferred from the default if given, so no need to specify both.
• Short (one-character) option names are created automatically. You can set them manually with :short.

Medium

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.

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

  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
end
Trollop::die :volume, "must be non-negative" if opts[:volume] < 0
Trollop::die :file, "must exist" unless File.exist?(opts[:file]) if opts[:file]

• You can specify a version and some banner text for the help message. --help and --version are defined for you.
• Any special error-checking is done by you, on the option hash. You can call Trollop::die to die with a nice message.

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
end

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

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

Specialized parsing behavior

Sometimes calling Trollop::options does too much for us. In this example, we create the parser without using Trollop::options, and force it to display the help message (and exit) if the user doesn't supply any arguments. The with_standard_exception_handling method takes care of dealing with the VersionNeeded, HelpNeeded and CommandlineError exceptions that Parser#parse throws, but we could handle those manually as well.

require 'trollop'
p = Trollop::Parser.new 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
end

opts = Trollop::with_standard_exception_handling p do
  o = p.parse ARGV
  raise Trollop::HelpNeeded if ARGV.empty? # show help screen
  o
end

Contributors

Trollop is brought to you by William Morgan and by:

• Tuomas Kareinen <tkareine at the gmail dot coms>
• Ohad Lutzky <ohad at the lutzky dot nets>
• Erik Ostrom <erik at the echographia dot coms>
• Will Fitzgerald <will.fitzgerald at the pobox dot coms>