class CLASP::Arguments
The main class for processing command-line arguments
Attributes
- DEPRECATED
-
Instead refer to
specifications
(Array) the (possibly mutated) array of arguments instance passed to new
(Array) unchanged copy of the original array of arguments passed to new
(Array) a frozen array of flags
(Array) a frozen array of options
(String) The program name
(Array) a frozen array of specifications
(Array) a frozen array of values
Public Class Methods
Loads an instance of the class, as specified by source
, according to the given parameters
See the documentation for the ::CLASP
module for examples
Signature¶ ↑
-
Parameters:
-
argv
(Array
) The arguments array. May not benil
. Defaults toARGV
-
source
(Hash
,IO
) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification -
options
An options hash, containing any of the following options
-
-
Options:
-
mutate_argv:
(Boolean
) Determines if the library should mutateargv
. Defaults totrue
. This is essential when usingCLASP
in conjunction with$<
-
# File lib/clasp/arguments.rb, line 262 def self.load(argv, source, options = {}) # :yields: An instance of +CLASP::Arguments+ options ||= {} specs = load_specifications(source, options) self.new argv, specs, options end
Loads the specifications as specified by source
, according to the given parameters
Signature¶ ↑
-
Parameters:
-
source
(Hash
,IO
) The arguments specification, either as a Hash or an instance of an IO-implementing type containing a YAML specification -
options
An options hash, containing any of the following options
-
# File lib/clasp/arguments.rb, line 278 def self.load_specifications(source, options = {}) # :yields: An array of specification instances options ||= {} h = nil case source when ::IO h = YAML.load(source.read) when ::Hash h = source else if source.respond_to?(:to_hash) h = source.to_hash else raise TypeError, "#{self}.#{__method__}() 'source' argument must be a #{::Hash}, or an object implementing #{::IO}, or a type implementing to_hash'" end end specs = [] _clasp = h['clasp'] or raise ArgumentError, "missing top-level 'clasp' element in load configuration" ::Hash === _clasp or raise ArgumentError, "top-level 'clasp' element must be a #{::Hash}" _specs = (_clasp['arg-specs'] || _clasp['specifications'] || _clasp['aliases']) or raise ArgumentError, "missing element 'clasp/specifications'" ::Array === _specs or raise ArgumentError, "top-level 'specifications' element must be a #{::Hash}" _specs.each do |_spec| case _spec when ::Hash # TODO: make a utility function and shrink all the following _spec.each do |_arg_type, _details| case _arg_type when 'flag', :flag _name = _details['name'] unless _name warn "flag specification missing required 'name' field" else _alias = _details['alias'] _aliases = _details['aliases'] _help = _details['help'] || _details['description'] specs << CLASP.Flag(_name, alias: _alias, aliases: _aliases, help: _help) end when 'option', :option _name = _details['name'] unless _name warn "option specification missing required 'name' field" else _alias = _details['alias'] _aliases = _details['aliases'] _default_value = _details['default_value'] || _details['default'] _help = _details['help'] || _details['description'] _required = _details['required'] _required_message = _details['required_message'] _values_range = _details['values_range'] || _details['values'] specs << CLASP.Option(_name, alias: _alias, aliases: _aliases, default_value: _default_value, help: _help, required: _required, required_message: _required_message, values_range: _values_range) end when 'alias', :alias _resolved = _details['resolved'] unless _resolved warn "alias specification missing required 'resolved' field" else _alias = _details['alias'] _aliases = _details['aliases'] unless _alias || _aliases warn "alias specification missing required 'alias' or 'aliases' field" else specs << CLASP.Flag(_resolved, alias: _alias, aliases: _aliases) end end else warn "unknown arg-type '#{_arg_type}' specified" end end else warn "non-#{::Hash} element in 'clasp/specifications': #{_spec} (of type #{_spec.class})" end end specs end
Constructs an instance of the class, according to the given parameters
See the documentation for the ::CLASP
module for examples
Signature¶ ↑
-
Parameters:
-
argv
(Array
) The arguments array. May not benil
. Defaults toARGV
-
specifications
(Array
) The specifications array. Defaults tonil
. If none supplied, no aliasing will be performed -
options
An options hash, containing any of the following options
-
-
Options:
-
mutate_argv:
(Boolean
) Determines if the library should mutateargv
. Defaults totrue
. This is essential when usingCLASP
in conjunction with$<
-
# File lib/clasp/arguments.rb, line 402 def initialize(argv = ARGV, specifications = nil, options = {}) # have to do this name-swap, as 'options' has CLASP-specific # meaning init_opts, options = options.dup, nil init_opts[:mutate_argv] = true unless init_opts.has_key? :mutate_argv @program_name = init_opts[:program_name] || Arguments.derive_program_name_ @argv = argv argv = argv.dup @argv_original_copy = argv.dup.freeze @specifications = specifications @aliases = @specifications specifications = nil if specifications and specifications.empty? flags, options, values = Arguments.parse_(argv, specifications) [ flags, options, values ].each do |ar| class << ar undef :inspect undef :to_s def to_s s = '' s += '[' s += self.map { |v| %Q<"#{v}"> }.join(', ') s += ']' s end def inspect s = '' s += "#<#{self.class}:0x#{(object_id << 1).to_s(16)} [" s += self.map { |v| v.inspect }.join(', ') s += "]>" s end end end @flags = flags.freeze @options = options.freeze @values = values.freeze # do argv-mutation, if required if init_opts[:mutate_argv] while not argv.empty? argv.shift end @values.each do |v| argv << v end end end
Public Instance Methods
Finds the first unknown flag or option; nil
if all used
Signature¶ ↑
-
Parameters:
-
options
(Hash) options
-
-
Options:
-
:specifications
([CLASP::Specification]) Array of specifications. If not specified, the instance'sspecifications
attribute is used
-
Return¶ ↑
(CLASP::Arguments::OptionArgument
) The first unknown option; nil
if none found
# File lib/clasp/arguments.rb, line 686 def find_first_unknown options = {} option = {} if options.nil? raise ArgumentError, "options must be nil or Hash - #{option.class} given" unless options.is_a? ::Hash specifications = options[:specifications] || options[:aliases] || @specifications raise ArgumentError, "specifications may not be nil" if specifications.nil? flags.each do |f| return f unless specifications.any? { |al| al.is_a?(::CLASP::FlagSpecification) && al.name == f.name } end self.options.each do |o| return o unless specifications.any? { |al| al.is_a?(::CLASP::OptionSpecification) && al.name == o.name } end nil end
Searches for a flag that matches the given id, returning the flag if found; nil
otherwise
Signature¶ ↑
-
Parameters:
-
id
(String, CLASP::FlagArgument) The name of a flag, or the flag itself
Return¶ ↑
(CLASP::Arguments::FlagArgument
) The first flag matching id
; nil
if none found
# File lib/clasp/arguments.rb, line 719 def find_flag(id) flags.each do |flag| return flag if flag == id end nil end
Searches for a option that matches the given id, returning the option if found; nil
otherwise
Signature¶ ↑
-
Parameter:
-
id
(String, CLASP::OptionArgument) The name of a option, or the option itself
Return¶ ↑
(CLASP::Arguments::OptionArgument
) The first option matching id
; nil
if none found
# File lib/clasp/arguments.rb, line 739 def find_option(id) options.each do |option| return option if option == id end nil end