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
63 def initialize
64   # We often look values up by name, so a hash makes more sense.
65   @values = {}
66 
67   # However, we want to retain the ability to match values in order,
68   # but we always prefer directly equality (i.e., strings) over regex matches.
69   @regexes = []
70   @strings = []
71 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
19 def aliasvalue(name, other)
20   other = other.to_sym
21   value = match?(other)
22   raise Puppet::DevError, _("Cannot alias nonexistent value %{value}") % { value: other } unless value
23 
24   value.alias(name)
25 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
31 def doc
32   unless defined?(@doc)
33     @doc = ""
34     unless values.empty?
35       @doc << "Valid values are "
36       @doc << @strings.collect do |value|
37         aliases = value.aliases
38         if aliases && ! aliases.empty?
39           "`#{value.name}` (also called `#{aliases.join(", ")}`)"
40         else
41           "`#{value.name}`"
42         end
43       end.join(", ") << ". "
44     end
45 
46     unless regexes.empty?
47       @doc << "Values can match `#{regexes.join("`, `")}`."
48     end
49   end
50 
51   @doc
52 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
57 def empty?
58   @values.empty?
59 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
82 def match?(test_value)
83   # First look for normal values
84   value = @strings.find { |v| v.match?(test_value) }
85   return value if value
86 
87   # Then look for a regex match
88   @regexes.find { |v| v.match?(test_value) }
89 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
 99 def munge(value)
100   return value if empty?
101 
102   instance = match?(value)
103   if instance
104     if instance.regex?
105       return value
106     else
107       return instance.name
108     end
109   else
110     return value
111   end
112 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
132 def newvalue(name, options = {}, &block)
133   call_opt = options[:call]
134   unless call_opt.nil?
135     devfail "Cannot use obsolete :call value '#{call_opt}' for property '#{self.class.name}'" unless call_opt == :none || call_opt == :instead
136     #TRANSLATORS ':call' is a property and should not be translated
137     message = _("Property option :call is deprecated and no longer used.")
138     message += ' ' + _("Please remove it.")
139     Puppet.deprecation_warning(message)
140     options = options.reject { |k,v| k == :call }
141   end
142 
143   value = Puppet::Parameter::Value.new(name)
144   @values[value.name] = value
145   if value.regex?
146     @regexes << value
147   else
148     @strings << value
149   end
150 
151   options.each { |opt, arg| value.send(opt.to_s + "=", arg) }
152   if block_given?
153     devfail "Cannot use :call value ':none' in combination with a block for property '#{self.class.name}'" if call_opt == :none
154     value.block = block
155     value.method ||= "set_#{value.name}" if !value.regex?
156   else
157     devfail "Cannot use :call value ':instead' without a block for property '#{self.class.name}'" if call_opt == :instead
158   end
159   value
160 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
167 def newvalues(*names)
168   names.each { |name| newvalue(name) }
169 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
174 def regexes
175   @regexes.collect { |r| r.name.inspect }
176 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
183 def validate(value)
184   return if empty?
185 
186   unless @values.detect {|name, v| v.match?(value)}
187     str = _("Invalid value %{value}.") % { value: value.inspect }
188     str += " " + _("Valid values are %{value_list}.") % { value_list: values.join(", ") } unless values.empty?
189     str += " " + _("Valid values match %{pattern}.") % { pattern: regexes.join(", ") } unless regexes.empty?
190     raise ArgumentError, str
191   end
192 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
201 def value(name)
202   @values[name]
203 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
209 def values
210   @strings.collect { |s| s.name }
211 end