Library for command line option analysis.
features:
+--------------+
| OptionParser |<>-----+
+--------------+ | +--------+
| ,-| Switch |
on_head -------->+---------------+ / +--------+
accept/reject -->| List |<|>-
| |<|>- +----------+
on ------------->+---------------+ `-| argument |
: : | class |
+---------------+ |==========|
on_tail -------->| | |pattern |
+---------------+ |----------|
OptionParser.accept ->| DefaultList | |converter |
reject |(shared between| +----------+
| all instances)|
+---------------+
Keyword completion module.
OptionParser::Completion#complete(key[, pat])Searches key, or pat with completion if not found.
OptionParser::Completion#convert(opt, *val)Extracts the first element from result of OptionParser::Completion#complete.
Map from option/keyword string to object with completion.
Hash
Individual switch class.
OptionParser::Switch.guess(arg)Guesses argument style from arg. Returns corresponding OptionParser::Switch subclass.
OptionParser::Switch.newOptionParser::Switch#parse_arg(arg) {non-serious error handler}Parses argument and returns rest of arg, and matched portion to the argument pattern.
OptionParser::Switch#conv_arg(arg, val) {semi-error handler}Parses argument, convert and returns arg, block and result of conversion.
substrings matched to @pattern, $&, $1, $2 and so on.
OptionParser::Switch#summarize(sdone, ldone, width, max, indent)Makes summary strings.
already summarized short style options keyed hash.
already summarized long style options keyed hash.
width of left side, option part. in other word, right side, description part strings start at width column.
maximum width of left side, options are filled within max columns.
prefix string indents each summarized lines.
blockto be passed each lines(without newline).
Switch that takes no arguments.
OptionParser::Switch::NoArgument#parseRaises an exception if any arguments given.
Switch that takes an argument.
OptionParser::Switch::RequiredArgument#parseRaises an exception if argument is not present.
Switch that can omit argument.
OptionParser::Switch::OptionalArgument#parseParses argument if given, or uses default value.
Simple option list providing mapping from short and/or long option string to OptionParser::Switch, and mapping from acceptable argument to matching pattern and converter pair. Also provides summary feature.
OptionParser::List.newJust initializes all instance variables.
OptionParser::List#atypeMap from acceptable argument types to pattern and converter pairs.
OptionParser::List#shortMap from short style option switches to actual switch objects.
OptionParser::List#longMap from long style option switches to actual switch objects.
OptionParser::List#listList of all switches and summary string.
OptionParser::List#accept(type[, pattern]) {...}see OptionParser.accept.
OptionParser::List#reject(type)see OptionParser.reject.
OptionParser::List#update(sw, sopts, lopts, nlopts = nil)Adds sw according to sopts, lopts and nlopts.
OptionParser::Switch instance to be added.
short style options list.
long style options list.
negated long style options list.
OptionParser::List#prepend(switch, short_opts, long_opts, nolong_opts)Inserts switch at head of the list, and associates short, long and negated long options.
OptionParser::List#append(switch, short_opts, long_opts, nolong_opts)Appends switch at tail of the list, and associates short, long and negated long options.
OptionParser::Switch instance to be inserted.
list of short style options.
list of long style options.
list of long style options with "no-" prefix.
OptionParser::List#search(id, key) [{block}]Searches key in id list.
OptionParser::List#complete(id, opt, *pat, &block)Searches list id for opt and *pat.
OptionParser::List#summarize(*args) {...}Making summary table, yields the block with each lines.
Each elements of @list should be able to summarize.
Hash with completion search feature.
Hash
OptionParser::CompletingHash#match(key)Completion for hash key.
The front-end of OptionParser.
OptionParser::ArgumentStyleEnumeration of acceptable argument styles; possible values are:
the switch takes no arguments. (:NONE)
the switch requires an argument. (:REQUIRED)
the switch requires an optional argument, that is, may take or
not. (:OPTIONAL)
Use like --switch=argument(long style) or
-Xargument(short style). For short style, only portion
matched to argument pattern is dealed as argument.
OptionParser::DefaultListSwitches common used such as '--', and also provides default argument classes
Default options, which never appear in option summary.
OptionParser.with([banner[, width[, indent]]]) [{...}]Initializes new instance, and evaluates the block in context of
the instance if called as iterator. This behavior is equivalent
to older new. This is deprecated method.
cf. OptionParser.new
OptionParser.inc(arg[, default])OptionParser#inc(arg[, default])Returns incremented value of default according to arg.
OptionParser.new([banner[, width[, indent]]]) [{...}]Initializes the instance, and yields itself if called as iterator.
OptionParser.terminate([arg])Terminates option parsing. Optional parameter arg would be pushed back if given.
string pushed back to be first non-option argument
OptionParser.accept(t, [pat]) {...}OptionParser#accept(t, [pat]) {...}Directs to accept specified class argument.
OptionParser.reject(t)OptionParser#reject(t)Directs to reject specified class argument.
argument class specifier, any object including Class.
OptionParser#bannerOptionParser#banner=(heading)Heading banner preceding summary.
OptionParser#summary_widthOptionParser#summary_width=(width)Width for option list portion of summary. Must be Numeric.
OptionParser#summary_indentOptionParser#summary_indent=(indent)Indentation for summary. Must be String (or have + String).
OptionParser#program_nameOptionParser#program_name=(name)Program name to be emitted in error message and default banner,
defaulted to $0.
OptionParser#versionOptionParser#version=(ver)Version.
OptionParser#releaseOptionParser#release=(rel)Release code.
OptionParser#verReturns version string from program_name, version and
release.
OptionParser#topOptionParser#baseSubject of on_tail.
OptionParser#newPushes a new List.
OptionParser#removeRemoves the last List.
OptionParser#summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent)Puts option summary into to, and returns to.
OptionParser#helpOptionParser#to_sReturns option summary string.
OptionParser#to_aReturns option summary list.
OptionParser#switchCreates OptionParser::Switch.
option definition:
acceptable option argument format, must pre-defined with
OptionParser.accept or OptionParser#accept, or
Regexp. This can appear once or assigned as String
if not present, otherwise causes exception ArgumentError.
possible argument values.
alternative way to give the handler.
specifies long style switch that takes mandatory, optional and no argument, respectively.
specifies short style switch that takes mandatory, optional and no argument, respectively.
special form short style switch that matches character range(not fullset of regular expression).
argument style and description.
description for this option.
blockhandler to convert option argument to arbitrary Class.
OptionParser#notwice(obj, prv, msg)Checks never given twice an argument. Called from OptionParser#switch only
OptionParser#on(*opts) [{...}]OptionParser#def_option(*opts) [{...}]OptionParser#on_head(*opts) [{...}]OptionParser#def_head_option(*opts) [{...}]OptionParser#on_tail(*opts) [{...}]OptionParser#def_tail_option(*opts) [{...}]Defines option switch and handler. on_head, def_head_option
and on_tail, def_tail_option put the switch at head
and tail of summary, respectively.
cf. OptionParser#switch.
OptionParser#order(*argv) [{...}]OptionParser#order!([argv = ARGV]) [{...}]Parses argv in order. When non-option argument encountered, yields it if called as iterator, otherwise terminates the parse process. Returns rest of argv left unparsed.
order! takes argument array itself, and removes switches
destructively.
Defaults to parse ARGV.
OptionParser#permute(*argv)OptionParser#permute!([argv = ARGV])Parses argv in permutation mode, and returns list of non-option arguments.
permute! takes argument array itself, and removes switches
destructively.
Defaults to parse ARGV.
command line arguments to be parsed.
OptionParser#parse(*argv)OptionParser#parse!([argv = ARGV])Parses argv in order when environment variable POSIXLY_CORRECT
is set, otherwise permutation mode
parse! takes argument array itself, and removes switches
destructively.
Defaults to parse ARGV.
command line arguments to be parsed.
OptionParser#visit(id, *args) {block}Traverses stacks calling method id with *args.
OptionParser#search(id, k)Searches k in stack for id hash, and returns it or yielded value if called as iterator.
OptionParser#complete(typ, opt, *etc)Completes shortened long style option switch, and returns pair of canonical switch and switch descriptorOptionParser::Switch.
OptionParser#load([filename])Loads options from file named as filename. Does nothing when the file is not present. Returns whether successfuly loaded.
option file name. defaulted to basename of the program without suffix in a directory ~/.options.
OptionParser#environment([env])Parses environment variable env or its uppercase with spliting like as shell.
defaulted to basename of the program.
any string, and no conversion. this is fall-back.
any none-empty string, and no conversion.
Ruby/C-like integer, octal for 0-7 sequence, binary for
0b, hexadecimal for 0x, and decimal for others; with
optional sign prefix. Converts to Integer.
Float number format, and converts to Float.
Generic numeric format, and converts to Integer for integer
format, Float for float format.
Decimal integer format, to be converted to Integer.
Ruby/C like octal/hexadecimal/binary integer format, to be converted
to Integer.
Decimal integer/float number format, to be converted to
Integer for integer format, Float for float format.
Boolean switch, which means whether it is present or not, whether it
is absent or not with prefix no-, or it takes an argument
yes/no/true/false/+/-.
Similar to TrueClass, but defaulted to false.
List of strings separated by ","
Base class of exceptions from OptionParser
RuntimeError
Reason caused error.
OptionParser::ParseError#recover(argv)Push backs erred argument(s) to argv.
OptionParser::ParseError#reasonReturns error reason. Override this to I18N.
OptionParser::ParseError#inspectReturns inspection string.
OptionParser::ParseError#messageOptionParser::ParseError#to_sOptionParser::ParseError#to_strDefault stringizing method to emit standard error message.
Raises when encountered ambiguously completable string.
Raises when encountered argument for switch defined as which takes no argument.
Raises when no argument found for switch defined as which needs argument.
Raises when undefined switch.
Raises when the given argument does not match required format.
Raises when the given argument word can't completed uniquely.
Extends command line arguments array to parse itself.
OptionParser::Arguable#options=(opt)Sets OptionParser object, when opt is false or
nil, methods OptionParser::Arguable#options and
OptionParser::Arguable#options= are undefined. Thus, there
is no ways to access the OptionParser object via the
receiver object.
OptionParser::Arguable#optionsActual OptionParser object, automatically created if not yet.
If called as iterator, yields with the OptionParser object
and returns the result of the block. In this case, rescues any
OptionParser::ParseError exceptions in the block, just emits
error message to STDERR and returns nil.
blockYielded with the OptionParser instance.
OptionParser::Arguable#order!OptionParser::Arguable#permute!OptionParser::Arguable#parse!Parses self destructively, and returns self just contains rest arguments left without parsed.
Initializes instance variable.
Acceptable argument classes. Now contains DecimalInteger,
OctalInteger and DecimalNumeric.
see Acceptable argument classes.
The following example is a complete Ruby program. You can run it and see the effect of specifying various options.
require 'optparse'
require 'optparse/time'
require 'ostruct'
require 'pp'
class OptparseExample
CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
CODE_ALIASES = {"jis" => "iso-2022-jp", "sjis" => "shift_jis"}
#
# Return a structure describing the options.
#
def self.parse(args)
# The options specified on the command line will be collected in *options*.
# We set default values here.
options = OpenStruct.new
options.library = []
options.inplace = false
options.encoding = "utf8"
options.transfer_type = :auto
options.verbose = false
opts = OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.separator ""
opts.separator "Specific options:"
# Mandatory argument.
opts.on("-r", "--require LIBRARY",
"Require the LIBRARY before executing your script") do |lib|
options.library << lib
end
# Optional argument; multi-line description.
opts.on("-i", "--inplace [EXTENSION]",
"Edit ARGV files in place",
" (make backup if EXTENSION supplied)") do |ext|
options.inplace = true
options.extension = ext || ''
options.extension.sub!(/\A\.?(?=.)/, ".") # Ensure extension begins with dot.
end
# Cast 'delay' argument to a Float.
opts.on("--delay N", Float, "Delay N seconds before executing") do |n|
options.delay = n
end
# Cast 'time' argument to a Time object.
opts.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
options.time = time
end
# Cast to octal integer.
opts.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
"Specify record separator (default \\0)") do |rs|
options.record_separator = rs
end
# List of arguments.
opts.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
options.list = list
end
# Keyword completion. We are specifying a specific set of arguments (CODES
# and CODE_ALIASES - notice the latter is a Hash), and the user may provide
# the shortest unambiguous text.
code_list = (CODE_ALIASES.keys + CODES).join(',')
opts.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
" (#{code_list})") do |encoding|
options.encoding = encoding
end
# Optional argument with keyword completion.
opts.on("--type [TYPE]", [:text, :binary, :auto], "Select transfer type (text, binary, auto)") do |t|
options.transfer_type = t
end
# Boolean switch.
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options.verbose = v
end
opts.separator ""
opts.separator "Common options:"
# No argument, shows at tail. This will print an options summary.
# Try it and see!
opts.on_tail("-h", "--help", "Show this message") do
puts opts
exit
end
# Another typical switch to print the version.
opts.on_tail("--version", "Show version") do
puts OptionParser::Version.join('.')
exit
end
end
opts.parse!(args)
options
end # parse()
end # class OptparseExample
options = OptparseExample.parse(ARGV)
pp options
Note: if you get errors or strange results from any of the above code, make sure you have the latest version installed. Some changes have been made since Ruby 1.8.0 was released.