Trollop

Current project news: see the blog.

Trollop is a commandline option parser for Ruby that just 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, robust option parsing, and sensible defaults for everything you don't specify.

Features

  1. Dirt-simple usage.
  2. Single file. Throw it in lib/ if you don't want to make it a Rubygem dependency.
  3. Sensible defaults. No tweaking necessary, much tweaking possible.
  4. Support for long options, short options, subcommands, and automatic type validation and conversion.
  5. Automatic help message generation, wrapped to current screen width.
  6. This gradient-free webpage. Fight the candy!

To install, you have three options:

To hack on it, 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 :name, "Monkey name", :type => :string        # string --name <s>, default nil
    opt :num_limbs, "Number of limbs", :default => 4  # integer --num-limbs <i>, default to 4
  end

  p opts # a hash: { :monkey=>false, :name=>nil, :num_limbs=>4, :help=>false }

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]

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
  raise Trollop::HelpNeeded if ARGV.empty? # show help screen
  p.parse ARGV
end

Contributors

Trollop is brought to you by William Morgan and by: