Parameters

Parameters are defined essentially exactly the same as properties; the only difference between them is that parameters never result in methods being called on providers.

To define a new parameter, call the newparam method. This method takes the name of the parameter (as a symbol) as its argument, as well as a block of code. You can and should provide documentation for each parameter by calling the desc method inside its block. Leading whitespace is trimmed from multiline strings as described above.

    newparam(:name) do
      desc "The name of the database."
    end

Specifying Allowed Values

If your parameter has a fixed list of valid values, you can declare them all at once:

    newparam(:color) do
      newvalues(:red, :green, :blue, :purple)
    end

You can specify regexes in addition to literal values; matches against regexes always happen after equality comparisons against literal values, and those matches are not converted to symbols. For instance, given the following definition:

    newparam(:color) do
      desc "Your color, and stuff."

      newvalues(:blue, :red, /.+/)
    end

If you provide blue as the value, then your parameter will get set to :blue, but if you provide green, then it will get set to “green”.

Validation and Munging

If your parameter does not have a defined list of values, or you need to convert the values in some way, you can use the validate and munge hooks:

    newparam(:color) do
      desc "Your color, and stuff."

      newvalues(:blue, :red, /.+/)

      validate do |value|
        if value == "green"
          raise ArgumentError,
            "Everyone knows green databases don't have enough RAM"
        else
          super
        end
      end

      munge do |value|
        case value
        when :mauve, :violet # are these colors really any different?
          :purple
        else
          super
        end
      end
    end

The default validate method looks for values defined using newvalues and if there are any values defined it accepts only those values (this is exactly how allowed values are validated). The default munge method converts any values that are specifically allowed into symbols. If you override either of these methods, note that you lose this value handling and symbol conversion, which you’ll have to call super for.

Values are always validated before they’re munged.

Lastly, validation and munging only* happen when a value is assigned. They have no role to play at all during use of a given value, only during assignment.

Boolean Parameters

Boolean parameters are common. To avoid repetition, some utilities are available:

    require 'puppet/parameter/boolean'
    # ...
    newparam(:force, :boolean => true, :parent => Puppet::Parameter::Boolean)

There are two parts here. The :parent => Puppet::Parameter::Boolean part configures the parameter to accept lots of names for true and false, to make things easy for your users. The :boolean => true creates a boolean method on the type class to return the value of the parameter. In this example, the method would be named force?.

abrader/parameters.md

Select an option