Class: CLASP::Arguments
- Inherits:
-
Object
- Object
- CLASP::Arguments
- Defined in:
- lib/clasp/arguments.rb
Overview
The main class for processing command-line arguments
Defined Under Namespace
Classes: FlagArgument, OptionArgument
Instance Attribute Summary collapse
-
#aliases ⇒ Object
readonly
- DEPRECATED
-
Instead refer to
specifications
.
-
#argv ⇒ Object
readonly
(Array) the (possibly mutated) array of arguments instance passed to new.
-
#argv_original_copy ⇒ Object
readonly
(Array) unchanged copy of the original array of arguments passed to new.
-
#double_slash_index ⇒ Object
readonly
(Integer,
nil
) index of the first ‘–’, if present;nil
otherwise. -
#flags ⇒ Object
readonly
(Array) a frozen array of flags.
-
#options ⇒ Object
readonly
(Array) a frozen array of options.
-
#program_name ⇒ Object
readonly
(String) The program name.
-
#specifications ⇒ Object
readonly
(Array) a frozen array of specifications.
-
#values ⇒ Object
readonly
(Array) a frozen array of values.
Class Method Summary collapse
-
.load(argv, source, options = {}) ⇒ Object
Loads an instance of the class, as specified by
source
, according to the given parameters. -
.load_specifications(source, options = {}) ⇒ Object
Loads the specifications as specified by
source
, according to the given parameters.
Instance Method Summary collapse
-
#find_first_unknown(options = {}) ⇒ Object
Finds the first unknown flag or option;
nil
if all used. -
#find_flag(id) ⇒ Object
Searches for a flag that matches the given id, returning the flag if found;
nil
otherwise. -
#find_option(id) ⇒ Object
Searches for a option that matches the given id, returning the option if found;
nil
otherwise. -
#initialize(argv = ARGV, specifications = nil, options = {}) ⇒ Arguments
constructor
Constructs an instance of the class, according to the given parameters.
Constructor Details
#initialize(argv = ARGV, specifications = nil, options = {}) ⇒ Arguments
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 using CLASP in conjunction with$<
-
403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 |
# File 'lib/clasp/arguments.rb', line 403 def initialize(argv = ARGV, specifications = nil, = {}) # have to do this name-swap, as 'options' has CLASP-specific # meaning init_opts, = .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, , values, double_slash_index = Arguments.parse_(argv, specifications) [ flags, , 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 = .freeze @values = values.freeze @double_slash_index = double_slash_index # 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 |
Instance Attribute Details
#aliases ⇒ Object (readonly)
- DEPRECATED
-
Instead refer to
specifications
662 663 664 |
# File 'lib/clasp/arguments.rb', line 662 def aliases @aliases end |
#argv ⇒ Object (readonly)
(Array) the (possibly mutated) array of arguments instance passed to new
677 678 679 |
# File 'lib/clasp/arguments.rb', line 677 def argv @argv end |
#argv_original_copy ⇒ Object (readonly)
(Array) unchanged copy of the original array of arguments passed to new
680 681 682 |
# File 'lib/clasp/arguments.rb', line 680 def argv_original_copy @argv_original_copy end |
#double_slash_index ⇒ Object (readonly)
(Integer, nil
) index of the first ‘–’, if present; nil
otherwise
674 675 676 |
# File 'lib/clasp/arguments.rb', line 674 def double_slash_index @double_slash_index end |
#flags ⇒ Object (readonly)
(Array) a frozen array of flags
665 666 667 |
# File 'lib/clasp/arguments.rb', line 665 def flags @flags end |
#options ⇒ Object (readonly)
(Array) a frozen array of options
668 669 670 |
# File 'lib/clasp/arguments.rb', line 668 def @options end |
#program_name ⇒ Object (readonly)
(String) The program name
683 684 685 |
# File 'lib/clasp/arguments.rb', line 683 def program_name @program_name end |
#specifications ⇒ Object (readonly)
(Array) a frozen array of specifications
659 660 661 |
# File 'lib/clasp/arguments.rb', line 659 def specifications @specifications end |
#values ⇒ Object (readonly)
(Array) a frozen array of values
671 672 673 |
# File 'lib/clasp/arguments.rb', line 671 def values @values end |
Class Method Details
.load(argv, source, options = {}) ⇒ Object
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 using CLASP in conjunction with$<
-
263 264 265 266 267 268 269 270 |
# File 'lib/clasp/arguments.rb', line 263 def self.load(argv, source, = {}) # :yields: An instance of +CLASP::Arguments+ ||= {} specs = load_specifications(source, ) self.new argv, specs, end |
.load_specifications(source, options = {}) ⇒ Object
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
-
279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 |
# File 'lib/clasp/arguments.rb', line 279 def self.load_specifications(source, = {}) # :yields: An array of specification instances ||= {} 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'] = _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: , 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 |
Instance Method Details
#find_first_unknown(options = {}) ⇒ Object
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
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 |
# File 'lib/clasp/arguments.rb', line 697 def find_first_unknown = {} option = {} if .nil? raise ArgumentError, "options must be nil or Hash - #{option.class} given" unless .is_a? ::Hash specifications = [:specifications] || [: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..each do |o| return o unless specifications.any? { |al| al.is_a?(::CLASP::OptionSpecification) && al.name == o.name } end nil end |
#find_flag(id) ⇒ Object
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
730 731 732 733 734 735 736 737 738 |
# File 'lib/clasp/arguments.rb', line 730 def find_flag(id) flags.each do |flag| return flag if flag == id end nil end |
#find_option(id) ⇒ Object
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
750 751 752 753 754 755 756 757 758 |
# File 'lib/clasp/arguments.rb', line 750 def find_option(id) .each do |option| return option if option == id end nil end |