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