puppet 4.0.0 → 4.5.0

data/lib/puppet/functions/filter.rb

@@ -1,35 +1,70 @@
-# Applies a parameterized block to each element in a sequence of entries from the first
-# argument and returns an array or hash (same type as left operand for array/hash, and array for
-# other enumerable types) with the entries for which the block evaluates to `true`.
+# Applies a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# to every value in a data structure and returns an array or hash containing any elements
+# for which the lambda evaluates to `true`.
 #
-# This function takes two mandatory arguments: the first should be an Array, a Hash, or an
-# Enumerable object (integer, Integer range, or String),
-# and the second a parameterized block as produced by the puppet syntax:
+# This function takes two mandatory arguments, in this order:
 #
-#       $a.filter |$x| { ... }
-#       filter($a) |$x| { ... }
+# 1. An array, hash, or other iterable object that the function will iterate over.
+# 2. A lambda, which the function calls for each element in the first argument. It can
+# request one or two parameters.
 #
-# When the first argument is something other than a Hash, the block is called with each entry in turn.
-# When the first argument is a Hash the entry is an array with `[key, value]`.
+# @example Using the `filter` function
 #
-# @example Using filter with one parameter
+# `$filtered_data = $data.filter |$parameter| { <PUPPET CODE BLOCK> }`
 #
-#       # selects all that end with berry
-#       $a = ["raspberry", "blueberry", "orange"]
-#       $a.filter |$x| { $x =~ /berry$/ }          # rasberry, blueberry
+# or
 #
-# If the block defines two parameters, they will be set to `index, value` (with index starting at 0) for all
-# enumerables except Hash, and to `key, value` for a Hash.
+# `$filtered_data = filter($data) |$parameter| { <PUPPET CODE BLOCK> }`
 #
-# @example Using filter with two parameters
+# When the first argument (`$data` in the above example) is an array, Puppet passes each
+# value in turn to the lambda and returns an array containing the results.
 #
-#      # selects all that end with 'berry' at an even numbered index
-#      $a = ["raspberry", "blueberry", "orange"]
-#      $a.filter |$index, $x| { $index % 2 == 0 and $x =~ /berry$/ } # raspberry
+# @example Using the `filter` function with an array and a one-parameter lambda
 #
-#      # selects all that end with 'berry' and value >= 1
-#      $a = {"raspberry"=>0, "blueberry"=>1, "orange"=>1}
-#      $a.filter |$key, $x| { $x =~ /berry$/ and $x >= 1 } # blueberry
+# ~~~ puppet
+# # For the array $data, return an array containing the values that end with "berry"
+# $data = ["orange", "blueberry", "raspberry"]
+# $filtered_data = $data.filter |$items| { $items =~ /berry$/ }
+# # $filtered_data = [blueberry, raspberry]
+# ~~~
+#
+# When the first argument is a hash, Puppet passes each key and value pair to the lambda
+# as an array in the form `[key, value]` and returns a hash containing the results.
+#
+# @example Using the `filter` function with a hash and a one-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, return a hash containing all values of keys that end with "berry"
+# $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
+# $filtered_data = $data.filter |$items| { $items[0] =~ /berry$/ }
+# # $filtered_data = {blueberry => 1, raspberry => 2}
+#
+# When the first argument is an array and the lambda has two parameters, Puppet passes the
+# array's indexes (enumerated from 0) in the first parameter and its values in the second
+# parameter.
+#
+# @example Using the `filter` function with an array and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the array $data, return an array of all keys that both end with "berry" and have
+# # an even-numbered index
+# $data = ["orange", "blueberry", "raspberry"]
+# $filtered_data = $data.filter |$indexes, $values| { $indexes % 2 == 0 and $values =~ /berry$/ }
+# # $filtered_data = [raspberry]
+# ~~~
+#
+# When the first argument is a hash, Puppet passes its keys to the first parameter and its
+# values to the second parameter.
+#
+# @example Using the `filter` function with a hash and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, return a hash of all keys that both end with "berry" and have 
+# # values less than or equal to 1
+# $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
+# $filtered_data = $data.filter |$keys, $values| { $keys =~ /berry$/ and $values <= 1 }
+# # $filtered_data = {blueberry => 1}
+# ~~~
 #
 # @since 4.0.0
 #
@@ -45,24 +80,24 @@ Puppet::Functions.create_function(:filter) do
   end
 
   dispatch :filter_Enumerable_2 do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[2,2]', :block
   end
 
   dispatch :filter_Enumerable_1 do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[1,1]', :block
   end
 
   def filter_Hash_1(hash)
-    result = hash.select {|x, y| yield([x, y]) }
+    result = hash.select {|x, y| yield([x, y]) == true }
     # Ruby 1.8.7 returns Array
     result = Hash[result] unless result.is_a? Hash
     result
   end
 
   def filter_Hash_2(hash)
-    result = hash.select {|x, y| yield(x, y) }
+    result = hash.select {|x, y| yield(x, y) == true }
     # Ruby 1.8.7 returns Array
     result = Hash[result] unless result.is_a? Hash
     result
@@ -70,8 +105,7 @@ Puppet::Functions.create_function(:filter) do
 
   def filter_Enumerable_1(enumerable)
     result = []
-    index = 0
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     begin
       loop do
         it = enum.next
@@ -87,7 +121,7 @@ Puppet::Functions.create_function(:filter) do
   def filter_Enumerable_2(enumerable)
     result = []
     index = 0
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     begin
       loop do
         it = enum.next
@@ -100,12 +134,4 @@ Puppet::Functions.create_function(:filter) do
     end
     result
   end
-
-  def asserted_enumerable(obj)
-    unless enum = Puppet::Pops::Types::Enumeration.enumerator(obj)
-      raise ArgumentError, ("#{self.class.name}(): wrong argument type (#{obj.class}; must be something enumerable.")
-    end
-    enum
-  end
-
 end

data/lib/puppet/functions/hiera.rb

@@ -1,7 +1,80 @@
 require 'hiera/puppet_function'
-
-# @see lib/puppet/parser/functions/hiera.rb for documentation
-# TODO: Move docs here when the format has been determined.
+# Performs a standard priority lookup of the hierarchy and returns the most specific value
+# for a given key. The returned value can be any type of data.
+#
+# The function takes up to three arguments, in this order:
+#
+# 1. A string key that Hiera searches for in the hierarchy. **Required**.
+# 2. An optional default value to return if Hiera doesn't find anything matching the key.
+#     * If this argument isn't provided and this function results in a lookup failure, Puppet
+#     fails with a compilation error.
+# 3. The optional name of an arbitrary
+# [hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+# top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+#     * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+#     searching the rest of the hierarchy.
+#
+# The `hiera` function does **not** find all matches throughout a hierarchy, instead
+# returining the first specific value starting at the top of the hierarchy. To search
+# throughout a hierarchy, use the `hiera_array` or `hiera_hash` functions.
+#
+# @example Using `hiera`
+#
+# ~~~ yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming web01.example.com.yaml:
+# # users:
+# #   - "Amy Barry"
+# #   - "Carrie Douglas"
+#
+# # Assuming common.yaml:
+# users:
+#   admins:
+#     - "Edith Franklin"
+#     - "Ginny Hamilton"
+#   regular:
+#     - "Iris Jackson"
+#     - "Kelly Lambert"
+# ~~~
+#
+# ~~~ puppet
+# # Assuming we are not web01.example.com:
+#
+# $users = hiera('users', undef)
+#
+# # $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
+# #                  regular => ["Iris Jackson", "Kelly Lambert"]}
+# ~~~
+#
+# You can optionally generate the default value with a
+# [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+# takes one parameter.
+#
+# @example Using `hiera` with a lambda
+#
+# ~~~ puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# $users = hiera('users') | $key | { "Key \'${key}\' not found" }
+#
+# # $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
+# #                  regular => ["Iris Jackson", "Kelly Lambert"]}
+# # If hiera couldn't match its key, it would return the lambda result,
+# # "Key 'users' not found".
+# ~~~
+#
+# The returned value's data type depends on the types of the results. In the example 
+# above, Hiera matches the 'users' key and returns it as a hash.
+#
+# See
+# [the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+# for more information about Hiera lookup functions.
+#
+# @since 4.0.0
 #
 Puppet::Functions.create_function(:hiera, Hiera::PuppetFunction) do
   init_dispatch

data/lib/puppet/functions/hiera_array.rb

@@ -1,7 +1,69 @@
 require 'hiera/puppet_function'
 
-# @see lib/puppet/parser/functions/hiera_array.rb for documentation
-# TODO: Move docs here when the format has been determined.
+# Finds all matches of a key throughout the hierarchy and returns them as a single flattened
+# array of unique values. If any of the matched values are arrays, they're flattened and
+# included in the results. This is called an
+# [array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge).
+#
+# The `hiera_array` function takes up to three arguments, in this order:
+#
+# 1. A string key that Hiera searches for in the hierarchy. **Required**.
+# 2. An optional default value to return if Hiera doesn't find anything matching the key.
+#     * If this argument isn't provided and this function results in a lookup failure, Puppet
+#     fails with a compilation error.
+# 3. The optional name of an arbitrary
+# [hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+# top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+#     * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+#     searching the rest of the hierarchy.
+#
+# @example Using `hiera_array`
+#
+# ~~~ yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming common.yaml:
+# # users:
+# #   - 'cdouglas = regular'
+# #   - 'efranklin = regular'
+#
+# # Assuming web01.example.com.yaml:
+# # users: 'abarry = admin'
+# ~~~
+#
+# ~~~ puppet
+# $allusers = hiera_array('users', undef)
+#
+# # $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+# ~~~
+#
+# You can optionally generate the default value with a
+# [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+# takes one parameter.
+#
+# @example Using `hiera_array` with a lambda
+#
+# ~~~ puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# $allusers = hiera_array('users') | $key | { "Key \'${key}\' not found" }
+#
+# # $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+# # If hiera_array couldn't match its key, it would return the lambda result,
+# # "Key 'users' not found".
+# ~~~
+#
+# `hiera_array` expects that all values returned will be strings or arrays. If any matched
+# value is a hash, Puppet raises a type mismatch error.
+#
+# See
+# [the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+# for more information about Hiera lookup functions.
+#
+# @since 4.0.0
 #
 Puppet::Functions.create_function(:hiera_array, Hiera::PuppetFunction) do
   init_dispatch
@@ -9,4 +71,4 @@ Puppet::Functions.create_function(:hiera_array, Hiera::PuppetFunction) do
   def merge_type
     :array
   end
-end
+end

data/lib/puppet/functions/hiera_hash.rb

@@ -1,7 +1,79 @@
 require 'hiera/puppet_function'
 
-# @see lib/puppet/parser/functions/hiera_hash.rb for documentation
-# TODO: Move docs here when the format has been determined.
+# Finds all matches of a key throughout the hierarchy and returns them in a merged hash.
+# If any of the matched hashes share keys, the final hash uses the value from the
+# highest priority match. This is called a
+# [hash merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#hash-merge).
+#
+# The merge strategy is determined by Hiera's
+# [`:merge_behavior`](https://docs.puppetlabs.com/hiera/latest/configuring.html#mergebehavior)
+# setting.
+#
+# The `hiera_hash` function takes up to three arguments, in this order:
+#
+# 1. A string key that Hiera searches for in the hierarchy. **Required**.
+# 2. An optional default value to return if Hiera doesn't find anything matching the key.
+#     * If this argument isn't provided and this function results in a lookup failure, Puppet
+#     fails with a compilation error.
+# 3. The optional name of an arbitrary
+# [hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+# top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+#     * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+#     searching the rest of the hierarchy.
+#
+# @example Using `hiera_hash`
+#
+# ~~~ yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming common.yaml:
+# # users:
+# #   regular:
+# #     'cdouglas': 'Carrie Douglas'
+#
+# # Assuming web01.example.com.yaml:
+# # users:
+# #   administrators:
+# #     'aberry': 'Amy Berry'
+# ~~~
+#
+# ~~~ puppet
+# # Assuming we are not web01.example.com:
+#
+# $allusers = hiera_hash('users', undef)
+#
+# # $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+# #                     administrators => {"aberry" => "Amy Berry"}}
+# ~~~
+#
+# You can optionally generate the default value with a
+# [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+# takes one parameter.
+#
+# @example Using `hiera_hash` with a lambda
+#
+# ~~~ puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# $allusers = hiera_hash('users') | $key | { "Key \'${key}\' not found" }
+#
+# # $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+# #                     administrators => {"aberry" => "Amy Berry"}}
+# # If hiera_hash couldn't match its key, it would return the lambda result,
+# # "Key 'users' not found".
+# ~~~
+#
+# `hiera_hash` expects that all values returned will be hashes. If any of the values
+# found in the data sources are strings or arrays, Puppet raises a type mismatch error.
+#
+# See
+# [the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+# for more information about Hiera lookup functions.
+#
+# @since 4.0.0
 #
 Puppet::Functions.create_function(:hiera_hash, Hiera::PuppetFunction) do
   init_dispatch

data/lib/puppet/functions/hiera_include.rb

@@ -1,7 +1,80 @@
 require 'hiera/puppet_function'
 
-# @see lib/puppet/parser/functions/hiera_include.rb for documentation
-# TODO: Move docs here when the format has been determined.
+# Assigns classes to a node using an
+# [array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge)
+# that retrieves the value for a user-specified key from Hiera's data.
+#
+# The `hiera_include` function requires:
+#
+# - A string key name to use for classes.
+# - A call to this function (i.e. `hiera_include('classes')`) in your environment's
+# `sites.pp` manifest, outside of any node definitions and below any top-scope variables
+# that Hiera uses in lookups.
+# - `classes` keys in the appropriate Hiera data sources, with an array for each
+# `classes` key and each value of the array containing the name of a class.
+#
+# The function takes up to three arguments, in this order:
+#
+# 1. A string key that Hiera searches for in the hierarchy. **Required**.
+# 2. An optional default value to return if Hiera doesn't find anything matching the key.
+#     * If this argument isn't provided and this function results in a lookup failure, Puppet
+#     fails with a compilation error.
+# 3. The optional name of an arbitrary
+# [hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+# top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+#     * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+#     searching the rest of the hierarchy.
+#
+# The function uses an
+# [array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge)
+# to retrieve the `classes` array, so every node gets every class from the hierarchy.
+#
+# @example Using `hiera_include`
+#
+# ~~~ yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming web01.example.com.yaml:
+# # classes:
+# #   - apache::mod::php
+#
+# # Assuming common.yaml:
+# # classes:
+# #   - apache
+# ~~~
+#
+# ~~~ puppet
+# # In site.pp, outside of any node definitions and below any top-scope variables:
+# hiera_include('classes', undef)
+#
+# # Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+# ~~~
+#
+# You can optionally generate the default value with a
+# [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+# takes one parameter.
+#
+# @example Using `hiera_include` with a lambda
+#
+# ~~~ puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# # In site.pp, outside of any node definitions and below any top-scope variables:
+# hiera_include('classes') | $key | {"Key \'${key}\' not found" }
+#
+# # Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+# # If hiera_include couldn't match its key, it would return the lambda result,
+# # "Key 'classes' not found".
+# ~~~
+#
+# See [the documentation](http://links.puppetlabs.com/hierainclude) for more information
+# and a more detailed example of how `hiera_include` uses array merge lookups to classify
+# nodes.
+#
+# @since 4.0.0
 #
 Puppet::Functions.create_function(:hiera_include, Hiera::PuppetFunction) do
   init_dispatch
@@ -10,8 +83,8 @@ Puppet::Functions.create_function(:hiera_include, Hiera::PuppetFunction) do
     :array
   end
 
-  def post_lookup(key, value)
+  def post_lookup(scope, key, value)
     raise Puppet::ParseError, "Could not find data item #{key}" if value.nil?
-    call_function('include', value) unless value.empty?
+    call_function_with_scope(scope, 'include', value) unless value.empty?
   end
 end

data/lib/puppet/functions/inline_epp.rb

@@ -1,74 +1,47 @@
-# 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.
-#
-# 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
-# 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):
-#
-# @example Various Examples using `inline_epp`
-#
-#     # produces 'Hello local variable world!'
-#     $x ='local variable'
-#     inline_epptemplate(@(END:epp))
-#     <%- |$x| -%>
-#     Hello <%= $x %> world!
-#     END
-# 
-#     # produces 'Hello given argument world!'
-#     $x ='local variable world'
-#     inline_epptemplate(@(END:epp), { x =>'given argument'})
-#     <%- |$x| -%>
-#     Hello <%= $x %> world!
-#     END
-#
-#     # produces 'Hello given argument world!'
-#     $x ='local variable world'
-#     inline_epptemplate(@(END:epp), { x =>'given argument'})
-#     <%- |$x| -%>
-#     Hello <%= $x %>!
-#     END
-#
-#     # results in error, missing value for y
-#     $x ='local variable world'
-#     inline_epptemplate(@(END:epp), { x =>'given argument'})
-#     <%- |$x, $y| -%>
-#     Hello <%= $x %>!
-#     END
-#
-#     # Produces 'Hello given argument planet'
-#     $x ='local variable world'
-#     inline_epptemplate(@(END:epp), { x =>'given argument'})
-#     <%- |$x, $y=planet| -%>
-#     Hello <%= $x %> <%= $y %>!
-#     END
+# Evaluates an Embedded Puppet (EPP) template string and returns the rendered
+# text result as a String.
+#
+# `inline_epp('<EPP TEMPLATE STRING>', <PARAMETER HASH>)`
+#
+# The first argument to this function should be a string containing an EPP
+# template. In most cases, the last argument is optional; if used, it should be a
+# [hash](/puppet/latest/reference/lang_data_hash.html) that contains parameters to
+# pass to the template.
+#
+# - See the [template](/puppet/latest/reference/lang_template.html) documentation
+# for general template usage information.
+# - See the [EPP syntax](/puppet/latest/reference/lang_template_epp.html)
+# documentation for examples of EPP.
+#
+# For example, to evaluate an inline EPP template and pass it the `docroot` and
+# `virtual_docroot` parameters, call the `inline_epp` function like this:
+#
+# `inline_epp('docroot: <%= $docroot %> Virtual docroot: <%= $virtual_docroot %>',
+# { 'docroot' => '/var/www/html', 'virtual_docroot' => '/var/www/example' })`
+#
+# Puppet produces a syntax error if you pass more parameters than are declared in
+# the template's parameter tag. When passing parameters to a template that
+# contains a parameter tag, use the same names as the tag's declared parameters.
+#
+# Parameters are required only if they are declared in the called template's
+# parameter tag without default values. Puppet produces an error if the
+# `inline_epp` function fails to pass any required parameter.
+#
+# An inline EPP template should be written as a single-quoted string or
+# [heredoc](/puppet/latest/reference/lang_data_string.html#heredocs).
+# A double-quoted string is subject to expression interpolation before the string
+# is parsed as an EPP template.
+#
+# For example, to evaluate an inline EPP template using a heredoc, call the
+# `inline_epp` function like this:
+#
+# ~~~ puppet
+# # Outputs 'Hello given argument planet!'
+# inline_epp(@(END), { x => 'given argument' })
+# <%- | $x, $y = planet | -%>
+# Hello <%= $x %> <%= $y %>!
+# END
+# ~~~
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/lest.rb

@@ -0,0 +1,53 @@
+# Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# (which should accept no arguments) if the argument given to the function is `undef`.
+# Returns the result of calling the lambda if the argument is `undef`, otherwwise the
+# given argument.
+#
+# The `lest` function is useful in a chain of `then` calls, or in general
+# as a guard against `undef` values. The function can be used to call `fail`, or to
+# return a default value.
+#
+# These two expressions are equivalent:
+# ~~~puppet
+# if $x == undef { do_things() }
+# lest($x) || { do_things() }
+# ~~
+#
+# @example Using `lest`
+#
+# ~~~ puppet
+# $data = {a => [ b, c ] }
+# notice $data.dig(a, b, c)
+#  .then |$x| { $x * 2 }
+#  .lest || { fail("no value for $data[a][b][c]" }
+# ~~~
+#
+# Would fail the operation because $data[a][b][c] results in `undef`
+#
+# In contrast - this example:
+#
+# ~~~ puppet
+# $data = {a => { b => { c => 10 } } }
+# notice $data.dig(a, b, c)
+#  .then |$x| { $x * 2 }
+#  .lest || { fail("no value for $data[a][b][c]" }
+# ~~~
+#
+# Would notice the value 20
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:lest) do
+  dispatch :lest do
+    param 'Any', :arg
+    block_param 'Callable[0,0]', :block
+  end
+
+  def lest(arg)
+    if arg.nil?
+      yield()
+    else
+      arg
+    end
+  end
+end