Docs / Function Reference

Function Reference

Function Reference

This page is autogenerated; any changes will get overwritten (last generated on 2015-06-30 13:08:47 -0700)

There are two types of functions in Puppet: Statements and rvalues. Statements stand on their own and do not return arguments; they are used for performing stand-alone work like importing. Rvalues return values and can only be used in a statement requiring a value, such as an assignment or a case statement.

Functions execute on the Puppet master. They do not execute on the Puppet agent. Hence they only have access to the commands and data available on the Puppet master host.

Here are the functions available in Puppet:

alert

Log a message on the server at level alert.

  • Type: statement

assert_type

Returns the given value if it is an instance of the given type, and raises an error otherwise. Optionally, if a block is given (accepting two parameters), it will be called instead of raising an error. This to enable giving the user richer feedback, or to supply a default value.

Example: assert that $b is a non empty String and assign to $a:

$a = assert_type(String[1], $b)

Example using custom error message:

$a = assert_type(String[1], $b) |$expected, $actual| { fail(‘The name cannot be empty’) }

Example, using a warning and a default:

$a = assert_type(String[1], $b) |$expected, $actual| { warning(‘Name is empty, using default’) ‘anonymous’ }

See the documentation for ‘The Puppet Type System’ for more information about types. - Since 4.0.0

  • Type: rvalue

contain

Contain one or more classes inside the current class. If any of these classes are undeclared, they will be declared as if called with the include function. Accepts a class name, an array of class names, or a comma-separated list of class names.

A contained class will not be applied before the containing class is begun, and will be finished before the containing class is finished.

You must use the class’s full name; relative names are not allowed. In addition to names in string form, you may also directly use Class and Resource Type values that are produced by evaluating resource and relationship expressions.

  • Since 4.0.0 support for Class and Resource Type values, absolute names

  • Type: statement

create_resources

Converts a hash into a set of resources and adds them to the catalog.

This function takes two mandatory arguments: a resource type, and a hash describing a set of resources. The hash should be in the form {title => {parameters} }:

# A hash of user resources:
$myusers = {
  'nick' => { uid    => '1330',
              gid    => allstaff,
              groups => ['developers', 'operations', 'release'], },
  'dan'  => { uid    => '1308',
              gid    => allstaff,
              groups => ['developers', 'prosvc', 'release'], },
}

create_resources(user, $myusers)

A third, optional parameter may be given, also as a hash:

$defaults = {
  'ensure'   => present,
  'provider' => 'ldap',
}

create_resources(user, $myusers, $defaults)

The values given on the third argument are added to the parameters of each resource present in the set given on the second argument. If a parameter is present on both the second and third arguments, the one on the second argument takes precedence.

This function can be used to create defined resources and classes, as well as native resources.

Virtual and Exported resources may be created by prefixing the type name with @ or @@ respectively. For example, the $myusers hash may be exported in the following manner:

create_resources("@@user", $myusers)

The $myusers may be declared as virtual resources using:

create_resources("@user", $myusers)
  • Type: statement

crit

Log a message on the server at level crit.

  • Type: statement

debug

Log a message on the server at level debug.

  • Type: statement

defined

Determine whether a given class or resource type is defined. This function can also determine whether a specific resource has been defined, or whether a variable has been assigned a value (including undef - as opposed to never having been assigned anything). Returns true or false. Accepts class names, type names, resource references, and variable reference strings of the form '$name'. When more than one argument is supplied, defined() returns true if any are defined.

The defined function checks both native and defined types, including types provided as plugins via modules. Types and classes are both checked using their names:

 defined("file")
 defined("customtype")
 defined("foo")
 defined("foo::bar")
 defined('$name')

Resource declarations are checked using resource references, e.g. defined( File['/tmp/myfile'] ). Checking whether a given resource has been declared is, unfortunately, dependent on the evaluation order of the configuration, and the following code will not work:

 if defined(File['/tmp/foo']) {
     notify { "This configuration includes the /tmp/foo file.":}
 }
 file { "/tmp/foo":
     ensure => present,
 }

However, this order requirement refers to evaluation order only, and ordering of resources in the configuration graph (e.g. with before or require) does not affect the behavior of defined.

You may also search using types:

 defined(Resource['file','/some/file'])
 defined(File['/some/file'])
 defined(Class['foo'])

The defined function does not answer if 4.x data types (e.g. Integer) are defined. If given the string ‘integer’ the result is false, and if given a non CatalogEntry type, an error is raised.

The rules for asking for undef, empty strings, and the main class are different from 3.x (non future parser) and 4.x (with future parser or in Puppet 4.0.0 and later):

 defined('')     # 3.x => true, 4.x => false
 defined(undef)  # 3.x => true, 4.x => error
 defined('main') # 3.x => false, 4.x => true

With the future parser, it is also possible to ask specifically if a name is a resource type (built in or defined), or a class, by giving its type:

 defined(Type[Class['foo']])
 defined(Type[Resource['foo']])

Which is different from asking:

 defined('foo')

Since the later returns true if ‘foo’ is either a class, a built-in resource type, or a user defined resource type, and a specific request like Type[Class['foo']] only returns true if 'foo' is a class.

  • Since 2.7.0
  • Since 3.6.0 variable reference and future parser types
  • Since 3.8.1 type specific requests with future parser

  • Type: rvalue

digest

Returns a hash value from a provided string using the digest_algorithm setting from the Puppet config file.

  • Type: rvalue

each

Applies a parameterized block to each element in a sequence of selected entries from the first argument and returns the first argument.

This function takes two mandatory arguments: the first should be an Array or a Hash or something that is of enumerable type (integer, Integer range, or String), and the second a parameterized block as produced by the puppet syntax:

  $a.each |$x| { ... }
  each($a) |$x| { ... }

When the first argument is an Array (or of enumerable type other than Hash), the parameterized block should define one or two block parameters. For each application of the block, the next element from the array is selected, and it is passed to the block if the block has one parameter. If the block has two parameters, the first is the elements index, and the second the value. The index starts from 0.

  $a.each |$index, $value| { ... }
  each($a) |$index, $value| { ... }

When the first argument is a Hash, the parameterized block should define one or two parameters. When one parameter is defined, the iteration is performed with each entry as an array of [key, value], and when two parameters are defined the iteration is performed with key and value.

  $a.each |$entry|       { ..."key ${$entry[0]}, value ${$entry[1]}" }
  $a.each |$key, $value| { ..."key ${key}, value ${value}" }

Example using each:

  [1,2,3].each |$val| { ... }                       # 1, 2, 3
  [5,6,7].each |$index, $val| { ... }               # (0, 5), (1, 6), (2, 7)
  {a=>1, b=>2, c=>3}].each |$val| { ... }           # ['a', 1], ['b', 2], ['c', 3]
  {a=>1, b=>2, c=>3}.each |$key, $val| { ... }      # ('a', 1), ('b', 2), ('c', 3)
  Integer[ 10, 20 ].each |$index, $value| { ... }   # (0, 10), (1, 11) ...
  "hello".each |$char| { ... }                      # 'h', 'e', 'l', 'l', 'o'
  3.each |$number| { ... }                          # 0, 1, 2
  • Since 4.0.0

  • Type: rvalue

emerg

Log a message on the server at level emerg.

  • Type: statement

epp

Evaluates an Embedded Puppet Template (EPP) file and returns the rendered text result as a String.

The first argument to this function should be a <MODULE NAME>/<TEMPLATE FILE> reference, which will load <TEMPLATE FILE> from a module’s templates directory. (For example, the reference apache/vhost.conf.epp will load the file <MODULES DIRECTORY>/apache/templates/vhost.conf.epp.)

The second argument is optional; if present, it should be a hash containing parameters for the template. (See below.)

EPP supports the following tags:

  • <%= puppet expression %> - This tag renders the value of the expression it contains.
  • <% puppet expression(s) %> - This tag will execute the expression(s) it contains, but renders nothing.
  • <%# comment %> - The tag and its content renders nothing.
  • <%% or %%> - Renders a literal <% or %> respectively.
  • <%- - Same as <% but suppresses any leading whitespace.
  • -%> - Same as %> but suppresses any trailing whitespace on the same line (including line break).
  • <%- |parameters| -%> - When placed as the first tag declares the template’s parameters.

File based EPP supports the following visibilities of variables in scope:

  • Global scope (i.e. top + node scopes) - global scope is always visible
  • Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
  • Global + declared parameters - if the EPP declares parameters, given argument names must match

EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example, <%- |$x, $y, $z = 'unicorn'| -%> when placed first in the EPP text declares that the parameters x and y must be given as template arguments when calling inline_epp, and that z if not given as a template argument defaults to 'unicorn'. Template parameters are available as variables, e.g.arguments $x, $y and $z in the example. Note that <%- must be used or any leading whitespace will be interpreted as text

Arguments are passed to the template by calling epp with a Hash as the last argument, where parameters are bound to values, e.g. epp('...', {'x'=>10, 'y'=>20}). Excess arguments may be given (i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all. Template parameters shadow variables in outer scopes. File based epp does never have access to variables in the scope where the epp function is called from.

  • See function inline_epp for examples of EPP
  • Since 4.0.0

  • Type: rvalue

err

Log a message on the server at level err.

  • Type: statement

fail

Fail with a parse error.

  • Type: statement

file

Loads a file from a module and returns its contents as a string.

The argument to this function should be a <MODULE NAME>/<FILE> reference, which will load <FILE> from a module’s files directory. (For example, the reference mysql/mysqltuner.pl will load the file <MODULES DIRECTORY>/mysql/files/mysqltuner.pl.)

This function can also accept:

  • An absolute path, which can load a file from anywhere on disk.
  • Multiple arguments, which will return the contents of the first file found, skipping any files that don’t exist.

  • Type: rvalue

filter

Applies a parameterized block to each element in a sequence of entries from the first argument and returns an array or hash (same type as left operand for array/hash, and array for other enumerable types) with the entries for which the block evaluates to true.

This function takes two mandatory arguments: the first should be an Array, a Hash, or an Enumerable object (integer, Integer range, or String), and the second a parameterized block as produced by the puppet syntax:

   $a.filter |$x| { ... }
   filter($a) |$x| { ... }

When the first argument is something other than a Hash, the block is called with each entry in turn. When the first argument is a Hash the entry is an array with [key, value].

Example Using filter with one parameter

   # selects all that end with berry
   $a = ["raspberry", "blueberry", "orange"]
   $a.filter |$x| { $x =~ /berry$/ }          # rasberry, blueberry

If the block defines two parameters, they will be set to index, value (with index starting at 0) for all enumerables except Hash, and to key, value for a Hash.

Example Using filter with two parameters

 # selects all that end with 'berry' at an even numbered index
 $a = ["raspberry", "blueberry", "orange"]
 $a.filter |$index, $x| { $index % 2 == 0 and $x =~ /berry$/ } # raspberry

 # selects all that end with 'berry' and value >= 1
 $a = {"raspberry"=>0, "blueberry"=>1, "orange"=>1}
 $a.filter |$key, $x| { $x =~ /berry$/ and $x >= 1 } # blueberry
  • Since 4.0.0

  • Type: statement

fqdn_rand

Usage: fqdn_rand(MAX, [SEED]). MAX is required and must be a positive integer; SEED is optional and may be any number or string.

Generates a random Integer number greater than or equal to 0 and less than MAX, combining the $fqdn fact and the value of SEED for repeatable randomness. (That is, each node will get a different random number from this function, but a given node’s result will be the same every time unless its hostname changes.)

This function is usually used for spacing out runs of resource-intensive cron tasks that run on many nodes, which could cause a thundering herd or degrade other services if they all fire at once. Adding a SEED can be useful when you have more than one such task and need several unrelated random numbers per node. (For example, fqdn_rand(30), fqdn_rand(30, 'expensive job 1'), and fqdn_rand(30, 'expensive job 2') will produce totally different numbers.)

  • Type: rvalue

generate

Calls an external command on the Puppet master and returns the results of the command. Any arguments are passed to the external command as arguments. If the generator does not exit with return code of 0, the generator is considered to have failed and a parse error is thrown. Generators can only have file separators, alphanumerics, dashes, and periods in them. This function will attempt to protect you from malicious generator calls (e.g., those with ‘..’ in them), but it can never be entirely safe. No subshell is used to execute generators, so all shell metacharacters are passed directly to the generator.

  • Type: rvalue

hiera

Performs a standard priority lookup and returns the most specific value for a given key. The returned value can be data of any type (strings, arrays, or hashes).

The function can be called in one of three ways: 1. Using 1 to 3 arguments where the arguments are: ‘key’ [String] Required The key to lookup. ‘default [Any] Optional A value to return when there's no match for key. Optional override` [Any] Optional An argument in the third position, providing a data source to consult for matching values, even if it would not ordinarily be part of the matched hierarchy. If Hiera doesn’t find a matching key in the named override data source, it will continue to search through the rest of the hierarchy.

  1. Using a ‘key’ and an optional ‘override’ parameter like in #1 but with a block to provide the default value. The block is called with one parameter (the key) and should return the value.

  2. Like #1 but with all arguments passed in an array.

More thorough examples of hiera are available at: http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions

  • Type: rvalue

hiera_array

Returns all matches throughout the hierarchy — not just the first match — as a flattened array of unique values. If any of the matched values are arrays, they’re flattened and included in the results.

The function can be called in one of three ways: 1. Using 1 to 3 arguments where the arguments are: ‘key’ [String] Required The key to lookup. ‘default [Any] Optional A value to return when there's no match for key. Optional override` [Any] Optional An argument in the third position, providing a data source to consult for matching values, even if it would not ordinarily be part of the matched hierarchy. If Hiera doesn’t find a matching key in the named override data source, it will continue to search through the rest of the hierarchy.

  1. Using a ‘key’ and an optional ‘override’ parameter like in #1 but with a block to provide the default value. The block is called with one parameter (the key) and should return the value.

  2. Like #1 but with all arguments passed in an array.

If any matched value is a hash, puppet will raise a type mismatch error.

More thorough examples of hiera are available at: http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions

  • Type: rvalue

hiera_hash

Returns a merged hash of matches from throughout the hierarchy. In cases where two or more hashes share keys, the hierarchy order determines which key/value pair will be used in the returned hash, with the pair in the highest priority data source winning.

The function can be called in one of three ways: 1. Using 1 to 3 arguments where the arguments are: ‘key’ [String] Required The key to lookup. ‘default [Any] Optional A value to return when there's no match for key. Optional override` [Any] Optional An argument in the third position, providing a data source to consult for matching values, even if it would not ordinarily be part of the matched hierarchy. If Hiera doesn’t find a matching key in the named override data source, it will continue to search through the rest of the hierarchy.

  1. Using a ‘key’ and an optional ‘override’ parameter like in #1 but with a block to provide the default value. The block is called with one parameter (the key) and should return the value.

  2. Like #1 but with all arguments passed in an array.

hiera_hash expects that all values returned will be hashes. If any of the values found in the data sources are strings or arrays, puppet will raise a type mismatch error.

More thorough examples of hiera_hash are available at: http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions

  • Type: rvalue

hiera_include

Assigns classes to a node using an array merge lookup that retrieves the value for a user-specified key from a Hiera data source.

To use hiera_include, the following configuration is required:

  • A key name to use for classes, e.g. classes.
  • A line in the puppet sites.pp file (e.g. /etc/puppetlabs/puppet/manifests/sites.pp) reading hiera_include('classes'). Note that this line must be outside any node definition and below any top-scope variables in use for Hiera lookups.
  • Class keys in the appropriate data sources. In a data source keyed to a node’s role, one might have:

        ---
        classes:
          - apache
          - apache::passenger
    

The function can be called in one of three ways: 1. Using 1 to 3 arguments where the arguments are: ‘key’ [String] Required The key to lookup. ‘default [Any] Optional A value to return when there's no match for key. Optional override` [Any] Optional An argument in the third position, providing a data source to consult for matching values, even if it would not ordinarily be part of the matched hierarchy. If Hiera doesn’t find a matching key in the named override data source, it will continue to search through the rest of the hierarchy.

  1. Using a ‘key’ and an optional ‘override’ parameter like in #1 but with a block to provide the default value. The block is called with one parameter (the key) and should return the array to be used in the subsequent call to include.

  2. Like #1 but with all arguments passed in an array.

More thorough examples of hiera_include are available at: http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions

  • Type: statement

include

Declares one or more classes, causing the resources in them to be evaluated and added to the catalog. Accepts a class name, an array of class names, or a comma-separated list of class names.

The include function can be used multiple times on the same class and will only declare a given class once. If a class declared with include has any parameters, Puppet will automatically look up values for them in Hiera, using <class name>::<parameter name> as the lookup key.

Contrast this behavior with resource-like class declarations (class {'name': parameter => 'value',}), which must be used in only one place per class and can directly set parameters. You should avoid using both include and resource-like declarations with the same class.

The include function does not cause classes to be contained in the class where they are declared. For that, see the contain function. It also does not create a dependency relationship between the declared class and the surrounding class; for that, see the require function.

You must use the class’s full name; relative names are not allowed. In addition to names in string form, you may also directly use Class and Resource Type values that are produced by the future parser’s resource and relationship expressions.

  • Since < 3.0.0
  • Since 4.0.0 support for class and resource type values, absolute names

  • Type: statement

info

Log a message on the server at level info.

  • Type: statement

inline_epp

Evaluates an Embedded Puppet Template (EPP) string and returns the rendered text result as a String.

EPP support the following tags:

  • <%= puppet expression %> - This tag renders the value of the expression it contains.
  • <% puppet expression(s) %> - This tag will execute the expression(s) it contains, but renders nothing.
  • <%# comment %> - The tag and its content renders nothing.
  • <%% or %%> - Renders a literal <% or %> respectively.
  • <%- - Same as <% but suppresses any leading whitespace.
  • -%> - Same as %> but suppresses any trailing whitespace on the same line (including line break).
  • <%- |parameters| -%> - When placed as the first tag declares the template’s parameters.

Inline EPP supports the following visibilities of variables in scope which depends on how EPP parameters are used - see further below:

  • Global scope (i.e. top + node scopes) - global scope is always visible
  • Global + Enclosing scope - if the EPP template does not declare parameters, and no arguments are given
  • Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
  • Global + declared parameters - if the EPP declares parameters, given argument names must match

EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example, <%- |$x, $y, $z='unicorn'| -%> when placed first in the EPP text declares that the parameters x and y must be given as template arguments when calling inline_epp, and that z if not given as a template argument defaults to 'unicorn'. Template parameters are available as variables, e.g.arguments $x, $y and $z in the example. Note that <%- must be used or any leading whitespace will be interpreted as text

Arguments are passed to the template by calling inline_epp with a Hash as the last argument, where parameters are bound to values, e.g. inline_epp('...', {'x'=>10, 'y'=>20}). Excess arguments may be given (i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all. Template parameters shadow variables in outer scopes.

Note: An inline template is best stated using a single-quoted string, or a heredoc since a double-quoted string is subject to expression interpolation before the string is parsed as an EPP template. Here are examples (using heredoc to define the EPP text):

# produces 'Hello local variable world!'
$x ='local variable'
inline_epptemplate(@(END:epp))
<%- |$x| -%>
Hello <%= $x %> world!
END

# produces 'Hello given argument world!'
$x ='local variable world'
inline_epptemplate(@(END:epp), { x =>'given argument'})
<%- |$x| -%>
Hello <%= $x %> world!
END

# produces 'Hello given argument world!'
$x ='local variable world'
inline_epptemplate(@(END:epp), { x =>'given argument'})
<%- |$x| -%>
Hello <%= $x %>!
END

# results in error, missing value for y
$x ='local variable world'
inline_epptemplate(@(END:epp), { x =>'given argument'})
<%- |$x, $y| -%>
Hello <%= $x %>!
END

# Produces 'Hello given argument planet'
$x ='local variable world'
inline_epptemplate(@(END:epp), { x =>'given argument'})
<%- |$x, $y=planet| -%>
Hello <%= $x %> <%= $y %>!
END
  • Since 3.5
  • Requires Future Parser

  • Type: rvalue

inline_template

Evaluate a template string and return its value. See the templating docs for more information. Note that if multiple template strings are specified, their output is all concatenated and returned as the output of the function.

  • Type: rvalue

lookup

Looks up data defined using Data Binding, and Data Providers using different strategies. The lookup searches in Data Bindings first (if configured; typically Hiera), then in the environments data provider (if any), and last in the module’s data provider (if any) of the module the call to lookup originates from. Thus, the global Data Binding has higher priority than data provided in the environment, which has higher priority than data provided in a module,

The lookup function can be called in one of these ways:

lookup(name)
lookup(name, value_type)
lookup(name, value_type, merge)
lookup(name, value_type, merge, default_value)
lookup(options_hash)
lookup(name, options_hash)

The function may optionally be called with a code block / lambda with the following signature:

lookup(...) |$name| { ... }

The block, if present, is mutually exclusive to the default_value and will be called with the name used in the lookup when no value is found. The value produced by the block then becomes the value produced by the lookup.

The meaning of the parameters or content of the options hash is:

  • name - The name or array of names to lookup (first found is returned)
  • value_type - The type to assert. Defaults to ‘Data’ See ‘Type Specification’ below.
  • default_value - The default value if there was no value found (must comply with the data type)
  • override - a hash with map from names to values that are used instead of the underlying bindings. If the name is found here it wins. Defaults to an empty hash.
  • default_values_hash - a hash with map from names to values that are used as a last resort to obtain a value. Defaults to an empty hash.
  • merge - A string of type Enum[unique, hash, merge] or a hash with the key ‘strategy’ set to that string. See ‘Merge Strategies’ below.

It is not permitted to pass the name as both a parameter and in the options hash.

The search will proceed as follows: 1. For each name given in the name array (or once, if it’s just one name): - If a matching key is found in the override hash, it’s value is immediately type checked and returned - Search and optionally merge Data Binding, environment data providers, and module data providers - Type check and return the value if a matching key is found 2. For each name given in the name array (or once, if it’s just one name): - Type check and return the value if a matching key is found in the default_values_hash 3. Type check and return either the given default_value or the result of calling the code block if either exist 4. Raise an error indicating that no matching value was found

Merge Strategies

The default behavior of the lookup is to return the first value that is found for the given name. The optional merge parameter will change this so that a lookup makes an attempt to find values in all three sources (the Data Binder, the environment, and the module scope) and then merge these values according to the given strategy. This does not apply to values found in the ‘override’ hash. Such values are returned immediately without merging. Note that merge is passed on to allow the underlying provider to return a merged result

The valid strategies are: - ‘hash’ Performs a simple hash-merge by overwriting keys of lower lookup priority. Merged values must be of Hash type - ‘unique’ Appends everything to an array containing no nested arrays and where all duplicates have been removed. Can append values of Scalar or Array[Scalar] type - ‘deep’ Performs a deep merge on values of Array and Hash type. See documentation for the DeepMerge gem’s deep_merge operation for details and options.

The ‘deep’ strategy can use additional options to control its behavior. Options can be passed as top level keys in the merge parameter when it is a given as a hash. Recognized options are: - ‘knockout_prefix’ Set to string value to signify prefix which deletes elements from existing element. Defaults is undef - ‘sort_merged_arrays’ Set to true to sort all arrays that are merged together. Default is false - ‘unpack_arrays’ Set to string value used as a deliminator to join all array values and then split them again. Default is undef - ‘merge_hash_arrays’ Set to true to merge hashes within arrays. Default is false

Type Specification

The type specification is a type in the Puppet Type System, e.g.: * Integer, an integral value with optional range e.g.: * Integer[0, default] - 0 or positive * Integer[default, -1] - negative, * Integer[1,100] - value between 1 and 100 inclusive * String- any string * Float - floating point number (same signature as for Integer for Integer ranges) * Boolean - true of false (strict) * Array - an array (of Data by default), or parameterized as Array[<element_type>], where <element_type> is the expected type of elements * Hash, - a hash (of default Literal keys and Data values), or parameterized as Hash[<value_type>], Hash[<key_type>, <value_type>], where <key_type>, and <value_type> are the types of the keys and values respectively (key is Literal by default). * Data - abstract type representing any Literal (including undef), Array[Data], or Hash[Literal, Data] * Pattern[<p1>, <p2>, ..., <pn>] - an enumeration of valid patterns (one or more) where a pattern is a regular expression string or regular expression, e.g. Pattern['.com$', '.net$'], Pattern[/[a-z]+[0-9]+/] * Enum[<s1>, <s2>, ..., <sn>], - an enumeration of exact string values (one or more) e.g. Enum[blue, red, green]. * Variant[<t1>, <t2>,...<tn>] - matches one of the listed types (at least one must be given) e.g. Variant[Integer[8000,8999], Integer[20000, 99999]] to accept a value in either range * Regexp- a regular expression (i.e. the result is a regular expression, not a string matching a regular expression).

For more options and details about types, see the Puppet Language Reference

Handling of undef

When no match is found for the given name when searching all sources, (including the overrideand default_values_hash), then the value used is either the default_value or the value produced by the given block. If neither is provided, then the lookup will always raise an error. Note that this only applies when there’s no match for the given name. It does not happen when a value is found and that value happens to be undef.

Validation of returned value

The produced value is subject to type validation using the value_type (if given) and an error is raised unless the resulting value is of correct type.

Examples

When called with one argument; the name, it returns the bound value with the given name after having asserted it has the default datatype Data:

lookup('the_name')

When called with two arguments; the name, and the expected type, it returns the bound value with the given name after having asserted it has the given data type (‘String’ in the example):

lookup('the_name', String)

When called with four arguments, the name, the expected type, the merge strategy, and a default value, it returns the bound value with the given name, or the default after having asserted the value has the given data type:

lookup('the_name', String, undef, 'Fred')
lookup('the_name', Array[String], 'unique', [Fred])

Using a lambda to provide a default value by calling a function:

lookup('the_size', Integer[1,100]) |$name| {
  obtain_size_default()
}

There are two ways to make lookup return undef when no matching key was found instead of raising an error. Either call it with four arguments (the merge argument must be present even when using the default strategy to ensure that the four argument variant is used):

 $are_you_there = lookup('peekaboo', Optional[String], undef, undef)

or call it using an options hash:

 $are_you_there = lookup('peekaboo', { 'default_value' => undef })
 $are_you_there = lookup({ 'name' => 'peekaboo', 'default_value' => undef })

or with a block that produces an undef value:

 $are_you_there = lookup('peekaboo', Optional[String]) |$name| { undef }
  • Since 4.0.0

  • Type: rvalue

map

Applies a parameterized block to each element in a sequence of entries from the first argument and returns an array with the result of each invocation of the parameterized block.

This function takes two mandatory arguments: the first should be an Array, Hash, or of Enumerable type (integer, Integer range, or String), and the second a parameterized block as produced by the puppet syntax:

  $a.map |$x| { ... }
  map($a) |$x| { ... }

When the first argument $a is an Array or of enumerable type, the block is called with each entry in turn. When the first argument is a hash the entry is an array with [key, value].

Example Using map with two arguments

 # Turns hash into array of values
 $a.map |$x|{ $x[1] }

 # Turns hash into array of keys
 $a.map |$x| { $x[0] }

When using a block with 2 parameters, the element’s index (starting from 0) for an array, and the key for a hash is given to the block’s first parameter, and the value is given to the block’s second parameter.args.

Example Using map with two arguments

 # Turns hash into array of values
 $a.map |$key,$val|{ $val }

 # Turns hash into array of keys
 $a.map |$key,$val|{ $key }
  • Since 4.0.0

  • Type: rvalue

match

Returns the match result of matching a String or Array[String] with one of:

  • Regexp
  • String - transformed to a Regexp
  • Pattern type
  • Regexp type

Returns An Array with the entire match at index 0, and each subsequent submatch at index 1-n. If there was no match undef is returned. If the value to match is an Array, a array with mapped match results is returned.

Example matching:

“abc123”.match(/([a-z]+)[1-9]+/) # => [“abc”] “abc123”.match(/([a-z]+)([1-9]+)/) # => [“abc”, “123”]

See the documentation for “The Puppet Type System” for more information about types.

  • Since 4.0.0

  • Type: statement

md5

Returns a MD5 hash value from a provided string.

  • Type: rvalue

notice

Log a message on the server at level notice.

  • Type: statement

realize

Make a virtual object real. This is useful when you want to know the name of the virtual object and don’t want to bother with a full collection. It is slightly faster than a collection, and, of course, is a bit shorter. You must pass the object using a reference; e.g.: realize User[luke].

  • Type: statement

reduce

Applies a parameterized block to each element in a sequence of entries from the first argument (the enumerable) and returns the last result of the invocation of the parameterized block.

This function takes two mandatory arguments: the first should be an Array, Hash, or something of enumerable type, and the last a parameterized block as produced by the puppet syntax:

  $a.reduce |$memo, $x| { ... }
  reduce($a) |$memo, $x| { ... }

When the first argument is an Array or someting of an enumerable type, the block is called with each entry in turn. When the first argument is a hash each entry is converted to an array with [key, value] before being fed to the block. An optional ‘start memo’ value may be supplied as an argument between the array/hash and mandatory block.

  $a.reduce(start) |$memo, $x| { ... }
  reduce($a, start) |$memo, $x| { ... }

If no ‘start memo’ is given, the first invocation of the parameterized block will be given the first and second elements of the enumeration, and if the enumerable has fewer than 2 elements, the first element is produced as the result of the reduction without invocation of the block.

On each subsequent invocation, the produced value of the invoked parameterized block is given as the memo in the next invocation.

Example Using reduce

  # Reduce an array
  $a = [1,2,3]
  $a.reduce |$memo, $entry| { $memo + $entry }
  #=> 6

  # Reduce hash values
  $a = {a => 1, b => 2, c => 3}
  $a.reduce |$memo, $entry| { [sum, $memo[1]+$entry[1]] }
  #=> [sum, 6]

  # reverse a string
  "abc".reduce |$memo, $char| { "$char$memo" }
  #=>"cbe"

It is possible to provide a starting ‘memo’ as an argument.

Example Using reduce with given start ‘memo’

  # Reduce an array
  $a = [1,2,3]
  $a.reduce(4) |$memo, $entry| { $memo + $entry }
  #=> 10

  # Reduce hash values
  $a = {a => 1, b => 2, c => 3}
  $a.reduce([na, 4]) |$memo, $entry| { [sum, $memo[1]+$entry[1]] }
  #=> [sum, 10]

Example Using reduce with an Integer range

  Integer[1,4].reduce |$memo, $x| { $memo + $x }
  #=> 10
  • since 4.0.0

  • Type: rvalue

regsubst

Perform regexp replacement on a string or array of strings.

  • Parameters (in order):
    • target The string or array of strings to operate on. If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array.
    • regexp The regular expression matching the target string. If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself.
    • replacement Replacement string. Can contain backreferences to what was matched using \0 (whole match), \1 (first set of parentheses), and so on.
    • flags Optional. String of single letter flags for how the regexp is interpreted:
      • E Extended regexps
      • I Ignore case in regexps
      • M Multiline regexps
      • G Global replacement; all occurrences of the regexp in each target string will be replaced. Without this, only the first occurrence will be replaced.
    • encoding Optional. How to handle multibyte characters. A single-character string with the following values:
      • N None
      • E EUC
      • S SJIS
      • U UTF-8
  • Examples

Get the third octet from the node’s IP address:

$i3 = regsubst($ipaddress,'^(\d+)\.(\d+)\.(\d+)\.(\d+)$','\3')

Put angle brackets around each octet in the node’s IP address:

$x = regsubst($ipaddress, '([0-9]+)', '<\1>', 'G')
  • Type: rvalue

require

Evaluate one or more classes, adding the required class as a dependency.

The relationship metaparameters work well for specifying relationships between individual resources, but they can be clumsy for specifying relationships between classes. This function is a superset of the ‘include’ function, adding a class relationship so that the requiring class depends on the required class.

Warning: using require in place of include can lead to unwanted dependency cycles.

For instance the following manifest, with ‘require’ instead of ‘include’ would produce a nasty dependence cycle, because notify imposes a before between File[/foo] and Service[foo]:

class myservice {
  service { foo: ensure => running }
}

class otherstuff {
  include myservice
  file { '/foo': notify => Service[foo] }
}

Note that this function only works with clients 0.25 and later, and it will fail if used with earlier clients.

You must use the class’s full name; relative names are not allowed. In addition to names in string form, you may also directly use Class and Resource Type values that are produced when evaluating resource and relationship expressions.

  • Since 4.0.0 Class and Resource types, absolute names

  • Type: statement

scanf

Scans a string and returns an array of one or more converted values as directed by a given format string.args See the documenation of Ruby’s String::scanf method for details about the supported formats (which are similar but not identical to the formats used in Puppet’s sprintf function.

This function takes two mandatory arguments: the first is the String to convert, and the second the format String. The result of the scan is an Array, with each sucessfully scanned and transformed value.args The scanning stops if a scan is unsuccesful and the scanned result up to that point is returned. If there was no succesful scan at all, the result is an empty Array.

  scanf("42", "%i")[0] == 42

When used with the future parser, an optional parameterized block may be given. The block is called with the result that is produced by scanf if no block is present, the result of the block is then returned by the function.

The optional code block is typically used to assert that the scan was succesful, and either produce the same input, or perform unwrapping of the result:

  "42".scanf("%i")
  "42".scanf("%i") |$x| {
    unless $x[0] =~ Integer {
      fail "Expected a well formed integer value, got '$x[0]'"
    }
    $x[0]
  }
  • since 3.7.4 with parser = future
  • since 3.7.5 with classic parser

  • Type: rvalue

sha1

Returns a SHA1 hash value from a provided string.

  • Type: rvalue

shellquote

Quote and concatenate arguments for use in Bourne shell.

Each argument is quoted separately, and then all are concatenated with spaces. If an argument is an array, the elements of that array is interpolated within the rest of the arguments; this makes it possible to have an array of arguments and pass that array to shellquote instead of having to specify each argument individually in the call.

  • Type: rvalue

slice

Applies a parameterized block to each slice of elements in a sequence of selected entries from the first argument and returns the first argument, or if no block is given returns a new array with a concatenation of the slices.

This function takes two mandatory arguments: the first, $a, should be an Array, Hash, or something of enumerable type (integer, Integer range, or String), and the second, $n, the number of elements to include in each slice. The optional third argument should be a a parameterized block as produced by the puppet syntax:

$a.slice($n) |$x| { ... }
slice($a) |$x| { ... }

The parameterized block should have either one parameter (receiving an array with the slice), or the same number of parameters as specified by the slice size (each parameter receiving its part of the slice). In case there are fewer remaining elements than the slice size for the last slice it will contain the remaining elements. When the block has multiple parameters, excess parameters are set to undef for an array or enumerable type, and to empty arrays for a Hash.

$a.slice(2) |$first, $second| { ... }

When the first argument is a Hash, each key,value entry is counted as one, e.g, a slice size of 2 will produce an array of two arrays with key, and value.

Example Using slice with Hash

$a.slice(2) |$entry|          { notice "first ${$entry[0]}, second ${$entry[1]}" }
$a.slice(2) |$first, $second| { notice "first ${first}, second ${second}" }

When called without a block, the function produces a concatenated result of the slices.

Example Using slice without a block

slice([1,2,3,4,5,6], 2) # produces [[1,2], [3,4], [5,6]]
slice(Integer[1,6], 2)  # produces [[1,2], [3,4], [5,6]]
slice(4,2)              # produces [[0,1], [2,3]]
slice('hello',2)        # produces [[h, e], [l, l], [o]]
  • Since 4.0.0

  • Type: rvalue

split

Split a string variable into an array using the specified split regexp.

Example:

$string     = 'v1.v2:v3.v4'
$array_var1 = split($string, ':')
$array_var2 = split($string, '[.]')
$array_var3 = split($string, '[.:]')

$array_var1 now holds the result ['v1.v2', 'v3.v4'], while $array_var2 holds ['v1', 'v2:v3', 'v4'], and $array_var3 holds ['v1', 'v2', 'v3', 'v4'].

Note that in the second example, we split on a literal string that contains a regexp meta-character (.), which must be escaped. A simple way to do that for a single character is to enclose it in square brackets; a backslash will also escape a single character.

  • Type: rvalue

sprintf

Perform printf-style formatting of text.

The first parameter is format string describing how the rest of the parameters should be formatted. See the documentation for the Kernel::sprintf function in Ruby for all the details.

  • Type: rvalue

tag

Add the specified tags to the containing class or definition. All contained objects will then acquire that tag, also.

  • Type: statement

tagged

A boolean function that tells you whether the current container is tagged with the specified tags. The tags are ANDed, so that all of the specified tags must be included for the function to return true.

  • Type: rvalue

template

Loads an ERB template from a module, evaluates it, and returns the resulting value as a string.

The argument to this function should be a <MODULE NAME>/<TEMPLATE FILE> reference, which will load <TEMPLATE FILE> from a module’s templates directory. (For example, the reference apache/vhost.conf.erb will load the file <MODULES DIRECTORY>/apache/templates/vhost.conf.erb.)

This function can also accept:

  • An absolute path, which can load a template file from anywhere on disk.
  • Multiple arguments, which will evaluate all of the specified templates and return their outputs concatenated into a single string.

  • Type: rvalue

versioncmp

Compares two version numbers.

Prototype:

$result = versioncmp(a, b)

Where a and b are arbitrary version strings.

This function returns:

  • 1 if version a is greater than version b
  • 0 if the versions are equal
  • -1 if version a is less than version b

Example:

if versioncmp('2.6-1', '2.4.5') > 0 {
    notice('2.6-1 is > than 2.4.5')
}

This function uses the same version comparison algorithm used by Puppet’s package type.

  • Type: rvalue

warning

Log a message on the server at level warning.

  • Type: statement

with

Call a lambda code block with the given arguments. Since the parameters of the lambda are local to the lambda’s scope, this can be used to create private sections of logic in a class so that the variables are not visible outside of the class.

Example:

 # notices the array [1, 2, 'foo']
 with(1, 2, 'foo') |$x, $y, $z| { notice [$x, $y, $z] }
  • since 4.0.0

  • Type: rvalue


This page autogenerated on 2015-06-30 13:08:48 -0700

↑ Back to top