Informs the user that their usage of arg was wrong, as detailed by msg, and dies. Example:

options do
  opt :volume, default: 0.0
end

die :volume, "too loud" if opts["volume"].value > 10.0
die :volume, "too soft" if opts["volume"].value < 0.1

In the one-argument case, simply print that message, a notice about -h, and die. Example:

options do
  opt :whatever # ...
end

Optimist.die "need at least one filename" if ARGV.empty?

An exit code can be provided if needed

Optimist.die "need at least one filename", -2 if ARGV.empty?

Disable real system exit at the class level

Displays the help message and dies. Example:

options do
  opt :volume, default: 0.0
  banner <<-EOS
Usage:
       #{PROGRAM_NAME} [options] <name>
where [options] are:
EOS
end

Optimist.educate if ARGV.empty?

Enable real system exit at the class level

The easy, syntactic-sugary entry method into Optimist. Creates a Parser, passes the block to it, then parses args with it, handling any errors or requests for help or version information appropriately (and then exiting). Modifies args in place. Returns a hash of option values.

The block passed in should contain zero or more calls to opt (Parser.opt), zero or more calls to banner (Parser.banner), and probably a call to version (Parser.version).

The returned block contains a value for every option specified with opt. The value will be the value given on the commandline, or the default value if the option was not specified on the commandline. For every option specified on the commandline, a boolean property named given? will be set to true/false.

Example

require "optimist"
opts = Optimist.options do
  opt :monkey, "Use monkey mode"                 # a flag --monkey, defaulting to false
  opt :name, "Monkey name", cls: StringOpt       # a string --name < s>, defaulting to nil
  opt :num_limbs, "Number of limbs", default: 4  # an integer --num-limbs < i>, defaulting to 4
end

# if called with no arguments
p opts # => {:monkey=>false, :name=>nil, :num_limbs=>4, :help=>false}

# if called with --monkey
p opts # => {:monkey=>true, :name=>nil, :num_limbs=>4, :help=>false, :monkey_given=>true}

Settings

Optimist.options and Optimist::Parser.new accept keyword args to control how options are interpreted, e.g:.

opts = Optimist.options(args: ARGV, inexact_match: true) do
  opt :foobar, "messed up"
  opt :forget, "forget it"
end

Keyword arguments include:

• exact_match : If false, allows a minimum unambigous number of characters to match a long option. If true, requires all characters of the long option to be give. Defaults to false.
• suggestions : If true, enables suggestions when unknown arguments are given. Defaults to true.
• explicit_short_options : If true, Short options will only be created where explicitly defined. If you do not like short-options, this will prevent having to define short: false for all of your options. Defaults to false.

If Optimist.options doesn't do quite what you want, you can create a Parser object and call Parser#parse on it. That method will throw CommandlineError, HelpNeeded and VersionNeeded exceptions when necessary; if you want to have these handled for you in the standard manner (e.g. show the help and then exit upon an HelpNeeded exception), call your code from within a block passed to this method.

Note that this method will raise SystemExit after handling an exception!

Usage example:

require "optimist"
par = 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 par do
  o = par.parse ARGV
  raise Optimist::HelpNeeded.new() if ARGV.empty? # show help screen
  o
end

Requires passing in the parser object.