# 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.

munger[R]

Unused? @todo The term “munger” only appears in this location in the Puppet code base. There is munge and unmunge

    and they seem to work perfectly fine without this attribute declaration.

@api private

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

validater[R]

Unused? @todo The term “validater” only appears in this location in the Puppet code base. There is `validate`

    which seems to works fine without this attribute declaration.

@api private

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_).

### Public Class Methods

format_value_for_display(value) click to toggle source

Produces a String with the value formatted for display to a human. When the parameter value is a:

- **single valued parameter value** the result is produced on the form `‘value’` where value is the string form of the parameter’s value.

- *Array* the list of values is enclosed in `[]`, and each produced value is separated by a comma.

- *Hash* value is output with keys in sorted order enclosed in `{}` with each entry formatted on the form `‘k’ => v` where `k` is the key in string form and v is the value of the key. Entries are comma separated.

For both Array and Hash this method is called recursively to format contained values. @note this method does not protect against infinite structures.

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

    # File lib/puppet/parameter.rb, line 541
    def self.format_value_for_display(value)
      if value.is_a? Array
        formatted_values = value.collect {|value| format_value_for_display(value)}.join(', ')
        "[#{formatted_values}]"
      elsif value.is_a? Hash
        # Sorting the hash keys for display is largely for having stable
        # output to test against, but also helps when scanning for hash
        # keys, since they will be in ASCIIbetical order.
        hash = value.keys.sort {|a,b| a.to_s <=> b.to_s}.collect do |k|
          "'#{k}' => #{format_value_for_display(value[k])}"
        end.join(', ')

        "{#{hash}}"
      else
        "'#{value}'"
      end
    end

new(options = {}) 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, line 329
    def initialize(options = {})
      options = symbolize_options(options)
      if resource = options[:resource]
        self.resource = resource
        options.delete(:resource)
      else
        raise Puppet::DevError, "No resource set for #{self.class.name}"
      end

      set_options(options)
    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, line 282
    def self.proxymethods(*values)
      values.each { |val|
        define_method(val) do
          self.class.send(val)
        end
      }
    end

### Public Instance 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, line 274
    def aliasvalue(name, other)
      @value_collection.aliasvalue(name, other)
    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 ::default @dsl type @api public

    # File lib/puppet/parameter.rb, line 99
    def defaultto(value = nil, &block)
      if block
        define_method(:default, &block)
      else
        if value.nil?
          raise Puppet::DevError,
            "Either a default value or block must be provided"
        end
        define_method(:default) do value end
      end
    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, line 154
    def desc(str)
      @doc = str
    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, line 117
    def doc
      @doc ||= ""

      unless defined?(@addeddocvals)
        @doc += value_collection.doc

        if f = self.required_features
          @doc += "  Requires features #{f.flatten.collect { |f| f.to_s }.join(" ")}."
        end
        @addeddocvals = true
      end

      @doc
    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, line 163
    def initvars
      @value_collection = ValueCollection.new
    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, line 202
    def isnamevar
      @isnamevar = true
      @required = true
    end

isnamevar?() click to toggle source

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

    # File lib/puppet/parameter.rb, line 210
    def isnamevar?
      @isnamevar
    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, line 220
    def isrequired
      @required = true
    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, line 346
    def log(msg)
      send_log(resource[:loglevel], msg)
    end

metaparam?() click to toggle source

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

    # File lib/puppet/parameter.rb, line 351
    def metaparam?
      self.class.metaparam
    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, line 175
    def munge(&block)
      # I need to wrap the unsafe version in begin/rescue parameterments,
      # but if I directly call the block then it gets bound to the
      # class's context, not the instance's, thus the two methods,
      # instead of just one.
      define_method(:unsafe_munge, &block)
    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, line 363
    def name
      self.class.name
    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, line 263
    def newvalues(*names)
      @value_collection.newvalues(*names)
    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, line 143
    def nodefault
      undef_method :default if public_method_defined? :default
    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, line 370
    def noop
      @noop ||= false
      tmp = @noop || self.resource.noop || Puppet[:noop] || false
      #debug "noop is #{tmp}"
      tmp
    end

pathbuilder() click to toggle source

@todo Original comment = _return the full path to us, for logging and rollback; not currently

    used_ This is difficult to figure out (if it is used or not as calls are certainly made to "pathbuilder"
    method is several places, not just sure if it is this implementation or not.

@api private

    # File lib/puppet/parameter.rb, line 382
    def pathbuilder
      if @resource
        return [@resource.pathbuilder, self.name]
      else
        return [self.name]
      end
    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, line 496
    def provider
      @resource.provider
    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, line 464
    def remove
      @resource = nil
    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, line 239
    def required?
      @required
    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, line 230
    def required_features=(*args)
      @required_features = args.flatten.collect { |a| a.to_s.downcase.intern }
    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 minimun, 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, line 508
    def tags
      unless defined?(@tags)
        @tags = []
        # This might not be true in testing
        @tags = @resource.tags if @resource.respond_to? :tags
        @tags << self.name.to_s
      end
      @tags
    end

to_s() click to toggle source

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

    # File lib/puppet/parameter.rb, line 519
    def to_s
      name.to_s
    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, line 191
    def unmunge(&block)
      define_method(:unmunge, &block)
    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, line 395
    def unsafe_munge(value)
      self.class.value_collection.munge(value)
    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, line 436
    def unsafe_validate(value)
      self.class.value_collection.validate(value)
    end

validate(&block) click to toggle source

@overload validate {|| … } Defines an optional method that is used to validate the parameter’s value. Validation should raise appropriate exceptions, the return value of the given block is ignored. @return [void] @dsl type @api public

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

value() click to toggle source

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

    # File lib/puppet/parameter.rb, line 469
    def value
      unmunge(@value) unless @value.nil?
    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 an 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 arameter. @return [Object] The given `value` after munging. @raise (see validate)

    # File lib/puppet/parameter.rb, line 484
    def value=(value)
      validate(value)

      @value = munge(value)
    end