Class: ArgParser::Argument Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/arg-parser/argument.rb

Overview

This class is abstract.

Abstract base class of all command-line argument types.

Direct Known Subclasses

FlagArgument, ValueArgument

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#default ⇒ String

Returns the default value for the argument, returned in the command-line parse results if no other value is specified.

Returns:

  • (String) —

    the default value for the argument, returned in the command-line parse results if no other value is specified.



36
37
38
 
# File 'lib/arg-parser/argument.rb', line 36

def default
  @default
end

#description ⇒ String (readonly)

Returns the description for this argument, which will be shown in the usage display.

Returns:

  • (String) —

    the description for this argument, which will be shown in the usage display.



24
25
26
 
# File 'lib/arg-parser/argument.rb', line 24

def description
  @description
end

#key ⇒ Symbol (readonly)

The key used to identify this argument value in the parsed command- line results Struct.

Returns:

  • (Symbol) —

    the key/method by which this argument can be retrieved from the parse result Struct.



21
22
23
 
# File 'lib/arg-parser/argument.rb', line 21

def key
  @key
end

#on_parse ⇒ Proc

An optional on_parse callback handler. The supplied block/Proc will be called after this argument has been parsed, with three arguments:

@param [String] The value from the command-line that was entered for
  this argument.
@param [Argument] The Argument sub-class object that represents the
  argument that was parsed.
@param [Hash] The results Hash containing the argument keys and their
  values parsed so far.

Returns:

  • (Proc) —

    the user supplied block to be called when the argument has been parsed.



47
48
49
 
# File 'lib/arg-parser/argument.rb', line 47

def on_parse
  @on_parse
end

#required ⇒ Boolean Also known as: required?

Returns whether this argument is a required (i.e. mandatory) argument. Mandatory arguments that do not get specified result in a ParseException.

Returns:

  • (Boolean) —

    whether this argument is a required (i.e. mandatory) argument. Mandatory arguments that do not get specified result in a ParseException.



32
33
34
 
# File 'lib/arg-parser/argument.rb', line 32

def required
  @required
end

#short_key ⇒ Symbol (readonly)

Returns a single letter or digit that can be used as a short alternative to the full key to identify an argument value in a command- line.

Returns:

  • (Symbol) —

    a single letter or digit that can be used as a short alternative to the full key to identify an argument value in a command- line.



28
29
30
 
# File 'lib/arg-parser/argument.rb', line 28

def short_key
  @short_key
end

#usage_break ⇒ String

Returns a label to use for a new section of options in the argument usage display. Should be specified on the first argument in the group.

Returns:

  • (String) —

    a label to use for a new section of options in the argument usage display. Should be specified on the first argument in the group.



51
52
53
 
# File 'lib/arg-parser/argument.rb', line 51

def usage_break
  @usage_break
end

Class Method Details

.lookup(lookup_key) ⇒ Argument

Return a copy of a pre-defined argument for use in an argument definition.

Parameters:

  • lookup_key (String, Symbol) —

    The key with which to register the argument for subsequent lookup. This can be different from the key which will represent the argument when parsed etc; this makes it possible to register several alternate versions of the same argument for use in different circumstances.

Returns:

  • (Argument) —

    A copy of the registered argument.



99
100
101
102
103
104
105
 
# File 'lib/arg-parser/argument.rb', line 99

def self.lookup(lookup_key)
    key = self.to_key(lookup_key)
    unless arg = PredefinedArguments[key]
        raise ArgumentError, "No pre-defined argument has been registered under key '#{lookup_key}'"
    end
    arg.clone
end

.register(lookup_key, arg) ⇒ Object

Register a common argument for use in multiple argument definitions. The registered argument is a completely defined argument that can be added to any argument definition via Definition#predefined_arg.

Parameters:

  • lookup_key (String, Symbol) —

    The key with which to register the argument for subsequent lookup. This can be different from the key which will represent the argument when parsed etc; this makes it possible to register several alternate versions of the same argument for use in different circumstances.

  • arg (Argument) —

    An Argument sub-class that represents the arg that is to be registered for later use. #TODO: Document how arg is created.

See Also:



81
82
83
84
85
86
87
 
# File 'lib/arg-parser/argument.rb', line 81

def self.register(lookup_key, arg)
    key = self.to_key(lookup_key)
    if PredefinedArguments.has_key?(key)
        raise ArgumentError, "An argument has already been registered under key '#{lookup_key}'"
    end
    PredefinedArguments[key] = arg
end

.to_key(label) ⇒ Symbol

Converts an argument key specification into a valid key, by stripping leading dashes, converting remaining dashes to underscores, and lower- casing all text. This is required to ensure the key name will be a valid accessor name on the parse results.

Returns:

  • (Symbol) —

    the key by which an argument can be retrieved from the arguments definition, and the parse results.



61
62
63
64
 
# File 'lib/arg-parser/argument.rb', line 61

def self.to_key(label)
    k = label.to_s.gsub(/^-+/, '').gsub('-', '_')
    k.length > 1 ? k.downcase.intern : k.intern
end