puppet 4.2.3-x86-mingw32 → 4.3.0-x86-mingw32

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.htmlarray-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.htmlarray-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

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

@@ -3,36 +3,71 @@ Puppet::Parser::Functions::newfunction(
   :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 with the result of each invocation of the parameterized block.
+Applies a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+to every value in a data structure and returns an array containing the results.
 
-This function takes two mandatory arguments: the first should be an Array, Hash, or of Enumerable type
-(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.map |$x| { ... }
-      map($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 `$a` is an Array or of enumerable type, 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 `map` function
 
-Example Using map with two arguments
+`$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
 
-     # Turns hash into array of values
-     $a.map |$x|{ $x[1] }
+or
 
-     # Turns hash into array of keys
-     $a.map |$x| { $x[0] }
+`$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
 
-When using a block with 2 parameters, the element's index (starting from 0) for an array, and the key for a hash
-is given to the block's first parameter, and the value is given to the block's second parameter.args.
+When the first argument (`$data` in the above example) is an array, Puppet passes each
+value in turn to the lambda.
 
-Example Using map with two arguments
+**Example**: Using the `map` function with an array and a one-parameter lambda
 
-     # Turns hash into array of values
-     $a.map |$key,$val|{ $val }
+~~~ 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]
+~~~
 
-     # Turns hash into array of keys
-     $a.map |$key,$val|{ $key }
+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

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

@@ -2,23 +2,38 @@ Puppet::Parser::Functions::newfunction(
   :match,
   :arity => 2,
   :doc => <<-DOC
-Returns the match result of matching a String or Array[String] with one of:
+Matches a regular expression against a string and returns an array containing the match
+and any matched capturing groups.
 
-* Regexp
-* String - transformed to a Regexp
-* Pattern type
-* Regexp type
+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.
 
-Returns An Array with the entire match at index 0, and each subsequent submatch at index 1-n.
-If there was no match `undef` is returned. If the value to match is an Array, a array
-with mapped match results is returned.
+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.
 
-Example matching:
+If the function doesn't find a match, it returns 'undef'.
 
-  "abc123".match(/([a-z]+)[1-9]+/)    # => ["abc"]
-  "abc123".match(/([a-z]+)([1-9]+)/)  # => ["abc", "123"]
+**Example**: Matching a regular expression in a string
 
-See the documentation for "The Puppet Type System" for more information about types.
+~~~ 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

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

@@ -3,66 +3,103 @@ Puppet::Parser::Functions::newfunction(
   :type => :rvalue,
   :arity => -3,
   :doc => <<-DOC
-Applies a parameterized block to each element in a sequence of entries from the first
-argument (_the enumerable_) and returns the last result of the invocation of the parameterized block.
-
-This function takes two mandatory arguments: the first should be an Array, Hash, or something of
-enumerable type, and the last a parameterized block as produced by the puppet syntax:
-
-      $a.reduce |$memo, $x| { ... }
-      reduce($a) |$memo, $x| { ... }
-
-When the first argument is an Array or someting of an enumerable type, the block is called with each entry in turn.
-When the first argument is a hash each entry is converted to an array with `[key, value]` before being
-fed to the block. An optional 'start memo' value may be supplied as an argument between the array/hash
-and mandatory block.
-
-      $a.reduce(start) |$memo, $x| { ... }
-      reduce($a, start) |$memo, $x| { ... }
-
-If no 'start memo' is given, the first invocation of the parameterized block will be given the first and second
-elements of the enumeration, and if the enumerable has fewer than 2 elements, the first
-element is produced as the result of the reduction without invocation of the block.
-
-On each subsequent invocation, the produced value of the invoked parameterized block is given as the memo in the
-next invocation.
-
-Example Using reduce
-
-      # Reduce an array
-      $a = [1,2,3]
-      $a.reduce |$memo, $entry| { $memo + $entry }
-      #=> 6
-
-      # Reduce hash values
-      $a = {a => 1, b => 2, c => 3}
-      $a.reduce |$memo, $entry| { [sum, $memo[1]+$entry[1]] }
-      #=> [sum, 6]
-
-      # reverse a string
-      "abc".reduce |$memo, $char| { "$char$memo" }
-      #=>"cbe"
-
-It is possible to provide a starting 'memo' as an argument.
-
-Example Using reduce with given start 'memo'
-
-      # Reduce an array
-      $a = [1,2,3]
-      $a.reduce(4) |$memo, $entry| { $memo + $entry }
-      #=> 10
-
-      # Reduce hash values
-      $a = {a => 1, b => 2, c => 3}
-      $a.reduce([na, 4]) |$memo, $entry| { [sum, $memo[1]+$entry[1]] }
-      #=> [sum, 10]
-
-Example Using reduce with an Integer range
-
-      Integer[1,4].reduce |$memo, $x| { $memo + $x }
-      #=> 10
-
-- since 4.0.0
+Applies a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+to every value in a data structure from the first argument, carrying over the returned
+value of each iteration, and returns the result of the lambda's final iteration. This
+lets you create a new value or data structure by combining values from the first
+argument's data structure.
+
+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 takes
+two mandatory parameters:
+    1. A memo value that is overwritten after each iteration with the iteration's result.
+    2. A second value that is overwritten after each iteration with the next value in the
+    function's first argument.
+
+**Example**: Using the `reduce` function
+
+`$data.reduce |$memo, $value| { ... }`
+
+or
+
+`reduce($data) |$memo, $value| { ... }`
+
+You can also pass an optional "start memo" value as an argument, such as `start` below:
+
+`$data.reduce(start) |$memo, $value| { ... }`
+
+or
+
+`reduce($data, start) |$memo, $value| { ... }`
+
+When the first argument (`$data` in the above example) is an array, Puppet passes each
+of the data structure's values in turn to the lambda's parameters. When the first
+argument is a hash, Puppet converts each of the hash's values to an array in the form
+`[key, value]`.
+
+If you pass a start memo value, Puppet executes the lambda with the provided memo value
+and the data structure's first value. Otherwise, Puppet passes the structure's first two
+values to the lambda.
+
+Puppet calls the lambda for each of the data structure's remaining values. For each
+call, it passes the result of the previous call as the first parameter ($memo in the
+above examples) and the next value from the data structure as the second parameter
+($value).
+
+If the structure has one value, Puppet returns the value and does not call the lambda.
+
+**Example**: Using the `reduce` function
+
+~~~ puppet
+# Reduce the array $data, returning the sum of all values in the array.
+$data = [1, 2, 3]
+$sum = $data.reduce |$memo, $value| { $memo + $value }
+# $sum contains 6
+
+# Reduce the array $data, returning the sum of a start memo value and all values in the
+# array.
+$data = [1, 2, 3]
+$sum = $data.reduce(4) |$memo, $value| { $memo + $value }
+# $sum contains 10
+
+# Reduce the hash $data, returning the sum of all values and concatenated string of all
+# keys.
+$data = {a => 1, b => 2, c => 3}
+$combine = $data.reduce |$memo, $value| {
+  $string = "${memo[0]}${value[0]}"
+  $number = $memo[1] + $value[1]
+  [$string, $number]
+}
+# $combine contains [abc, 6]
+~~~
+
+**Example**: Using the `reduce` function with a start memo and two-parameter lambda
+
+~~~ puppet
+# Reduce the array $data, returning the sum of all values in the array and starting
+# with $memo set to an arbitrary value instead of $data's first value.
+$data = [1, 2, 3]
+$sum = $data.reduce(4) |$memo, $value| { $memo + $value }
+# At the start of the lambda's first iteration, $memo contains 4 and $value contains 1.
+# After all iterations, $sum contains 10.
+
+# Reduce the hash $data, returning the sum of all values and concatenated string of
+# all keys, and starting with $memo set to an arbitrary array instead of $data's first
+# key-value pair.
+$data = {a => 1, b => 2, c => 3}
+$combine = $data.reduce( [d, 4] ) |$memo, $value| {
+  $string = "${memo[0]}${value[0]}"
+  $number = $memo[1] + $value[1]
+  [$string, $number]
+}
+# At the start of the lambda's first iteration, $memo contains [d, 4] and $value
+# contains [a, 1].
+# $combine contains [dabc, 10]
+~~~
+
+- Since 4.0.0
 DOC
 ) do |args|
   function_fail(["reduce() is only available when parser/evaluator future is in effect"])