class Puppet::Parameter

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
275 def aliasvalue(name, other)
276   @value_collection.aliasvalue(name, other)
277 end

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
83 def defaultto(value = nil, &block)
84   if block
85     define_method(:default, &block)
86   else
87     if value.nil?
88       raise Puppet::DevError,
89         "Either a default value or block must be provided"
90     end
91     define_method(:default) do value end
92   end
93 end

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
151 def desc(str)
152   @doc = str
153 end

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
109 def doc
110   @doc ||= ""
111 
112   unless defined?(@addeddocvals)
113     @doc = Puppet::Util::Docs.scrub(@doc)
114     vals = value_collection.doc
115     if vals
116       @doc << "\n\n#{vals}"
117     end
118 
119     features = self.required_features
120     if features
121       @doc << "\n\nRequires features #{features.flatten.collect { |f| f.to_s }.join(" ")}."
122     end
123     @addeddocvals = true
124   end
125 
126   @doc
127 end

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
575 def self.format_value_for_display(value)
576   Puppet::Pops::Types::StringConverter.convert(value, Puppet::Pops::Types::StringConverter::DEFAULT_PARAMETER_FORMAT)
577 end

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

    # File lib/puppet/parameter.rb
160 def initvars
161   @value_collection = ValueCollection.new
162 end

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
199 def isnamevar
200   @isnamevar = true
201   @required = true
202 end

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

    # File lib/puppet/parameter.rb
207 def isnamevar?
208   @isnamevar
209 end

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
217 def isrequired
218   @required = true
219 end

@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
172 def munge(&block)
173   # I need to wrap the unsafe version in begin/rescue parameterments,
174   # but if I directly call the block then it gets bound to the
175   # class's context, not the instance's, thus the two methods,
176   # instead of just one.
177   define_method(:unsafe_munge, &block)
178 end

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
344 def initialize(resource: nil, value: nil, should: nil)
345   if resource
346     self.resource = resource
347   else
348     raise Puppet::DevError, _("No resource set for %{name}") % { name: self.class.name }
349   end
350 
351   self.value = value if value
352   self.should = should if should
353 end

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
264 def newvalues(*names)
265   @value_collection.newvalues(*names)
266 end

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
140 def nodefault
141   undef_method :default if public_method_defined? :default
142 end

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

    # File lib/puppet/parameter.rb
283 def self.proxymethods(*values)
284   values.each { |val|
285     define_method(val) do
286       self.class.send(val)
287     end
288   }
289 end

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
236 def required?
237   @required
238 end

@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
227 def required_features=(*args)
228   @required_features = args.flatten.collect { |a| a.to_s.downcase.intern }
229 end

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

    # File lib/puppet/parameter.rb
188 def unmunge(&block)
189   define_method(:unsafe_unmunge, &block)
190 end

@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
251 def validate(&block)
252   define_method(:unsafe_validate, &block)
253 end

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

    # File lib/puppet/parameter.rb
324 def file
325   resource.file
326 end

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
564 def format(fmt, *args)
565   fmt % args.map { |arg| @sensitive ? "[redacted]" : arg.to_s }
566 end

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

    # File lib/puppet/parameter.rb
319 def line
320   resource.line
321 end

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
360 def log(msg)
361   send_log(resource[:loglevel], msg)
362 end

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

    # File lib/puppet/parameter.rb
365 def metaparam?
366   self.class.metaparam
367 end

Munges the value from DSL form 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
440 def munge(value)
441   return value if value.is_a?(Puppet::Pops::Evaluator::DeferredValue)
442 
443   begin
444     ret = unsafe_munge(value)
445   rescue Puppet::Error => detail
446     Puppet.debug { "Reraising #{detail}" }
447     raise
448   rescue => detail
449     raise Puppet::DevError, _("Munging failed for value %{value} in class %{class_name}: %{detail}") % { value: value.inspect, class_name: self.name, detail: detail }, detail.backtrace
450   end
451   ret
452 end

@!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
377 def name
378   self.class.name
379 end

@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
384 def noop
385   @noop ||= false
386   tmp = @noop || self.resource.noop || Puppet[:noop] || false
387   #debug "noop is #{tmp}"
388   tmp
389 end

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

    # File lib/puppet/parameter.rb
314 def path
315   @path ||= '/' + pathbuilder.join('/')
316 end

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
396 def pathbuilder
397   if @resource
398     return [@resource.pathbuilder, self.name]
399   else
400     return [self.name]
401   end
402 end

@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
525 def provider
526   @resource.provider
527 end

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

    # File lib/puppet/parameter.rb
493 def remove
494   @resource = nil
495 end

@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
537 def tags
538   unless defined?(@tags)
539     @tags = []
540     # This might not be true in testing
541     @tags = @resource.tags if @resource.respond_to? :tags
542     @tags << self.name.to_s
543   end
544   @tags
545 end

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

    # File lib/puppet/parameter.rb
548 def to_s
549   name.to_s
550 end

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
418 def unmunge(value)
419   return value if value.is_a?(Puppet::Pops::Evaluator::DeferredValue)
420 
421   unsafe_unmunge(value)
422 end

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
409 def unsafe_munge(value)
410   self.class.value_collection.munge(value)
411 end

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

@api private

    # File lib/puppet/parameter.rb
429 def unsafe_unmunge(value)
430   value
431 end

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
463 def unsafe_validate(value)
464   self.class.value_collection.validate(value)
465 end

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
475 def validate(value)
476   return if value.is_a?(Puppet::Pops::Evaluator::DeferredValue)
477 
478   begin
479     unsafe_validate(value)
480   rescue ArgumentError => detail
481     self.fail Puppet::Error, detail.to_s, detail
482   rescue Puppet::Error, TypeError
483     raise
484   rescue => detail
485     raise Puppet::DevError, _("Validate method failed for class %{class_name}: %{detail}") % { class_name: self.name, detail: detail }, detail.backtrace
486   end
487 end

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

    # File lib/puppet/parameter.rb
498 def value
499   unmunge(@value) unless @value.nil?
500 end

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
513 def value=(value)
514   validate(value)
515 
516   @value = munge(value)
517 end

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

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