OptionParserOptionParser is a class for command-line option analysis. It is much more advanced, yet also easier to use, than GetoptLong, and is a more Ruby-oriented solution.
The argument specification and the code to handle it are written in the same place.
It can output an option summary; you don't need to maintain this string separately.
Optional and mandatory arguments are specified very gracefully.
Arguments can be automatically converted to a specified class.
Arguments can be restricted to a certain set.
All of these features are demonstrated in the examples below. See make_switch for full documentation.
require 'optparse'
options = {}
OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options[:verbose] = v
end
end.parse!
p options
p ARGV
OptionParser can be used to automatically generate help for the commands you write:
require 'optparse'
Options = Struct.new(:name)
class Parser
def self.parse(options)
args = Options.new("world")
opt_parser = OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.on("-nNAME", "--name=NAME", "Name to say hello to") do |n|
args.name = n
end
opts.on("-h", "--help", "Prints this help") do
puts opts
exit
end
end
opt_parser.parse!(options)
return args
end
end
options = Parser.parse %w[--help]
#=>
# Usage: example.rb [options]
# -n, --name=NAME Name to say hello to
# -h, --help Prints this help
For options that require an argument, option specification strings may include an option name in all caps. If an option is used without the required argument, an exception will be raised.
require 'optparse'
options = {}
OptionParser.new do |parser|
parser.on("-r", "--require LIBRARY",
"Require the LIBRARY before executing your script") do |lib|
puts "You required #{lib}!"
end
end.parse!
Used:
$ ruby optparse-test.rb -r optparse-test.rb:9:in `<main>': missing argument: -r (OptionParser::MissingArgument) $ ruby optparse-test.rb -r my-library You required my-library!
OptionParser supports the ability to coerce command line arguments into objects for us.
OptionParser comes with a few ready-to-use kinds of type coercion. They are:
Date – Anything accepted by Date.parse
DateTime – Anything accepted by DateTime.parse
Time – Anything accepted by Time.httpdate or Time.parse
URI – Anything accepted by URI.parse
Shellwords – Anything accepted by Shellwords.shellwords
String – Any non-empty string
Integer – Any integer. Will convert octal. (e.g. 124, -3, 040)
Float – Any float. (e.g. 10, 3.14, -100E+13)
Numeric – Any integer, float, or rational (1, 3.4, 1/3)
DecimalInteger – Like Integer, but no octal format.
OctalInteger – Like Integer, but no decimal format.
DecimalNumeric – Decimal integer or float.
TrueClass – Accepts '+, yes, true, -, no, false' and defaults as true
FalseClass – Same as TrueClass, but defaults to false
Array – Strings separated by ',' (e.g. 1,2,3)
Regexp – Regular expressions. Also includes options.
We can also add our own coercions, which we will cover below.
As an example, the built-in Time conversion is used. The other built-in conversions behave in the same way. OptionParser will attempt to parse the argument as a Time. If it succeeds, that time will be passed to the handler block. Otherwise, an exception will be raised.
require 'optparse'
require 'optparse/time'
OptionParser.new do |parser|
parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
p time
end
end.parse!
Used:
$ ruby optparse-test.rb -t nonsense ... invalid argument: -t nonsense (OptionParser::InvalidArgument) $ ruby optparse-test.rb -t 10-11-12 2010-11-12 00:00:00 -0500 $ ruby optparse-test.rb -t 9:30 2014-08-13 09:30:00 -0400
The accept method on OptionParser may be used to create converters. It specifies which conversion block to call whenever a class is specified. The example below uses it to fetch a User object before the on handler receives it.
require 'optparse'
User = Struct.new(:id, :name)
def find_user id
not_found = ->{ raise "No User Found for id #{id}" }
[ User.new(1, "Sam"),
User.new(2, "Gandalf") ].find(not_found) do |u|
u.id == id
end
end
op = OptionParser.new
op.accept(User) do |user_id|
find_user user_id.to_i
end
op.on("--user ID", User) do |user|
puts user
end
op.parse!
Used:
$ ruby optparse-test.rb --user 1 #<struct User id=1, name="Sam"> $ ruby optparse-test.rb --user 2 #<struct User id=2, name="Gandalf"> $ ruby optparse-test.rb --user 3 optparse-test.rb:15:in `block in find_user': No User Found for id 3 (RuntimeError)
Hash
The into option of order, parse and so on methods stores command line options into a Hash.
require 'optparse'
params = {}
OptionParser.new do |opts|
opts.on('-a')
opts.on('-b NUM', Integer)
opts.on('-v', '--verbose')
end.parse!(into: params)
p params
Used:
$ ruby optparse-test.rb -a
{:a=>true}
$ ruby optparse-test.rb -a -v
{:a=>true, :verbose=>true}
$ ruby optparse-test.rb -a -b 100
{:a=>true, :b=>100} The following example is a complete Ruby program. You can run it and see the effect of specifying various options. This is probably the best way to learn the features of optparse.
require 'optparse'
require 'optparse/time'
require 'ostruct'
require 'pp'
class OptparseExample
Version = '1.0.0'
CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
class ScriptOptions
attr_accessor :library, :inplace, :encoding, :transfer_type,
:verbose, :extension, :delay, :time, :record_separator,
:list
def initialize
self.library = []
self.inplace = false
self.encoding = "utf8"
self.transfer_type = :auto
self.verbose = false
end
def define_options(parser)
parser.banner = "Usage: example.rb [options]"
parser.separator ""
parser.separator "Specific options:"
# add additional options
perform_inplace_option(parser)
delay_execution_option(parser)
execute_at_time_option(parser)
specify_record_separator_option(parser)
list_example_option(parser)
specify_encoding_option(parser)
optional_option_argument_with_keyword_completion_option(parser)
boolean_verbose_option(parser)
parser.separator ""
parser.separator "Common options:"
# No argument, shows at tail. This will print an options summary.
# Try it and see!
parser.on_tail("-h", "--help", "Show this message") do
puts parser
exit
end
# Another typical switch to print the version.
parser.on_tail("--version", "Show version") do
puts Version
exit
end
end
def perform_inplace_option(parser)
# Specifies an optional option argument
parser.on("-i", "--inplace [EXTENSION]",
"Edit ARGV files in place",
"(make backup if EXTENSION supplied)") do |ext|
self.inplace = true
self.extension = ext || ''
self.extension.sub!(/\A\.?(?=.)/, ".") # Ensure extension begins with dot.
end
end
def delay_execution_option(parser)
# Cast 'delay' argument to a Float.
parser.on("--delay N", Float, "Delay N seconds before executing") do |n|
self.delay = n
end
end
def execute_at_time_option(parser)
# Cast 'time' argument to a Time object.
parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
self.time = time
end
end
def specify_record_separator_option(parser)
# Cast to octal integer.
parser.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
"Specify record separator (default \\0)") do |rs|
self.record_separator = rs
end
end
def list_example_option(parser)
# List of arguments.
parser.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
self.list = list
end
end
def specify_encoding_option(parser)
# 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(', ')
parser.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
"(#{code_list})") do |encoding|
self.encoding = encoding
end
end
def optional_option_argument_with_keyword_completion_option(parser)
# Optional '--type' option argument with keyword completion.
parser.on("--type [TYPE]", [:text, :binary, :auto],
"Select transfer type (text, binary, auto)") do |t|
self.transfer_type = t
end
end
def boolean_verbose_option(parser)
# Boolean switch.
parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
self.verbose = v
end
end
end
#
# Return a structure describing the options.
#
def parse(args)
# The options specified on the command line will be collected in
# *options*.
@options = ScriptOptions.new
@args = OptionParser.new do |parser|
@options.define_options(parser)
parser.parse!(args)
end
@options
end
attr_reader :parser, :options
end # class OptparseExample
example = OptparseExample.new
options = example.parse(ARGV)
pp options # example.options
pp ARGV
Completion
For modern shells (e.g. bash, zsh, etc.), you can use shell completion for command line options.
The above examples should be enough to learn how to use this class. If you have any questions, file a ticket at bugs.ruby-lang.org.
Heading banner preceding summary.
Strings to be parsed in default.
Program name to be emitted in error message and default banner, defaults to $0.
Release code
Heading banner preceding summary.
Program name to be emitted in error message and default banner, defaults to $0.
Width for option list portion of summary. Must be Numeric.
Width for option list portion of summary. Must be Numeric.
Version
# File lib/optparse.rb, line 1130 def self.accept(*args, &blk) top.accept(*args, &blk) end
See accept.
# File lib/optparse/version.rb, line 50
def each_const(path, base = ::Object)
path.split(/::|\//).inject(base) do |klass, name|
raise NameError, path unless Module === klass
klass.constants.grep(/#{name}/i) do |c|
klass.const_defined?(c) or next
klass.const_get(c)
end
end
end # File lib/optparse.rb, line 1740 def self.getopts(*args) new.getopts(*args) end
See getopts.
# File lib/optparse.rb, line 1066
def self.inc(arg, default = nil)
case arg
when Integer
arg.nonzero?
when nil
default.to_i + 1
end
end Returns an incremented value of default according to arg.
# File lib/optparse.rb, line 1085 def initialize(banner = nil, width = 32, indent = ' ' * 4) @stack = [DefaultList, List.new, List.new] @program_name = nil @banner = banner @summary_width = width @summary_indent = indent @default_argv = ARGV add_officious yield self if block_given? end
Initializes the instance and yields itself if called with a block.
banner Banner message.
width Summary width.
indent Summary indent.
# File lib/optparse.rb, line 1143 def self.reject(*args, &blk) top.reject(*args, &blk) end
See reject.
# File lib/optparse/version.rb, line 60
def search_const(klass, name)
klasses = [klass]
while klass = klasses.shift
klass.constants.each do |cname|
klass.const_defined?(cname) or next
const = klass.const_get(cname)
yield klass, cname, const if name === cname
klasses << const if Module === const and const != ::Object
end
end
end # File lib/optparse/version.rb, line 5
def show_version(*pkgs)
progname = ARGV.options.program_name
result = false
show = proc do |klass, cname, version|
str = "#{progname}"
unless klass == ::Object and cname == :VERSION
version = version.join(".") if Array === version
str << ": #{klass}" unless klass == Object
str << " version #{version}"
end
[:Release, :RELEASE].find do |rel|
if klass.const_defined?(rel)
str << " (#{klass.const_get(rel)})"
end
end
puts str
result = true
end
if pkgs.size == 1 and pkgs[0] == "all"
self.search_const(::Object, /\AV(?:ERSION|ersion)\z/) do |klass, cname, version|
unless cname[1] == ?e and klass.const_defined?(:Version)
show.call(klass, cname.intern, version)
end
end
else
pkgs.each do |pkg|
begin
pkg = pkg.split(/::|\//).inject(::Object) {|m, c| m.const_get(c)}
v = case
when pkg.const_defined?(:Version)
pkg.const_get(n = :Version)
when pkg.const_defined?(:VERSION)
pkg.const_get(n = :VERSION)
else
n = nil
"unknown"
end
show.call(pkg, n, v)
rescue NameError
end
end
end
result
end # File lib/optparse.rb, line 1110 def self.terminate(arg = nil) throw :terminate, arg end
# File lib/optparse.rb, line 1115 def self.top() DefaultList end
# File lib/optparse.rb, line 1057 def self.with(*args, &block) opts = new(*args) opts.instance_eval(&block) opts end
Initializes a new instance and evaluates the optional block in context of the instance. Arguments args are passed to new, see there for description of parameters.
This method is deprecated, its behavior corresponds to the older new method.
# File lib/optparse.rb, line 1224
def abort(mesg = $!)
super("#{program_name}: #{mesg}")
end Kernel#abort # File lib/optparse.rb, line 1126 def accept(*args, &blk) top.accept(*args, &blk) end
Directs to accept specified class t. The argument string is passed to the block in which it should be converted to the desired class.
t Argument class specifier, any object including Class.
pat Pattern for argument, defaults to t if it responds to match.
accept(t, pat, &block)
# File lib/optparse.rb, line 1791
def additional_message(typ, opt)
return unless typ and opt and defined?(DidYouMean::SpellChecker)
all_candidates = []
visit(:get_candidates, typ) do |candidates|
all_candidates.concat(candidates)
end
all_candidates.select! {|cand| cand.is_a?(String) }
checker = DidYouMean::SpellChecker.new(dictionary: all_candidates)
DidYouMean.formatter.message_for(all_candidates & checker.correct(opt))
end Returns additional info.
# File lib/optparse.rb, line 1168
def banner
unless @banner
@banner = +"Usage: #{program_name} [options]"
visit(:add_banner, @banner)
end
@banner
end Heading banner preceding summary.
# File lib/optparse.rb, line 1238 def base @stack[1] end
Subject of on_tail.
# File lib/optparse.rb, line 1802
def candidate(word)
list = []
case word
when '-'
long = short = true
when /\A--/
word, arg = word.split(/=/, 2)
argpat = Completion.regexp(arg, false) if arg and !arg.empty?
long = true
when /\A-/
short = true
end
pat = Completion.regexp(word, long)
visit(:each_option) do |opt|
next unless Switch === opt
opts = (long ? opt.long : []) + (short ? opt.short : [])
opts = Completion.candidate(word, true, pat, &opts.method(:each)).map(&:first) if pat
if /\A=/ =~ opt.arg
opts.map! {|sw| sw + "="}
if arg and CompletingHash === opt.pattern
if opts = opt.pattern.candidate(arg, false, argpat)
opts.map!(&:last)
end
end
end
list.concat(opts)
end
list
end # File lib/optparse.rb, line 1499 def define(*opts, &block) top.append(*(sw = make_switch(opts, block))) sw[0] end
# File lib/optparse/kwargs.rb, line 5
def define_by_keywords(options, meth, **opts)
meth.parameters.each do |type, name|
case type
when :key, :keyreq
op, cl = *(type == :key ? %w"[ ]" : ["", ""])
define("--#{name}=#{op}#{name.upcase}#{cl}", *opts[name]) do |o|
options[name] = o
end
end
end
options
end # File lib/optparse.rb, line 1514 def define_head(*opts, &block) top.prepend(*(sw = make_switch(opts, block))) sw[0] end
# File lib/optparse.rb, line 1528 def define_tail(*opts, &block) base.append(*(sw = make_switch(opts, block))) sw[0] end
# File lib/optparse.rb, line 1872 def environment(env = File.basename($0, '.*')) env = ENV[env] || ENV[env.upcase] or return require 'shellwords' parse(*Shellwords.shellwords(env)) end
Parses environment variable env or its uppercase with splitting like a shell.
env defaults to the basename of the program.
# File lib/optparse.rb, line 1705
def getopts(*args)
argv = Array === args.first ? args.shift : default_argv
single_options, *long_options = *args
result = {}
single_options.scan(/(.)(:)?/) do |opt, val|
if val
result[opt] = nil
define("-#{opt} VAL")
else
result[opt] = false
define("-#{opt}")
end
end if single_options
long_options.each do |arg|
arg, desc = arg.split(';', 2)
opt, val = arg.split(':', 2)
if val
result[opt] = val.empty? ? nil : val
define("--#{opt}=#{result[opt] || "VAL"}", *[desc].compact)
else
result[opt] = false
define("--#{opt}", *[desc].compact)
end
end
parse_in_order(argv, result.method(:[]=))
result
end Wrapper method for getopts.rb.
params = ARGV.getopts("ab:", "foo", "bar:", "zot:Z;zot option")
# params["a"] = true # -a
# params["b"] = "1" # -b1
# params["foo"] = "1" # --foo
# params["bar"] = "x" # --bar x
# params["zot"] = "z" # --zot Z
# File lib/optparse.rb, line 1280
def help; summarize("#{banner}".sub(/\n?\z/, "\n")) end Returns option summary string.
# File lib/optparse.rb, line 1074 def inc(*args) self.class.inc(*args) end
# File lib/optparse.rb, line 1840
def load(filename = nil)
unless filename
basename = File.basename($0, '.*')
return true if load(File.expand_path(basename, '~/.options')) rescue nil
basename << ".options"
return [
# XDG
ENV['XDG_CONFIG_HOME'],
'~/.config',
*ENV['XDG_CONFIG_DIRS']&.split(File::PATH_SEPARATOR),
# Haiku
'~/config/settings',
].any? {|dir|
next if !dir or dir.empty?
load(File.expand_path(basename, dir)) rescue nil
}
end
begin
parse(*IO.readlines(filename).each {|s| s.chomp!})
true
rescue Errno::ENOENT, Errno::ENOTDIR
false
end
end Loads options from file names as filename. Does nothing when the file is not present. Returns whether successfully loaded.
filename defaults to basename of the program without suffix in a directory ~/.options, then the basename with '.options' suffix under XDG and Haiku standard places.
# File lib/optparse.rb, line 1366
def make_switch(opts, block = nil)
short, long, nolong, style, pattern, conv, not_pattern, not_conv, not_style = [], [], []
ldesc, sdesc, desc, arg = [], [], []
default_style = Switch::NoArgument
default_pattern = nil
klass = nil
q, a = nil
has_arg = false
opts.each do |o|
# argument class
next if search(:atype, o) do |pat, c|
klass = notwice(o, klass, 'type')
if not_style and not_style != Switch::NoArgument
not_pattern, not_conv = pat, c
else
default_pattern, conv = pat, c
end
end
# directly specified pattern(any object possible to match)
if (!(String === o || Symbol === o)) and o.respond_to?(:match)
pattern = notwice(o, pattern, 'pattern')
if pattern.respond_to?(:convert)
conv = pattern.method(:convert).to_proc
else
conv = SPLAT_PROC
end
next
end
# anything others
case o
when Proc, Method
block = notwice(o, block, 'block')
when Array, Hash
case pattern
when CompletingHash
when nil
pattern = CompletingHash.new
conv = pattern.method(:convert).to_proc if pattern.respond_to?(:convert)
else
raise ArgumentError, "argument pattern given twice"
end
o.each {|pat, *v| pattern[pat] = v.fetch(0) {pat}}
when Module
raise ArgumentError, "unsupported argument type: #{o}", ParseError.filter_backtrace(caller(4))
when *ArgumentStyle.keys
style = notwice(ArgumentStyle[o], style, 'style')
when /^--no-([^\[\]=\s]*)(.+)?/
q, a = $1, $2
o = notwice(a ? Object : TrueClass, klass, 'type')
not_pattern, not_conv = search(:atype, o) unless not_style
not_style = (not_style || default_style).guess(arg = a) if a
default_style = Switch::NoArgument
default_pattern, conv = search(:atype, FalseClass) unless default_pattern
ldesc << "--no-#{q}"
(q = q.downcase).tr!('_', '-')
long << "no-#{q}"
nolong << q
when /^--\[no-\]([^\[\]=\s]*)(.+)?/
q, a = $1, $2
o = notwice(a ? Object : TrueClass, klass, 'type')
if a
default_style = default_style.guess(arg = a)
default_pattern, conv = search(:atype, o) unless default_pattern
end
ldesc << "--[no-]#{q}"
(o = q.downcase).tr!('_', '-')
long << o
not_pattern, not_conv = search(:atype, FalseClass) unless not_style
not_style = Switch::NoArgument
nolong << "no-#{o}"
when /^--([^\[\]=\s]*)(.+)?/
q, a = $1, $2
if a
o = notwice(NilClass, klass, 'type')
default_style = default_style.guess(arg = a)
default_pattern, conv = search(:atype, o) unless default_pattern
end
ldesc << "--#{q}"
(o = q.downcase).tr!('_', '-')
long << o
when /^-(\[\^?\]?(?:[^\\\]]|\\.)*\])(.+)?/
q, a = $1, $2
o = notwice(Object, klass, 'type')
if a
default_style = default_style.guess(arg = a)
default_pattern, conv = search(:atype, o) unless default_pattern
else
has_arg = true
end
sdesc << "-#{q}"
short << Regexp.new(q)
when /^-(.)(.+)?/
q, a = $1, $2
if a
o = notwice(NilClass, klass, 'type')
default_style = default_style.guess(arg = a)
default_pattern, conv = search(:atype, o) unless default_pattern
end
sdesc << "-#{q}"
short << q
when /^=/
style = notwice(default_style.guess(arg = o), style, 'style')
default_pattern, conv = search(:atype, Object) unless default_pattern
else
desc.push(o)
end
end
default_pattern, conv = search(:atype, default_style.pattern) unless default_pattern
if !(short.empty? and long.empty?)
if has_arg and default_style == Switch::NoArgument
default_style = Switch::RequiredArgument
end
s = (style || default_style).new(pattern || default_pattern,
conv, sdesc, ldesc, arg, desc, block)
elsif !block
if style or pattern
raise ArgumentError, "no switch given", ParseError.filter_backtrace(caller)
end
s = desc
else
short << pattern
s = (style || default_style).new(pattern,
conv, nil, nil, arg, desc, block)
end
return s, short, long,
(not_style.new(not_pattern, not_conv, sdesc, ldesc, nil, desc, block) if not_style),
nolong
end Creates an OptionParser::Switch from the parameters. The parsed argument value is passed to the given block, where it can be processed.
See at the beginning of OptionParser for some full examples.
opts can include the following elements:
One of the following:
:NONE, :REQUIRED, :OPTIONAL
Acceptable option argument format, must be pre-defined with OptionParser.accept or OptionParser#accept, or Regexp. This can appear once or assigned as String if not present, otherwise causes an ArgumentError. Examples:
Float, Time, Array
[:text, :binary, :auto]
%w[iso-2022-jp shift_jis euc-jp utf8 binary]
{ "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
Specifies a long style switch which takes a mandatory, optional or no argument. It's a string of the following form:
"--switch=MANDATORY" or "--switch MANDATORY" "--switch[=OPTIONAL]" "--switch"
Specifies short style switch which takes a mandatory, optional or no argument. It's a string of the following form:
"-xMANDATORY" "-x[OPTIONAL]" "-x"
There is also a special form which matches character range (not full set of regular expression):
"-[a-z]MANDATORY" "-[a-z][OPTIONAL]" "-[a-z]"
Instead of specifying mandatory or optional arguments directly in the switch parameter, this separate parameter can be used.
"=MANDATORY" "=[OPTIONAL]"
Description string for the option.
"Run verbosely"
If you give multiple description strings, each string will be printed line by line.
Handler for the parsed argument value. Either give a block or pass a Proc or Method as an argument.
# File lib/optparse.rb, line 1245
def new
@stack.push(List.new)
if block_given?
yield self
else
self
end
end Pushes a new List.
# File lib/optparse.rb, line 1508 def on(*opts, &block) define(*opts, &block) self end
Add option switch and handler. See make_switch for an explanation of parameters.
# File lib/optparse.rb, line 1522 def on_head(*opts, &block) define_head(*opts, &block) self end
Add option switch like with on, but at head of summary.
# File lib/optparse.rb, line 1536 def on_tail(*opts, &block) define_tail(*opts, &block) self end
Add option switch like with on, but at tail of summary.
# File lib/optparse.rb, line 1558 def order(*argv, into: nil, &nonopt) argv = argv[0].dup if argv.size == 1 and Array === argv[0] order!(argv, into: into, &nonopt) end
Parses command line arguments argv in order. When a block is given, each non-option argument is yielded. When optional into keyword argument is provided, the parsed option values are stored there via []= method (so it can be Hash, or OpenStruct, or other similar object).
Returns the rest of argv left unparsed.
# File lib/optparse.rb, line 1567
def order!(argv = default_argv, into: nil, &nonopt)
setter = ->(name, val) {into[name.to_sym] = val} if into
parse_in_order(argv, setter, &nonopt)
end Same as order, but removes switches destructively. Non-option arguments remain in argv.
# File lib/optparse.rb, line 1678 def parse(*argv, into: nil) argv = argv[0].dup if argv.size == 1 and Array === argv[0] parse!(argv, into: into) end
Parses command line arguments argv in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise. When optional into keyword argument is provided, the parsed option values are stored there via []= method (so it can be Hash, or OpenStruct, or other similar object).
# File lib/optparse.rb, line 1687
def parse!(argv = default_argv, into: nil)
if ENV.include?('POSIXLY_CORRECT')
order!(argv, into: into)
else
permute!(argv, into: into)
end
end Same as parse, but removes switches destructively. Non-option arguments remain in argv.
# File lib/optparse.rb, line 1655 def permute(*argv, into: nil) argv = argv[0].dup if argv.size == 1 and Array === argv[0] permute!(argv, into: into) end
Parses command line arguments argv in permutation mode and returns list of non-option arguments. When optional into keyword argument is provided, the parsed option values are stored there via []= method (so it can be Hash, or OpenStruct, or other similar object).
# File lib/optparse.rb, line 1664 def permute!(argv = default_argv, into: nil) nonopts = [] order!(argv, into: into, &nonopts.method(:<<)) argv[0, 0] = nonopts argv end
Same as permute, but removes switches destructively. Non-option arguments remain in argv.
# File lib/optparse.rb, line 1180 def program_name @program_name || File.basename($0, '.*') end
Program name to be emitted in error message and default banner, defaults to $0.
# File lib/optparse.rb, line 1139 def reject(*args, &blk) top.reject(*args, &blk) end
Directs to reject specified class argument.
t Argument class specifier, any object including Class.
reject(t)
# File lib/optparse.rb, line 1205 def release (defined?(@release) && @release) || (defined?(::Release) && ::Release) || (defined?(::RELEASE) && ::RELEASE) end
Release code
# File lib/optparse.rb, line 1257 def remove @stack.pop end
Removes the last List.
# File lib/optparse.rb, line 1545 def separator(string) top.append(string, nil, nil) end
Add separator in summary.
# File lib/optparse.rb, line 1270
def summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
nl = "\n"
blk ||= proc {|l| to << (l.index(nl, -1) ? l : l + nl)}
visit(:summarize, {}, {}, width, max, indent, &blk)
to
end Puts option summary into to and returns to. Yields each line if a block is given.
to Output destination, which must have method <<. Defaults to [].
width Width of left side, defaults to @summary_width.
max Maximum length allowed for left side, defaults to width - 1.
indent Indentation, defaults to @summary_indent.
# File lib/optparse.rb, line 1107 def terminate(arg = nil) self.class.terminate(arg) end
Terminates option parsing. Optional parameter arg is a string pushed back to be the first non-option argument.
# File lib/optparse.rb, line 1286
def to_a; summarize("#{banner}".split(/^/)) end Returns option summary list.
# File lib/optparse.rb, line 1212
def ver
if v = version
str = +"#{program_name} #{[v].join('.')}"
str << " (#{v})" if v = release
str
end
end Returns version string from program_name, version and release.
# File lib/optparse.rb, line 1198 def version (defined?(@version) && @version) || (defined?(::Version) && ::Version) end
Version
# File lib/optparse.rb, line 1220
def warn(mesg = $!)
super("#{program_name}: #{mesg}")
end Kernel#warn # File lib/optparse.rb, line 1776
def complete(typ, opt, icase = false, *pat)
if pat.empty?
search(typ, opt) {|sw| return [sw, opt]} # exact match or...
end
ambiguous = catch(:ambiguous) {
visit(:complete, typ, opt, icase, *pat) {|o, *sw| return sw}
}
exc = ambiguous ? AmbiguousOption : InvalidOption
raise exc.new(opt, additional: self.method(:additional_message).curry[typ])
end Completes shortened long style option switch and returns pair of canonical switch and switch descriptor OptionParser::Switch.
typ Searching table.
opt Searching key.
icase Search case insensitive if true.
pat Optional pattern for completion.
# File lib/optparse.rb, line 1296
def notwice(obj, prv, msg)
unless !prv or prv == obj
raise(ArgumentError, "argument #{msg} given twice: #{obj}",
ParseError.filter_backtrace(caller(2)))
end
obj
end Checks if an argument is given twice, in which case an ArgumentError is raised. Called from OptionParser#switch only.
obj New argument.
prv Previously specified argument.
msg Exception message.
# File lib/optparse.rb, line 1759
def search(id, key)
block_given = block_given?
visit(:search, id, key) do |k|
return block_given ? yield(k) : k
end
end Searches key in @stack for id hash and returns or yields the result.
# File lib/optparse.rb, line 1748
def visit(id, *args, &block)
@stack.reverse_each do |el|
el.send(id, *args, &block)
end
nil
end Traverses @stack, sending each element method id with args and block.
Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.