Strings

To be treated as a string, a bare word must:

• Begin with a lower case letter;

• Contain only letters, digits, hyphens (-), and underscores (_); and

• Not be a reserved word.

For example, in the following code, running is a bare word string:

service { "ntp":
  ensure => running, # bare word string
}

Unquoted words that begin with upper case letters are interpreted as data types or resource references, not strings.

For example:

if $autoupdate {
  notice('autoupdate parameter has been deprecated and replaced with package_ensure.  Set this to latest for the same behavior as autoupdate => true.')
}

The following escape sequences are available in single-quoted strings:

Sequence	Result
\\	Single backslash
\'	Literal single quotation mark

Within single quotation marks, if a backslash is followed by any character other than another backslash or a single quotation mark, Puppet treats it as a literal backslash.

The following escape sequences are available in double-quoted strings:

Sequence	Result
\\	Single backslash
\n	New line
\r	Carriage return
\t	Tab
\s	Space
\$	Literal dollar sign (to prevent interpolation)
\uXXXX	Unicode character number XXXX (a four-digit hexadecimal number)
\u{XXXXXX}	Unicode character XXXXXX (a hexadecimal number between two and six digits)
\"	Literal double quotation mark
\'	Literal single quotation mark

$gitconfig = @("GITCONFIG"/L)
    [user]
        name = ${displayname}
        email = ${email}
    [color]
        ui = true
    [alias]
        lg = "log --pretty=format:'%C(yellow)%h%C(reset) %s \
    %C(cyan)%cr%C(reset) %C(blue)%an%C(reset) %C(green)%d%C(reset)' --graph"
        wdiff = diff --word-diff=color --ignore-space-at-eol \
    --word-diff-regex='[[:alnum:]]+|[^[:space:][:alnum:]]+'
    [merge]
        defaultToUpstream = true
    [push]
        default = upstream
    | GITCONFIG

file { "${homedir}/.gitconfig":
  ensure  => file,
  content => $gitconfig,
}

The general form of a heredoc string is:

heredoc tag @("ENDTEXT"/<X>)	You can use a heredoc tag in Puppet code, anywhere a string value is accepted. In the above example, the heredoc tag @("GITCONFIG"/L) completes the line of Puppet code: $gitconfig = . A heredoc tag starts with @( and ends with ). Between those characters, the heredoc tag contains end text (see below) — text that is used to mark the end of the string. You can optionally surround this end text with double quotation marks to enable interpolation (see below). In the above example, the end text is GITCONFIG. It also optionally contains escape switches (see below), which start with a slash /. In the above example, the heredoc tag has the escape switch /L.
the string This is the text that makes up my string.	The content of the string starts on the next line, and can run over multiple lines. If you specified escape switches in the heredoc tag, the string can contain the enabled escape sequences. In the above example, the string starts with [user] and ends with default = upstream. It uses the escape sequence \ to add cosmetic line breaks, because the heredoc tag contained the /L escape switch.
end marker | - ENDTEXT	On a line of its own, the end marker consists of: Optional indentation and a pipe character (|) to indicate how much indentation is stripped from the lines of the string (see below). An optional hyphen character (-), with any amount of space around it, to trim the final line break from the string (see below). The end text, repeating the same end text used in the heredoc tag, always without quotation marks. In the above example, the end marker is | GITCONFIG.

If a line of code includes more than one heredoc tag, Puppet reads all of those heredocs in order: the first one begins on the following line and continue until its end marker, the second one begins on the line immediately after the first end marker, and so on. Puppet won’t start evaluating additional lines of Puppet code until it reaches the end marker for the final heredoc tag from the original line.

End text can be any run of text that doesn’t include line breaks, colons, slashes, or parentheses. It can include spaces, and can be mixed case. The following are all valid end text:

• EOT

• ...end...end...

• Verse 8 of The Raven

By default, heredocs do not allow you to interpolate values into the string content. You can enable interpolation by double-quoting the end text in the opening heredoc tag. That is:

• An opening tag like @(EOT) won’t allow interpolation.

• An opening tag like @("EOT") allows interpolation.

To enable individual escape sequences, add a slash (/) and one or more switches. For example, to enable an escape sequence for dollar signs (\$) and new lines (\n), add /$n to the heredoc tag :

@("EOT"/$n)

To enable all escape sequences, add a slash and no switches:

@("EOT"/)

Use the following switches to enable escape sequences:

Switch to put in the heredoc tag	Escape sequence to use in the heredoc string	Result in the string value
(automatic)	\\	Single backslash. This switch is enabled when any other escape sequence is enabled.
n	\n	New line
r	\r	Carriage return
t	\t	Tab
s	\s	Space
$	\$	Literal dollar sign (to prevent interpolation)
u	\uXXXX or \u{XXXXXX}	Unicode character number XXXX (a four-digit hexadecimal number) or XXXXXX (a two- to six-digit hexadecimal number)
L	\<New line or carriage return>	Nothing. This lets you put line breaks in the heredoc source code that does not appear in the string value.

To enable syntax checking of heredoc text, add the name of the syntax to the heredoc tag. For example:

@(END:pp)
@(END:epp)
@(END:json)

To make your code easier to read, you can indent the content of a heredoc to separate it from the surrounding code. To strip this indentation from the resulting string value, put the same amount of indentation in front of the end marker and use a pipe character (|) to indicate the position of the first “real” character on each line.

$mytext = @(EOT)
    This block of text is
    visibly separated from
    everything around it.
    | EOT

If a line has less indentation than you’ve indicated with the pipe, Puppet strips any spaces it can without deleting non-space characters.

For example, Puppet would read this as a single line:

lg = "log --pretty=format:'%C(yellow)%h%C(reset) %s \
%C(cyan)%cr%C(reset) %C(blue)%an%C(reset) %C(green)%d%C(reset)' --graph"

For example, Puppet would read this as a string with no line break at the end:

$mytext = @("EOT")
    This is too inconvenient for ${double} or ${single} quotes, but must be one line.
    |-EOT

The most common thing to interpolate into a string is the value of a variable. To make this easier, Puppet has some shorter forms of the interpolation syntax:

$myvariable

A variable reference (without curly braces) can be replaced with that variable’s value. This also works with qualified variable names like $myclass::myvariable.

Because this syntax doesn’t have an explicit stopping point (like a closing curly brace), Puppet assumes the variable name is everything between the dollar sign and the first character that couldn’t legally be part of a variable name. (Or the end of the string, if that comes first.)

This means you can’t use this style of interpolation when a value must run up against some other word-like text. And even in some cases where you can use this style, the following style can be clearer.

${myvariable}

A dollar sign followed by a variable name in curly braces can be replaced with that variable’s value. This also works with qualified variable names like ${myclass::myvariable}.

With this syntax, you can follow a variable name with any combination of chained function calls or hash access / array access / substring access expressions. For example:

"Using interface ${::interfaces.split(',')[3]} for broadcast"

However, this doesn’t work if the variable’s name overlaps with a language keyword. For example, if you had a variable called $inherits, you would have to use normal-style interpolation:

"Inheriting ${$inherits.upcase}."

Puppet converts the value of any interpolated expression to a string using these rules:

Data type	Conversion
String	The contents of the string, with any quoting syntax removed.
Undef	An empty string.
Boolean	The string 'true' or 'false'.
Number	The number in decimal notation (base 10). For floats, the value can vary on different platforms. Use the sprintf function for more precise formatting.
Array	A pair of square brackets ([ and ]) containing the array’s elements, separated by a comma and a space (, ), with no trailing comma. Each element is converted to a string using these rules.
Hash	A pair of curly braces ({ and }) containing a <KEY> => <VALUE> string for each key-value pair, separated by a comma and a space (, ), with no trailing comma. Each key and value is converted to a string using these rules.
Regular expression	A stringified regular expression.
Resource reference or data type	The value as a string.

Puppet does not attempt to convert line breaks, so whatever type of line break is used in the file (LF for *nix or CRLF for Windows) is preserved. Use escape sequences to insert specific types of line breaks into strings:

• To insert a CRLF in a manifest file that uses *nix line endings, use the \r\n escape sequences in a double-quoted string, or a heredoc with those escapes enabled.

• To insert an LF in a manifest that uses Windows line endings, use the \n escape sequence in a double-quoted string, or a heredoc with that escape enabled.

Examples:

$mystring = 'abcdef'
notice( $mystring[0] )    # resolves to 'a'
notice( $mystring[0,2] )  # resolves to 'ab'
notice( $mystring[1,2] )  # resolves to 'bc'
notice( $mystring[1,-2] ) # resolves to 'bcde'
notice( $mystring[-3,2] ) # resolves to 'de'

Text outside the actual range of the string is treated as an infinite amount of empty string:

$mystring = 'abcdef'
notice( $mystring[10] )    # resolves to ''
notice( $mystring[3,10] )  # resolves to 'def'
notice( $mystring[-10,2] ) # resolves to ''
notice( $mystring[-10,6] ) # resolves to 'ab'

The full signature for String is:

String[<MIN LENGTH>, <MAX LENGTH>]

These parameters are optional. They must be listed in order; if you need to specify a later parameter, you must also specify values for any prior ones.

Position	Parameter	Data type	Default value	Description
1	Minimum length	Integer	0	The minimum number of (Unicode) characters in the string. This parameter accepts the special value default, which uses its default value.
2	Maximum length	Integer	infinite	The maximum number of (Unicode) characters in the string. This parameter accepts the special value default, which uses its default value.

Examples:

String

Matches a string of any length.

String[6]

Matches a string with at least six characters.

String[6,8]

Matches a string with at least six and at most eight characters.