puppet 4.0.0 → 4.5.0

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

@@ -1,39 +1,75 @@
 Puppet::Parser::Functions::newfunction(
   :filter,
+  :type => :rvalue,
   :arity => -3,
   :doc => <<-DOC
- 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 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.
 
- 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
 DOC

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

@@ -4,7 +4,7 @@ Puppet::Parser::Functions::newfunction(:fqdn_rand, :arity => -2, :type => :rvalu
   "Usage: `fqdn_rand(MAX, [SEED])`. MAX is required and must be a positive
   integer; SEED is optional and may be any number or string.
 
-  Generates a random whole number greater than or equal to 0 and less than MAX,
+  Generates a random Integer number greater than or equal to 0 and less than MAX,
   combining the `$fqdn` fact and the value of SEED for repeatable randomness.
   (That is, each node will get a different random number from this function, but
   a given node's result will be the same every time unless its hostname changes.)
@@ -16,6 +16,6 @@ Puppet::Parser::Functions::newfunction(:fqdn_rand, :arity => -2, :type => :rvalu
   node. (For example, `fqdn_rand(30)`, `fqdn_rand(30, 'expensive job 1')`, and
   `fqdn_rand(30, 'expensive job 2')` will produce totally different numbers.)") do |args|
     max = args.shift.to_i
-    seed = Digest::MD5.hexdigest([self['::fqdn'],args].join(':')).hex
-    Puppet::Util.deterministic_rand(seed,max)
+    seed = Digest::MD5.hexdigest([self['::fqdn'],max,args].join(':')).hex
+    Puppet::Util.deterministic_rand_int(seed,max)
 end

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

@@ -1,33 +1,89 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera, :type => :rvalue, :arity => -2, :doc => "Performs a
-  standard priority lookup and returns the most specific value for a given key.
-  The returned value can be data of any type (strings, arrays, or hashes). 
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the value.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  More thorough examples of `hiera` are available at:  
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<DOC
+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
+DOC
+  ) do |*args|
     function_fail(["hiera() has been converted to 4x API"])
   end
 end
-

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

@@ -1,34 +1,77 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_array, :type => :rvalue, :arity => -2,:doc => "Returns all 
-  matches throughout the hierarchy --- not just the first match --- as a flattened array of unique values.
-  If any of the matched values are arrays, they're flattened and included in the results.
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the value.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  If any matched value is a hash, puppet will raise a type mismatch error.
-
-  More thorough examples of `hiera` are available at:  
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera_array,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<-DOC
+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
+DOC
+) do |*args|
     function_fail(["hiera_array() has been converted to 4x API"])
   end
 end

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

@@ -1,36 +1,87 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_hash, :type => :rvalue, :arity => -2, :doc => 
-  "Returns a merged hash of matches from throughout the hierarchy. In cases where two or 
-  more hashes share keys, the hierarchy  order determines which key/value pair will be 
-  used in the returned hash, with the pair in the highest priority data source winning.
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the value.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  `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 will raise a type mismatch error.
-
-  More thorough examples of `hiera_hash` are available at:  
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera_hash,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<-DOC
+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
+DOC
+  ) do |*args|
     function_fail(["hiera_hash() has been converted to 4x API"])
   end
 end

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

@@ -1,46 +1,87 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_include, :arity => -2, :doc => "Assigns classes to a node
-  using an array merge lookup that retrieves the value for a user-specified key
-  from a Hiera data source.
-
-  To use `hiera_include`, the following configuration is required:
-
-  - A key name to use for classes, e.g. `classes`.
-  - A line in the puppet `sites.pp` file (e.g. `/etc/puppetlabs/puppet/manifests/sites.pp`)
-    reading `hiera_include('classes')`. Note that this line must be outside any node
-    definition and below any top-scope variables in use for Hiera lookups.
-  - Class keys in the appropriate data sources. In a data source keyed to a node's role,
-    one might have:
-
-            ---
-            classes:
-              - apache
-              - apache::passenger
-
-  The function can be called in one of three ways:
-  1. Using 1 to 3 arguments where the arguments are:
-     'key'      [String] Required
-           The key to lookup.
-     'default`  [Any] Optional
-           A value to return when there's no match for `key`. Optional
-     `override` [Any] Optional
-           An argument in the third position, providing a data source
-           to consult for matching values, even if it would not ordinarily be
-           part of the matched hierarchy. If Hiera doesn't find a matching key
-           in the named override data source, it will continue to search through the
-           rest of the hierarchy.
-
-  2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
-     provide the default value. The block is called with one parameter (the key) and
-     should return the array to be used in the subsequent call to include.
-
-  3. Like #1 but with all arguments passed in an array.
-
-  More thorough examples of `hiera_include` are available at:
-  <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
-  ") do |*args|
+  newfunction(
+    :hiera_include,
+    :arity => -2,
+    :doc => <<-DOC
+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
+DOC
+  ) do |*args|
     function_fail(["hiera_include() has been converted to 4x API"])
   end
 end