class Puppet::Parameter::ValueCollection

A collection of values and regular expressions, used for specifying allowed values in a given parameter. @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.

@comment This class probably have several problems when trying to use it with a combination of

regular expressions and aliases as it finds an acceptable value holder vi "name" which may be
a regular expression...

@api private

Public Class Methods

new() click to toggle source

@api private

   # File lib/puppet/parameter/value_collection.rb
64 def initialize
65   # We often look values up by name, so a hash makes more sense.
66   @values = {}
67 
68   # However, we want to retain the ability to match values in order,
69   # but we always prefer directly equality (i.e., strings) over regex matches.
70   @regexes = []
71   @strings = []
72 end

Public Instance Methods

aliasvalue(name, other) click to toggle source

Aliases the given existing other value with the additional given name. @return [void] @api private

   # File lib/puppet/parameter/value_collection.rb
20 def aliasvalue(name, other)
21   other = other.to_sym
22   value = match?(other)
23   raise Puppet::DevError, _("Cannot alias nonexistent value %{value}") % { value: other } unless value
24 
25   value.alias(name)
26 end

doc() click to toggle source

Returns a doc string (enumerating the acceptable values) for all of the values in this parameter/property. @return [String] a documentation string. @api private

   # File lib/puppet/parameter/value_collection.rb
32 def doc
33   unless defined?(@doc)
34     @doc = String.new
35     unless values.empty?
36       @doc << "Valid values are "
37       @doc << @strings.collect do |value|
38         aliases = value.aliases
39         if aliases && ! aliases.empty?
40           "`#{value.name}` (also called `#{aliases.join(", ")}`)"
41         else
42           "`#{value.name}`"
43         end
44       end.join(", ") << ". "
45     end
46 
47     unless regexes.empty?
48       @doc << "Values can match `#{regexes.join("`, `")}`."
49     end
50   end
51 
52   @doc
53 end

empty?() click to toggle source

@return [Boolean] Returns whether the set of allowed values is empty or not. @api private

   # File lib/puppet/parameter/value_collection.rb
58 def empty?
59   @values.empty?
60 end

match?(test_value) click to toggle source

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.

@param test_value [Object] the value to test if it complies with the configured rules @return [Puppet::Parameter::Value, nil] The instance of Puppet::Parameter::Value that matched the given value, or nil if there was no match. @api private

   # File lib/puppet/parameter/value_collection.rb
83 def match?(test_value)
84   # First look for normal values
85   value = @strings.find { |v| v.match?(test_value) }
86   return value if value
87 
88   # Then look for a regex match
89   @regexes.find { |v| v.match?(test_value) }
90 end

munge(value) click to toggle source

Munges the value if it is valid, else produces the same value. @param value [Object] the value to munge @return [Object] the munged value, or the given value @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?

@api private

    # File lib/puppet/parameter/value_collection.rb
100 def munge(value)
101   return value if empty?
102 
103   instance = match?(value)
104   if instance
105     if instance.regex?
106       return value
107     else
108       return instance.name
109     end
110   else
111     return value
112   end
113 end

newvalue(name, options = {}, &block) click to toggle source

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.

@param name [Symbol, Regexp] a valid literal value, or a regexp that matches a value @param options [Hash] a hash with options @option options [Symbol] :event The event that should be emitted when this value is set. @todo Option :event original comment says “event should be returned…”, is “returned” the correct word

to use?

@option options [Symbol] :invalidate_refreshes 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.

@option options [Object] any 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).

@api private

    # File lib/puppet/parameter/value_collection.rb
133 def newvalue(name, options = {}, &block)
134   call_opt = options[:call]
135   unless call_opt.nil?
136     devfail "Cannot use obsolete :call value '#{call_opt}' for property '#{self.class.name}'" unless call_opt == :none || call_opt == :instead
137     #TRANSLATORS ':call' is a property and should not be translated
138     message = _("Property option :call is deprecated and no longer used.")
139     message += ' ' + _("Please remove it.")
140     Puppet.deprecation_warning(message)
141     options = options.reject { |k,v| k == :call }
142   end
143 
144   value = Puppet::Parameter::Value.new(name)
145   @values[value.name] = value
146   if value.regex?
147     @regexes << value
148   else
149     @strings << value
150   end
151 
152   options.each { |opt, arg| value.send(opt.to_s + "=", arg) }
153   if block_given?
154     devfail "Cannot use :call value ':none' in combination with a block for property '#{self.class.name}'" if call_opt == :none
155     value.block = block
156     value.method ||= "set_#{value.name}" if !value.regex?
157   else
158     devfail "Cannot use :call value ':instead' without a block for property '#{self.class.name}'" if call_opt == :instead
159   end
160   value
161 end

newvalues(*names) click to toggle source

Defines one or more valid values (literal or regexp) for a parameter or property. @return [void] @dsl type @api private

    # File lib/puppet/parameter/value_collection.rb
168 def newvalues(*names)
169   names.each { |name| newvalue(name) }
170 end

regexes() click to toggle source

@return [Array<String>] An array of the regular expressions in string form, configured as matching valid values. @api private

    # File lib/puppet/parameter/value_collection.rb
175 def regexes
176   @regexes.collect { |r| r.name.inspect }
177 end

validate(value) click to toggle source

Validates the given value against the set of valid literal values and regular expressions. @raise [ArgumentError] if the value is not accepted @return [void] @api private

    # File lib/puppet/parameter/value_collection.rb
184 def validate(value)
185   return if empty?
186 
187   unless @values.detect {|name, v| v.match?(value)}
188     str = _("Invalid value %{value}.") % { value: value.inspect }
189     str += " " + _("Valid values are %{value_list}.") % { value_list: values.join(", ") } unless values.empty?
190     str += " " + _("Valid values match %{pattern}.") % { pattern: regexes.join(", ") } unless regexes.empty?
191     raise ArgumentError, str
192   end
193 end

value(name) click to toggle source

Returns a valid value matcher (a literal or regular expression) @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...

@return [Puppet::Parameter::Value] a valid value matcher @api private

    # File lib/puppet/parameter/value_collection.rb
202 def value(name)
203   @values[name]
204 end

values() click to toggle source

@return [Array<Symbol>] Returns a list of valid literal values. @see regexes @api private

    # File lib/puppet/parameter/value_collection.rb
210 def values
211   @strings.collect { |s| s.name }
212 end