/source/references/2.6.0/function.markdown

% Function Reference
% 
% 

**This page is autogenerated; any changes will get overwritten**
*(last generated on Mon Jul 19 21:53:31 -0700 2010)*

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.

Here are the functions available in Puppet:

# alert

Log a message on the server at level alert.

-   **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 type is defined, either as a native type
or a defined type, or whether a class is defined. This is useful
for checking whether a class is defined and only including it if it
is. This function can also test whether a resource has been
defined, using resource references (e.g.,
`if defined(File['/tmp/myfile']) { ... }`). This function is
unfortunately dependent on the parse order of the configuration
when testing whether a resource is defined.

-   **Type**: rvalue

# emerg

Log a message on the server at level emerg.

-   **Type**: statement

# err

Log a message on the server at level err.

-   **Type**: statement

# fail

Fail with a parse error.

-   **Type**: statement

# file

Return the contents of a file. Multiple files can be passed, and
the first file that exists will be read in.

-   **Type**: rvalue

# fqdn\_rand

Generates random numbers based on the node's fqdn. The first
argument sets the range. Additional (optional) arguments may be
used to further distinguish the seed.

-   **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

# include

Evaluate one or more classes.

-   **Type**: statement

# info

Log a message on the server at level info.

-   **Type**: statement

# inline\_template

Evaluate a template string and return its value. See
[the templating docs](http://docs.puppetlabs.com/guides/templating.html)
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

# 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

# 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 back references to what was
    matched using 0, 1, 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.

lang
  ~ 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,'^([0-9]+)[.]([0-9]+)[.]([0-9]+)[.]([0-9]+)$','\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.

-   **Type**: statement

# search

Add another namespace for this class to search. This allows you to
create classes with sets of definitions and add those classes to
another class's search path.

-   **Type**: statement

# 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

# split

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

Usage:

    $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 string that contains
a regexp meta-character (.), and that needs protection. A simple
way to do that for a single character is to enclose it in square
brackets.

-   **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

Evaluate a template and return its value. See
[the templating docs](http://docs.puppetlabs.com/guides/templating.html)
for more information. Note that if multiple templates are
specified, their output is all concatenated and returned as the
output of the function.

-   **Type**: rvalue

# versioncmp

Compares two versions

Prototype:

    $result = versioncmp(a, b)
    
    where a and b are arbitrary version strings

This functions returns a number:

    * > 0 if version a is greater than version b
    * == 0 if both version are equals
    * < 0 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')
    }

-   **Type**: rvalue

# warning

Log a message on the server at level warning.

-   **Type**: statement


* * * * *

*This page autogenerated on Mon Jul 19 21:53:31 -0700 2010*