diff --git a/lib/puppet/parser/functions/epp.rb b/lib/puppet/parser/functions/epp.rb index 616d61422..3e938e129 100644 --- a/lib/puppet/parser/functions/epp.rb +++ b/lib/puppet/parser/functions/epp.rb @@ -1,41 +1,41 @@ Puppet::Parser::Functions::newfunction(:epp, :type => :rvalue, :arity => -2, :doc => "Evaluates an Embedded Puppet Template (EPP) file 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. +* `<%- |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 +`<%- |$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 - Requires Future Parser") do |arguments| # Requires future parser unless Puppet[:parser] == "future" raise ArgumentError, "epp(): function is only available when --parser future is in effect" end Puppet::Pops::Evaluator::EppEvaluator.epp(self, arguments[0], self.compiler.environment, arguments[1]) end diff --git a/lib/puppet/parser/functions/inline_epp.rb b/lib/puppet/parser/functions/inline_epp.rb index cfc1597a1..663e7b0a4 100644 --- a/lib/puppet/parser/functions/inline_epp.rb +++ b/lib/puppet/parser/functions/inline_epp.rb @@ -1,79 +1,79 @@ Puppet::Parser::Functions::newfunction(:inline_epp, :type => :rvalue, :arity => -2, :doc => "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. +* `<%- |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 +`<%- |$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 )-%> + <%- |$x| -%> Hello <%= $x %> world! END # produces 'Hello given argument world!' $x ='local variable world' inline_epptemplate(@(END:epp), { x =>'given argument'}) - <%-( $x )-%> + <%- |$x| -%> Hello <%= $x %> world! END # produces 'Hello given argument world!' $x ='local variable world' inline_epptemplate(@(END:epp), { x =>'given argument'}) - <%-( $x )-%> + <%- |$x| -%> Hello <%= $x %>! END # results in error, missing value for y $x ='local variable world' inline_epptemplate(@(END:epp), { x =>'given argument'}) - <%-( $x, $y )-%> + <%- |$x, $y| -%> Hello <%= $x %>! END # Produces 'Hello given argument planet' $x ='local variable world' inline_epptemplate(@(END:epp), { x =>'given argument'}) - <%-( $x, $y=planet)-%> + <%- |$x, $y=planet| -%> Hello <%= $x %> <%= $y %>! END - Since 3.5 - Requires Future Parser") do |arguments| # Requires future parser unless Puppet[:parser] == "future" raise ArgumentError, "inline_epp(): function is only available when --parser future is in effect" end Puppet::Pops::Evaluator::EppEvaluator.inline_epp(self, arguments[0], arguments[1]) end