Parameters

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. Tools that generate docs from this description trim leading whitespace from multiline strings, as described for type descriptions.

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

Namevar

Every type must have at least one mandatory parameter: the namevar. This parameter uniquely identifies each resource of the type on the target system — for example, the path of a file on disk, the name of a user account, or the name of a package.

If the user doesn’t specify a value for the namevar when declaring a resource, its value defaults to the title of the resource.

There are three ways to designate a namevar. Every type must have exactly one parameter that meets exactly one of these criteria:

1. Create a parameter whose name is :name. Because most types just use :name as the namevar, it gets special treatment and automatically becomes the namevar.

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

2. Provide the :namevar => true option as an additional argument to the newparam call. This allows you to use a namevar with a different, more descriptive name, such as the file type’s path parameter.

   newparam(:path, :namevar => true) do
     ...
   end

3. Call the isnamevar method (which takes no arguments) inside the parameter’s code block. This allows you to use a namevar with a different, more descriptive name. There is no practical difference between this and option 2.

   newparam(:path) do
     isnamevar
     ...
   end

Specifying allowed values

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

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

You can specify regular expressions in addition to literal values; matches against regex 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 is set to :blue, but if you provide green, then it is 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(value)
    end
  end

  munge do |value|
    case value
    when :mauve, :violet # are these colors really any different?
      :purple
    else
      super(value)
    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 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?.