class CLASP::Arguments

The main class for processing command-line arguments

Attributes

aliases[R]
DEPRECATED

Instead refer to specifications

argv[R]

(Array) the (possibly mutated) array of arguments instance passed to new

argv_original_copy[R]

(Array) unchanged copy of the original array of arguments passed to new

flags[R]

(Array) a frozen array of flags

options[R]

(Array) a frozen array of options

program_name[R]

(String) The program name

specifications[R]

(Array) a frozen array of specifications

values[R]

(Array) a frozen array of values

Public Class Methods

load(argv, source, options = {}) { |An instance of +Arguments+| ... } click to toggle source

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 be nil. Defaults to ARGV

    • 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 mutate argv. Defaults to true. This is essential when using CLASP 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
load_specifications(source, options = {}) { |An array of specification instances| ... } click to toggle source

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
new(argv = ARGV, specifications = nil, options = {}) click to toggle source

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 be nil. Defaults to ARGV

    • specifications (Array) The specifications array. Defaults to nil. 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 mutate argv. Defaults to true. This is essential when using CLASP 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

find_first_unknown(options = {}) click to toggle source

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's specifications 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
find_flag(id) click to toggle source

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
find_option(id) click to toggle source

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