Class: Puppet::Parameter::ValueCollection Private

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/parameter/value_collection.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Note:

This class is considered part of the internal implementation of Puppet::Parameter, and Puppet::Property and the functionality provided by this class should be used via their interfaces.

A collection of values and regular expressions, used for specifying allowed values in a given parameter.

Instance Method Summary (collapse)

Constructor Details

- (ValueCollection) initialize  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A new instance of ValueCollection



61
62
63
64
65
66
67
68
69
 
# File 'lib/puppet/parameter/value_collection.rb', line 61

def initialize
  # We often look values up by name, so a hash makes more sense.
  @values = {}

  # However, we want to retain the ability to match values in order,
  # but we always prefer directly equality (i.e., strings) over regex matches.
  @regexes = []
  @strings = []
end

Instance Method Details

- aliasvalue(name, other)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Aliases the given existing other value with the additional given name.



19
20
21
22
23
24
25
26
 
# File 'lib/puppet/parameter/value_collection.rb', line 19

def aliasvalue(name, other)
  other = other.to_sym
  unless value = match?(other)
    raise Puppet::DevError, "Cannot alias nonexistent value #{other}"
  end

  value.alias(name)
end

- (String) doc  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a doc string (enumerating the acceptable values) for all of the values in this parameter/property.

Returns:

  • (String) —

    a documentation string.



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/puppet/parameter/value_collection.rb', line 32

def doc
  unless defined?(@doc)
    @doc = ""
    unless values.empty?
      @doc += "  Valid values are "
      @doc += @strings.collect do |value|
        if aliases = value.aliases and ! aliases.empty?
          "`#{value.name}` (also called `#{aliases.join(", ")}`)"
        else
          "`#{value.name}`"
        end
      end.join(", ") + "."
    end

    @doc += "  Values can match `" + regexes.join("`, `") + "`." unless regexes.empty?
  end

  @doc
end

- (Boolean) empty?  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether the set of allowed values is empty or not.

Returns:

  • (Boolean) —

    Returns whether the set of allowed values is empty or not.



55
56
57
 
# File 'lib/puppet/parameter/value_collection.rb', line 55

def empty?
  @values.empty?
end

- (Puppet::Parameter::Value?) match?(test_value)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Checks if the given value is acceptable (matches one of the literal values or patterns) and returns the “matcher” that matched. Literal string matchers are tested first, if both a literal and a regexp match would match, the literal match wins.

Parameters:

  • test_value (Object) —

    the value to test if it complies with the configured rules

Returns:

  • (Puppet::Parameter::Value, nil) —

    The instance of Puppet::Parameter::Value that matched the given value, or nil if there was no match.



80
81
82
83
84
85
86
87
88
 
# File 'lib/puppet/parameter/value_collection.rb', line 80

def match?(test_value)
  # First look for normal values
  if value = @strings.find { |v| v.match?(test_value) }
    return value
  end

  # Then look for a regex match
  @regexes.find { |v| v.match?(test_value) }
end

- (Object) munge(value)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

This method does not seem to do any munging. It just returns the value if it matches the regexp, or the (most likely Symbolic) allowed value if it matches (which is more of a replacement of one instance with an equal one. Is the intent that this method should be specialized?

Munges the value if it is valid, else produces the same value.

Parameters:

  • value (Object) —

    the value to munge

Returns:

  • (Object) —

    the munged value, or the given value



98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/puppet/parameter/value_collection.rb', line 98

def munge(value)
  return value if empty?

  if instance = match?(value)
    if instance.regex?
      return value
    else
      return instance.name
    end
  else
    return value
  end
end

- (Object) newvalue(name, options = {}, &block)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

Option :event original comment says “event should be returned…”, is “returned” the correct word to use?

Defines a new valid value for a Puppet::Property. A valid value is specified as a literal (typically a Symbol), but can also be specified with a regexp.

Parameters:

  • name (Symbol, Regexp) —

    a valid literal value, or a regexp that matches a value

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

    a hash with options

Options Hash (options):

  • :event (Symbol) —

    The event that should be emitted when this value is set.

  • :call (Symbol) —

    When to call any associated block. The default value is :instead which means that the block should be called instead of the provider. In earlier versions (before 20081031) it was possible to specify a value of :before or :after for the purpose of calling both the block and the provider. Use of these deprecated options will now raise an exception later in the process when the is value is set (see Puppet::Property#set).

  • _any_ (Object) —

    Any other option is treated as a call to a setter having the given option name (e.g. :required_features calls required_features= with the option’s value as an argument).



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/puppet/parameter/value_collection.rb', line 131

def newvalue(name, options = {}, &block)
  value = Puppet::Parameter::Value.new(name)
  @values[value.name] = value
  if value.regex?
    @regexes << value
  else
    @strings << value
  end

  options.each { |opt, arg| value.send(opt.to_s + "=", arg) }
  if block_given?
    value.block = block
  else
    value.call = options[:call] || :none
  end

  value.method ||= "set_#{value.name}" if block_given? and ! value.regex?

  value
end

- newvalues(*names)  privateDSL

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines one or more valid values (literal or regexp) for a parameter or property.

DSL:

  • type



157
158
159
 
# File 'lib/puppet/parameter/value_collection.rb', line 157

def newvalues(*names)
  names.each { |name| newvalue(name) }
end

- (Array<String>) regexes  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

An array of the regular expressions in string form, configured as matching valid values.

Returns:

  • (Array<String>) —

    An array of the regular expressions in string form, configured as matching valid values.



164
165
166
 
# File 'lib/puppet/parameter/value_collection.rb', line 164

def regexes
  @regexes.collect { |r| r.name.inspect }
end

- validate(value)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Validates the given value against the set of valid literal values and regular expressions.

Raises:

  • (ArgumentError) —

    if the value is not accepted



173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/puppet/parameter/value_collection.rb', line 173

def validate(value)
  return if empty?

  unless @values.detect { |name, v| v.match?(value) }
    str = "Invalid value #{value.inspect}. "

    str += "Valid values are #{values.join(", ")}. " unless values.empty?

    str += "Valid values match #{regexes.join(", ")}." unless regexes.empty?

    raise ArgumentError, str
  end
end

- (Puppet::Parameter::Value) value(name)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

This looks odd, asking for an instance that matches a symbol, or a instance that has a regexp. What is the intention here? Marking as api private…

Returns a valid value matcher (a literal or regular expression)

Returns:



194
195
196
 
# File 'lib/puppet/parameter/value_collection.rb', line 194

def value(name)
  @values[name]
end

- (Array<Symbol>) values  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a list of valid literal values.

Returns:

  • (Array<Symbol>) —

    Returns a list of valid literal values.

See Also:

  • regexes


202
203
204
 
# File 'lib/puppet/parameter/value_collection.rb', line 202

def values
  @strings.collect { |s| s.name }
end