puppet 5.4.0 → 5.5.0

data/lib/puppet/functions/eyaml_lookup_key.rb

@@ -50,7 +50,9 @@ Puppet::Functions.create_function(:eyaml_lookup_key) do
         if data.is_a?(Hash)
           Puppet::Pops::Lookup::HieraConfig.symkeys_to_string(data)
         else
-          Puppet.warning(_("%{path}: file does not contain a valid yaml hash") % { path: path })
+          msg = _("%{path}: file does not contain a valid yaml hash") % { path: path }
+          raise Puppet::DataBinding::LookupError, msg if Puppet[:strict] == :error && data != false
+          Puppet.warning(msg)
           {}
         end
       rescue YAML::SyntaxError => ex

data/lib/puppet/functions/filter.rb

@@ -21,19 +21,19 @@
 #
 # @example Using the `filter` function with an array and a one-parameter lambda
 #
-# ~~~ puppet
+# ```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
+# ```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$/ }
@@ -45,26 +45,26 @@
 #
 # @example Using the `filter` function with an array and a two-parameter lambda
 #
-# ~~~ puppet
+# ```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
+# ```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
 #

data/lib/puppet/functions/find_file.rb

@@ -1,5 +1,19 @@
 # Finds an existing file from a module and returns its path.
-# (Documented in 3.x stub)
+#
+# The argument to this function should be a String as a `<MODULE NAME>/<FILE>`
+# reference, which will search for `<FILE>` relative to a module's `files`
+# directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
+# file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+#
+# This function can also accept:
+# 
+# * An absolute String path, which will check for the existence of a file from anywhere on disk.
+# * Multiple String arguments, which will return the path of the **first** file
+#   found, skipping non existing files.
+# * An array of string paths, which will return the path of the **first** file
+#   found from the given paths in the array, skipping non existing files.
+#
+# The function returns `undef` if none of the given paths were found
 #
 # @since 4.8.0
 #

data/lib/puppet/functions/flatten.rb

@@ -0,0 +1,64 @@
+# Returns a flat Array produced from its possibly deeply nested given arguments.
+#
+# One or more arguments of any data type can be given to this function.
+# The result is always a flat array representation where any nested arrays are recursively flattened.
+#
+# @example Typical use of `flatten()`
+#
+# ```puppet
+# flatten(['a', ['b', ['c']]])
+# # Would return: ['a','b','c']
+# ```
+#
+# To flatten other kinds of iterables (for example hashes, or intermediate results like from a `reverse_each`)
+# first convert the result to an array using `Array($x)`, or `$x.convert_to(Array)`. See the `new` function
+# for details and options when performing a conversion.
+#
+# @example Flattening a Hash
+#
+# ```puppet
+# $hsh = { a => 1, b => 2}
+#
+# # -- without conversion
+# $hsh.flatten()
+# # Would return [{a => 1, b => 2}]
+#
+# # -- with conversion
+# $hsh.convert_to(Array).flatten()
+# # Would return [a,1,b,2]
+#
+# flatten(Array($hsh))
+# # Would also return [a,1,b,2]
+# ```
+#
+# @example Flattening and concatenating at the same time
+#
+# ```puppet
+# $a1 = [1, [2, 3]]
+# $a2 = [[4,[5,6]]
+# $x = 7
+# flatten($a1, $a2, $x)
+# # would return [1,2,3,4,5,6,7]
+# ```
+#
+# @example Transforming to Array if not already an Array
+#
+# ```puppet
+# flatten(42)
+# # Would return [42]
+#
+# flatten([42])
+# # Would also return [42]
+# ```
+#
+# @since 5.5.0 support for flattening and concatenating at the same time
+#
+Puppet::Functions.create_function(:flatten) do
+  dispatch :flatten_args do
+    repeated_param 'Any', :args
+  end
+
+  def flatten_args(*args)
+    args.flatten()
+  end
+end

data/lib/puppet/functions/hiera.rb

@@ -25,7 +25,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -44,16 +44,16 @@ require 'hiera/puppet_function'
 #   regular:
 #     - "Iris Jackson"
 #     - "Kelly Lambert"
-# ~~~
+# ```
 #
-# ~~~ puppet
+# ```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
@@ -61,7 +61,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera` with a lambda
 #
-# ~~~ puppet
+# ```puppet
 # # Assuming the same Hiera data as the previous example:
 #
 # $users = hiera('users') | $key | { "Key \'${key}\' not found" }
@@ -70,7 +70,7 @@ require 'hiera/puppet_function'
 # #                  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.

data/lib/puppet/functions/hiera_array.rb

@@ -24,7 +24,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera_array`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -37,13 +37,13 @@ require 'hiera/puppet_function'
 #
 # # Assuming web01.example.com.yaml:
 # # users: 'abarry = admin'
-# ~~~
+# ```
 #
-# ~~~ puppet
+# ```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
@@ -51,7 +51,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera_array` with a lambda
 #
-# ~~~ puppet
+# ```puppet
 # # Assuming the same Hiera data as the previous example:
 #
 # $allusers = hiera_array('users') | $key | { "Key \'${key}\' not found" }
@@ -59,7 +59,7 @@ require 'hiera/puppet_function'
 # # $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.

data/lib/puppet/functions/hiera_hash.rb

@@ -29,7 +29,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera_hash`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -44,16 +44,16 @@ require 'hiera/puppet_function'
 # # users:
 # #   administrators:
 # #     'aberry': 'Amy Berry'
-# ~~~
+# ```
 #
-# ~~~ puppet
+# ```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
@@ -61,7 +61,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera_hash` with a lambda
 #
-# ~~~ puppet
+# ```puppet
 # # Assuming the same Hiera data as the previous example:
 #
 # $allusers = hiera_hash('users') | $key | { "Key \'${key}\' not found" }
@@ -70,7 +70,7 @@ require 'hiera/puppet_function'
 # #                     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.

data/lib/puppet/functions/hiera_include.rb

@@ -11,10 +11,10 @@ require 'hiera/puppet_function'
 #
 # @example Using `lookup` and `include` instead of of the deprecated `hiera_include`
 # 
-# ~~~puppet
+# ```puppet
 # # In site.pp, outside of any node definitions and below any top-scope variables:
 # lookup('classes', Array[String], 'unique').include
-# ~~~
+# ```
 #
 # The `hiera_include` function requires:
 #
@@ -43,7 +43,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera_include`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -56,14 +56,14 @@ require 'hiera/puppet_function'
 # # Assuming common.yaml:
 # # classes:
 # #   - apache
-# ~~~
+# ```
 #
-# ~~~ puppet
+# ```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
@@ -71,7 +71,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera_include` with a lambda
 #
-# ~~~ puppet
+# ```puppet
 # # Assuming the same Hiera data as the previous example:
 #
 # # In site.pp, outside of any node definitions and below any top-scope variables:
@@ -80,7 +80,7 @@ require 'hiera/puppet_function'
 # # 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 'Using the lookup function' documentation](https://docs.puppet.com/puppet/latest/hiera_use_function.html) for how to perform lookup of data.

data/lib/puppet/functions/include.rb

@@ -1,5 +1,31 @@
-# Include the specified classes
-# For documentation see the 3.x stub
+# 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.
+#
+# The `include` function can be used multiple times on the same class and will
+# only declare a given class once. If a class declared with `include` has any
+# parameters, Puppet will automatically look up values for them in Hiera, using
+# `<class name>::<parameter name>` as the lookup key.
+#
+# Contrast this behavior with resource-like class declarations
+# (`class {'name': parameter => 'value',}`), which must be used in only one place
+# per class and can directly set parameters. You should avoid using both `include`
+# and resource-like declarations with the same class.
+#
+# The `include` function does not cause classes to be contained in the class
+# where they are declared. For that, see the `contain` function. It also
+# does not create a dependency relationship between the declared class and the
+# surrounding class; for that, see the `require` function.
+#
+# You must use the class's full name;
+# relative names are not allowed. In addition to names in string form,
+# you may also directly use `Class` and `Resource` `Type`-values that are produced by
+# the 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
+#
 Puppet::Functions.create_function(:include, Puppet::Functions::InternalFunction) do
   dispatch :include do
     scope_param

data/lib/puppet/functions/info.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level info.
+# Logs a message on the server at level `info`.
 Puppet::Functions.create_function(:info, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/inline_epp.rb

@@ -35,13 +35,13 @@
 # For example, to evaluate an inline EPP template using a heredoc, call the
 # `inline_epp` function like this:
 #
-# ~~~ puppet
+# ```puppet
 # # Outputs 'Hello given argument planet!'
 # inline_epp(@(END), { x => 'given argument' })
 # <%- | $x, $y = planet | -%>
 # Hello <%= $x %> <%= $y %>!
 # END
-# ~~~
+# ```
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/join.rb

@@ -0,0 +1,56 @@
+# Joins the values of an Array into a string with elements separated by a delimiter.
+#
+# Supports up to two arguments
+# * **values** - first argument is required and must be an an `Array`
+# * **delimiter** - second arguments is the delimiter between elements, must be a `String` if given, and defaults to an empty string.
+#
+# @example Typical use of `join`
+#
+# ```puppet
+# join(['a','b','c'], ",")
+# # Would result in: "a,b,c"
+# ```
+#
+# Note that array is flattened before elements are joined, but flattening does not extend to arrays nested in hashes or other objects.
+#
+# @example Arrays nested in hashes are not joined
+#
+# ```puppet
+# $a = [1,2, undef, 'hello', [x,y,z], {a => 2, b => [3, 4]}]
+# notice join($a, ', ')
+#
+# # would result in noticing:
+# # 1, 2, , hello, x, y, z, {"a"=>2, "b"=>[3, 4]}
+# ```
+#
+# For joining iterators and other containers of elements a conversion must first be made to
+# an `Array`. The reason for this is that there are many options how such a conversion should
+# be made.
+#
+# @example Joining the result of a reverse_each converted to an array
+# 
+# ```puppet
+# [1,2,3].reverse_each.convert_to(Array).join(', ')
+# # would result in: "3, 2, 1"
+# ```
+# @example Joining a hash
+#
+# ```puppet
+# {a => 1, b => 2}.convert_to(Array).join(', ')
+# # would result in "a, 1, b, 2"
+# ```
+#
+# For more detailed control over the formatting (including indentations and line breaks, delimiters around arrays
+# and hash entries, between key/values in hash entries, and individual formatting of values in the array)
+# see the `new` function for `String` and its formatting options for `Array` and `Hash`.
+#
+Puppet::Functions.create_function(:join) do
+  dispatch :join do
+    param 'Array', :arg
+    optional_param 'String', :delimiter
+  end
+
+  def join(arg, delimiter = '', puppet_formatting = false)
+      arg.join(delimiter)
+  end
+end