puppet 8.3.1-universal-darwin → 8.5.0-universal-darwin

data/lib/puppet/parser/functions/hiera_include.rb

@@ -1,102 +1,102 @@
 # frozen_string_literal: true
+
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
   newfunction(
     :hiera_include,
     :arity => -2,
-    :doc => <<-DOC
-Assigns classes to a node using an
-[array merge lookup](https://puppet.com/docs/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://puppet.com/docs/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://puppet.com/docs/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://puppet.com/docs/puppet/latest/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".
-~~~
-
-`hiera_include` is deprecated in favor of using a combination of `include` and `lookup` and will be
-removed in Puppet 6.0.0. Replace the calls as follows:
-
-| from  | to |
-| ----  | ---|
-| hiera_include($key) | include(lookup($key, { 'merge' => 'unique' })) |
-| hiera_include($key, $default) | include(lookup($key, { 'default_value' => $default, 'merge' => 'unique' })) |
-| hiera_include($key, $default, $level) | override level not supported |
-
-See
-[the Upgrading to Hiera 5 migration guide](https://puppet.com/docs/puppet/5.5/hiera_migrate.html)
-for more information.
-
-Note that calls using the 'override level' option are not directly supported by 'lookup' and the produced
-result must be post processed to get exactly the same result, for example using simple hash/array `+` or
-with calls to stdlib's `deep_merge` function depending on kind of hiera call and setting of merge in hiera.yaml.
-
-- Since 4.0.0
-DOC
-  ) do |*args|
+    :doc => <<~DOC
+      Assigns classes to a node using an
+      [array merge lookup](https://puppet.com/docs/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://puppet.com/docs/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://puppet.com/docs/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://puppet.com/docs/puppet/latest/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".
+      ~~~
+
+      `hiera_include` is deprecated in favor of using a combination of `include` and `lookup` and will be
+      removed in Puppet 6.0.0. Replace the calls as follows:
+
+      | from  | to |
+      | ----  | ---|
+      | hiera_include($key) | include(lookup($key, { 'merge' => 'unique' })) |
+      | hiera_include($key, $default) | include(lookup($key, { 'default_value' => $default, 'merge' => 'unique' })) |
+      | hiera_include($key, $default, $level) | override level not supported |
+
+      See
+      [the Upgrading to Hiera 5 migration guide](https://puppet.com/docs/puppet/5.5/hiera_migrate.html)
+      for more information.
+
+      Note that calls using the 'override level' option are not directly supported by 'lookup' and the produced
+      result must be post processed to get exactly the same result, for example using simple hash/array `+` or
+      with calls to stdlib's `deep_merge` function depending on kind of hiera call and setting of merge in hiera.yaml.
+
+      - Since 4.0.0
+    DOC
+  ) do |*_args|
     Error.is4x('hiera_include')
   end
 end
-

data/lib/puppet/parser/functions/include.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+
 # Include the specified classes
-Puppet::Parser::Functions::newfunction(:include, :arity => -2, :doc =>
+Puppet::Parser::Functions.newfunction(:include, :arity => -2, :doc =>
 "Declares one or more classes, causing the resources in them to be
 evaluated and added to the catalog. Accepts a class name, an array of class
 names, or a comma-separated list of class names.
@@ -27,9 +28,9 @@ the future parser's resource and relationship expressions.
 
 - Since < 3.0.0
 - Since 4.0.0 support for class and resource type values, absolute names
-- Since 4.7.0 returns an Array[Type[Class]] of all included classes 
+- Since 4.7.0 returns an Array[Type[Class]] of all included classes
 ") do |classes|
   call_function('include', classes)
-  #TRANSLATORS "function_include", "Scope", and "Scope#call_function" refer to Puppet internals and should not be translated
+  # TRANSLATORS "function_include", "Scope", and "Scope#call_function" refer to Puppet internals and should not be translated
   Puppet.warn_once('deprecations', '3xfunction#include', _("Calling function_include via the Scope class is deprecated. Use Scope#call_function instead"))
 end

data/lib/puppet/parser/functions/inline_epp.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-Puppet::Parser::Functions::newfunction(:inline_epp, :type => :rvalue, :arity => -2, :doc =>
+
+Puppet::Parser::Functions.newfunction(:inline_epp, :type => :rvalue, :arity => -2, :doc =>
 "Evaluates an Embedded Puppet (EPP) template string and returns the rendered
 text result as a String.
 
@@ -46,7 +47,6 @@ END
 ~~~
 
 - Since 3.5
-- Requires [future parser](https://puppet.com/docs/puppet/3.8/experiments_future.html) in Puppet 3.5 to 3.8") do |arguments|
-
+- Requires [future parser](https://puppet.com/docs/puppet/3.8/experiments_future.html) in Puppet 3.5 to 3.8") do |_arguments|
   Puppet::Parser::Functions::Error.is4x('inline_epp')
 end

data/lib/puppet/parser/functions/inline_template.rb

@@ -1,27 +1,28 @@
 # frozen_string_literal: true
-Puppet::Parser::Functions::newfunction(:inline_template, :type => :rvalue, :arity => -2, :doc =>
+
+Puppet::Parser::Functions.newfunction(:inline_template, :type => :rvalue, :arity => -2, :doc =>
   "Evaluate a template string and return its value.  See
   [the templating docs](https://puppet.com/docs/puppet/latest/lang_template.html) for
   more information. Note that if multiple template strings are specified, their
   output is all concatenated and returned as the output of the function.") do |vals|
-
   if Puppet[:tasks]
     raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
       Puppet::Pops::Issues::FEATURE_NOT_SUPPORTED_WHEN_SCRIPTING,
-      {:feature => 'ERB inline_template'})
+      { :feature => 'ERB inline_template' }
+    )
   end
 
   require 'erb'
 
-    vals.collect do |string|
-      # Use a wrapper, so the template can't get access to the full
-      # Scope object.
+  vals.collect do |string|
+    # Use a wrapper, so the template can't get access to the full
+    # Scope object.
 
-      wrapper = Puppet::Parser::TemplateWrapper.new(self)
-      begin
-        wrapper.result(string)
-      rescue => detail
-        raise Puppet::ParseError, _("Failed to parse inline template: %{detail}") % { detail: detail }, detail.backtrace
-      end
-    end.join("")
+    wrapper = Puppet::Parser::TemplateWrapper.new(self)
+    begin
+      wrapper.result(string)
+    rescue => detail
+      raise Puppet::ParseError, _("Failed to parse inline template: %{detail}") % { detail: detail }, detail.backtrace
+    end
+  end.join("")
 end

data/lib/puppet/parser/functions/lest.rb

@@ -1,50 +1,51 @@
 # frozen_string_literal: true
-Puppet::Parser::Functions::newfunction(
+
+Puppet::Parser::Functions.newfunction(
   :lest,
   :type => :rvalue,
   :arity => -2,
-  :doc => <<-DOC
-Call a [lambda](https://puppet.com/docs/puppet/latest/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`, otherwise the
-given argument.
+  :doc => <<~DOC
+    Call a [lambda](https://puppet.com/docs/puppet/latest/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`, otherwise 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.
+    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:
+    These two expressions are equivalent:
 
-```puppet
-if $x == undef { do_things() }
-lest($x) || { do_things() }
-```
+    ```puppet
+    if $x == undef { do_things() }
+    lest($x) || { do_things() }
+    ```
 
-**Example:** Using the `lest` function
+    **Example:** Using the `lest` function
 
-```puppet
-$data = {a => [ b, c ] }
-notice $data.dig(a, b, c)
- .then |$x| { $x * 2 }
- .lest || { fail("no value for $data[a][b][c]" }
-```
+    ```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`
-(there is no `b` key in `a`).
+    Would fail the operation because $data[a][b][c] results in `undef`
+    (there is no `b` key in `a`).
 
-In contrast - this example:
+    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]" }
-```
+    ```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`
+    Would notice the value `20`
 
-* Since 4.5.0
-DOC
-) do |args|
+    * Since 4.5.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('lest')
 end

data/lib/puppet/parser/functions/lookup.rb

@@ -1,133 +1,134 @@
 # frozen_string_literal: true
+
 module Puppet::Parser::Functions
-  newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<-'ENDHEREDOC') do |args|
-Uses the Puppet lookup system to retrieve a value for a given key. By default,
-this returns the first value found (and fails compilation if no values are
-available), but you can configure it to merge multiple values into one, fail
-gracefully, and more.
-
-When looking up a key, Puppet will search up to three tiers of data, in the
-following order:
-
-1. Hiera.
-2. The current environment's data provider.
-3. The indicated module's data provider, if the key is of the form
-   `<MODULE NAME>::<SOMETHING>`.
-
-#### Arguments
-
-You must provide the name of a key to look up, and can optionally provide other
-arguments. You can combine these arguments in the following ways:
-
-* `lookup( <NAME>, [<VALUE TYPE>], [<MERGE BEHAVIOR>], [<DEFAULT VALUE>] )`
-* `lookup( [<NAME>], <OPTIONS HASH> )`
-* `lookup( as above ) |$key| { # lambda returns a default value }`
-
-Arguments in `[square brackets]` are optional.
-
-The arguments accepted by `lookup` are as follows:
-
-1. `<NAME>` (string or array) --- The name of the key to look up.
-    * This can also be an array of keys. If Puppet doesn't find anything for the
-    first key, it will try again with the subsequent ones, only resorting to a
-    default value if none of them succeed.
-2. `<VALUE TYPE>` (data type) --- A
-[data type](https://puppet.com/docs/puppet/latest/lang_data_type.html)
-that must match the retrieved value; if not, the lookup (and catalog
-compilation) will fail. Defaults to `Data` (accepts any normal value).
-3. `<MERGE BEHAVIOR>` (string or hash; see **"Merge Behaviors"** below) ---
-Whether (and how) to combine multiple values. If present, this overrides any
-merge behavior specified in the data sources. Defaults to no value; Puppet will
-use merge behavior from the data sources if present, and will otherwise do a
-first-found lookup.
-4. `<DEFAULT VALUE>` (any normal value) --- If present, `lookup` returns this
-when it can't find a normal value. Default values are never merged with found
-values. Like a normal value, the default must match the value type. Defaults to
-no value; if Puppet can't find a normal value, the lookup (and compilation) will
-fail.
-5. `<OPTIONS HASH>` (hash) --- Alternate way to set the arguments above, plus
-some less-common extra options. If you pass an options hash, you can't combine
-it with any regular arguments (except `<NAME>`). An options hash can have the
-following keys:
-    * `'name'` --- Same as `<NAME>` (argument 1). You can pass this as an
-    argument or in the hash, but not both.
-    * `'value_type'` --- Same as `<VALUE TYPE>` (argument 2).
-    * `'merge'` --- Same as `<MERGE BEHAVIOR>` (argument 3).
-    * `'default_value'` --- Same as `<DEFAULT VALUE>` (argument 4).
-    * `'default_values_hash'` (hash) --- A hash of lookup keys and default
-    values. If Puppet can't find a normal value, it will check this hash for the
-    requested key before giving up. You can combine this with `default_value` or
-    a lambda, which will be used if the key isn't present in this hash. Defaults
-    to an empty hash.
-    * `'override'` (hash) --- A hash of lookup keys and override values. Puppet
-    will check for the requested key in the overrides hash _first;_ if found, it
-    returns that value as the _final_ value, ignoring merge behavior. Defaults
-    to an empty hash.
-
-Finally, `lookup` can take a lambda, which must accept a single parameter.
-This is yet another way to set a default value for the lookup; if no results are
-found, Puppet will pass the requested key to the lambda and use its result as
-the default value.
-
-#### Merge Behaviors
-
-Puppet lookup uses a hierarchy of data sources, and a given key might have
-values in multiple sources. By default, Puppet returns the first value it finds,
-but it can also continue searching and merge all the values together.
-
-> **Note:** Data sources can use the special `lookup_options` metadata key to
-request a specific merge behavior for a key. The `lookup` function will use that
-requested behavior unless you explicitly specify one.
-
-The valid merge behaviors are:
-
-* `'first'` --- Returns the first value found, with no merging. Puppet lookup's
-default behavior.
-* `'unique'` (called "array merge" in classic Hiera) --- Combines any number of
-arrays and scalar values to return a merged, flattened array with all duplicate
-values removed. The lookup will fail if any hash values are found.
-* `'hash'` --- Combines the keys and values of any number of hashes to return a
-merged hash. If the same key exists in multiple source hashes, Puppet will use
-the value from the highest-priority data source; it won't recursively merge the
-values.
-* `'deep'` --- Combines the keys and values of any number of hashes to return a
-merged hash. If the same key exists in multiple source hashes, Puppet will
-recursively merge hash or array values (with duplicate values removed from
-arrays). For conflicting scalar values, the highest-priority value will win.
-* `{'strategy' => 'first|unique|hash'}` --- Same as the string versions of these
-merge behaviors.
-* `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
-but can adjust the merge with additional options. The available options are:
-    * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a
-    value should be _removed_ from the final result. Defaults to `undef`, which
-    disables this feature.
-    * `'sort_merged_arrays'` (boolean) --- Whether to sort all arrays that are
-    merged together. Defaults to `false`.
-    * `'merge_hash_arrays'` (boolean) --- Whether to merge hashes within arrays.
-    Defaults to `false`.
-
-#### Examples
-
-Look up a key and return the first value found:
-
-    lookup('ntp::service_name')
-
-Do a unique merge lookup of class names, then add all of those classes to the
-catalog (like `hiera_include`):
-
-    lookup('classes', Array[String], 'unique').include
-
-Do a deep hash merge lookup of user data, but let higher priority sources
-remove values by prefixing them with `--`:
-
-    lookup( { 'name'  => 'users',
-              'merge' => {
-                'strategy'        => 'deep',
-                'knockout_prefix' => '--',
-              },
-    })
-
-ENDHEREDOC
-  Error.is4x('lookup')
-end
+  newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<~'ENDHEREDOC') do |_args|
+    Uses the Puppet lookup system to retrieve a value for a given key. By default,
+    this returns the first value found (and fails compilation if no values are
+    available), but you can configure it to merge multiple values into one, fail
+    gracefully, and more.
+
+    When looking up a key, Puppet will search up to three tiers of data, in the
+    following order:
+
+    1. Hiera.
+    2. The current environment's data provider.
+    3. The indicated module's data provider, if the key is of the form
+       `<MODULE NAME>::<SOMETHING>`.
+
+    #### Arguments
+
+    You must provide the name of a key to look up, and can optionally provide other
+    arguments. You can combine these arguments in the following ways:
+
+    * `lookup( <NAME>, [<VALUE TYPE>], [<MERGE BEHAVIOR>], [<DEFAULT VALUE>] )`
+    * `lookup( [<NAME>], <OPTIONS HASH> )`
+    * `lookup( as above ) |$key| { # lambda returns a default value }`
+
+    Arguments in `[square brackets]` are optional.
+
+    The arguments accepted by `lookup` are as follows:
+
+    1. `<NAME>` (string or array) --- The name of the key to look up.
+        * This can also be an array of keys. If Puppet doesn't find anything for the
+        first key, it will try again with the subsequent ones, only resorting to a
+        default value if none of them succeed.
+    2. `<VALUE TYPE>` (data type) --- A
+    [data type](https://puppet.com/docs/puppet/latest/lang_data_type.html)
+    that must match the retrieved value; if not, the lookup (and catalog
+    compilation) will fail. Defaults to `Data` (accepts any normal value).
+    3. `<MERGE BEHAVIOR>` (string or hash; see **"Merge Behaviors"** below) ---
+    Whether (and how) to combine multiple values. If present, this overrides any
+    merge behavior specified in the data sources. Defaults to no value; Puppet will
+    use merge behavior from the data sources if present, and will otherwise do a
+    first-found lookup.
+    4. `<DEFAULT VALUE>` (any normal value) --- If present, `lookup` returns this
+    when it can't find a normal value. Default values are never merged with found
+    values. Like a normal value, the default must match the value type. Defaults to
+    no value; if Puppet can't find a normal value, the lookup (and compilation) will
+    fail.
+    5. `<OPTIONS HASH>` (hash) --- Alternate way to set the arguments above, plus
+    some less-common extra options. If you pass an options hash, you can't combine
+    it with any regular arguments (except `<NAME>`). An options hash can have the
+    following keys:
+        * `'name'` --- Same as `<NAME>` (argument 1). You can pass this as an
+        argument or in the hash, but not both.
+        * `'value_type'` --- Same as `<VALUE TYPE>` (argument 2).
+        * `'merge'` --- Same as `<MERGE BEHAVIOR>` (argument 3).
+        * `'default_value'` --- Same as `<DEFAULT VALUE>` (argument 4).
+        * `'default_values_hash'` (hash) --- A hash of lookup keys and default
+        values. If Puppet can't find a normal value, it will check this hash for the
+        requested key before giving up. You can combine this with `default_value` or
+        a lambda, which will be used if the key isn't present in this hash. Defaults
+        to an empty hash.
+        * `'override'` (hash) --- A hash of lookup keys and override values. Puppet
+        will check for the requested key in the overrides hash _first;_ if found, it
+        returns that value as the _final_ value, ignoring merge behavior. Defaults
+        to an empty hash.
+
+    Finally, `lookup` can take a lambda, which must accept a single parameter.
+    This is yet another way to set a default value for the lookup; if no results are
+    found, Puppet will pass the requested key to the lambda and use its result as
+    the default value.
+
+    #### Merge Behaviors
+
+    Puppet lookup uses a hierarchy of data sources, and a given key might have
+    values in multiple sources. By default, Puppet returns the first value it finds,
+    but it can also continue searching and merge all the values together.
+
+    > **Note:** Data sources can use the special `lookup_options` metadata key to
+    request a specific merge behavior for a key. The `lookup` function will use that
+    requested behavior unless you explicitly specify one.
+
+    The valid merge behaviors are:
+
+    * `'first'` --- Returns the first value found, with no merging. Puppet lookup's
+    default behavior.
+    * `'unique'` (called "array merge" in classic Hiera) --- Combines any number of
+    arrays and scalar values to return a merged, flattened array with all duplicate
+    values removed. The lookup will fail if any hash values are found.
+    * `'hash'` --- Combines the keys and values of any number of hashes to return a
+    merged hash. If the same key exists in multiple source hashes, Puppet will use
+    the value from the highest-priority data source; it won't recursively merge the
+    values.
+    * `'deep'` --- Combines the keys and values of any number of hashes to return a
+    merged hash. If the same key exists in multiple source hashes, Puppet will
+    recursively merge hash or array values (with duplicate values removed from
+    arrays). For conflicting scalar values, the highest-priority value will win.
+    * `{'strategy' => 'first|unique|hash'}` --- Same as the string versions of these
+    merge behaviors.
+    * `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
+    but can adjust the merge with additional options. The available options are:
+        * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a
+        value should be _removed_ from the final result. Defaults to `undef`, which
+        disables this feature.
+        * `'sort_merged_arrays'` (boolean) --- Whether to sort all arrays that are
+        merged together. Defaults to `false`.
+        * `'merge_hash_arrays'` (boolean) --- Whether to merge hashes within arrays.
+        Defaults to `false`.
+
+    #### Examples
+
+    Look up a key and return the first value found:
+
+        lookup('ntp::service_name')
+
+    Do a unique merge lookup of class names, then add all of those classes to the
+    catalog (like `hiera_include`):
+
+        lookup('classes', Array[String], 'unique').include
+
+    Do a deep hash merge lookup of user data, but let higher priority sources
+    remove values by prefixing them with `--`:
+
+        lookup( { 'name'  => 'users',
+                  'merge' => {
+                    'strategy'        => 'deep',
+                    'knockout_prefix' => '--',
+                  },
+        })
+
+  ENDHEREDOC
+    Error.is4x('lookup')
+  end
 end