module Optimist
Constants
- FLOAT_RE
Regex for floating point numbers
- PARAM_RE
Regex for parameters
- VERSION
note: this is duplicated in gemspec please change over there too
Public Class Methods
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] > 10.0 die :volume, "too soft" if opts[:volume] < 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 provide if needed
Optimist::die "need at least one filename", -2 if ARGV.empty?
# File lib/optimist.rb, line 984 def die(arg, msg = nil, error_code = nil) if @last_parser @last_parser.die arg, msg, error_code else raise ArgumentError, "Optimist::die can only be called after Optimist::options" end end
Displays the help message and dies. Example:
options do opt :volume, :default => 0.0 banner <<-EOS Usage: #$0 [options] <name> where [options] are: EOS end Optimist::educate if ARGV.empty?
# File lib/optimist.rb, line 1004 def educate if @last_parser @last_parser.educate exit else raise ArgumentError, "Optimist::educate can only be called after Optimist::options" end end
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 text
(Parser#text
), 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 key “<option name>_given” will also be set in the hash.
Example:
require 'optimist' opts = Optimist::options do opt :monkey, "Use monkey mode" # a flag --monkey, defaulting to false opt :name, "Monkey name", :type => :string # 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}
See more examples at optimist.rubyforge.org.
# File lib/optimist.rb, line 920 def options(args = ARGV, *a, &b) @last_parser = Parser.new(*a, &b) with_standard_exception_handling(@last_parser) { @last_parser.parse args } end
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 call System#exit after handling an exception!
Usage example:
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 o = p.parse ARGV raise Optimist::HelpNeeded if ARGV.empty? # show help screen o end
Requires passing in the parser object.
# File lib/optimist.rb, line 950 def with_standard_exception_handling(parser) yield rescue CommandlineError => e parser.die(e.message, nil, e.error_code) rescue HelpNeeded parser.educate exit rescue VersionNeeded puts parser.version exit end
Private Instance Methods
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] > 10.0 die :volume, "too soft" if opts[:volume] < 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 provide if needed
Optimist::die "need at least one filename", -2 if ARGV.empty?
# File lib/optimist.rb, line 984 def die(arg, msg = nil, error_code = nil) if @last_parser @last_parser.die arg, msg, error_code else raise ArgumentError, "Optimist::die can only be called after Optimist::options" end end
Displays the help message and dies. Example:
options do opt :volume, :default => 0.0 banner <<-EOS Usage: #$0 [options] <name> where [options] are: EOS end Optimist::educate if ARGV.empty?
# File lib/optimist.rb, line 1004 def educate if @last_parser @last_parser.educate exit else raise ArgumentError, "Optimist::educate can only be called after Optimist::options" end end
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 text
(Parser#text
), 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 key “<option name>_given” will also be set in the hash.
Example:
require 'optimist' opts = Optimist::options do opt :monkey, "Use monkey mode" # a flag --monkey, defaulting to false opt :name, "Monkey name", :type => :string # 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}
See more examples at optimist.rubyforge.org.
# File lib/optimist.rb, line 920 def options(args = ARGV, *a, &b) @last_parser = Parser.new(*a, &b) with_standard_exception_handling(@last_parser) { @last_parser.parse args } end
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 call System#exit after handling an exception!
Usage example:
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 o = p.parse ARGV raise Optimist::HelpNeeded if ARGV.empty? # show help screen o end
Requires passing in the parser object.
# File lib/optimist.rb, line 950 def with_standard_exception_handling(parser) yield rescue CommandlineError => e parser.die(e.message, nil, e.error_code) rescue HelpNeeded parser.educate exit rescue VersionNeeded puts parser.version exit end