puppet 5.0.0 → 6.0.0

data/lib/puppet/functions/getvar.rb

@@ -0,0 +1,87 @@
+# Digs into a variable with dot notation to get a value from a structure.
+#
+# **To get the value from a variable** (that may or may not exist), call the function with
+# one or two arguments:
+#
+# * The **first** argument must be a string, and must start with a variable name without leading `$`,
+#   for example `get('facts')`. The variable name can be followed
+#   by a _dot notation navigation string_ to dig out a value in the array or hash value
+#   of the variable.
+# * The **optional second** argument can be any type of value and it is used as the
+#   _default value_ if the function would otherwise return `undef`.
+# * An **optional lambda** for error handling taking one `Error` argument.
+#
+# **Dot notation navigation string** -
+# The dot string consists of period `.` separated segments where each
+# segment is either the index into an array or the value of a hash key.
+# If a wanted key contains a period it must be quoted to avoid it being
+# taken as a segment separator. Quoting can be done with either
+# single quotes `'` or double quotes `"`. If a segment is
+# a decimal number it is converted to an Integer index. This conversion
+# can be prevented by quoting the value.
+#
+# @example Getting the value of a variable
+# ```puppet
+# getvar('facts') # results in the value of $facts
+# ```
+#
+# @example Navigating into a variable
+# ```puppet
+# getvar('facts.os.family') # results in the value of $facts['os']['family']
+# ```
+#
+# @example Using a default value
+# ```puppet
+# $x = [1,2,[{'name' =>'waldo'}]]
+# getvar('x.2.1.name', 'not waldo')
+# # results in 'not waldo'
+# ```
+#
+# For further examples and how to perform error handling, see the `get()` function
+# which this function delegates to after having resolved the variable value.
+#
+# @since 6.0.0 - the ability to dig into the variable's value with dot notation.
+#
+Puppet::Functions.create_function(:getvar, Puppet::Functions::InternalFunction) do
+  dispatch :get_from_navigation do
+    scope_param
+     param 'Pattern[/\A(?:::)?(?:[a-z]\w*::)*[a-z_]\w*(?:\.|\Z)/]', :get_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable[1,1]', :block
+  end
+
+  argument_mismatch :invalid_variable_error do
+    param 'String', :get_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable', :block
+  end
+
+  def invalid_variable_error(navigation, default_value=nil, &block)
+    _("The given string does not start with a valid variable name")
+  end
+
+  # Gets a result from a navigation string starting with $var
+  #
+  def get_from_navigation(scope, navigation, default_value = nil, &block)
+    # asserted to start with a valid variable name - dig out the variable
+    matches = navigation.match(/^((::)?(\w+::)*\w+)(.*)\z/)
+    navigation = matches[4]
+    if navigation[0] == '.'
+      navigation = navigation[1..-1]
+    else
+      unless navigation.empty?
+        raise ArgumentError, _("First character after var name in get string must be a '.' - got %{char}") % {char: navigation[0]}
+      end
+    end
+    get_from_var_name(scope, matches[1], navigation, default_value, &block)
+  end
+
+  # Gets a result from a $var name and a navigation string
+  #
+  def get_from_var_name(scope, var_string, navigation, default_value = nil, &block)
+    catch(:undefined_variable) do
+      return call_function_with_scope(scope,'get', scope.lookupvar(var_string), navigation, default_value, &block)
+    end
+    default_value
+  end
+end

data/lib/puppet/functions/hiera.rb

@@ -14,7 +14,7 @@ require 'hiera/puppet_function'
 #     * 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
+# [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.
@@ -25,7 +25,7 @@ require 'hiera/puppet_function'
 #
 # @example Using `hiera`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -44,24 +44,24 @@ 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
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
 # takes one parameter.
 #
 # @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,15 +70,15 @@ 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 
+# 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 'Using the lookup function' documentation](https://docs.puppet.com/puppet/latest/hiera_use_function.html) for how to perform lookup of data.
+# [the 'Using the lookup function' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html) for how to perform lookup of data.
 # Also see
-# [the 'Using the deprecated hiera functions' documentation](https://docs.puppet.com/puppet/latest/hiera_use_hiera_functions.html)
+# [the 'Using the deprecated hiera functions' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html)
 # for more information about the Hiera 3 functions.
 #
 # @since 4.0.0

data/lib/puppet/functions/hiera_array.rb

@@ -3,7 +3,7 @@ require 'hiera/puppet_function'
 # 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).
+# [array merge lookup](https://puppet.com/docs/hiera/latest/lookup_types.html#array-merge).
 #
 # This function is deprecated in favor of the `lookup` function. While this function
 # continues to work, it does **not** support:
@@ -17,14 +17,14 @@ require 'hiera/puppet_function'
 #     * 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
+# [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.
 #
 # @example Using `hiera_array`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -37,21 +37,21 @@ 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
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
 # takes one parameter.
 #
 # @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,15 +59,15 @@ 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.
 #
 # See
-# [the 'Using the lookup function' documentation](https://docs.puppet.com/puppet/latest/hiera_use_function.html) for how to perform lookup of data.
+# [the 'Using the lookup function' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html) for how to perform lookup of data.
 # Also see
-# [the 'Using the deprecated hiera functions' documentation](https://docs.puppet.com/puppet/latest/hiera_use_hiera_functions.html)
+# [the 'Using the deprecated hiera functions' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html)
 # for more information about the Hiera 3 functions.
 #
 # @since 4.0.0

data/lib/puppet/functions/hiera_hash.rb

@@ -9,10 +9,10 @@ require 'hiera/puppet_function'
 #
 # 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).
+# [hash merge lookup](https://puppet.com/docs/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)
+# [`:merge_behavior`](https://puppet.com/docs/hiera/latest/configuring.html#mergebehavior)
 # setting.
 #
 # The `hiera_hash` function takes up to three arguments, in this order:
@@ -22,14 +22,14 @@ require 'hiera/puppet_function'
 #     * 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
+# [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.
 #
 # @example Using `hiera_hash`
 #
-# ~~~ yaml
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -44,24 +44,24 @@ 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
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
 # takes one parameter.
 #
 # @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,15 +70,15 @@ 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.
 #
 # See
-# [the 'Using the lookup function' documentation](https://docs.puppet.com/puppet/latest/hiera_use_function.html) for how to perform lookup of data.
+# [the 'Using the lookup function' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html) for how to perform lookup of data.
 # Also see
-# [the 'Using the deprecated hiera functions' documentation](https://docs.puppet.com/puppet/latest/hiera_use_hiera_functions.html)
+# [the 'Using the deprecated hiera functions' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html)
 # for more information about the Hiera 3 functions.
 #
 # @since 4.0.0

data/lib/puppet/functions/hiera_include.rb

@@ -1,7 +1,7 @@
 require 'hiera/puppet_function'
 
 # Assigns classes to a node using an
-# [array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge)
+# [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.
 #
 # This function is deprecated in favor of the `lookup` function in combination with `include`.
@@ -10,11 +10,11 @@ require 'hiera/puppet_function'
 # * lookup across global, environment, and module layers
 #
 # @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:
 #
@@ -32,18 +32,18 @@ require 'hiera/puppet_function'
 #     * 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
+# [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://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge)
+# [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
+# ```yaml
 # # Assuming hiera.yaml
 # # :hierarchy:
 # #   - web01.example.com
@@ -56,22 +56,22 @@ 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
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
 # takes one parameter.
 #
 # @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,12 +80,12 @@ 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.
+# [the 'Using the lookup function' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html) for how to perform lookup of data.
 # Also see
-# [the 'Using the deprecated hiera functions' documentation](https://docs.puppet.com/puppet/latest/hiera_use_hiera_functions.html)
+# [the 'Using the deprecated hiera functions' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html)
 # for more information about the Hiera 3 functions.
 #
 # @since 4.0.0

data/lib/puppet/functions/hocon_data.rb

@@ -1,5 +1,5 @@
 # The `hocon_data` is a hiera 5 `data_hash` data provider function.
-# See [the configuration guide documentation](https://docs.puppet.com/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
+# See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
 # how to use this function.
 #
 # Note that this function is not supported without a hocon library being present.

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
@@ -11,6 +37,12 @@ Puppet::Functions.create_function(:include, Puppet::Functions::InternalFunction)
   end
 
   def include(scope, *classes)
+    if Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+        {:operation => 'include'})
+    end
+
     classes = scope.transform_and_assert_classnames(classes.flatten)
     result = classes.map {|name| Puppet::Pops::Types::TypeFactory.host_class(name) }
     scope.compiler.evaluate_classes(classes, scope, false)

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

data/lib/puppet/functions/json_data.rb

@@ -1,5 +1,5 @@
 # The `json_data` is a hiera 5 `data_hash` data provider function.
-# See [the configuration guide documentation](https://docs.puppet.com/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
+# See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
 # how to use this function.
 #
 # @since 4.8.0
@@ -19,8 +19,8 @@ Puppet::Functions.create_function(:json_data) do
     path = options['path']
     context.cached_file_data(path) do |content|
       begin
-        JSON.parse(content)
-      rescue JSON::ParserError => ex
+        Puppet::Util::Json.load(content)
+      rescue Puppet::Util::Json::ParseError => ex
         # Filename not included in message, so we add it here.
         raise Puppet::DataBinding::LookupError, "Unable to parse (%{path}): %{message}" % { path: path, message: ex.message }
       end

data/lib/puppet/functions/keys.rb

@@ -0,0 +1,25 @@
+# Returns the keys of a hash as an Array
+#
+# @example Using `keys`
+#
+# ```puppet
+# $hsh = {"apples" => 3, "oranges" => 4 }
+# $hsh.keys()
+# keys($hsh)
+# # both results in the array ["apples", "oranges"]
+# ```
+#
+# * Note that a hash in the puppet language accepts any data value (including `undef`) unless
+#   it is constrained with a `Hash` data type that narrows the allowed data types.
+# * For an empty hash, an empty array is returned.
+# * The order of the keys is the same as the order in the hash (typically the order in which they were added).
+#
+Puppet::Functions.create_function(:keys) do
+  dispatch :keys do
+    param 'Hash', :hsh
+  end
+
+  def keys(hsh)
+    hsh.keys
+  end
+end

data/lib/puppet/functions/length.rb

@@ -0,0 +1,44 @@
+# Returns the length of an Array, Hash, String, or Binary value.
+#
+# The returned value is a positive integer indicating the number
+# of elements in the container; counting (possibly multibyte) characters for a `String`,
+# bytes in a `Binary`, number of elements in an `Array`, and number of
+# key-value associations in a Hash.
+#
+# @example Using `length`
+#
+# ```puppet
+# "roses".length()        # 5
+# length("violets")       # 7
+# [10, 20].length         # 2
+# {a => 1, b => 3}.length # 2
+# ```
+#
+# @since 5.5.0 - also supporting Binary
+#
+Puppet::Functions.create_function(:length) do
+  dispatch :collection_length do
+    param 'Collection', :arg
+  end
+
+  dispatch :string_length do
+    param 'String', :arg
+  end
+
+  dispatch :binary_length do
+    param 'Binary', :arg
+  end
+
+  def collection_length(col)
+    col.size
+  end
+
+  def string_length(s)
+    s.length
+  end
+
+  def binary_length(bin)
+    bin.length
+  end
+
+end

data/lib/puppet/functions/lest.rb

@@ -1,4 +1,42 @@
-# (Documented in 3.x stub)
+# Calls a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+# without arguments if the value given to `lest` 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
 #
 Puppet::Functions.create_function(:lest) do