# 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 3.5 # @note Requires Future Parser Puppet::Functions.create_function(:epp, Puppet::Functions::InternalFunction) do dispatch :epp do scope_param param 'String', :path optional_param 'Hash[Pattern[/^\w+$/], Any]', :parameters end def epp(scope, path, parameters = nil) Puppet::Pops::Evaluator::EppEvaluator.epp(scope, path, scope.compiler.environment, parameters) end end