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

#initialize ⇒ ValueCollection

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 new instance of ValueCollection.



64
65
66
67
68
69
70
71
72
 
# File 'lib/puppet/parameter/value_collection.rb', line 64

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) ⇒ void

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.

Raises:



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

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

  value.alias(name)
end

#doc ⇒ String

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
51
52
53
 
# File 'lib/puppet/parameter/value_collection.rb', line 32

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

    unless regexes.empty?
      @doc << "Values can match `#{regexes.join('`, `')}`."
    end
  end

  @doc
end

#empty? ⇒ Boolean

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.



58
59
60
 
# File 'lib/puppet/parameter/value_collection.rb', line 58

def empty?
  @values.empty?
end

#match?(test_value) ⇒ Puppet::Parameter::Value?

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.



83
84
85
86
87
88
89
90
 
# File 'lib/puppet/parameter/value_collection.rb', line 83

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

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

#munge(value) ⇒ Object

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



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

def munge(value)
  return value if empty?

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

#newvalue(name, options = {}, &block) ⇒ Object

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.

  • :invalidate_refreshes (Symbol) —

    True if a change on this property should invalidate and remove any scheduled refreshes (from notify or subscribe) targeted at the same resource. For example, if a change in this property takes into account any changes that a scheduled refresh would have performed, then the scheduled refresh would be deleted.

  • _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).



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/puppet/parameter/value_collection.rb', line 133

def newvalue(name, options = {}, &block)
  call_opt = options[:call]
  unless call_opt.nil?
    devfail "Cannot use obsolete :call value '#{call_opt}' for property '#{self.class.name}'" unless call_opt == :none || call_opt == :instead
    # TRANSLATORS ':call' is a property and should not be translated
    message = _("Property option :call is deprecated and no longer used.")
    message += ' ' + _("Please remove it.")
    Puppet.deprecation_warning(message)
    options = options.reject { |k, _v| k == :call }
  end

  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?
    devfail "Cannot use :call value ':none' in combination with a block for property '#{self.class.name}'" if call_opt == :none
    value.block = block
    value.method ||= "set_#{value.name}" unless value.regex?
  elsif call_opt == :instead
    devfail "Cannot use :call value ':instead' without a block for property '#{self.class.name}'"
  end
  value
end

#newvalues(*names) ⇒ void

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.



168
169
170
 
# File 'lib/puppet/parameter/value_collection.rb', line 168

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

#regexes ⇒ Array<String>

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 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.



175
176
177
 
# File 'lib/puppet/parameter/value_collection.rb', line 175

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

#validate(value) ⇒ void

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



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/puppet/parameter/value_collection.rb', line 184

def validate(value)
  return if empty?

  unless @values.detect { |_name, v| v.match?(value) }
    str = _("Invalid value %{value}.") % { value: value.inspect }
    str += " " + _("Valid values are %{value_list}.") % { value_list: values.join(", ") } unless values.empty?
    str += " " + _("Valid values match %{pattern}.") % { pattern: regexes.join(", ") } unless regexes.empty?
    raise ArgumentError, str
  end
end

#value(name) ⇒ Puppet::Parameter::Value

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 an 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:



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

def value(name)
  @values[name]
end

#values ⇒ Array<Symbol>

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:



210
211
212
 
# File 'lib/puppet/parameter/value_collection.rb', line 210

def values
  @strings.collect(&:name)
end