class Ncio::Trollop::Parser
The commandline parser. In typical usage, the methods in this class will be handled internally by Trollop::options
. In this case, only the opt
, banner
and version
, depends
, and conflicts
methods will typically be called.
If you want to instantiate this class yourself (for more complicated argument-parsing logic), call parse
to actually produce the output hash, and consider calling it from within Trollop::with_standard_exception_handling
.
Constants
- FLAG_TYPES
The set of values that indicate a flag option when passed as the
:type
parameter ofopt
.- MULTI_ARG_TYPES
The set of values that indicate a multiple-parameter option (i.e., that takes multiple space-separated values on the commandline) when passed as the
:type
parameter ofopt
.- SINGLE_ARG_TYPES
The set of values that indicate a single-parameter (normal) option when passed as the
:type
parameter ofopt
.A value of
io
corresponds to a readable IO resource, including a filename, URI, or the strings 'stdin' or '-'.- TYPES
The complete set of legal values for the
:type
parameter ofopt
.
Attributes
A flag that determines whether or not to raise an error if the parser is passed one or more
options that were not registered ahead of time. If 'true', then the parser will simply ignore options that it does not recognize.
The values from the commandline that were not interpreted by parse
.
The complete configuration hashes for each option. (Mainly useful for testing.)
Public Class Methods
Initializes the parser, and instance-evaluates any block given.
# File lib/ncio/trollop.rb, line 85 def initialize(*a, &b) @version = nil @leftovers = [] @specs = {} @long = {} @short = {} @order = [] @constraints = [] @stop_words = [] @stop_on_unknown = false @educate_on_error = false # instance_eval(&b) if b # can't take arguments cloaker(&b).bind(self).call(*a) if b end
Public Instance Methods
Marks two (or more!) options as conflicting.
# File lib/ncio/trollop.rb, line 291 def conflicts(*syms) syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] } @constraints << [:conflicts, syms] end
Marks two (or more!) options as requiring each other. Only handles undirected (i.e., mutual) dependencies. Directed dependencies are better modeled with Trollop::die
.
# File lib/ncio/trollop.rb, line 285 def depends(*syms) syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] } @constraints << [:depends, syms] end
The per-parser version of Trollop::die
(see that for documentation).
# File lib/ncio/trollop.rb, line 581 def die(arg, msg = nil, error_code = nil) if msg $stderr.puts "Error: argument --#{@specs[arg][:long]} #{msg}." else $stderr.puts "Error: #{arg}." end if @educate_on_error $stderr.puts educate $stderr else $stderr.puts "Try --help for help." end exit(error_code || -1) end
Print the help message to stream
.
# File lib/ncio/trollop.rb, line 477 def educate(stream = $stdout) width # hack: calculate it now; otherwise we have to be careful not to # call this unless the cursor's at the beginning of a line. left = {} @specs.each do |name, spec| left[name] = (spec[:short] && spec[:short] != :none ? "-#{spec[:short]}" : "") + (spec[:short] && spec[:short] != :none ? ", " : "") + "--#{spec[:long]}" + case spec[:type] when :flag then "" when :int then "=<i>" when :ints then "=<i+>" when :string then "=<s>" when :strings then "=<s+>" when :float then "=<f>" when :floats then "=<f+>" when :io then "=<filename/uri>" when :ios then "=<filename/uri+>" when :date then "=<date>" when :dates then "=<date+>" end + (spec[:type] == :flag && spec[:default] ? ", --no-#{spec[:long]}" : "") end leftcol_width = left.values.map(&:length).max || 0 rightcol_start = leftcol_width + 6 # spaces unless @order.size > 0 && @order.first.first == :text command_name = File.basename($0).gsub(/\.[^.]+$/, '') stream.puts "Usage: #{command_name} #{@usage}\n" if @usage stream.puts "#{@synopsis}\n" if @synopsis stream.puts if @usage || @synopsis stream.puts "#{@version}\n" if @version stream.puts "Options:" end @order.each do |what, opt| if what == :text stream.puts wrap(opt) next end spec = @specs[opt] stream.printf " %-#{leftcol_width}s ", left[opt] desc = spec[:desc] + begin default_s = case spec[:default] when $stdout then "<stdout>" when $stdin then "<stdin>" when $stderr then "<stderr>" when Array spec[:default].join(", ") else spec[:default].to_s end if spec[:default] if spec[:desc] =~ /\.$/ " (Default: #{default_s})" else " (default: #{default_s})" end else "" end end stream.puts wrap(desc, :width => width - rightcol_start - 1, :prefix => rightcol_start) end end
Instead of displaying “Try –help for help.” on an error display the usage (via educate)
# File lib/ncio/trollop.rb, line 319 def educate_on_error @educate_on_error = true end
Define an option. name
is the option name, a unique identifier for the option that you will use internally, which should be a symbol or a string. desc
is a string description which will be displayed in help messages.
Takes the following optional arguments:
:long
-
Specify the long form of the argument, i.e. the form with two dashes. If unspecified, will be automatically derived based on the argument name by turning the
name
option into a string, and replacing any _'s by -'s. :short
-
Specify the short form of the argument, i.e. the form with one dash. If unspecified, will be automatically derived from
name
. Use :none: to not have a short value. :type
-
Require that the argument take a parameter or parameters of type
type
. For a single parameter, the value can be a member ofSINGLE_ARG_TYPES
, or a corresponding Ruby class (e.g.Integer
for:int
). For multiple-argument parameters, the value can be any member ofMULTI_ARG_TYPES
constant. If unset, the default argument type is:flag
, meaning that the argument does not take a parameter. The specification of:type
is not necessary if a:default
is given. :default
-
Set the default value for an argument. Without a default value, the hash returned by
parse
(and thusTrollop::options
) will have anil
value for this key unless the argument is given on the commandline. The argument type is derived automatically from the class of the default value given, so specifying a:type
is not necessary if a:default
is given. (But see below for an important caveat when:multi
: is specified too.) If the argument is a flag, and the default is set totrue
, then if it is specified on the the commandline the value will befalse
. :required
-
If set to
true
, the argument must be provided on the commandline. :multi
-
If set to
true
, allows multiple occurrences of the option on the commandline. Otherwise, only a single instance of the option is allowed. (Note that this is different from taking multiple parameters. See below.)
Note that there are two types of argument multiplicity: an argument can take multiple values, e.g. “–arg 1 2 3”. An argument can also be allowed to occur multiple times, e.g. “–arg 1 –arg 2”.
Arguments that take multiple values should have a :type
parameter drawn from MULTI_ARG_TYPES
(e.g. :strings
), or a :default:
value of an array of the correct type (e.g. [String]). The value of this argument will be an array of the parameters on the commandline.
Arguments that can occur multiple times should be marked with :multi
=> true
. The value of this argument will also be an array. In contrast with regular non-multi options, if not specified on the commandline, the default value will be [], not nil.
These two attributes can be combined (e.g. :type
=> :strings
, :multi
=> true
), in which case the value of the argument will be an array of arrays.
There's one ambiguous case to be aware of: when :multi
: is true and a :default
is set to an array (of something), it's ambiguous whether this is a multi-value argument as well as a multi-occurrence argument. In thise case, Trollop
assumes that it's not a multi-value argument. If you want a multi-value, multi-occurrence argument with a default value, you must specify :type
as well.
# File lib/ncio/trollop.rb, line 141 def opt(name, desc = "", opts = {}, &b) raise ArgumentError, "you already have an argument named '#{name}'" if @specs.member? name ## fill in :type opts[:type] = # normalize case opts[:type] when :boolean, :bool then :flag when :integer then :int when :integers then :ints when :double then :float when :doubles then :floats when Class case opts[:type].name when 'TrueClass', 'FalseClass' then :flag when 'String' then :string when 'Integer' then :int when 'Float' then :float when 'IO' then :io when 'Date' then :date else raise ArgumentError, "unsupported argument type '#{opts[:type].class.name}'" end when nil then nil else raise ArgumentError, "unsupported argument type '#{opts[:type]}'" unless TYPES.include?(opts[:type]) opts[:type] end ## for options with :multi => true, an array default doesn't imply ## a multi-valued argument. for that you have to specify a :type ## as well. (this is how we disambiguate an ambiguous situation; ## see the docs for Parser#opt for details.) disambiguated_default = if opts[:multi] && opts[:default].kind_of?(Array) && !opts[:type] opts[:default].first else opts[:default] end type_from_default = case disambiguated_default when Integer then :int when Numeric then :float when TrueClass, FalseClass then :flag when String then :string when IO then :io when Date then :date when Array if opts[:default].empty? if opts[:type] raise ArgumentError, "multiple argument type must be plural" unless MULTI_ARG_TYPES.include?(opts[:type]) nil else raise ArgumentError, "multiple argument type cannot be deduced from an empty array for '#{opts[:default][0].class.name}'" end else case opts[:default][0] # the first element determines the types when Integer then :ints when Numeric then :floats when String then :strings when IO then :ios when Date then :dates else raise ArgumentError, "unsupported multiple argument type '#{opts[:default][0].class.name}'" end end when nil then nil else raise ArgumentError, "unsupported argument type '#{opts[:default].class.name}'" end raise ArgumentError, ":type specification and default type don't match (default type is #{type_from_default})" if opts[:type] && type_from_default && opts[:type] != type_from_default opts[:type] = opts[:type] || type_from_default || :flag ## fill in :long opts[:long] = opts[:long] ? opts[:long].to_s : name.to_s.gsub("_", "-") opts[:long] = case opts[:long] when /^--([^-].*)$/ then $1 when /^[^-]/ then opts[:long] else raise ArgumentError, "invalid long option name #{opts[:long].inspect}" end raise ArgumentError, "long option name #{opts[:long].inspect} is already taken; please specify a (different) :long" if @long[opts[:long]] ## fill in :short opts[:short] = opts[:short].to_s if opts[:short] && opts[:short] != :none opts[:short] = case opts[:short] when /^-(.)$/ then $1 when nil, :none, /^.$/ then opts[:short] else raise ArgumentError, "invalid short option name '#{opts[:short].inspect}'" end if opts[:short] raise ArgumentError, "short option name #{opts[:short].inspect} is already taken; please specify a (different) :short" if @short[opts[:short]] raise ArgumentError, "a short option name can't be a number or a dash" if opts[:short] =~ INVALID_SHORT_ARG_REGEX end ## fill in :default for flags opts[:default] = false if opts[:type] == :flag && opts[:default].nil? ## autobox :default for :multi (multi-occurrence) arguments opts[:default] = [opts[:default]] if opts[:default] && opts[:multi] && !opts[:default].kind_of?(Array) ## fill in :multi opts[:multi] ||= false opts[:callback] ||= b if block_given? opts[:desc] ||= desc @long[opts[:long]] = name @short[opts[:short]] = name if opts[:short] && opts[:short] != :none @specs[name] = opts @order << [:opt, name] end
Parses the commandline. Typically called by Trollop::options
, but you can call it directly if you need more control.
throws CommandlineError
, HelpNeeded
, and VersionNeeded
exceptions.
# File lib/ncio/trollop.rb, line 327 def parse(cmdline = ARGV) vals = {} required = {} opt :version, "Print version and exit" if @version && ! (@specs[:version] || @long["version"]) opt :help, "Show this message" unless @specs[:help] || @long["help"] @specs.each do |sym, opts| required[sym] = true if opts[:required] vals[sym] = opts[:default] vals[sym] = [] if opts[:multi] && !opts[:default] # multi arguments default to [], not nil end resolve_default_short_options! ## resolve symbols given_args = {} @leftovers = each_arg cmdline do |arg, params| ## handle --no- forms arg, negative_given = if arg =~ /^--no-([^-]\S*)$/ ["--#{$1}", true] else [arg, false] end sym = case arg when /^-([^-])$/ then @short[$1] when /^--([^-]\S*)$/ then @long[$1] || @long["no-#{$1}"] else raise CommandlineError, "invalid argument syntax: '#{arg}'" end sym = nil if arg =~ /--no-/ # explicitly invalidate --no-no- arguments next 0 if ignore_invalid_options && !sym raise CommandlineError, "unknown argument '#{arg}'" unless sym if given_args.include?(sym) && !@specs[sym][:multi] raise CommandlineError, "option '#{arg}' specified multiple times" end given_args[sym] ||= {} given_args[sym][:arg] = arg given_args[sym][:negative_given] = negative_given given_args[sym][:params] ||= [] # The block returns the number of parameters taken. num_params_taken = 0 unless params.nil? if SINGLE_ARG_TYPES.include?(@specs[sym][:type]) given_args[sym][:params] << params[0, 1] # take the first parameter num_params_taken = 1 elsif MULTI_ARG_TYPES.include?(@specs[sym][:type]) given_args[sym][:params] << params # take all the parameters num_params_taken = params.size end end num_params_taken end ## check for version and help args raise VersionNeeded if given_args.include? :version raise HelpNeeded if given_args.include? :help ## check constraint satisfaction @constraints.each do |type, syms| constraint_sym = syms.find { |sym| given_args[sym] } next unless constraint_sym case type when :depends syms.each { |sym| raise CommandlineError, "--#{@specs[constraint_sym][:long]} requires --#{@specs[sym][:long]}" unless given_args.include? sym } when :conflicts syms.each { |sym| raise CommandlineError, "--#{@specs[constraint_sym][:long]} conflicts with --#{@specs[sym][:long]}" if given_args.include?(sym) && (sym != constraint_sym) } end end required.each do |sym, val| raise CommandlineError, "option --#{@specs[sym][:long]} must be specified" unless given_args.include? sym end ## parse parameters given_args.each do |sym, given_data| arg, params, negative_given = given_data.values_at :arg, :params, :negative_given opts = @specs[sym] if params.empty? && opts[:type] != :flag raise CommandlineError, "option '#{arg}' needs a parameter" unless opts[:default] params << (opts[:default].kind_of?(Array) ? opts[:default].clone : [opts[:default]]) end vals["#{sym}_given".intern] = true # mark argument as specified on the commandline case opts[:type] when :flag vals[sym] = (sym.to_s =~ /^no_/ ? negative_given : !negative_given) when :int, :ints vals[sym] = params.map { |pg| pg.map { |p| parse_integer_parameter p, arg } } when :float, :floats vals[sym] = params.map { |pg| pg.map { |p| parse_float_parameter p, arg } } when :string, :strings vals[sym] = params.map { |pg| pg.map(&:to_s) } when :io, :ios vals[sym] = params.map { |pg| pg.map { |p| parse_io_parameter p, arg } } when :date, :dates vals[sym] = params.map { |pg| pg.map { |p| parse_date_parameter p, arg } } end if SINGLE_ARG_TYPES.include?(opts[:type]) if opts[:multi] # multiple options, each with a single parameter vals[sym] = vals[sym].map { |p| p[0] } else # single parameter vals[sym] = vals[sym][0][0] end elsif MULTI_ARG_TYPES.include?(opts[:type]) && !opts[:multi] vals[sym] = vals[sym][0] # single option, with multiple parameters end # else: multiple options, with multiple parameters opts[:callback].call(vals[sym]) if opts.key?(:callback) end ## modify input in place with only those ## arguments we didn't process cmdline.clear @leftovers.each { |l| cmdline << l } ## allow openstruct-style accessors class << vals def method_missing(m, *_args) self[m] || self[m.to_s] end end vals end
Defines a set of words which cause parsing to terminate when encountered, such that any options to the left of the word are parsed as usual, and options to the right of the word are left intact.
A typical use case would be for subcommand support, where these would be set to the list of subcommands. A subsequent Trollop
invocation would then be used to parse subcommand options, after shifting the subcommand off of ARGV.
# File lib/ncio/trollop.rb, line 305 def stop_on(*words) @stop_words = [*words].flatten end
Similar to stop_on
, but stops on any unknown word when encountered (unless it is a parameter for an argument). This is useful for cases where you don't know the set of subcommands ahead of time, i.e., without first parsing the global options.
# File lib/ncio/trollop.rb, line 313 def stop_on_unknown @stop_on_unknown = true end
Adds a synopsis (command summary description) right below the usage line, or as the first line if usage isn't specified.
# File lib/ncio/trollop.rb, line 271 def synopsis(s = nil) s ? @synopsis = s : @synopsis end
Sets the usage string. If set the message will be printed as the first line in the help (educate) output and ending in two new lines.
# File lib/ncio/trollop.rb, line 265 def usage(s = nil) s ? @usage = s : @usage end
Sets the version string. If set, the user can request the version on the commandline. Should probably be of the form “<program name> <version number>”.
# File lib/ncio/trollop.rb, line 258 def version(s = nil) s ? @version = s : @version end
Private Instance Methods
instance_eval but with ability to handle block arguments thanks to _why: redhanded.hobix.com/inspect/aBlockCostume.html
# File lib/ncio/trollop.rb, line 731 def cloaker(&b) (class << self; self; end).class_eval do define_method :cloaker_, &b meth = instance_method :cloaker_ remove_method :cloaker_ meth end end
# File lib/ncio/trollop.rb, line 686 def collect_argument_parameters(args, start_at) params = [] pos = start_at while args[pos] && args[pos] !~ PARAM_RE && !@stop_words.member?(args[pos]) do params << args[pos] pos += 1 end params end
yield successive arg, parameter pairs
# File lib/ncio/trollop.rb, line 599 def each_arg(args) remains = [] i = 0 until i >= args.length return remains += args[i..-1] if @stop_words.member? args[i] case args[i] when /^--$/ # arg terminator return remains += args[(i + 1)..-1] when /^--(\S+?)=(.*)$/ # long argument with equals yield "--#{$1}", [$2] i += 1 when /^--(\S+)$/ # long argument params = collect_argument_parameters(args, i + 1) if params.empty? yield args[i], nil i += 1 else num_params_taken = yield args[i], params unless num_params_taken if @stop_on_unknown return remains += args[i + 1..-1] else remains += params end end i += 1 + num_params_taken end when /^-(\S+)$/ # one or more short arguments shortargs = $1.split(//) shortargs.each_with_index do |a, j| if j == (shortargs.length - 1) params = collect_argument_parameters(args, i + 1) if params.empty? yield "-#{a}", nil i += 1 else num_params_taken = yield "-#{a}", params unless num_params_taken if @stop_on_unknown return remains += args[i + 1..-1] else remains += params end end i += 1 + num_params_taken end else yield "-#{a}", nil end end else if @stop_on_unknown return remains += args[i..-1] else remains << args[i] i += 1 end end end remains end
# File lib/ncio/trollop.rb, line 559 def legacy_width # Support for older Rubies where io/console is not available `tput cols`.to_i rescue Errno::ENOENT 80 end
# File lib/ncio/trollop.rb, line 668 def parse_float_parameter(param, arg) raise CommandlineError, "option '#{arg}' needs a floating-point number" unless param =~ FLOAT_RE param.to_f end
# File lib/ncio/trollop.rb, line 663 def parse_integer_parameter(param, arg) raise CommandlineError, "option '#{arg}' needs an integer" unless param =~ /^-?[\d_]+$/ param.to_i end
# File lib/ncio/trollop.rb, line 673 def parse_io_parameter(param, arg) if param =~ /^(stdin|-)$/i $stdin else require 'open-uri' begin open param rescue SystemCallError => e raise CommandlineError, "file or url for option '#{arg}' cannot be opened: #{e.message}" end end end
# File lib/ncio/trollop.rb, line 696 def resolve_default_short_options! @order.each do |type, name| opts = @specs[name] next if type != :opt || opts[:short] c = opts[:long].split(//).find { |d| d !~ INVALID_SHORT_ARG_REGEX && !@short.member?(d) } if c # found a character to use opts[:short] = c @short[c] = name end end end
# File lib/ncio/trollop.rb, line 709 def wrap_line(str, opts = {}) prefix = opts[:prefix] || 0 width = opts[:width] || (self.width - 1) start = 0 ret = [] until start > str.length nextt = if start + width >= str.length str.length else x = str.rindex(/\s/, start + width) x = str.index(/\s/, start) if x && x < start x || str.length end ret << ((ret.empty? && !opts[:inner]) ? "" : " " * prefix) + str[start...nextt] start = nextt + 1 end ret end