Class: ArgParser::ArgumentScope

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

Overview

Represents a scope within which an argument is defined/alid. Scopes may be nested, and argument requests will search the scope chain to find a matching argument.

Direct Known Subclasses

Definition

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, parent = nil) ⇒ ArgumentScope

Returns a new instance of ArgumentScope.



17
18
19
20
21
22
23
24
25
 
# File 'lib/arg-parser/definition.rb', line 17

def initialize(name, parent = nil)
    @name = name
    @parent = parent
    @parent.add_child(self) if @parent
    @children = []
    @arguments = {}
    @short_keys = {}
    @predefined_args = nil
end

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/arg-parser/definition.rb', line 13

def name
  @name
end

#parent ⇒ Object (readonly)

Returns the value of attribute parent.



13
14
15
 
# File 'lib/arg-parser/definition.rb', line 13

def parent
  @parent
end

#predefined_args ⇒ Object

Returns the value of attribute predefined_args.



14
15
16
 
# File 'lib/arg-parser/definition.rb', line 14

def predefined_args
  @predefined_args
end

Instance Method Details

#<<(arg) ⇒ Object

Adds the specified argument to the command-line definition.

Parameters:

  • arg (Argument) —

    An Argument sub-class to be added to the command- line definition.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/arg-parser/definition.rb', line 102

def <<(arg)
    case arg
    when CommandArgument, PositionalArgument, KeywordArgument, FlagArgument, RestArgument
        if used = self.key_used?(arg.key)
            raise ArgumentError, "An argument with key '#{arg.key}' has already been defined: #{used}"
        end
        if arg.short_key && used = self.key_used?(arg.short_key)
            raise ArgumentError, "The short key '#{arg.short_key}' has already been registered: #{used}"
        end
        if arg.is_a?(RestArgument) && rest_args?
            raise ArgumentError, "Only one rest argument can be defined"
        end
        @arguments[arg.key] = arg
        @short_keys[arg.short_key] = arg if arg.short_key
    else
        raise ArgumentError, "arg must be an instance of CommandArgument, PositionalArgument, " +
            "KeywordArgument, FlagArgument or RestArgument"
    end
end

#[](key) ⇒ Argument

Returns the argument with the specified key.

Returns:

  • (Argument) —

    the argument with the specified key

Raises:

  • (ArgumentError) —

    if no argument has been defined with the specified key.



92
93
94
95
 
# File 'lib/arg-parser/definition.rb', line 92

def [](key)
    arg = has_key?(key)
    arg or raise NoSuchArgumentError, "No argument defined for key '#{Argument.to_key(key)}'"
end

#add_child(arg_scope) ⇒ Object

Adds a Scope as a child of this scope.

Raises:

  • (ArgumentError) 


29
30
31
32
33
 
# File 'lib/arg-parser/definition.rb', line 29

def add_child(arg_scope)
    raise ArgumentError, "#{arg_scope} must be an ArgumentScope instance" unless arg_scope.is_a?(ArgumentScope)
    raise ArgumentError, "#{arg_scope} parent not set to this ArgumentScope" if arg_scope.parent != self
    @children << arg_scope
end

#args ⇒ Array

Returns all arguments that have been defined.

Returns:

  • (Array) —

    all arguments that have been defined.



216
217
218
 
# File 'lib/arg-parser/definition.rb', line 216

def args
    @arguments.values
end

#command_arg(key, desc, opts = {}, &block) ⇒ Object

Add a command argument to the set of arguments in this command-line argument definition.

See Also:



126
127
128
129
130
 
# File 'lib/arg-parser/definition.rb', line 126

def command_arg(key, desc, opts = {}, &block)
    cmd_arg = ArgParser::CommandArgument.new(key, desc, opts)
    CommandBlock.new(self, cmd_arg, &block)
    self << cmd_arg
end

#command_args ⇒ Array

Returns all command arguments that have been defined.

Returns:

  • (Array) —

    all command arguments that have been defined



222
223
224
 
# File 'lib/arg-parser/definition.rb', line 222

def command_args
    @arguments.values.select{ |arg| CommandArgument === arg }
end

#command_args? ⇒ Boolean

Returns True if a command arg has been defined.

Returns:

  • (Boolean) —

    True if a command arg has been defined



228
229
230
 
# File 'lib/arg-parser/definition.rb', line 228

def command_args?
    command_args.size > 0
end

#flag_arg(key, desc, opts = {}, &block) ⇒ Object

Add a flag argument to the set of arguments in this command-line argument definition.

See Also:



152
153
154
 
# File 'lib/arg-parser/definition.rb', line 152

def flag_arg(key, desc, opts = {}, &block)
    self << ArgParser::FlagArgument.new(key, desc, opts, &block)
end

#flag_args ⇒ Array

Returns the flag arguments that have been defined.

Returns:

  • (Array) —

    the flag arguments that have been defined



276
277
278
 
# File 'lib/arg-parser/definition.rb', line 276

def flag_args
    @arguments.values.select{ |arg| FlagArgument === arg }
end

#flag_args? ⇒ Boolean

Returns True if any flag arguments have been defined.

Returns:

  • (Boolean) —

    True if any flag arguments have been defined.



282
283
284
 
# File 'lib/arg-parser/definition.rb', line 282

def flag_args?
    flag_args.size > 0
end

#has_key?(key) ⇒ Argument

Returns the argument for the given key if it exists, or nil if it does not.

Returns:

  • (Argument) —

    the argument for the given key if it exists, or nil if it does not.



83
84
85
86
 
# File 'lib/arg-parser/definition.rb', line 83

def has_key?(key)
    k = Argument.to_key(key)
    @arguments[k] || @short_keys[k]
end

#key_used?(key) ⇒ Argument|nil

Checks if a key has been used in this scope, any ancestor scopes, or any descendant scopes.

Parameters:

  • key (String) —

    The key under which an argument is to be registered

Returns:

  • (Argument|nil) —

    The Argument that already uses the key, or nil if the key is not used.



42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/arg-parser/definition.rb', line 42

def key_used?(key)
    self.walk_ancestors do |anc|
        arg = anc.has_key?(key)
        return arg if arg
    end
    self.walk_children do |child|
        arg = child.has_key?(key)
        return arg if arg
    end
    nil
end

#keys ⇒ Array

Returns all argument keys that have been defined.

Returns:

  • (Array) —

    all argument keys that have been defined.



204
205
206
 
# File 'lib/arg-parser/definition.rb', line 204

def keys
    @arguments.keys
end

#keyword_arg(key, desc, opts = {}, &block) ⇒ Object

Add a keyword argument to the set of arguments in this command-line argument definition.

See Also:



144
145
146
 
# File 'lib/arg-parser/definition.rb', line 144

def keyword_arg(key, desc, opts = {}, &block)
    self << ArgParser::KeywordArgument.new(key, desc, opts, &block)
end

#keyword_args ⇒ Array

Returns the keyword arguments that have been defined.

Returns:

  • (Array) —

    the keyword arguments that have been defined.



264
265
266
 
# File 'lib/arg-parser/definition.rb', line 264

def keyword_args
    @arguments.values.select{ |arg| KeywordArgument === arg }
end

#keyword_args? ⇒ Boolean

Returns True if any keyword arguments have been defined.

Returns:

  • (Boolean) —

    True if any keyword arguments have been defined.



270
271
272
 
# File 'lib/arg-parser/definition.rb', line 270

def keyword_args?
    keyword_args.size > 0
end

#non_positional_args ⇒ Array

Returns the non-positional (i.e. keyword and flag) arguments that have been defined.

Returns:

  • (Array) —

    the non-positional (i.e. keyword and flag) arguments that have been defined.



249
250
251
252
253
254
 
# File 'lib/arg-parser/definition.rb', line 249

def non_positional_args
    @arguments.values.reject{ |arg| CommandArgument === arg || 
                                    CommandInstance === arg ||
                                    PositionalArgument === arg ||
                                    RestArgument === arg }
end

#non_positional_args? ⇒ Boolean

Returns True if any non-positional arguments have been defined.

Returns:

  • (Boolean) —

    True if any non-positional arguments have been defined.



258
259
260
 
# File 'lib/arg-parser/definition.rb', line 258

def non_positional_args?
    non_positional_args.size > 0
end

#positional_arg(key, desc, opts = {}, &block) ⇒ Object

Add a positional argument to the set of arguments in this command-line argument definition.

See Also:



136
137
138
 
# File 'lib/arg-parser/definition.rb', line 136

def positional_arg(key, desc, opts = {}, &block)
    self << ArgParser::PositionalArgument.new(key, desc, opts, &block)
end

#positional_args ⇒ Array

Returns all positional arguments that have been defined.

Returns:

  • (Array) —

    all positional arguments that have been defined



234
235
236
237
238
 
# File 'lib/arg-parser/definition.rb', line 234

def positional_args
    @arguments.values.select{ |arg| CommandArgument === arg ||
                                    CommandInstance === arg ||
                                    PositionalArgument === arg }
end

#positional_args? ⇒ Boolean

Returns True if any positional arguments have been defined.

Returns:

  • (Boolean) —

    True if any positional arguments have been defined.



242
243
244
 
# File 'lib/arg-parser/definition.rb', line 242

def positional_args?
    positional_args.size > 0
end

#predefined_arg(lookup_key, opts = {}) ⇒ Object

Lookup a pre-defined argument (created earlier via Argument#register), and add it to this arguments definition.

Parameters:

  • lookup_key (String, Symbol) —

    The key under which the pre-defined argument was registered.

  • desc (String) —

    An optional override for the argument description for this use of the pre-defined argument.

  • opts (Hash) (defaults to: {}) —

    An options hash for those select properties that can be overridden on a pre-defined argument.

Options Hash (opts):

  • :description (String) —

    The argument description for this use of the pre-defined argument.

  • :usage_break (String) —

    The usage break for this use of the pre-defined argument.

  • :required (Boolean) —

    Whether this argument is a required (i.e. mandatory) argument.

  • :default (String) —

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

Raises:

  • (ArgumentError)

See Also:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/arg-parser/definition.rb', line 185

def predefined_arg(lookup_key, opts = {})
    #arg = Argument.lookup(lookup_key)
    arg = nil
    self.walk_ancestors do |scope|
        arg = scope.predefined_args && scope.predefined_args.has_key?(lookup_key)
        break if arg
    end
    raise ArgumentError, "No predefined argument with key '#{lookup_key}' found" unless arg
    arg.short_key = opts[:short_key] if opts.has_key?(:short_key)
    arg.description = opts[:description] if opts.has_key?(:description)
    arg.usage_break = opts[:usage_break] if opts.has_key?(:usage_break)
    arg.required = opts[:required] if opts.has_key?(:required)
    arg.default = opts[:default] if opts.has_key?(:default)
    arg.on_parse = opts[:on_parse] if opts.has_key?(:on_parse)
    self << arg
end

#rest_arg(key, desc, opts = {}, &block) ⇒ Object

Add a rest argument to the set of arguments in this command-line argument definition.

See Also:



160
161
162
 
# File 'lib/arg-parser/definition.rb', line 160

def rest_arg(key, desc, opts = {}, &block)
    self << ArgParser::RestArgument.new(key, desc, opts, &block)
end

#rest_args ⇒ RestArgument

Returns the RestArgument defined for this command-line, or nil if no RestArgument is defined.

Returns:

  • (RestArgument) —

    the RestArgument defined for this command-line, or nil if no RestArgument is defined.



289
290
291
 
# File 'lib/arg-parser/definition.rb', line 289

def rest_args
    @arguments.values.find{ |arg| RestArgument === arg }
end

#rest_args? ⇒ Boolean

Returns True if a RestArgument has been defined.

Returns:

  • (Boolean) —

    True if a RestArgument has been defined.



295
296
297
 
# File 'lib/arg-parser/definition.rb', line 295

def rest_args?
    !!rest_args
end

#short_keys ⇒ Array

Returns all argument short keys that have been defined.

Returns:

  • (Array) —

    all argument short keys that have been defined.



210
211
212
 
# File 'lib/arg-parser/definition.rb', line 210

def short_keys
    @short_keys.keys
end

#size ⇒ Integer

Returns the number of arguments that have been defined.

Returns:

  • (Integer) —

    the number of arguments that have been defined.



308
309
310
 
# File 'lib/arg-parser/definition.rb', line 308

def size
    @arguments.size
end

#value_args ⇒ Array

Returns all the positional, keyword, and rest arguments that have been defined.

Returns:

  • (Array) —

    all the positional, keyword, and rest arguments that have been defined.



302
303
304
 
# File 'lib/arg-parser/definition.rb', line 302

def value_args
    @arguments.values.select{ |arg| ValueArgument === arg }
end

#walk_ancestors(inc_self = true, &blk) ⇒ Object

Yields each ancestor of this scope, optionally including this scope.



62
63
64
65
66
67
68
 
# File 'lib/arg-parser/definition.rb', line 62

def walk_ancestors(inc_self = true, &blk)
    scope = inc_self ? self : self.parent
    while scope do
        yield scope
        scope = scope.parent
    end
end

#walk_arguments(&blk) ⇒ Object

Yields each key/argument pair for this ArgumentScope



56
57
58
 
# File 'lib/arg-parser/definition.rb', line 56

def walk_arguments(&blk)
    @arguments.each(&blk)
end

#walk_children(inc_self = false) {|_self| ... } ⇒ Object

Recursively walks and yields each descendant scopes of this scope.

Yields:

  • (_self)

Yield Parameters:



72
73
74
75
76
77
78
 
# File 'lib/arg-parser/definition.rb', line 72

def walk_children(inc_self = false, &blk)
    yield self if inc_self
    @children.each do |child|
        yield child
        child.walk_children(&blk)
    end
end