Class: Gem::OptionParser
- Inherits:
-
Object
- Object
- Gem::OptionParser
- Defined in:
- lib/rubygems/optparse/lib/optparse.rb,
lib/rubygems/optparse/lib/optparse/kwargs.rb
Overview
–
Developer Documentation (not for RDoc output)
Class tree
- Gem::OptionParser
-
front end
- Gem::OptionParser::Switch
-
each switches
- Gem::OptionParser::List
-
options list
- Gem::OptionParser::ParseError
-
errors on parsing
-
Gem::OptionParser::AmbiguousOption
-
Gem::OptionParser::NeedlessArgument
-
Gem::OptionParser::MissingArgument
-
Gem::OptionParser::InvalidOption
-
Gem::OptionParser::InvalidArgument
-
Gem::OptionParser::AmbiguousArgument
-
Object relationship diagram
+--------------+
| Gem::OptionParser |<>-----+
+--------------+ | +--------+
| ,-| Switch |
on_head -------->+---------------+ / +--------+
accept/reject -->| List |<|>-
| |<|>- +----------+
on ------------->+---------------+ `-| argument |
: : | class |
+---------------+ |==========|
on_tail -------->| | |pattern |
+---------------+ |----------|
Gem::OptionParser.accept ->| DefaultList | |converter |
reject |(shared between| +----------+
| all instances)|
+---------------+
++
Gem::OptionParser
New to Gem::OptionParser?
See the Tutorial.
Introduction
Gem::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 'rubygems/optparse/lib/optparse'
= {}
Gem::OptionParser.new do |parser|
parser. = "Usage: example.rb [options]"
parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
[:verbose] = v
end
end.parse!
p
p ARGV
Generating Help
Gem::OptionParser can be used to automatically generate help for the commands you write:
require 'rubygems/optparse/lib/optparse'
Options = Struct.new(:name)
class Parser
def self.parse()
args = Options.new("world")
opt_parser = Gem::OptionParser.new do |parser|
parser. = "Usage: example.rb [options]"
parser.on("-nNAME", "--name=NAME", "Name to say hello to") do |n|
args.name = n
end
parser.on("-h", "--help", "Prints this help") do
puts parser
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 'rubygems/optparse/lib/optparse'
= {}
Gem::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 (Gem::OptionParser::MissingArgument)
$ ruby optparse-test.rb -r my-library
You required my-library!
Type Coercion
Gem::OptionParser supports the ability to coerce command line arguments into objects for us.
Gem::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 below.
Using Built-in Conversions
As an example, the built-in Time
conversion is used. The other built-in conversions behave in the same way. Gem::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 'rubygems/optparse/lib/optparse'
require 'rubygems/optparse/lib/optparse/time'
Gem::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 (Gem::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
Creating Custom Conversions
The accept
method on Gem::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 'rubygems/optparse/lib/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 = Gem::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)
Store options to a Hash
The into
option of order
, parse
and so on methods stores command line options into a Hash.
require 'rubygems/optparse/lib/optparse'
= {}
Gem::OptionParser.new do |parser|
parser.on('-a')
parser.on('-b NUM', Integer)
parser.on('-v', '--verbose')
end.parse!(into: )
p
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}
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 'rubygems/optparse/lib/optparse'
require 'rubygems/optparse/lib/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]", Gem::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*.
= ScriptOptions.new
@args = Gem::OptionParser.new do |parser|
.(parser)
parser.parse!(args)
end
end
attr_reader :parser, :options
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, along with the accompanying Tutorial, should be enough to learn how to use this class. If you have any questions, file a ticket at bugs.ruby-lang.org.
Direct Known Subclasses
Defined Under Namespace
Modules: Acceptables, Arguable, Completion Classes: AC, AmbiguousArgument, AmbiguousOption, CompletingHash, InvalidArgument, InvalidOption, List, MissingArgument, NeedlessArgument, OptionMap, ParseError, Switch
Constant Summary collapse
- Version =
"0.2.0"
- NoArgument =
:stopdoc:
[NO_ARGUMENT = :NONE, nil].freeze
- RequiredArgument =
[REQUIRED_ARGUMENT = :REQUIRED, true].freeze
- OptionalArgument =
[OPTIONAL_ARGUMENT = :OPTIONAL, false].freeze
- ArgumentStyle =
Enumeration of acceptable argument styles. Possible values are:
- NO_ARGUMENT
-
The switch takes no arguments. (:NONE)
- REQUIRED_ARGUMENT
-
The switch requires an argument. (:REQUIRED)
- OPTIONAL_ARGUMENT
-
The switch requires an optional argument. (:OPTIONAL)
Use like –switch=argument (long style) or -Xargument (short style). For short style, only portion matched to argument pattern is treated as argument.
{}
- DefaultList =
Switches common used such as ‘–’, and also provides default argument classes
List.new
- COMPSYS_HEADER =
:nodoc:
"\ntypeset -A opt_args\nlocal context state line\n\n_argume\n" # :nodoc:
- Officious =
Default options for ARGV, which never appear in option summary.
{}
- SPLAT_PROC =
:nodoc:
proc {|*a| a.length <= 1 ? a.first : a}
- DecimalInteger =
Decimal integer format, to be converted to Integer.
/\A[-+]?#{decimal}\z/io
- OctalInteger =
Ruby/C like octal/hexadecimal/binary integer format, to be converted to Integer.
/\A[-+]?(?:[0-7]+(?:_[0-7]+)*|0(?:#{binary}|#{hex}))\z/io
- DecimalNumeric =
Decimal integer/float number format, to be converted to Integer for integer format, Float for float format.
floatpat
Instance Attribute Summary collapse
-
#banner ⇒ Object
Heading banner preceding summary.
-
#default_argv ⇒ Object
Strings to be parsed in default.
-
#program_name ⇒ Object
Program name to be emitted in error message and default banner, defaults to $0.
-
#release ⇒ Object
Release code.
-
#require_exact ⇒ Object
Whether to require that options match exactly (disallows providing abbreviated long option as short option).
-
#summary_indent ⇒ Object
Indentation for summary.
-
#summary_width ⇒ Object
Width for option list portion of summary.
-
#version ⇒ Object
Version.
Class Method Summary collapse
-
.accept(*args, &blk) ⇒ Object
See #accept.
- .each_const(path, base = ::Object) ⇒ Object
-
.getopts(*args) ⇒ Object
See #getopts.
-
.inc(arg, default = nil) ⇒ Object
Returns an incremented value of
default
according toarg
. -
.reject(*args, &blk) ⇒ Object
See #reject.
- .search_const(klass, name) ⇒ Object
- .show_version(*pkgs) ⇒ Object
- .terminate(arg = nil) ⇒ Object
- .top ⇒ Object
-
.with(*args, &block) ⇒ Object
Initializes a new instance and evaluates the optional block in context of the instance.
Instance Method Summary collapse
- #abort(mesg = $!) ⇒ Object
-
#accept(*args, &blk) ⇒ Object
Directs to accept specified class
t
. -
#add_officious ⇒ Object
:nodoc:.
-
#additional_message(typ, opt) ⇒ Object
Returns additional info.
-
#base ⇒ Object
Subject of #on_tail.
- #candidate(word) ⇒ Object
-
#compsys(to, name = File.basename($0)) ⇒ Object
:nodoc:.
-
#define(*opts, &block) ⇒ Object
(also: #def_option)
:call-seq: define(*params, &block).
-
#define_by_keywords(options, meth, **opts) ⇒ Object
:call-seq: define_by_keywords(options, method, **params).
-
#define_head(*opts, &block) ⇒ Object
(also: #def_head_option)
:call-seq: define_head(*params, &block).
-
#define_tail(*opts, &block) ⇒ Object
(also: #def_tail_option)
:call-seq: define_tail(*params, &block).
-
#environment(env = File.basename($0, '.*')) ⇒ Object
Parses environment variable
env
or its uppercase with splitting like a shell. -
#getopts(*args) ⇒ Object
Wrapper method for getopts.rb.
-
#help ⇒ Object
(also: #to_s)
Returns option summary string.
- #inc(*args) ⇒ Object
-
#initialize(banner = nil, width = 32, indent = ' ' * 4) {|_self| ... } ⇒ OptionParser
constructor
Initializes the instance and yields itself if called with a block.
-
#load(filename = nil) ⇒ Object
Loads options from file names as
filename
. -
#make_switch(opts, block = nil) ⇒ Object
:call-seq: make_switch(params, block = nil).
-
#new ⇒ Object
Pushes a new List.
-
#on(*opts, &block) ⇒ Object
:call-seq: on(*params, &block).
-
#on_head(*opts, &block) ⇒ Object
:call-seq: on_head(*params, &block).
-
#on_tail(*opts, &block) ⇒ Object
:call-seq: on_tail(*params, &block).
-
#order(*argv, into: nil, &nonopt) ⇒ Object
Parses command line arguments
argv
in order. -
#order!(argv = default_argv, into: nil, &nonopt) ⇒ Object
Same as #order, but removes switches destructively.
-
#parse(*argv, into: nil) ⇒ Object
Parses command line arguments
argv
in order when environment variable POSIXLY_CORRECT is set, and in permutation mode otherwise. -
#parse!(argv = default_argv, into: nil) ⇒ Object
Same as #parse, but removes switches destructively.
-
#permute(*argv, into: nil) ⇒ Object
Parses command line arguments
argv
in permutation mode and returns list of non-option arguments. -
#permute!(argv = default_argv, into: nil) ⇒ Object
Same as #permute, but removes switches destructively.
-
#reject(*args, &blk) ⇒ Object
Directs to reject specified class argument.
-
#remove ⇒ Object
Removes the last List.
-
#separator(string) ⇒ Object
Add separator in summary.
-
#summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk) ⇒ Object
Puts option summary into
to
and returnsto
. -
#terminate(arg = nil) ⇒ Object
Terminates option parsing.
-
#to_a ⇒ Object
Returns option summary list.
-
#top ⇒ Object
Subject of #on / #on_head, #accept / #reject.
-
#ver ⇒ Object
Returns version string from program_name, version and release.
- #warn(mesg = $!) ⇒ Object
Constructor Details
#initialize(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.
1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1093 def initialize( = nil, width = 32, indent = ' ' * 4) @stack = [DefaultList, List.new, List.new] @program_name = nil = @summary_width = width @summary_indent = indent @default_argv = ARGV @require_exact = false add_officious yield self if block_given? end |
Instance Attribute Details
#banner ⇒ Object
Heading banner preceding summary.
1181 1182 1183 1184 1185 1186 1187 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1181 def unless = +"Usage: #{program_name} [options]" visit(:add_banner, ) end end |
#default_argv ⇒ Object
Strings to be parsed in default.
1172 1173 1174 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1172 def default_argv @default_argv end |
#program_name ⇒ Object
Program name to be emitted in error message and default banner, defaults to $0.
1193 1194 1195 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1193 def program_name @program_name || File.basename($0, '.*') end |
#release ⇒ Object
Release code
1218 1219 1220 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1218 def release (defined?(@release) && @release) || (defined?(::Release) && ::Release) || (defined?(::RELEASE) && ::RELEASE) end |
#require_exact ⇒ Object
Whether to require that options match exactly (disallows providing abbreviated long option as short option).
1176 1177 1178 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1176 def require_exact @require_exact end |
#summary_indent ⇒ Object
Indentation for summary. Must be String (or have + String method).
1169 1170 1171 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1169 def summary_indent @summary_indent end |
#summary_width ⇒ Object
Width for option list portion of summary. Must be Numeric.
1166 1167 1168 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1166 def summary_width @summary_width end |
#version ⇒ Object
Version
1211 1212 1213 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1211 def version (defined?(@version) && @version) || (defined?(::Version) && ::Version) end |
Class Method Details
.accept(*args, &blk) ⇒ Object
See #accept.
1139 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1139 def self.accept(*args, &blk) top.accept(*args, &blk) end |
.each_const(path, base = ::Object) ⇒ Object
50 51 52 53 54 55 56 57 58 |
# File 'lib/rubygems/optparse/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 |
.getopts(*args) ⇒ Object
See #getopts.
1733 1734 1735 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1733 def self.getopts(*args) new.getopts(*args) end |
.inc(arg, default = nil) ⇒ Object
Returns an incremented value of default
according to arg
.
1074 1075 1076 1077 1078 1079 1080 1081 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1074 def self.inc(arg, default = nil) case arg when Integer arg.nonzero? when nil default.to_i + 1 end end |
.reject(*args, &blk) ⇒ Object
See #reject.
1152 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1152 def self.reject(*args, &blk) top.reject(*args, &blk) end |
.search_const(klass, name) ⇒ Object
60 61 62 63 64 65 66 67 68 69 70 |
# File 'lib/rubygems/optparse/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) ⇒ Object
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
# File 'lib/rubygems/optparse/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) ⇒ Object
1119 1120 1121 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1119 def self.terminate(arg = nil) throw :terminate, arg end |
.top ⇒ Object
1124 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1124 def self.top() DefaultList end |
.with(*args, &block) ⇒ Object
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.
1065 1066 1067 1068 1069 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1065 def self.with(*args, &block) opts = new(*args) opts.instance_eval(&block) opts end |
Instance Method Details
#abort(mesg = $!) ⇒ Object
1237 1238 1239 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1237 def abort(mesg = $!) super("#{program_name}: #{mesg}") end |
#accept(*args, &blk) ⇒ Object
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)
1135 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1135 def accept(*args, &blk) top.accept(*args, &blk) end |
#add_officious ⇒ Object
:nodoc:
1105 1106 1107 1108 1109 1110 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1105 def add_officious # :nodoc: list = base() Officious.each do |opt, block| list.long[opt] ||= block.call(self) end end |
#additional_message(typ, opt) ⇒ Object
Returns additional info.
1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1784 def (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) suggestions = all_candidates & checker.correct(opt) if DidYouMean.respond_to?(:formatter) DidYouMean.formatter.(suggestions) else "\nDid you mean? #{suggestions.join("\n ")}" end end |
#base ⇒ Object
Subject of #on_tail.
1251 1252 1253 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1251 def base @stack[1] end |
#candidate(word) ⇒ Object
1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1800 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 |
#compsys(to, name = File.basename($0)) ⇒ Object
:nodoc:
982 983 984 985 986 987 988 989 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 982 def compsys(to, name = File.basename($0)) # :nodoc: to << "#compdef #{name}\n" to << COMPSYS_HEADER visit(:compsys, {}, {}) {|o, d| to << %Q[ "#{o}[#{d.gsub(/[\"\[\]]/, '\\\\\&')}]" \\\n] } to << " '*:file:_files' && return 0\n" end |
#define(*opts, &block) ⇒ Object Also known as: def_option
:call-seq:
define(*params, &block)
:include: ../doc/optparse/creates_option.rdoc
1463 1464 1465 1466 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1463 def define(*opts, &block) top.append(*(sw = make_switch(opts, block))) sw[0] end |
#define_by_keywords(options, meth, **opts) ⇒ Object
:call-seq:
define_by_keywords(, method, **params)
:include: ../../doc/optparse/creates_option.rdoc
10 11 12 13 14 15 16 17 18 19 20 21 |
# File 'lib/rubygems/optparse/lib/optparse/kwargs.rb', line 10 def define_by_keywords(, 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| [name] = o end end end end |
#define_head(*opts, &block) ⇒ Object Also known as: def_head_option
:call-seq:
define_head(*params, &block)
:include: ../doc/optparse/creates_option.rdoc
1484 1485 1486 1487 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1484 def define_head(*opts, &block) top.prepend(*(sw = make_switch(opts, block))) sw[0] end |
#define_tail(*opts, &block) ⇒ Object Also known as: def_tail_option
:call-seq:
define_tail(*params, &block)
:include: ../doc/optparse/creates_option.rdoc
1507 1508 1509 1510 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1507 def define_tail(*opts, &block) base.append(*(sw = make_switch(opts, block))) sw[0] end |
#environment(env = File.basename($0, '.*')) ⇒ Object
Parses environment variable env
or its uppercase with splitting like a shell.
env
defaults to the basename of the program.
1870 1871 1872 1873 1874 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1870 def environment(env = File.basename($0, '.*')) env = ENV[env] || ENV[env.upcase] or return require 'shellwords' parse(*Shellwords.shellwords(env)) end |
#getopts(*args) ⇒ Object
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
1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1698 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 ⇒ Object Also known as: to_s
Returns option summary string.
1293 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1293 def help; summarize("#{banner}".sub(/\n?\z/, "\n")) end |
#inc(*args) ⇒ Object
1082 1083 1084 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1082 def inc(*args) self.class.inc(*args) end |
#load(filename = nil) ⇒ Object
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.
1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1838 def load(filename = nil) unless filename basename = File.basename($0, '.*') return true if load(File.(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.(basename, dir)) rescue nil } end begin parse(*IO.readlines(filename).each {|s| s.chomp!}) true rescue Errno::ENOENT, Errno::ENOTDIR false end end |
#make_switch(opts, block = nil) ⇒ Object
:call-seq:
make_switch(params, block = nil)
:include: ../doc/optparse/creates_option.rdoc
1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1325 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 |
#new ⇒ Object
Pushes a new List.
1258 1259 1260 1261 1262 1263 1264 1265 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1258 def new @stack.push(List.new) if block_given? yield self else self end end |
#on(*opts, &block) ⇒ Object
:call-seq:
on(*params, &block)
:include: ../doc/optparse/creates_option.rdoc
1473 1474 1475 1476 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1473 def on(*opts, &block) define(*opts, &block) self end |
#on_head(*opts, &block) ⇒ Object
:call-seq:
on_head(*params, &block)
:include: ../doc/optparse/creates_option.rdoc
The new option is added at the head of the summary.
1496 1497 1498 1499 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1496 def on_head(*opts, &block) define_head(*opts, &block) self end |
#on_tail(*opts, &block) ⇒ Object
:call-seq:
on_tail(*params, &block)
:include: ../doc/optparse/creates_option.rdoc
The new option is added at the tail of the summary.
1520 1521 1522 1523 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1520 def on_tail(*opts, &block) define_tail(*opts, &block) self end |
#order(*argv, into: nil, &nonopt) ⇒ Object
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.
1542 1543 1544 1545 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1542 def order(*argv, into: nil, &nonopt) argv = argv[0].dup if argv.size == 1 and Array === argv[0] order!(argv, into: into, &nonopt) end |
#order!(argv = default_argv, into: nil, &nonopt) ⇒ Object
Same as #order, but removes switches destructively. Non-option arguments remain in argv
.
1551 1552 1553 1554 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1551 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 |
#parse(*argv, into: nil) ⇒ Object
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).
1671 1672 1673 1674 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1671 def parse(*argv, into: nil) argv = argv[0].dup if argv.size == 1 and Array === argv[0] parse!(argv, into: into) end |
#parse!(argv = default_argv, into: nil) ⇒ Object
Same as #parse, but removes switches destructively. Non-option arguments remain in argv
.
1680 1681 1682 1683 1684 1685 1686 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1680 def parse!(argv = default_argv, into: nil) if ENV.include?('POSIXLY_CORRECT') order!(argv, into: into) else permute!(argv, into: into) end end |
#permute(*argv, into: nil) ⇒ Object
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).
1648 1649 1650 1651 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1648 def permute(*argv, into: nil) argv = argv[0].dup if argv.size == 1 and Array === argv[0] permute!(argv, into: into) end |
#permute!(argv = default_argv, into: nil) ⇒ Object
Same as #permute, but removes switches destructively. Non-option arguments remain in argv
.
1657 1658 1659 1660 1661 1662 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1657 def permute!(argv = default_argv, into: nil) nonopts = [] order!(argv, into: into, &nonopts.method(:<<)) argv[0, 0] = nonopts argv end |
#reject(*args, &blk) ⇒ Object
Directs to reject specified class argument.
t
-
Argument class specifier, any object including Class.
reject(t)
1148 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1148 def reject(*args, &blk) top.reject(*args, &blk) end |
#remove ⇒ Object
Removes the last List.
1270 1271 1272 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1270 def remove @stack.pop end |
#separator(string) ⇒ Object
Add separator in summary.
1529 1530 1531 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1529 def separator(string) top.append(string, nil, nil) end |
#summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk) ⇒ Object
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.
1283 1284 1285 1286 1287 1288 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1283 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 |
#terminate(arg = nil) ⇒ Object
Terminates option parsing. Optional parameter arg
is a string pushed back to be the first non-option argument.
1116 1117 1118 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1116 def terminate(arg = nil) self.class.terminate(arg) end |
#to_a ⇒ Object
Returns option summary list.
1299 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1299 def to_a; summarize("#{banner}".split(/^/)) end |
#top ⇒ Object
Subject of #on / #on_head, #accept / #reject
1244 1245 1246 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1244 def top @stack[-1] end |
#ver ⇒ Object
Returns version string from program_name, version and release.
1225 1226 1227 1228 1229 1230 1231 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1225 def ver if v = version str = +"#{program_name} #{[v].join('.')}" str << " (#{v})" if v = release str end end |
#warn(mesg = $!) ⇒ Object
1233 1234 1235 |
# File 'lib/rubygems/optparse/lib/optparse.rb', line 1233 def warn(mesg = $!) super("#{program_name}: #{mesg}") end |