If you’re using data types to match or restrict values and need more flexibility than what the core data types (such as String or Array) allow, you can use one of the abstract data types to construct a data type that suits your needs and matches the values you want.
Each of Puppet's core data types has a corresponding value that represents that data type, which can be used to match values of that type in several contexts. Each of those core data types only match a particular set of values. They let you further restrict the values they’ll match, but only in limited ways, and there’s no way to expand the set of values they’ll match. If you need to do this, use the corresponding abstract data type.
Flexible data types
These abstract data types can match values with a variety of concrete data types. Some of them are similar to a concrete type but offer alternate ways to restrict them (for example, Enum), and some of them let you combine types and match a union of what they would individually match (for example, Variant and Optional).
The Optional data type
The Optional data type wraps one other data type, and results in a data type that matches anything that type would match plus undef. This is useful for matching values that are allowed to be absent. It takes one required parameter.
Optional is:Optional[<DATA TYPE>]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 | Data type | Type or String | none (you must specify a value) | The data type to add undef to. |
If you specify a string "my string" as the parameter, it's equivalent to using Optional[Enum["my string"]] — it matches only that exact string value or undef.
Optional[<DATA TYPE>] is equivalent to Variant[ <DATA TYPE>, Undef ].
-
Optional[String] - Matches any string or
undef. -
Optional[Array[Integer[0, 10]]] - Matches an array of integers between 0 and 10, or
undef. -
Optional["present"] - Matches the exact string
"present"orundef.
The NotUndef data type
The NotUndef type matches any value except undef. It can also wrap one other data type, resulting in a type that matches anything the original type would match except undef. It accepts one optional parameter.
NotUndef is:NotUndef[<DATA TYPE>]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 | Data type | Type or String | Any | The data type to subtract undef from. |
If you specify a string as a parameter for NotUndef, it's equivalent to writing NotUndef[Enum["my string"]] — it matches only that exact string value. This doesn’t actually subtract anything, because the Enum wouldn’t have matched undef anyway, but it's a convenient notation for mandatory keys in Struct schema hashes.
The Variant data type
The Variant data type combines any number of other data types, and results in a type that matches the union of what any of those data types would match. It takes any number of parameters, and requires at least one.
Variant is:Variant[ <DATA TYPE>, (<DATA TYPE, ...) ]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 and up | Data type | Type | none (required) | A data type to add to the resulting compound data type. You must provide at least one data type parameter, and can provide any number of additional ones. |
-
Variant[Integer, Float] - Matches any integer or floating point number (equivalent to
Numeric). -
Variant[Enum['true', 'false'], Boolean] - matches
'true','false',true, orfalse.
The Pattern data type
The Pattern data type only matches strings, but it provides an alternate way to restrict which strings it matches. It takes any number of regular expressions, and results in a data type that matches any strings that would match any of those regular expressions. It takes any number of parameters, and requires at least one.
Pattern[ <REGULAR EXPRESSION>, (<REGULAR EXPRESSION>, ...) ]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 and up | Regular expression | Regexp | none (required) | A regular expression describing a set of strings that the resulting data type should match. You must provide at least one regular expression parameter, and can provide any number of additional ones. |
You can use capture groups in the regular expressions, but they won’t cause any variables, like $1, to be set.
-
Pattern[/\A[a-z].*/] - Matches any string that begins with a lowercase letter.
-
Pattern[/\A[a-z].*/, /\ANone\Z/] - Matches the above or the exact string
None.
The Enum data type
The Enum data type only matches strings, but it provides an alternate way to restrict which strings it matches. It takes any number of strings, and results in a data type that matches any string values that exactly match one of those strings. Unlike the == operator, this matching is case-sensitive. It takes any number of parameters, and requires at least one.
Enum is:Enum[ <OPTION>, (<OPTION>, ...) ]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 and up | Option | String | none (required) | One of the literal string values that the resulting data type should match. You must provide at least one option parameter, and can provide any number of additional ones. |
-
Enum['stopped', 'running'] - Matches the strings
'stopped'and'running', and no other values. -
Enum['true', 'false'] - Matches the strings
'true'and'false', and no other values. Does not match the boolean valuestrueorfalse(without quotes).
The Tuple data type
The Tuple type only matches arrays, but it lets you specify different data types for every element of the array, in order. It takes any number of parameters, and requires at least one.
Tuple is:Tuple[ <CONTENT TYPE>, (<CONTENT TYPE>, ..., <MIN SIZE>, <MAX SIZE>) ]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 and up | Content type | Type | none (required) | What kind of values the array contains at the given position. You must provide at least one content type parameter, and can provide any number of additional ones. |
| -2 (second-last) | Minimum size | Integer | number of content types | The minimum number of elements in the array. If this is smaller than the number of content types you provided, any elements beyond the minimum are optional; however, if present, they must still match the provided content types. This parameter accepts the value default, but this won’t use the default value; instead, it means 0 (all elements optional). |
| -1 (last) | Maximum size | Integer | number of content types | The maximum number of elements in the array. You cannot specify a maximum without also specifying a minimum. If the maximum is larger than the number of content types you provided, it means the array can contain any number of additional elements, which all must match the last content type. This parameter accepts the value Don't set the maximum smaller than the number of content types you provide. |
-
Tuple[String, Integer] - Matches a two-element array containing a string followed by an integer, like
["hi", 2]. -
Tuple[String, Integer, 1] - Matches the above or a one-element array containing only a string.
-
Tuple[String, Integer, 1, 4] - Matches an array containing one string followed by zero to three integers.
-
Tuple[String, Integer, 1, default] - Matches an array containing one string followed by any number of integers.
The Struct data type
Struct type only matches hashes, but it lets you specify: The name of every allowed key.
Whether each key is required or optional.
The allowed data type for each of those keys’ values.
It takes one mandatory parameter.
Struct is:Struct[<SCHEMA HASH>]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 | Schema hash | Hash[Variant[String, Optional, NotUndef], Type] | none (required) | A hash that has all of the allowed keys and data types for the struct. |
A Struct’s schema hash must have the same keys as the hashes it matches. Each value must be a data type that matches the allowed values for that key.
The keys in a schema hash are usually strings. They can also be an Optional or NotUndef type with the key’s name as their parameter.
If a key is a string, Puppet uses the value’s type to determine whether it’s optional — because accessing a missing key resolves to the value undef, the key is optional if the value type accepts undef (like Optional[Array]).
Note that this doesn’t distinguish between an explicit value of undef and an absent key. If you want to be more explicit, you can use Optional['my_key'] to indicate that a key can be absent, and NotUndef['my_key'] to make it mandatory. If you use one of these, a value type that accepts undef is only used to decide about explicit undef values, not missing keys.
Struct matches hashes like {mode => 'read', path => '/etc/fstab'}. Both the mode and path keys are mandatory; mode’s value must be one of 'read', 'write', or 'update', and path must be a string of at least one character:Struct[{mode => Enum[read, write, update],
path => String[1]}]path key is optional. If present, path must match String[1] or Undef:Struct[{mode => Enum[read, write, update],
path => Optional[String[1]]}]owner key can be absent, but if it’s present, it must be a string; a value of undef isn’t allowed:Struct[{mode => Enum[read, write, update],
path => Optional[String[1]],
Optional[owner] => String[1]}]undef value:Struct[{mode => Enum[read, write, update],
path => Optional[String[1]],
NotUndef[owner] => Optional[String[1]]}]Parent types
These abstract data types are the parents of multiple other types, and match values that would match any of their sub-types. They’re useful when you have very loose restrictions but not no restrictions.
The
Scalar data type
Scalar data type matches all values of the following concrete data types:
-
Numbers (both integers and floats)
-
Strings
-
Booleans
-
Regular expressions
It doesn’t match undef, default, resource references, arrays, or hashes. It takes no parameters.
Scalar is equivalent to Variant[Integer, Float, String, Boolean, Regexp].
The
Data data type
Data data type matches any value that would match Scalar, but it also matches:
-
undef -
Arrays that only conatin values that also match
Data -
Hashes whose keys match
Scalarand whose values also matchData
It doesn't match default or resource references. It takes no parameters.
Data is especially useful because it represents the subset of types that can be directly represented in almost all serialization format, such as JSON.
The
Collection data type
The Collection type matches any array or hash, regardless of what kinds of values or keys it contains. It only partially overlaps with Data — there are values, such as an array of resource references, that match Collection but do not match Data.
Collection is equivalent to Variant[Array[Any], Hash[Any, Any]].
The
Catalogentry data type
The Catalogentry data type is the parent type of Resource and Class. Like those types, the Puppet language contains no values that it ever matches. However, the type Type[Catalogentry] matches any class reference or resource reference. It takes no parameters.
The
Any data type
The Any data type matches any value of any data type.
Other types
These types aren’t quite like the others.
The
Callable data type
The Callable data type matches callable lambdas provided as function arguments.
There is no way to interact with Callable values in the Puppet language, but Ruby functions written to the function API (Puppet::Functions) can use Callable to inspect the lambda provided to the function.
Callable is:Callable[ (<DATA TYPE>, ...,) <MIN COUNT>, <MAX COUNT>, <BLOCK TYPE> ]| Position | Parameter | Data type | Default value | Description |
|---|---|---|---|---|
| 1 to n | Data type | Type | none | Any number of data types, representing the data type of each argument the lambda accepts. |
| -3 (third last) | Minimum count | Integer | 0 | The minimum number of arguments the lambda accepts. This parameter accepts the value default, which uses its default value 0.
|
| -2 (second last) | Maximum count | Integer | infinity | The maximum number of arguments the lambda accepts. This parameter accepts the value default, which uses its default value, infinity.
|
| -1 (last) | Block type | Type[Callable] | none | The block_type of the lambda.
|