Class: OptionParser
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Exceptions:
| |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Inherits: | Object |
Defined in: | lib/optparse.rb |
Overview
Introduction
OptionParser
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.
Features
-
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.
Minimal example
require 'optparse'
= {}
OptionParser.new do |opts|
opts. = "Usage: example.rb [options]"
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
[:verbose] = v
end
end.parse!
p
p ARGV
Generating Help
OptionParser
can be used to automatically generate help for the commands you write:
require 'optparse'
Options = Struct.new(:name)
class Parser
def self.parse( )
args = Options.new("world")
opt_parser = OptionParser.new do |opts|
opts. = "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!( )
return args
end
end
= Parser.parse %w[--help]
#=>
# Usage: example.rb [options]
# -n, --name=NAME Name to say hello to
# -h, --help Prints this help
Required Arguments
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'
= {}
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:
bash-3.2$ ruby optparse-test.rb -r
optparse-test.rb:9:in `<main>': missing argument: -r (OptionParser::MissingArgument)
bash-3.2$ ruby optparse-test.rb -r my-library
You required my-library!
Type Coercion
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
orTime.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 tofalse
-
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 soon.
Using Built-in Conversions
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:
bash-3.2$ ruby optparse-test.rb -t nonsense
#... invalid argument: -t nonsense (OptionParser::InvalidArgument)
from ... time.rb:5:in `block in <top (required)>'
from optparse-test.rb:31:in `<main>'
bash-3.2$ ruby optparse-test.rb -t 10-11-12
2010-11-12 00:00:00 -0500
bash-3.2$ ruby optparse-test.rb -t 9:30
2014-08-13 09:30:00 -0400
Creating Custom Conversions
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!
output:
bash-3.2$ ruby optparse-test.rb --user 1
#<struct User id=1, name="Sam">
bash-3.2$ ruby optparse-test.rb --user 2
#<struct User id=2, name="Gandalf">
bash-3.2$ ruby optparse-test.rb --user 3
optparse-test.rb:15:in `block in find_user': No User Found for id 3 (RuntimeError)
Complete example
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 (parser)
parser. = "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. (parser)
parser.parse!(args)
end
@options
end
attr_reader :parser, :
end # class OptparseExample
example = OptparseExample.new
= example.parse(ARGV)
pp # example.options
pp ARGV
Shell Completion
For modern shells (e.g. bash, zsh, etc.), you can use shell completion for command line options.
Further documentation
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.
Constant Summary
-
DecimalInteger =
Decimal integer format, to be converted to Integer.
/\A[-+]?#{decimal}\z/io
-
DecimalNumeric =
Decimal integer/float number format, to be converted to Integer for integer format, Float for float format.
floatpat
-
OctalInteger =
Ruby/C like octal/hexadecimal/binary integer format, to be converted to Integer.
/\A[-]?(?:[0-7](?:_[0-7]+)*|0(?:#{binary}|#{hex}))\z/io
Class Method Summary
-
.accept(*args, &blk)
See #accept.
- .each_const(path, base = ::Object)
-
.getopts(*args)
See #getopts.
-
.inc(arg, default = nil)
Returns an incremented value of
default
according toarg
. -
.new(banner = nil, width = 32, indent = ' ' * 4) {|_self| ... } ⇒ OptionParser
constructor
Initializes the instance and yields itself if called with a block.
-
.reject(*args, &blk)
See #reject.
- .search_const(klass, name)
- .show_version(*pkgs)
- .terminate(arg = nil)
- .top
-
.with(*args, &block)
Initializes a new instance and evaluates the optional block in context of the instance.
Instance Attribute Summary
-
#banner
rw
Heading banner preceding summary.
-
#banner=(value)
(also: #set_banner)
rw
Heading banner preceding summary.
-
#default_argv
rw
Strings to be parsed in default.
-
#program_name
rw
Program name to be emitted in error message and default banner, defaults to $0.
-
#program_name=(value)
(also: #set_program_name)
rw
Program name to be emitted in error message and default banner, defaults to $0.
-
#release
rw
Release code.
-
#release=(value)
rw
Release code.
-
#summary_indent
rw
Indentation for summary.
-
#summary_width
rw
Width for option list portion of summary.
-
#version
rw
Version.
-
#version=(value)
rw
Version.
Instance Method Summary
- #abort(mesg = $!)
-
#accept(*args, &blk)
Directs to accept specified class
t
. -
#base
Subject of #on_tail.
- #candidate(word)
-
#def_head_option(*opts, &block)
Alias for #define_head.
-
#def_option(*opts, &block)
Alias for #define.
-
#def_tail_option(*opts, &block)
Alias for #define_tail.
- #define(*opts, &block) (also: #def_option)
- #define_head(*opts, &block) (also: #def_head_option)
- #define_tail(*opts, &block) (also: #def_tail_option)
-
#environment(env = File.basename($0, '.*'))
Parses environment variable
env
or its uppercase with splitting like a shell. -
#getopts(*args)
Wrapper method for getopts.rb.
-
#help
(also: #to_s)
Returns option summary string.
- #inc(*args)
-
#load(filename = nil)
Loads options from file names as
filename
. -
#make_switch(opts, block = nil)
Creates an Switch from the parameters.
-
#new
Pushes a new List.
-
#on(*opts, &block)
Add option switch and handler.
-
#on_head(*opts, &block)
Add option switch like with #on, but at head of summary.
-
#on_tail(*opts, &block)
Add option switch like with #on, but at tail of summary.
-
#order(*argv, &block)
Parses command line arguments
argv
in order. -
#order!(argv = default_argv, &nonopt)
Same as #order, but removes switches destructively.
-
#parse(*argv)
Parses command line arguments
argv
in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise. -
#parse!(argv = default_argv)
Same as #parse, but removes switches destructively.
-
#permute(*argv)
Parses command line arguments
argv
in permutation mode and returns list of non-option arguments. -
#permute!(argv = default_argv)
Same as #permute, but removes switches destructively.
-
#reject(*args, &blk)
Directs to reject specified class argument.
-
#remove
Removes the last List.
-
#separator(string)
Add separator in summary.
-
#summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
Puts option summary into
to
and returnsto
. -
#terminate(arg = nil)
Terminates option parsing.
-
#to_a
Returns option summary list.
-
#to_s
Alias for #help.
- #top
-
#ver
Returns version string from program_name, version and release.
- #warn(mesg = $!)
-
#complete(typ, opt, icase = false, *pat)
private
Completes shortened long style option switch and returns pair of canonical switch and switch descriptor Switch.
-
#notwice(obj, prv, msg)
private
Checks if an argument is given twice, in which case an ArgumentError is raised.
-
#search(id, key)
private
Searches
key
in @stack forid
hash and returns or yields the result. -
#visit(id, *args, &block)
private
Traverses @stack, sending each element method
id
withargs
andblock
.
Constructor Details
.new(banner = nil, width = 32, indent = ' ' * 4) {|_self| ... } ⇒ OptionParser
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 1054
def initialize( = nil, width = 32, indent = ' ' * 4) @stack = [DefaultList, List.new, List.new] @program_name = nil @banner = @summary_width = width @summary_indent = indent @default_argv = ARGV add_officious yield self if block_given? end
Class Method Details
.accept(*args, &blk)
See #accept.
# File 'lib/optparse.rb', line 1099
def self.accept(*args, &blk) top.accept(*args, &blk) end
.each_const(path, base = ::Object)
[ GitHub ].getopts(*args)
See #getopts.
# File 'lib/optparse.rb', line 1691
def self.getopts(*args) new.getopts(*args) end
.inc(arg, default = nil)
Returns an incremented value of default
according to arg
.
# File 'lib/optparse.rb', line 1035
def self.inc(arg, default = nil) case arg when Integer arg.nonzero? when nil default.to_i + 1 end end
.reject(*args, &blk)
See #reject.
# File 'lib/optparse.rb', line 1112
def self.reject(*args, &blk) top.reject(*args, &blk) end
.search_const(klass, name)
[ GitHub ]# 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
.show_version(*pkgs)
[ GitHub ]# File 'lib/optparse/version.rb', line 5
def show_version(*pkgs) progname = ARGV. .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
.terminate(arg = nil)
[ GitHub ]# File 'lib/optparse.rb', line 1079
def self.terminate(arg = nil) throw :terminate, arg end
.top
[ GitHub ]# File 'lib/optparse.rb', line 1084
def self.top() DefaultList end
.with(*args, &block)
# File 'lib/optparse.rb', line 1026
def self.with(*args, &block) opts = new(*args) opts.instance_eval(&block) opts end
Instance Attribute Details
#banner (rw)
Heading banner preceding summary.
# File 'lib/optparse.rb', line 1137
def unless @banner @banner = "Usage: #{program_name} [options]" visit(:, @banner) end @banner end
#banner=(value) (rw) Also known as: #set_banner
Heading banner preceding summary.
# File 'lib/optparse.rb', line 1119
attr_writer :
#default_argv (rw)
Strings to be parsed in default.
# File 'lib/optparse.rb', line 1132
attr_accessor :default_argv
#program_name (rw)
Program name to be emitted in error message and default banner, defaults to $0.
# File 'lib/optparse.rb', line 1149
def program_name @program_name || File.basename($0, '.*') end
#program_name=(value) (rw) Also known as: #set_program_name
Program name to be emitted in error message and default banner, defaults to $0.
# File 'lib/optparse.rb', line 1123
attr_writer :program_name
#release (rw)
Release code
# File 'lib/optparse.rb', line 1174
def release @release || (defined?(::Release) && ::Release) || (defined?(::RELEASE) && ::RELEASE) end
#release=(value) (rw)
Release code
# File 'lib/optparse.rb', line 1162
attr_writer :release
#summary_indent (rw)
Indentation for summary. Must be String (or have + String method).
# File 'lib/optparse.rb', line 1129
attr_accessor :summary_indent
#summary_width (rw)
Width for option list portion of summary. Must be Numeric.
# File 'lib/optparse.rb', line 1126
attr_accessor :summary_width
#version (rw)
Version
# File 'lib/optparse.rb', line 1167
def version @version || (defined?(::Version) && ::Version) end
#version=(value) (rw)
Version
# File 'lib/optparse.rb', line 1160
attr_writer :version
Instance Method Details
#abort(mesg = $!)
[ GitHub ]# File 'lib/optparse.rb', line 1193
def abort(mesg = $!) super("#{program_name}: #{mesg}") end
#accept(*args, &blk)
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 1095
def accept(*args, &blk) top.accept(*args, &blk) end
#base
Subject of #on_tail.
# File 'lib/optparse.rb', line 1207
def base @stack[1] end
#candidate(word)
[ GitHub ]# File 'lib/optparse.rb', line 1738
def candidate(word) list = [] case word when /\A--/ word, arg = word.split(/=/, 2) argpat = Completion.regexp(arg, false) if arg and !arg.empty? long = true when /\A-(!-)/ short = true when /\A-/ long = short = true end pat = Completion.regexp(word, true) 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
#complete(typ, opt, icase = false, *pat) (private)
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 1727
def complete(typ, opt, icase = false, *pat) if pat.empty? search(typ, opt) {|sw| return [sw, opt]} # exact match or... end raise AmbiguousOption, catch(:ambiguous) { visit(:complete, typ, opt, icase, *pat) {|o, *sw| return sw} raise InvalidOption, opt } end
#def_head_option(*opts, &block)
Alias for #define_head.
# File 'lib/optparse.rb', line 1489
alias def_head_option define_head
#def_option(*opts, &block)
Alias for #define.
# File 'lib/optparse.rb', line 1475
alias def_option define
#def_tail_option(*opts, &block)
Alias for #define_tail.
# File 'lib/optparse.rb', line 1503
alias def_tail_option define_tail
#define(*opts, &block) Also known as: #def_option
[ GitHub ]# File 'lib/optparse.rb', line 1462
def define(*opts, &block) top.append(*(sw = make_switch(opts, block))) sw[0] end
#define_head(*opts, &block) Also known as: #def_head_option
[ GitHub ]# File 'lib/optparse.rb', line 1477
def define_head(*opts, &block) top.prepend(*(sw = make_switch(opts, block))) sw[0] end
#define_tail(*opts, &block) Also known as: #def_tail_option
[ GitHub ]# File 'lib/optparse.rb', line 1491
def define_tail(*opts, &block) base.append(*(sw = make_switch(opts, block))) sw[0] end
#environment(env = File.basename($0, '.*'))
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 1795
def environment(env = File.basename($0, '.*')) env = ENV[env] || ENV[env.upcase] or return require 'shellwords' parse(*Shellwords.shellwords(env)) end
#getopts(*args)
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 1656
def getopts(*args) argv = Array === args.first ? args.shift : default_argv , * = *args result = {} .scan(/(.)(:)?/) do |opt, val| if val result[opt] = nil define("-#{opt} VAL") else result[opt] = false define("-#{opt}") end end if .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
#help Also known as: #to_s
Returns option summary string.
# File 'lib/optparse.rb', line 1248
def help; summarize("#{}".sub(/\n?\z/, "\n")) end
#inc(*args)
[ GitHub ]# File 'lib/optparse.rb', line 1043
def inc(*args) self.class.inc(*args) end
#load(filename = nil)
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.
# File 'lib/optparse.rb', line 1775
def load(filename = nil) begin filename ||= File. (File.basename($0, '.*'), '~/.options') rescue return false end begin parse(*IO.readlines(filename).each {|s| s.chomp!}) true rescue Errno::ENOENT, Errno::ENOTDIR false end end
#make_switch(opts, block = nil)
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:
- Argument style:
-
One of the following:
:NONE, :REQUIRED, :OPTIONAL
- Argument pattern:
-
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
- Possible argument values:
-
Hash or Array.
[:text, :binary, :auto] %w[iso-2022-jp shift_jis euc-jp utf8 binary] { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
- Long style switch:
-
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"
- Short style 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]"
- Argument style and description:
-
Instead of specifying mandatory or optional arguments directly in the switch parameter, this separate parameter can be used.
"=MANDATORY" "=[OPTIONAL]"
- Description:
-
Description string for the option.
"Run verbosely"
- Handler:
-
Handler for the parsed argument value. Either give a block or pass a Proc or Method as an argument.
# File 'lib/optparse.rb', line 1332
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}" long << 'no-' + (q = q.downcase) 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}" long << (o = q.downcase) 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}" long << (o = q.downcase) 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
#new
Pushes a new ::OptionParser::List.
#notwice(obj, prv, msg) (private)
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 1264
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
#on(*opts, &block)
Add option switch and handler. See #make_switch for an explanation of parameters.
# File 'lib/optparse.rb', line 1471
def on(*opts, &block) define(*opts, &block) self end
#on_head(*opts, &block)
Add option switch like with #on, but at head of summary.
# File 'lib/optparse.rb', line 1485
def on_head(*opts, &block) define_head(*opts, &block) self end
#on_tail(*opts, &block)
Add option switch like with #on, but at tail of summary.
# File 'lib/optparse.rb', line 1499
def on_tail(*opts, &block) define_tail(*opts, &block) self end
#order(*argv, &block)
Parses command line arguments argv
in order. When a block is given, each non-option argument is yielded.
Returns the rest of argv
left unparsed.
# File 'lib/optparse.rb', line 1518
def order(*argv, &block) argv = argv[0].dup if argv.size == 1 and Array === argv[0] order!(argv, &block) end
#order!(argv = default_argv, &nonopt)
Same as #order, but removes switches destructively. Non-option arguments remain in argv
.
# File 'lib/optparse.rb', line 1527
def order!(argv = default_argv, &nonopt) parse_in_order(argv, &nonopt) end
#parse(*argv)
Parses command line arguments argv
in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise.
# File 'lib/optparse.rb', line 1629
def parse(*argv) argv = argv[0].dup if argv.size == 1 and Array === argv[0] parse!(argv) end
#parse!(argv = default_argv)
Same as #parse, but removes switches destructively. Non-option arguments remain in argv
.
# File 'lib/optparse.rb', line 1638
def parse!(argv = default_argv) if ENV.include?('POSIXLY_CORRECT') order!(argv) else permute!(argv) end end
#permute(*argv)
Parses command line arguments argv
in permutation mode and returns list of non-option arguments.
# File 'lib/optparse.rb', line 1609
def permute(*argv) argv = argv[0].dup if argv.size == 1 and Array === argv[0] permute!(argv) end
#permute!(argv = default_argv)
Same as #permute, but removes switches destructively. Non-option arguments remain in argv
.
# File 'lib/optparse.rb', line 1618
def permute!(argv = default_argv) nonopts = [] order!(argv, &nonopts.method(:<<)) argv[0, 0] = nonopts argv end
#reject(*args, &blk)
Directs to reject specified class argument.
t
-
Argument class specifier, any object including Class.
reject(t)
# File 'lib/optparse.rb', line 1108
def reject(*args, &blk) top.reject(*args, &blk) end
#remove
Removes the last ::OptionParser::List.
# File 'lib/optparse.rb', line 1226
def remove @stack.pop end
#search(id, key) (private)
Searches key
in @stack for id
hash and returns or yields the result.
# File 'lib/optparse.rb', line 1710
def search(id, key) block_given = block_given? visit(:search, id, key) do |k| return block_given ? yield(k) : k end end
#separator(string)
Add separator in summary.
# File 'lib/optparse.rb', line 1508
def separator(string) top.append(string, nil, nil) end
#summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
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 1239
def summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk) blk ||= proc {|l| to << (l.index($/, -1) ? l : l + $/)} visit(:summarize, {}, {}, width, max, indent, &blk) to end
#terminate(arg = nil)
Terminates option parsing. Optional parameter arg
is a string pushed back to be the first non-option argument.
# File 'lib/optparse.rb', line 1076
def terminate(arg = nil) self.class.terminate(arg) end
#to_a
Returns option summary list.
# File 'lib/optparse.rb', line 1254
def to_a; summarize("#{}".split(/^/)) end
#to_s
Alias for #help.
# File 'lib/optparse.rb', line 1249
alias to_s help
#top
[ GitHub ]# File 'lib/optparse.rb', line 1200
def top @stack[-1] end
#ver
Returns version string from program_name, version and release.
# File 'lib/optparse.rb', line 1181
def ver if v = version str = "#{program_name} #{[v].join('.')}" str << " (#{v})" if v = release str end end
#visit(id, *args, &block) (private)
Traverses @stack, sending each element method id
with args
and block
.
# File 'lib/optparse.rb', line 1699
def visit(id, *args, &block) @stack.reverse_each do |el| el.send(id, *args, &block) end nil end
#warn(mesg = $!)
[ GitHub ]# File 'lib/optparse.rb', line 1189
def warn(mesg = $!) super("#{program_name}: #{mesg}") end