puppet 4.0.0 → 4.5.0

data/lib/puppet/functions/reduce.rb

@@ -1,92 +1,121 @@
-# 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
+# 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, hash, or other iterable object that 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
 #
 Puppet::Functions.create_function(:reduce) do
 
   dispatch :reduce_without_memo do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[2,2]', :block
   end
 
   dispatch :reduce_with_memo do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     param 'Any', :memo
     block_param 'Callable[2,2]', :block
   end
 
   def reduce_without_memo(enumerable)
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     enum.reduce {|memo, x| yield(memo, x) }
   end
 
   def reduce_with_memo(enumerable, given_memo)
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     enum.reduce(given_memo) {|memo, x| yield(memo, x) }
   end
-
-  def asserted_enumerable(obj)
-    unless enum = Puppet::Pops::Types::Enumeration.enumerator(obj)
-      raise ArgumentError, ("#{self.class.name}(): wrong argument type (#{obj.class}; must be something enumerable.")
-    end
-    enum
-  end
-
 end

data/lib/puppet/functions/regsubst.rb

@@ -16,9 +16,10 @@
 # @param regexp [String|Regexp|Type[Regexp]]
 #      The regular expression matching the target string.  If you want it anchored at the start
 #      and or end of the string, you must do that with ^ and $ yourself.
-# @param replacement [String]
+# @param replacement [String|Hash[String, String]]
 #      Replacement string. Can contain backreferences to what was matched using \\0 (whole match),
 #      \\1 (first set of parentheses), and so on.
+#      If the second argument is a Hash, and the matched text is one of its keys, the corresponding value is the replacement string.
 # @param flags [String]
 #      Optional. String of single letter flags for how the regexp is interpreted (E, I, and M cannot be used
 #      if pattern is a precompiled regexp):
@@ -37,18 +38,18 @@
 #
 Puppet::Functions.create_function(:regsubst) do
   dispatch :regsubst_string do
-    param          'Variant[Array[String],String]',  :target
-    param          'String',                         :pattern
-    param          'String',                         :replacement
-    optional_param 'Optional[Pattern[/^[GEIM]*$/]]', :flags
-    optional_param "Enum['N','E','S','U']",          :encoding
+    param          'Variant[Array[String],String]',       :target
+    param          'String',                              :pattern
+    param          'Variant[String,Hash[String,String]]', :replacement
+    optional_param 'Optional[Pattern[/^[GEIM]*$/]]',      :flags
+    optional_param "Enum['N','E','S','U']",               :encoding
   end
 
   dispatch :regsubst_regexp do
-    param          'Variant[Array[String],String]',  :target
-    param          'Variant[Regexp,Type[Regexp]]',   :pattern
-    param          'String',                         :replacement
-    optional_param 'Pattern[/^G?$/]',                :flags
+    param          'Variant[Array[String],String]',       :target
+    param          'Variant[Regexp,Type[Regexp]]',        :pattern
+    param          'Variant[String,Hash[String,String]]', :replacement
+    optional_param 'Pattern[/^G?$/]',                     :flags
   end
 
   def regsubst_string(target, pattern, replacement, flags = nil, encoding = nil)
@@ -68,7 +69,7 @@ Puppet::Functions.create_function(:regsubst) do
   end
 
   def regsubst_regexp(target, pattern, replacement, flags = nil)
-    pattern = pattern.pattern if pattern.is_a?(Puppet::Pops::Types::PRegexpType)
+    pattern = (pattern.pattern || '') if pattern.is_a?(Puppet::Pops::Types::PRegexpType)
     inner_regsubst(target, pattern, replacement, operation = flags == 'G' ? :gsub : :sub)
   end
 

data/lib/puppet/functions/reverse_each.rb

@@ -0,0 +1,82 @@
+# Reverses the order of the elements of something that is iterable and optionally runs a
+# [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) for each
+# element.
+#
+# This function takes one to two arguments.
+#
+# 1. An `Iterable` that the function will iterate over.
+# 2. An optional lambda, which the function calls for each element in the first argument. It must
+# request one parameter.
+#
+# @example Using the `reverse_each` function
+#
+# `$data.reverse_each |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `$reverse_data = $data.reverse_each`
+#
+# or
+#
+# `reverse_each($data) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `$reverse_data = reverse_each($data)`
+#
+# When no second argument is present, Puppet returns an `Iterable` that represents the reverse
+# order of its first argument. This allows methods on `Iterable` to be chained.
+#
+# When a lamdba is given as the second argument, Puppet iterates the first argument in reverse
+# order and passes each value in turn to the lambda, then returns `undef`.
+#
+# @example Using the `reverse_each` function with an array and a one-parameter lambda
+#
+# ~~~ puppet
+# # Puppet will log a notice for each of the three items in $data in reverse order.
+# $data = [1,2,3]
+# $data.reverse_each |$item| { notice($item) }
+#
+# ~~~
+#
+# When no second argument is present, Puppet returns a new `Iterable` which allows it to
+# be directly chained into another function that takes an `Iterable` as an argument.
+#
+# @example Using the `reverse_each` function chained with a `map` function.
+#
+# # For the array $data, return an array containing each value multiplied by 10 in reverse order
+# $data = [1,2,3]
+# $transformed_data = $data.reverse_each.map |$item| { $item * 10 }
+# # $transformed_data is set to [30,20,10]
+# ~~~
+#
+# @example The same example using `reverse_each` function chained with a `map` in alternative syntax
+#
+# # For the array $data, return an array containing each value multiplied by 10 in reverse order
+# $data = [1,2,3]
+# $transformed_data = map(reverse_each($data)) |$item| { $item * 10 }
+# # $transformed_data is set to [30,20,10]
+# ~~~
+#
+# @since 4.4.0
+#
+Puppet::Functions.create_function(:reverse_each) do
+  dispatch :reverse_each do
+    param 'Iterable', :iterable
+  end
+
+  dispatch :reverse_each_block do
+    param 'Iterable', :iterable
+    block_param 'Callable[1,1]', :block
+  end
+
+  def reverse_each(iterable)
+    # produces an Iterable
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable).reverse_each
+  end
+
+  def reverse_each_block(iterable, &block)
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable).reverse_each(&block)
+    nil
+  end
+end

data/lib/puppet/functions/scanf.rb

@@ -1,23 +1,16 @@
-# Scans a string and returns an array of one or more converted values as directed by a given format string.args
-# See the documenation of Ruby's String::scanf method for details about the supported formats (which
-# are similar but not identical to the formats used in Puppet's `sprintf` function.
-#
-# This function takes two mandatory arguments: the first is the String to convert, and the second
-# the format String. A parameterized block may optionally be given, which is called with the result
-# that is produced by scanf if no block is present, the result of the block is then returned by
-# the function.
-#
-# The result of the scan is an Array, with each sucessfully scanned and transformed value.args The scanning
-# stops if a scan is unsuccesful and the scanned result up to that point is returned. If there was no
-# succesful scan at all, the result is an empty Array. The optional code block is typically used to
-# assert that the scan was succesful, and either produce the same input, or perform unwrapping of
-# the result
-#
-# @example scanning an integer in string form (result is an array with
-#   integer, or empty if  unsuccessful)
+# Scans a string and returns an array of one or more converted values based on the given format string.
+# See the documenation of Ruby's String#scanf method for details about the supported formats (which
+# are similar but not identical to the formats used in Puppet's `sprintf` function.)
+#
+# This function takes two mandatory arguments: the first is the string to convert, and the second is
+# the format string. The result of the scan is an array, with each sucessfully scanned and transformed value.
+# The scanning stops if a scan is unsuccesful, and the scanned result up to that point is returned. If there
+# was no succesful scan, the result is an empty array.
+#
 #    "42".scanf("%i")
 #
-# @example scanning and processing resulting array to assert result and unwrap
+# You can also optionally pass a lambda to scanf, to do additional validation or processing.
+#
 #
 #     "42".scanf("%i") |$x| {
 #       unless $x[0] =~ Integer {
@@ -26,6 +19,10 @@
 #       $x[0]
 #     }
 #
+#
+#
+#
+#
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:scanf) do

data/lib/puppet/functions/slice.rb

@@ -1,51 +1,45 @@
-# Applies a parameterized block to each _slice_ of elements in a sequence of selected entries from the first
-# argument and returns the first argument, or if no block is given returns a new array with a concatenation of
-# the slices.
+# This function takes two mandatory arguments: the first should be an array or hash, and the second specifies
+# the number of elements to include in each slice.
 #
-# This function takes two mandatory arguments: the first, `$a`, should be an Array, Hash, or something of
-# enumerable type (integer, Integer range, or String), and the second, `$n`, the number of elements to include
-# in each slice. The optional third argument should be a a parameterized block as produced by the puppet syntax:
-#
-#     $a.slice($n) |$x| { ... }
-#     slice($a) |$x| { ... }
-#
-# The parameterized block should have either one parameter (receiving an array with the slice), or the same number
-# of parameters as specified by the slice size (each parameter receiving its part of the slice).
-# In case there are fewer remaining elements than the slice size for the last slice it will contain the remaining
-# elements. When the block has multiple parameters, excess parameters are set to undef for an array or
-# enumerable type, and to empty arrays for a Hash.
-#
-#     $a.slice(2) |$first, $second| { ... }
-#
-# When the first argument is a Hash, each `key,value` entry is counted as one, e.g, a slice size of 2 will produce
+# When the first argument is a hash, each key value pair is counted as one. For example, a slice size of 2 will produce
 # an array of two arrays with key, and value.
 #
-# @example Using slice with Hash
-#
 #     $a.slice(2) |$entry|          { notice "first ${$entry[0]}, second ${$entry[1]}" }
 #     $a.slice(2) |$first, $second| { notice "first ${first}, second ${second}" }
 #
-# When called without a block, the function produces a concatenated result of the slices.
-#
-# @example Using slice without a block
+# The function produces a concatenated result of the slices.
 #
 #     slice([1,2,3,4,5,6], 2) # produces [[1,2], [3,4], [5,6]]
 #     slice(Integer[1,6], 2)  # produces [[1,2], [3,4], [5,6]]
 #     slice(4,2)              # produces [[0,1], [2,3]]
 #     slice('hello',2)        # produces [[h, e], [l, l], [o]]
 #
+#
+# You can also optionally pass a lambda to slice.
+#
+#     $a.slice($n) |$x| { ... }
+#     slice($a) |$x| { ... }
+#
+# The lambda should have either one parameter (receiving an array with the slice), or the same number
+# of parameters as specified by the slice size (each parameter receiving its part of the slice).
+# If there are fewer remaining elements than the slice size for the last slice, it will contain the remaining
+# elements. If the lambda has multiple parameters, excess parameters are set to undef for an array, or
+# to empty arrays for a hash.
+#
+#     $a.slice(2) |$first, $second| { ... }
+#
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:slice) do
   dispatch :slice_Hash do
     param 'Hash[Any, Any]', :hash
-    param 'Integer[1, default]', :slize_size
+    param 'Integer[1, default]', :slice_size
     optional_block_param
   end
 
   dispatch :slice_Enumerable do
-    param 'Any', :enumerable
-    param 'Integer[1, default]', :slize_size
+    param 'Iterable', :enumerable
+    param 'Integer[1, default]', :slice_size
     optional_block_param
   end
 
@@ -55,7 +49,7 @@ Puppet::Functions.create_function(:slice) do
   end
 
   def slice_Enumerable(enumerable, slice_size, &pblock)
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     result = slice_Common(enum, slice_size, nil, block_given? ? pblock : nil)
     block_given? ? enumerable : result
   end
@@ -114,12 +108,4 @@ Puppet::Functions.create_function(:slice) do
     end
     serving_size
   end
-
-  def asserted_enumerable(obj)
-    unless enum = Puppet::Pops::Types::Enumeration.enumerator(obj)
-      raise ArgumentError, ("#{self.class.name}(): wrong argument type (#{obj.class}; must be something enumerable.")
-    end
-    enum
-  end
-
 end

data/lib/puppet/functions/split.rb

@@ -6,7 +6,7 @@
 #     $string     = 'v1.v2:v3.v4'
 #     $array_var1 = split($string, /:/)
 #     $array_var2 = split($string, '[.]')
-#     $array_var3 = split($string, Regexp('[.:]'))
+#     $array_var3 = split($string, Regexp['[.:]'])
 #
 # `$array_var1` now holds the result `['v1.v2', 'v3.v4']`,
 # while `$array_var2` holds `['v1', 'v2:v3', 'v4']`, and
@@ -15,7 +15,7 @@
 # Note that in the second example, we split on a literal string that contains
 # a regexp meta-character (.), which must be escaped.  A simple
 # way to do that for a single character is to enclose it in square
-# brackets; a backslash will also escape a single character.") do |args|
+# brackets; a backslash will also escape a single character.
 #
 Puppet::Functions.create_function(:split) do
   dispatch :split_String do
@@ -42,6 +42,6 @@ Puppet::Functions.create_function(:split) do
   end
 
   def split_RegexpType(str, pattern)
-    str.split(pattern.pattern)
+    str.split(pattern.regexp)
   end
 end

data/lib/puppet/functions/step.rb

@@ -0,0 +1,88 @@
+# Provides stepping with given interval over elements in an iterable and optionally runs a
+# [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) for each
+# element.
+#
+# This function takes two to three arguments.
+#
+# 1. An 'Iterable' that the function will iterate over.
+# 2. An `Integer` step factor. This must be a positive integer.
+# 3. An optional lambda, which the function calls for each element in the interval. It must
+# request one parameter.
+#
+# @example Using the `step` function
+#
+# `$data.step(<n>) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `$stepped_data = $data.step(<n>)`
+#
+# or
+#
+# `step($data, <n>) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `$stepped_data = step($data, <n>)`
+#
+# When no block is given, Puppet returns an `Iterable` that yields the first element and every nth successor
+# element, from its first argument. This allows functions on iterables to be chained.
+#
+# When a block is given, Puppet iterates and calls the block with the first element and then with
+# every nth successor element. It then returns `undef`.
+#
+# @example Using the `step` function with an array, a step factor, and a one-parameter block
+#
+# ~~~ puppet
+# # For the array $data, call a block with the first element and then with each 3rd successor element
+# $data = [1,2,3,4,5,6,7,8]
+# $data.step(3) |$item| {
+#  notice($item)
+# }
+# # Puppet notices the values '1', '4', '7'.
+# ~~~
+#
+# When no block is given, Puppet returns a new `Iterable` which allows it to be directly chained into
+# another function that takes an `Iterable` as an argument.
+#
+# @example Using the `step` function chained with a `map` function.
+#
+# # For the array $data, return an array, set to the first element and each 5th successor element, in reverse
+# # order multiplied by 10
+# $data = Integer[0,20]
+# $transformed_data = $data.step(5).map |$item| { $item * 10 }
+# # $transformed_data contains [0,50,100,150,200]
+# ~~~
+#
+# @example The same example using `step` function chained with a `map` in alternative syntax
+#
+# # For the array $data, return an array, set to the first and each 5th successor, in reverse order, multiplied by 10
+# $data = Integer[0,20]
+# $transformed_data = map(step($data, 5)) |$item| { $item * 10 }
+# # $transformed_data contains [0,50,100,150,200]
+# ~~~
+#
+# @since 4.4.0
+#
+Puppet::Functions.create_function(:step) do
+  dispatch :step do
+    param 'Iterable', :iterable
+    param 'Integer[1]', :step
+  end
+
+  dispatch :step_block do
+    param 'Iterable', :iterable
+    param 'Integer[1]', :step
+    block_param 'Callable[1,1]', :block
+  end
+
+  def step(iterable, step)
+    # produces an Iterable
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable).step(step)
+  end
+
+  def step_block(iterable, step, &block)
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable).step(step, &block)
+    nil
+  end
+end

data/lib/puppet/functions/then.rb

@@ -0,0 +1,74 @@
+# Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# with the given argument unless the argument is undef. Return undef if argument is
+# undef, and otherwise the result of giving the argument to the lambda.
+#
+# This is useful to process a sequence of operations where an intermediate
+# result may be undef (which makes the entire sequence undef).
+# The `then` function is especially useful with the function `dig` which
+# performs in a similar way "digging out" a value in a complex structure.
+#
+# @example Using `then`
+#
+# ~~~ puppet
+# $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
+# notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
+# ~~~
+#
+# Would notice the value 200
+#
+# Contrast this with:
+#
+# ~~~ puppet
+# $data = {a => { b => [{x => 10, y => 20}, {ex => 100, why => 200}]}}
+# notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
+# ~~~
+#
+# Which would notice undef since the last lookup of 'x' results in `undef` which
+# is returned (without calling the block).
+#
+# As a result there was no need for conditional logic or a temporary (non local) 
+# variable as the result is now either the wanted value (x) multiplied
+# by 2 or `undef`.
+#
+# Calls to `then` can be chained. In the next example, a structure is using an offset that
+# is using 1 as the index to the first element (instead of 0 which is used in the language).
+# We are not sure if user input actually contains an index at all, or if it is
+# outside the range of available names.
+#
+# ~~~ puppet
+# # Names to choose from
+# $names = ['Ringo', 'Paul', 'George', 'John']
+#
+# # structure where 'beatle 2' is wanted (but where the number refers
+# # to 'Paul' because input comes from a source using 1 for the first
+# # element).
+#
+# $data = [202, { beatle => 2 }]
+# $picked = assert_type(String,
+#   # the data we are interested in is the second in the array,
+#   # a hash, where we want the value of the key 'beatle'
+#   $data.dig(1, 'beatle')
+#     # and we want the index in $names before the given index
+#     .then |$x| { $names[$x-1] }
+#     # so we can construct a string with that beatle's name
+#     .then |$x| { "Picked Beatle '${x}'" }
+# )
+#
+# ~~~ puppet
+#
+# Would notice "Picked Beatle 'Paul'", and would raise an error if the result
+# was not a String.
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:then) do
+  dispatch :then do
+    param 'Any', :arg
+    block_param 'Callable[1,1]', :block
+  end
+
+  def then(arg)
+    return nil if arg.nil?
+    yield(arg)
+  end
+end