class Puppet::Parameter

The Parameter class is the implementation of a resource's attributes of parameter kind. The Parameter class is also the base class for {Puppet::Property}, and is used to describe meta-parameters (parameters that apply to all resource types). A Parameter (in contrast to a Property) has a single value where a property has both a current and a wanted value. The Parameter class methods are used to configure and create an instance of Parameter that represents one particular attribute data type; its valid value(s), and conversion to/from internal form.

The intention is that a new parameter is created by using the DSL method {Puppet::Type.newparam}, or {Puppet::Type.newmetaparam} if the parameter should be applicable to all resource types.

A Parameter that does not specify and valid values (via {newvalues}) accepts any value.

@see Puppet::Type @see Puppet::Property @api public

Attributes

default[R]

@return [Object] The default value of the parameter as determined by the {defaultto} method, or nil if no

default has been set.
metaparam[RW]

@return [Boolean] Flag indicating whether this parameter is a meta-parameter or not.

name[R]

@return [Symbol] The parameter name as given when it was created.

required_features[R]

@comment This somewhat odd documentation construct is because the getter and setter are not

orthogonal; the setter uses varargs and this confuses yard. To overcome the problem both the
getter and the setter are documented here. If this issues is fixed, a todo will be displayed
for the setter method, and the setter documentation can be moved there.
Since the attribute is actually RW it should  perhaps instead just be implemented as a setter
and a getter method (and no attr_xxx declaration).

@!attribute [rw] required_features @return [Array<Symbol>] The names of the _provider features_ required for this parameter to work.

the returned names are always all lower case symbols.

@overload required_features

Returns the required _provider features_ as an array of lower case symbols

@overload required_features=(*args)

@param *args [Symbol] one or more names of required provider features
Sets the required_provider_features_ from one or more values, or array. The given arguments
are flattened, and internalized.

@api public @dsl type

value_collection[R]

@return [Puppet::Parameter::ValueCollection] The set of valid values (or an empty set that accepts any value). @api private

parent[RW]

@comment LAK 2007-05-09: Keep the @parent around for backward compatibility. @return [Puppet::Parameter] A reference to the parameter's parent kept for backwards compatibility. @api private

resource[RW]

@return [Puppet::Resource] A reference to the resource this parameter is an attribute of (the _associated resource_).

sensitive[RW]

@!attribute [rw] sensitive

@return [true, false] If this parameter has been tagged as sensitive.

Public Class Methods

aliasvalue(name, other) click to toggle source

Makes the given `name` an alias for the given `other` name. Or said differently, the valid value `other` can now also be referred to via the given `name`. Aliasing may affect how the parameter's value is serialized/stored (it may store the `other` value instead of the alias). @api public @dsl type

    # File lib/puppet/parameter.rb
274 def aliasvalue(name, other)
275   @value_collection.aliasvalue(name, other)
276 end
defaultto(value = nil, &block) click to toggle source

Defines how the `default` value of a parameter is computed. The computation of the parameter's default value is defined by providing a value or a block. A default of `nil` can not be used. @overload defaultto(value)

Defines the default value with a literal value
@param value [Object] the literal value to use as the default value

@overload defaultto({|| … })

Defines that the default value is produced by the given block. The given block
should produce the default value.

@raise [Puppet::DevError] if value is nil, and no block is given. @return [void] @see Parameter.default @dsl type @api public

   # File lib/puppet/parameter.rb
82 def defaultto(value = nil, &block)
83   if block
84     define_method(:default, &block)
85   else
86     if value.nil?
87       raise Puppet::DevError,
88         "Either a default value or block must be provided"
89     end
90     define_method(:default) do value end
91   end
92 end
desc(str) click to toggle source

Sets the documentation for this parameter. @param str [String] The documentation string to set @return [String] the given `str` parameter @see doc @dsl type @api public

    # File lib/puppet/parameter.rb
150 def desc(str)
151   @doc = str
152 end
doc() click to toggle source

Produces a documentation string. If an enumeration of _valid values_ has been defined, it is appended to the documentation for this parameter specified with the {desc} method. @return [String] Returns a documentation string. @api public

    # File lib/puppet/parameter.rb
108 def doc
109   @doc ||= ""
110 
111   unless defined?(@addeddocvals)
112     @doc = Puppet::Util::Docs.scrub(@doc)
113     vals = value_collection.doc
114     if vals
115       @doc << "\n\n#{vals}"
116     end
117 
118     features = self.required_features
119     if features
120       @doc << "\n\nRequires features #{features.flatten.collect { |f| f.to_s }.join(" ")}."
121     end
122     @addeddocvals = true
123   end
124 
125   @doc
126 end
format_value_for_display(value) click to toggle source

Produces a String with the value formatted for display to a human.

The output is created using the StringConverter with format '%#p' to produce human readable code that is understood by puppet.

@return [String] The formatted value in string form.

    # File lib/puppet/parameter.rb
559 def self.format_value_for_display(value)
560   Puppet::Pops::Types::StringConverter.convert(value, Puppet::Pops::Types::StringConverter::DEFAULT_PARAMETER_FORMAT)
561 end
initvars() click to toggle source

Initializes the instance variables. Clears the internal value collection (set of allowed values). @return [void] @api private

    # File lib/puppet/parameter.rb
159 def initvars
160   @value_collection = ValueCollection.new
161 end
isnamevar() click to toggle source

Sets a marker indicating that this parameter is the namevar (unique identifier) of the type where the parameter is contained. This also makes the parameter a required value. The marker can not be unset once it has been set. @return [void] @dsl type @api public

    # File lib/puppet/parameter.rb
198 def isnamevar
199   @isnamevar = true
200   @required = true
201 end
isnamevar?() click to toggle source

@return [Boolean] Returns whether this parameter is the namevar or not. @api public

    # File lib/puppet/parameter.rb
206 def isnamevar?
207   @isnamevar
208 end
isrequired() click to toggle source

Sets a marker indicating that this parameter is required. Once set, it is not possible to make a parameter optional. @return [void] @dsl type @api public

    # File lib/puppet/parameter.rb
216 def isrequired
217   @required = true
218 end
munge(&block) click to toggle source

@overload munge {|| … } Defines an optional method used to convert the parameter value from DSL/string form to an internal form. If a munge method is not defined, the DSL/string value is used as is. @note This adds a method with the name `unsafe_munge` in the created parameter class. Later this method is

called in a context where exceptions will be rescued and handled.

@dsl type @api public

    # File lib/puppet/parameter.rb
171 def munge(&block)
172   # I need to wrap the unsafe version in begin/rescue parameterments,
173   # but if I directly call the block then it gets bound to the
174   # class's context, not the instance's, thus the two methods,
175   # instead of just one.
176   define_method(:unsafe_munge, &block)
177 end
new(resource: nil, value: nil, should: nil) click to toggle source

Initializes the parameter with a required resource reference and optional attribute settings. The option `:resource` must be specified or an exception is raised. Any additional options passed are used to initialize the attributes of this parameter by treating each key in the `options` hash as the name of the attribute to set, and the value as the value to set. @param options [Hash{Symbol => Object]] Options, where `resource` is required @option options [Puppet::Resource] :resource The resource this parameter holds a value for. Required. @raise [Puppet::DevError] If resource is not specified in the options hash. @api public @note A parameter should be created via the DSL method {Puppet::Type::newparam}

    # File lib/puppet/parameter.rb
343 def initialize(resource: nil, value: nil, should: nil)
344   if resource
345     self.resource = resource
346   else
347     raise Puppet::DevError, _("No resource set for %{name}") % { name: self.class.name }
348   end
349 
350   self.value = value if value
351   self.should = should if should
352 end
newvalues(*names) click to toggle source

Defines valid values for the parameter (enumeration or regular expressions). The set of valid values for the parameter can be limited to a (mix of) literal values and regular expression patterns. @note Each call to this method adds to the set of valid values @param names [Symbol, Regexp] The set of valid literal values and/or patterns for the parameter. @return [void] @dsl type @api public

    # File lib/puppet/parameter.rb
263 def newvalues(*names)
264   @value_collection.newvalues(*names)
265 end
nodefault() click to toggle source

Removes the `default` method if defined. Has no effect if the default method is not defined. This method is intended to be used in a DSL scenario where a parameter inherits from a parameter with a default value that is not wanted in the derived parameter (otherwise, simply do not define a default value method).

@return [void] @see desc @api public @dsl type

    # File lib/puppet/parameter.rb
139 def nodefault
140   undef_method :default if public_method_defined? :default
141 end
proxymethods(*values) click to toggle source

Creates instance (proxy) methods that delegates to a class method with the same name. @api private

    # File lib/puppet/parameter.rb
282 def self.proxymethods(*values)
283   values.each { |val|
284     define_method(val) do
285       self.class.send(val)
286     end
287   }
288 end
required?() click to toggle source

Returns whether this parameter is required or not. A parameter is required if a call has been made to the DSL method {isrequired}. @return [Boolean] Returns whether this parameter is required or not. @api public

    # File lib/puppet/parameter.rb
235 def required?
236   @required
237 end
required_features=(*args) click to toggle source

@comment This method is not picked up by yard as it has a different signature than

expected for an attribute (varargs). Instead, this method is documented as an overload
of the attribute required_features. (Not ideal, but better than nothing).

@todo If this text appears in documentation - see comment in source and makes corrections - it means

that an issue in yardoc has been fixed.
    # File lib/puppet/parameter.rb
226 def required_features=(*args)
227   @required_features = args.flatten.collect { |a| a.to_s.downcase.intern }
228 end
sensitive(value = nil, &block) click to toggle source
    # File lib/puppet/parameter.rb
 94 def sensitive(value = nil, &block)
 95   if block
 96     define_method(:is_sensitive, &block)
 97   else
 98     define_method(:is_sensitive) do value end
 99   end
100 end
unmunge(&block) click to toggle source

@overload unmunge {|| … } Defines an optional method used to convert the parameter value to DSL/string form from an internal form. If an `unmunge` method is not defined, the internal form is used. @see munge @note This adds a method with the name `unmunge` in the created parameter class. @dsl type @api public

    # File lib/puppet/parameter.rb
187 def unmunge(&block)
188   define_method(:unmunge, &block)
189 end
validate(&block) click to toggle source

@overload validate {|| … } Defines an optional method that is used to validate the parameter's DSL/string value. Validation should raise appropriate exceptions, the return value of the given block is ignored. The easiest way to raise an appropriate exception is to call the method {Puppet::Util::Errors.fail} with the message as an argument. To validate the munged value instead, just munge the value (`munge(value)`).

@return [void] @dsl type @api public

    # File lib/puppet/parameter.rb
250 def validate(&block)
251   define_method(:unsafe_validate, &block)
252 end

Public Instance Methods

file() click to toggle source

@return [Integer] Returns the result of calling the same method on the associated resource.

    # File lib/puppet/parameter.rb
323 def file
324   resource.file
325 end
format(fmt, *args) click to toggle source

Formats the given string and conditionally redacts the provided interpolation variables, depending on if this property is sensitive.

@note Because the default implementation of Puppet::Property#is_to_s returns the current value as-is, it

doesn't necessarily return a string. For the sake of sanity we just cast everything to a string for
interpolation so we don't introduce issues with unexpected property values.

@see String#format @param fmt [String] The format string to interpolate. @param args [Array<String>] One or more strings to conditionally redact and interpolate into the format string.

@return [String]

    # File lib/puppet/parameter.rb
548 def format(fmt, *args)
549   fmt % args.map { |arg| @sensitive ? "[redacted]" : arg.to_s }
550 end
line() click to toggle source

@return [Integer] Returns the result of calling the same method on the associated resource.

    # File lib/puppet/parameter.rb
318 def line
319   resource.line
320 end
log(msg) click to toggle source

Writes the given `msg` to the log with the loglevel indicated by the associated resource's `loglevel` parameter. @todo is loglevel a metaparameter? it is looked up with `resource` @return [void] @api public

    # File lib/puppet/parameter.rb
359 def log(msg)
360   send_log(resource[:loglevel], msg)
361 end
metaparam?() click to toggle source

@return [Boolean] Returns whether this parameter is a meta-parameter or not.

    # File lib/puppet/parameter.rb
364 def metaparam?
365   self.class.metaparam
366 end
munge(value) click to toggle source

Munges the value to internal form. This implementation of `munge` provides exception handling around the specified munging of this parameter. @note This method should not be overridden. Use the DSL method {munge} to define a munging method

if required.

@param value [Object] the DSL value to munge @return [Object] the munged (internal) value

    # File lib/puppet/parameter.rb
428 def munge(value)
429   begin
430     ret = unsafe_munge(value)
431   rescue Puppet::Error => detail
432     Puppet.debug { "Reraising #{detail}" }
433     raise
434   rescue => detail
435     raise Puppet::DevError, _("Munging failed for value %{value} in class %{class_name}: %{detail}") % { value: value.inspect, class_name: self.name, detail: detail }, detail.backtrace
436   end
437   ret
438 end
name() click to toggle source

@!attribute [r] name @return [Symbol] The parameter's name as given when it was created. @note Since a Parameter defines the name at the class level, each Parameter class must be

unique within a type's inheritance chain.

@comment each parameter class must define the name method, and parameter

instances do not change that name this implicitly means that a given
object can only have one parameter instance of a given parameter
class
    # File lib/puppet/parameter.rb
376 def name
377   self.class.name
378 end
noop() click to toggle source

@return [Boolean] Returns true if this parameter, the associated resource, or overall puppet mode is `noop`. @todo How is noop mode set for a parameter? Is this of value in DSL to inhibit a parameter?

    # File lib/puppet/parameter.rb
383 def noop
384   @noop ||= false
385   tmp = @noop || self.resource.noop || Puppet[:noop] || false
386   #debug "noop is #{tmp}"
387   tmp
388 end
path() click to toggle source

Returns a string representation of the resource's containment path in the catalog. @return [String]

    # File lib/puppet/parameter.rb
313 def path
314   @path ||= '/' + pathbuilder.join('/')
315 end
pathbuilder() click to toggle source

Returns an array of strings representing the containment hierarchy (types/classes) that make up the path to the resource from the root of the catalog. This is mostly used for logging purposes.

@api private

    # File lib/puppet/parameter.rb
395 def pathbuilder
396   if @resource
397     return [@resource.pathbuilder, self.name]
398   else
399     return [self.name]
400   end
401 end
provider() click to toggle source

@return [Puppet::Provider] Returns the provider of the associated resource. @todo The original comment says = _“Retrieve the resource's provider.

Some types don't have providers, in which case we return the resource object itself."_
This does not seem to be true, the default implementation that sets this value may be
{Puppet::Type.provider=} which always gets either the name of a provider or an instance of one.
    # File lib/puppet/parameter.rb
509 def provider
510   @resource.provider
511 end
remove() click to toggle source

Sets the associated resource to nil. @todo Why - what is the intent/purpose of this? @return [nil]

    # File lib/puppet/parameter.rb
477 def remove
478   @resource = nil
479 end
tags() click to toggle source

@return [Array<Symbol>] Returns an array of the associated resource's symbolic tags (including the parameter itself). Returns an array of the associated resource's symbolic tags (including the parameter itself). At a minimum, the array contains the name of the parameter. If the associated resource has tags, these tags are also included in the array. @todo The original comment says = _“The properties need to return tags so that logs correctly

collect them."_ what if anything of that is of interest to document. Should tags and their relationship
to logs be described. This is a more general concept.
    # File lib/puppet/parameter.rb
521 def tags
522   unless defined?(@tags)
523     @tags = []
524     # This might not be true in testing
525     @tags = @resource.tags if @resource.respond_to? :tags
526     @tags << self.name.to_s
527   end
528   @tags
529 end
to_s() click to toggle source

@return [String] The name of the parameter in string form.

    # File lib/puppet/parameter.rb
532 def to_s
533   name.to_s
534 end
unmunge(value) click to toggle source

Unmunges the value by transforming it from internal form to DSL form. This is the default implementation of `unmunge` that simply returns the value without processing. The DSL method {unmunge} should be used to define an overriding method if required. @return [Object] the unmunged value

    # File lib/puppet/parameter.rb
417 def unmunge(value)
418   value
419 end
unsafe_munge(value) click to toggle source

This is the default implementation of `munge` that simply produces the value (if it is valid). The DSL method {munge} should be used to define an overriding method if munging is required.

@api private

    # File lib/puppet/parameter.rb
408 def unsafe_munge(value)
409   self.class.value_collection.munge(value)
410 end
unsafe_validate(value) click to toggle source

This is the default implementation of `validate` that may be overridden by the DSL method {validate}. If no valid values have been defined, the given value is accepted, else it is validated against the literal values (enumerator) and/or patterns defined by calling {newvalues}.

@param value [Object] the value to check for validity @raise [ArgumentError] if the value is not valid @return [void] @api private

    # File lib/puppet/parameter.rb
449 def unsafe_validate(value)
450   self.class.value_collection.validate(value)
451 end
validate(value) click to toggle source

Performs validation of the given value against the rules defined by this parameter. @return [void] @todo Better description of when the various exceptions are raised.ArgumentError is rescued and

changed into Puppet::Error.

@raise [ArgumentError, TypeError, Puppet::DevError, Puppet::Error] under various conditions A protected validation method that only ever raises useful exceptions. @api public

    # File lib/puppet/parameter.rb
461 def validate(value)
462   begin
463     unsafe_validate(value)
464   rescue ArgumentError => detail
465     self.fail Puppet::Error, detail.to_s, detail
466   rescue Puppet::Error, TypeError
467     raise
468   rescue => detail
469     raise Puppet::DevError, _("Validate method failed for class %{class_name}: %{detail}") % { class_name: self.name, detail: detail }, detail.backtrace
470   end
471 end
value() click to toggle source

@return [Object] Gets the value of this parameter after performing any specified unmunging.

    # File lib/puppet/parameter.rb
482 def value
483   unmunge(@value) unless @value.nil?
484 end
value=(value) click to toggle source

Sets the given value as the value of this parameter. @todo This original comment _“All of the checking should possibly be

late-binding (e.g., users might not exist when the value is assigned
but might when it is asked for)."_ does not seem to be correct, the implementation
calls both validate and munge on the given value, so no late binding.

The given value is validated and then munged (if munging has been specified). The result is store as the value of this parameter. @return [Object] The given `value` after munging. @raise (see validate)

    # File lib/puppet/parameter.rb
497 def value=(value)
498   validate(value)
499 
500   @value = munge(value)
501 end
version() click to toggle source

@return [Integer] Returns the result of calling the same method on the associated resource.

    # File lib/puppet/parameter.rb
328 def version
329   resource.version
330 end