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.



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

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.



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 %{value}") % { value: other }
  end

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

    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.



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

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.



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

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

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

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

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

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.

Parameters:

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

    a customizable set of options

Options Hash (options):

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



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

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}" if !value.regex?
  else
    devfail "Cannot use :call value ':instead' without a block for property '#{self.class.name}'" if call_opt == :instead
  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.



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

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.



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

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



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

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:



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

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:



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

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