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:

It requires fewer lines of code than any other option out there.
It doesn't require you to subclass some shit just to use a damn option parser.
It's a single file. You don't even need to make it a dependency. Just throw it in lib/.
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 (why?) 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"                     # 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
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}"



 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>