EPP tags

Embedded Puppet (EPP) has two tags for Puppet code expressions, optional tags for parameters and comments, and a way to escape tag delimiters.

The following table provides an overview of the main tag types used with EPP. See the sections below for additional detail about each tag, including instructions on trimming white space and escaping special characters.

I want to ...	EPP tag syntax
Insert the value of a single expression.	`<%= EXPRESSION %>`
Execute an expression without inserting a value.	`<% EXPRESSION %>`
Declare the template’s parameters.	`<% \| PARAMETERS \| %>`
Add a comment.	`<%# COMMENT %>`

Text outside a tag is treated as literal text, but is subject to any tagged Puppet code surrounding it. For example, text surrounded by a tagged if statement only appears in the output if the condition is true.

Expression-printing tags

An expression-printing tag inserts the value of a single Puppet expression into the output.

Opening tag	`<%=`
Closing tag	`%>`
Closing tag with trailing white space and line break trimming	`-%>`

An expression-printing tag must contain any single Puppet expression that resolves to a value, including plain variables, function calls, and arithmetic expressions. If the value isn’t a string, Puppet automatically converts it to a string based on the rules for value interpolation in double-quoted strings.

All facts are available in EPP templates. For example, to insert the value of the fqdn and hostname facts in an EPP template for an Apache config file:

ServerName <%= $facts[fqdn] %>
ServerAlias <%= $facts[hostname] %>

Non-printing tags

A non-printing tag executes the code it contains, but doesn’t insert a value into the output.

Opening tag	`<%`
Opening tag with indentation trimming	`<%-`
Closing tag	`%>`
Closing tag with trailing white space and line break trimming	`-%>`

Non-printing tags that contain iterative and conditional expressions can affect the untagged text they surround.

For example, to insert text only if a certain variable was set, write:

<% if $broadcastclient == true { -%>
broadcastclient
<% } -%>

Expressions in non-printing tags don’t have to resolve to a value or be a complete statement, but the tag must close at a place where it would be legal to write another expression. For example, this doesn't work:

<%# Syntax error: %>
<% $servers.each -%>
# some server
<% |$server| { %> server <%= server %>
<% } -%>

You must keep |$server| { inside the first tag, because you can’t insert an arbitrary statement between a function call and its required block.

Parameter tags

A parameter tag declares which parameters the template accepts. Each parameter can be typed and can have a default value.

Opening tag with indentation trimming	`<%- \|`
Closing tag with trailing white space and line break trimming	`\| -%>`

Example tag:

<%- | Boolean $keys_enable = false, String $keys_file = '' | -%>

The parameter tag is optional; if used, it must be the first content in a template. Always close the parameter tag with a right-trimmed delimiter (-%>) to avoid outputting a blank line. Literal text, line breaks, and non-comment tags cannot precede the template’s parameter tag. (Comment tags that precede a parameter tag must use the right-trimming tag to trim trailing white space.)

The parameter tag’s pair of pipe characters (|) contains a comma-separated list of parameters. Each parameter follows this format:

Boolean $keys_enable = false

An optional data type, which restricts the allowed values for the parameter (defaults to Any)
A variable name
An optional equals (=) sign and default value, which must match the data type, if one was specified

Parameters with default values are optional, and can be omitted when the template is evaluated. If you want to use a default value of undef, make sure to also specify a data type that allows undef. For example, Optional[String] accepts undef as well as any string.

Comment tags

A comment tag’s contents do not appear in the template's output.

Opening tag	`<%#`
Closing tag	`%>`
Closing tag with space trimming	`-%>`

Example tag:

<%# This is a comment. %>

Literal tag delimiters

If you need the template’s final output to contain a literal <% or %>, you can escape the characters as <%% or %%>. The first literal tag is taken, and the rest of the line is treated as a literal. This means that <%% Test %%> in an EPP template would turn out as <% Test %%>, not <% Test %>.