Optimist

Optimist 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:

• Optimist is a single file with no dependencies. Download it and throw it in your code directory.
• You can use rubygems and command your computer to gem install optimist.

To hack on it, command your computer to git clone git://github.com/manageiq/optimist.git, or see the Optimist GitHub page.

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

Examples

Simple

require 'optimist'
  opts = Optimist::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 }

• Optimist::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 'optimist'
opts = Optimist::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
Optimist::die :volume, "must be non-negative" if opts[:volume] < 0
Optimist::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 Optimist::die to die with a nice message.

Sub-commands, a la SVN and Git

require 'optimist'

## 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 Optimist twice; one for the global options and once for
## the subcommand options. We need to tell Optimist 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 = Optimist::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
    Optimist::options do
      opt :force, "Force deletion"
    end
  when "copy"  # parse copy options
    Optimist::options do
      opt :double, "Copy twice for safety's sake"
    end
  else
    Optimist::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 Optimist::options does too much for us. In this example, we create the parser without using Optimist::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 'optimist'
p = Optimist::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 = Optimist::with_standard_exception_handling p do
  raise Optimist::HelpNeeded if ARGV.empty? # show help screen
  p.parse ARGV
end

Contributors

Optimist was originally brought to you by William Morgan and is currently maintained by Keenan Brock, with contributions from many wonderful contributors.