puppet 8.3.1 → 8.4.0

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

@@ -1,50 +1,51 @@
 # frozen_string_literal: true
+
 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.
-
-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 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]" }
-```
-
-Would fail the operation because $data[a][b][c] results in `undef`
-(there is no `b` key in `a`).
-
-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
-DOC
-) do |args|
+  :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.
+    
+    These two expressions are equivalent:
+    
+    ```puppet
+    if $x == undef { do_things() }
+    lest($x) || { do_things() }
+    ```
+    
+    **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]" }
+    ```
+    
+    Would fail the operation because $data[a][b][c] results in `undef`
+    (there is no `b` key in `a`).
+    
+    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
+  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
+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
 end

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

@@ -1,77 +1,78 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :map,
   :type => :rvalue,
   :arity => -3,
-  :doc => <<-DOC
-Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
-to every value in a data structure and returns an array containing the results.
-
-This function takes two mandatory arguments, in this order:
-
-1. An array or hash 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.
-
-**Example**: Using the `map` function
-
-`$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
-
-or
-
-`$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
-
-When the first argument (`$data` in the above example) is an array, Puppet passes each
-value in turn to the lambda.
-
-**Example**: Using the `map` function with an array and a one-parameter lambda
-
-~~~ puppet
-# For the array $data, return an array containing each value multiplied by 10
-$data = [1,2,3]
-$transformed_data = $data.map |$items| { $items * 10 }
-# $transformed_data contains [10,20,30]
-~~~
-
-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]`.
-
-**Example**: Using the `map` function with a hash and a one-parameter lambda
-
-~~~ puppet
-# For the hash $data, return an array containing the keys
-$data = {'a'=>1,'b'=>2,'c'=>3}
-$transformed_data = $data.map |$items| { $items[0] }
-# $transformed_data contains ['a','b','c']
-~~~
-
-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 `map` function with an array and a two-parameter lambda
-
-~~~ puppet
-# For the array $data, return an array containing the indexes
-$data = [1,2,3]
-$transformed_data = $data.map |$index,$value| { $index }
-# $transformed_data contains [0,1,2]
-~~~
-
-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 `map` function with a hash and a two-parameter lambda
-
-~~~ puppet
-# For the hash $data, return an array containing each value
-$data = {'a'=>1,'b'=>2,'c'=>3}
-$transformed_data = $data.map |$key,$value| { $value }
-# $transformed_data contains [1,2,3]
-~~~
-
-- Since 4.0.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+    to every value in a data structure and returns an array containing the results.
+    
+    This function takes two mandatory arguments, in this order:
+    
+    1. An array or hash 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.
+    
+    **Example**: Using the `map` function
+    
+    `$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
+    
+    or
+    
+    `$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
+    
+    When the first argument (`$data` in the above example) is an array, Puppet passes each
+    value in turn to the lambda.
+    
+    **Example**: Using the `map` function with an array and a one-parameter lambda
+    
+    ~~~ puppet
+    # For the array $data, return an array containing each value multiplied by 10
+    $data = [1,2,3]
+    $transformed_data = $data.map |$items| { $items * 10 }
+    # $transformed_data contains [10,20,30]
+    ~~~
+    
+    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]`.
+    
+    **Example**: Using the `map` function with a hash and a one-parameter lambda
+    
+    ~~~ puppet
+    # For the hash $data, return an array containing the keys
+    $data = {'a'=>1,'b'=>2,'c'=>3}
+    $transformed_data = $data.map |$items| { $items[0] }
+    # $transformed_data contains ['a','b','c']
+    ~~~
+    
+    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 `map` function with an array and a two-parameter lambda
+    
+    ~~~ puppet
+    # For the array $data, return an array containing the indexes
+    $data = [1,2,3]
+    $transformed_data = $data.map |$index,$value| { $index }
+    # $transformed_data contains [0,1,2]
+    ~~~
+    
+    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 `map` function with a hash and a two-parameter lambda
+    
+    ~~~ puppet
+    # For the hash $data, return an array containing each value
+    $data = {'a'=>1,'b'=>2,'c'=>3}
+    $transformed_data = $data.map |$key,$value| { $value }
+    # $transformed_data contains [1,2,3]
+    ~~~
+    
+    - Since 4.0.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('map')
 end

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

@@ -1,44 +1,45 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :match,
   :arity => 2,
-  :doc => <<-DOC
-Matches a regular expression against a string and returns an array containing the match
-and any matched capturing groups.
-
-The first argument is a string or array of strings. The second argument is either a
-regular expression, regular expression represented as a string, or Regex or Pattern
-data type that the function matches against the first argument.
-
-The returned array contains the entire match at index 0, and each captured group at
-subsequent index values. If the value or expression being matched is an array, the
-function returns an array with mapped match results.
-
-If the function doesn't find a match, it returns 'undef'.
-
-**Example**: Matching a regular expression in a string
-
-~~~ ruby
-$matches = "abc123".match(/[a-z]+[1-9]+/)
-# $matches contains [abc123]
-~~~
-
-**Example**: Matching a regular expressions with grouping captures in a string
-
-~~~ ruby
-$matches = "abc123".match(/([a-z]+)([1-9]+)/)
-# $matches contains [abc123, abc, 123]
-~~~
-
-**Example**: Matching a regular expression with grouping captures in an array of strings
-
-~~~ ruby
-$matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
-# $matches contains [[abc123, abc, 123], [def456, def, 456]]
-~~~
-
-- Since 4.0.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Matches a regular expression against a string and returns an array containing the match
+    and any matched capturing groups.
+    
+    The first argument is a string or array of strings. The second argument is either a
+    regular expression, regular expression represented as a string, or Regex or Pattern
+    data type that the function matches against the first argument.
+    
+    The returned array contains the entire match at index 0, and each captured group at
+    subsequent index values. If the value or expression being matched is an array, the
+    function returns an array with mapped match results.
+    
+    If the function doesn't find a match, it returns 'undef'.
+    
+    **Example**: Matching a regular expression in a string
+    
+    ~~~ ruby
+    $matches = "abc123".match(/[a-z]+[1-9]+/)
+    # $matches contains [abc123]
+    ~~~
+    
+    **Example**: Matching a regular expressions with grouping captures in a string
+    
+    ~~~ ruby
+    $matches = "abc123".match(/([a-z]+)([1-9]+)/)
+    # $matches contains [abc123, abc, 123]
+    ~~~
+    
+    **Example**: Matching a regular expression with grouping captures in an array of strings
+    
+    ~~~ ruby
+    $matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
+    # $matches contains [[abc123, abc, 123], [def456, def, 456]]
+    ~~~
+    
+    - Since 4.0.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('match')
 end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+
 require 'digest/md5'
 
 Puppet::Parser::Functions::newfunction(:md5, :type => :rvalue, :arity => 1, :doc => "Returns a MD5 hash value from a provided string.") do |args|
-      Digest::MD5.hexdigest(args[0])
+  Digest::MD5.hexdigest(args[0])
 end