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.
-
#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$<
-
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 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 |
# File 'lib/clasp/arguments.rb', line 375 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 = 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 # 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
609 610 611 |
# File 'lib/clasp/arguments.rb', line 609 def aliases @aliases end |
#argv ⇒ Object (readonly)
(Array) the (possibly mutated) array of arguments instance passed to new
621 622 623 |
# File 'lib/clasp/arguments.rb', line 621 def argv @argv end |
#argv_original_copy ⇒ Object (readonly)
(Array) unchanged copy of the original array of arguments passed to new
624 625 626 |
# File 'lib/clasp/arguments.rb', line 624 def argv_original_copy @argv_original_copy end |
#flags ⇒ Object (readonly)
(Array) a frozen array of flags
612 613 614 |
# File 'lib/clasp/arguments.rb', line 612 def flags @flags end |
#options ⇒ Object (readonly)
(Array) a frozen array of options
615 616 617 |
# File 'lib/clasp/arguments.rb', line 615 def @options end |
#program_name ⇒ Object (readonly)
(String) The program name
627 628 629 |
# File 'lib/clasp/arguments.rb', line 627 def program_name @program_name end |
#specifications ⇒ Object (readonly)
(Array) a frozen array of specifications
606 607 608 |
# File 'lib/clasp/arguments.rb', line 606 def specifications @specifications end |
#values ⇒ Object (readonly)
(Array) a frozen array of values
618 619 620 |
# File 'lib/clasp/arguments.rb', line 618 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$<
-
235 236 237 238 239 240 241 242 |
# File 'lib/clasp/arguments.rb', line 235 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
-
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 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 |
# File 'lib/clasp/arguments.rb', line 251 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
641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 |
# File 'lib/clasp/arguments.rb', line 641 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
674 675 676 677 678 679 680 681 682 |
# File 'lib/clasp/arguments.rb', line 674 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
694 695 696 697 698 699 700 701 702 |
# File 'lib/clasp/arguments.rb', line 694 def find_option(id) .each do |option| return option if option == id end nil end |