puppet 5.0.0 → 6.0.0

data/lib/puppet/functions/next.rb

@@ -1,4 +1,4 @@
-# Make iteration continue with the next value optionally given a value for this iteration.
+# Makes iteration continue with the next value, optionally with a given value for this iteration.
 # If a value is not given it defaults to `undef`
 #
 # @since 4.7.0
@@ -9,14 +9,7 @@ Puppet::Functions.create_function(:next) do
   end
 
   def next_impl(value = nil)
-    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
-    if stacktrace.size > 0
-      file, line = stacktrace[0]
-    else
-      file = nil
-      line = nil
-    end
-
+    file, line = Puppet::Pops::PuppetStack.top_of_stack
     exc = Puppet::Pops::Evaluator::Next.new(value, file, line)
     raise exc
   end

data/lib/puppet/functions/notice.rb

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

data/lib/puppet/functions/reduce.rb

@@ -1,4 +1,4 @@
-# Applies a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# Applies a [lambda](https://puppet.com/docs/puppet/latest/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
@@ -47,7 +47,7 @@
 #
 # @example Using the `reduce` function
 #
-# ~~~ puppet
+# ```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 }
@@ -68,11 +68,11 @@
 #   [$string, $number]
 # }
 # # $combine contains [abc, 6]
-# ~~~
+# ```
 #
 # @example Using the `reduce` function with a start memo and two-parameter lambda
 #
-# ~~~ puppet
+# ```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]
@@ -92,7 +92,38 @@
 # # At the start of the lambda's first iteration, $memo contains [d, 4] and $value
 # # contains [a, 1].
 # # $combine contains [dabc, 10]
-# ~~~
+# ```
+#
+# @example Using the `reduce` function to reduce a hash of hashes
+#
+# ```puppet
+# # Reduce a hash of hashes $data, merging defaults into the inner hashes.
+# $data = {
+#   'connection1' => {
+#     'username' => 'user1',
+#     'password' => 'pass1',
+#   },
+#   'connection_name2' => {
+#     'username' => 'user2',
+#     'password' => 'pass2',
+#   },
+# }
+#
+# $defaults = {
+#   'maxActive' => '20',
+#   'maxWait'   => '10000',
+#   'username'  => 'defaultuser',
+#   'password'  => 'defaultpass',
+# }
+#
+# $merged = $data.reduce( {} ) |$memo, $x| {
+#   $memo + { $x[0] => $defaults + $data[$x[0]] }
+# }
+# # At the start of the lambda's first iteration, $memo is set to {}, and $x is set to
+# # the first [key, value] tuple. The key in $data is, therefore, given by $x[0]. In
+# # subsequent rounds, $memo retains the value returned by the expression, i.e.
+# # $memo + { $x[0] => $defaults + $data[$x[0]] }.
+# ```
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/regsubst.rb

@@ -1,4 +1,4 @@
-# Perform regexp replacement on a string or array of strings.
+# Performs regexp replacement on a string or array of strings.
 #
 # @param target [String, Array[String]]
 #      The string or array of strings to operate on.  If an array, the replacement will be
@@ -27,10 +27,16 @@
 # @return [Array[String], String] The result of the substitution. Result type is the same as for the target parameter.
 #
 # @example Get the third octet from the node's IP address:
-#     $i3 = regsubst($ipaddress,'^(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$','\\3')
+#
+# ```puppet
+# $i3 = regsubst($ipaddress,'^(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$','\\3')
+# ```
 #
 # @example Put angle brackets around each octet in the node's IP address:
-#     $x = regsubst($ipaddress, /([0-9]+)/, '<\\1>', 'G')
+#
+# ```puppet
+# $x = regsubst($ipaddress, /([0-9]+)/, '<\\1>', 'G')
+# ```
 #
 Puppet::Functions.create_function(:regsubst) do
   dispatch :regsubst_string do
@@ -66,7 +72,7 @@ Puppet::Functions.create_function(:regsubst) do
 
   def regsubst_regexp(target, pattern, replacement, flags = nil)
     pattern = (pattern.pattern || '') if pattern.is_a?(Puppet::Pops::Types::PRegexpType)
-    inner_regsubst(target, pattern, replacement, operation = flags == 'G' ? :gsub : :sub)
+    inner_regsubst(target, pattern, replacement, flags == 'G' ? :gsub : :sub)
   end
 
   def inner_regsubst(target, re, replacement, op)

data/lib/puppet/functions/require.rb

@@ -1,5 +1,39 @@
-# Requires the specified classes
-# For documentation see the 3.x function stub
+# Requires the specified classes.
+# Evaluate one or more classes, adding the required class as a dependency.
+#
+# The relationship metaparameters work well for specifying relationships
+# between individual resources, but they can be clumsy for specifying
+# relationships between classes.  This function is a superset of the
+# 'include' function, adding a class relationship so that the requiring
+# class depends on the required class.
+#
+# Warning: using require in place of include can lead to unwanted dependency cycles.
+#
+# For instance the following manifest, with 'require' instead of 'include' would produce a nasty
+# dependence cycle, because notify imposes a before between File[/foo] and Service[foo]:
+#
+# ```puppet
+# class myservice {
+#   service { foo: ensure => running }
+# }
+#
+# class otherstuff {
+#    include myservice
+#    file { '/foo': notify => Service[foo] }
+# }
+# ```
+#
+# Note that this function only works with clients 0.25 and later, and it will
+# fail if used with earlier clients.
+#
+# 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 when evaluating
+# resource and relationship expressions.
+#
+# - Since 4.0.0 Class and Resource types, absolute names
+# - Since 4.7.0 Returns an Array[Type[Class]] with references to the required classes
+#
 Puppet::Functions.create_function(:require, Puppet::Functions::InternalFunction) do
   dispatch :require_impl do
     scope_param
@@ -11,6 +45,12 @@ Puppet::Functions.create_function(:require, Puppet::Functions::InternalFunction)
   end
 
   def require_impl(scope, *classes)
+    if Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+        {:operation => 'require'})
+    end
+
     # Make call patterns uniform and protected against nested arrays, also make
     # names absolute if so desired.
     classes = scope.transform_and_assert_classnames(classes.flatten)

data/lib/puppet/functions/return.rb

@@ -1,4 +1,4 @@
-# Make iteration continue with the next value optionally given a value for this iteration.
+# Makes iteration continue with the next value, optionally with a given value for this iteration.
 # If a value is not given it defaults to `undef`
 #
 # @since 4.7.0
@@ -9,14 +9,7 @@ Puppet::Functions.create_function(:return, Puppet::Functions::InternalFunction)
   end
 
   def return_impl(value = nil)
-    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
-    if stacktrace.size > 0
-      file, line = stacktrace[0]
-    else
-      file = nil
-      line = nil
-    end
-
+    file, line = Puppet::Pops::PuppetStack.top_of_stack
     raise Puppet::Pops::Evaluator::Return.new(value, file, line)
   end
 end

data/lib/puppet/functions/reverse_each.rb

@@ -1,5 +1,74 @@
-# Reverses the order of the elements of something that is iterable.
-# (Documentation in 3.x stub)
+# Reverses the order of the elements of something that is iterable and optionally runs a
+# [lambda](https://puppet.com/docs/puppet/latest/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
+#
+# ```puppet
+# $data.reverse_each |$parameter| { <PUPPET CODE BLOCK> }
+# ```
+#
+# or
+#
+# ```puppet
+# $reverse_data = $data.reverse_each
+# ```
+#
+# or
+#
+# ```puppet
+# reverse_each($data) |$parameter| { <PUPPET CODE BLOCK> }
+# ```
+#
+# or
+#
+# ```puppet
+# $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 lambda 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.
+#
+# ```puppet
+# # 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 Using `reverse_each` function chained with a `map` in alternative syntax
+#
+# ```puppet
+# # 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
 #

data/lib/puppet/functions/round.rb

@@ -0,0 +1,24 @@
+# Returns an `Integer` value rounded to the nearest value.
+# Takes a single `Numeric` value as an argument.
+#
+# @example 'rounding a value'
+#
+# ```puppet
+# notice(round(2.9)) # would notice 3
+# notice(round(2.1)) # would notice 2
+# notice(round(-2.9)) # would notice -3
+# ```
+#
+Puppet::Functions.create_function(:round) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  def on_numeric(x)
+    if x > 0
+      Integer(x + 0.5)
+    else
+      Integer(x - 0.5)
+    end
+  end
+end

data/lib/puppet/functions/rstrip.rb

@@ -0,0 +1,58 @@
+# Strips trailing spaces from a String
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes all trailing ASCII white space characters such as space, tab, newline, and return.
+#   It does not remove other space-like characters like hard space (Unicode U+00A0). (Tip, `/^[[:space:]]/` regular expression
+#   matches all space-like characters).
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is processed and the conversion is not recursive.
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# @example Removing trailing space from a String
+# ```puppet
+# "hello\n\t".lstrip()
+# camelcase("hello\n\t")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing trailing space from strings in an Array
+# ```puppet
+# ["hello\n\t", "hi\n\t"].lstrip()
+# lstrip(["hello\n\t", "hi\n\t"])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:rstrip) do
+
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_iterable do
+    param 'Iterable[Variant[String, Numeric]]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.rstrip
+  end
+
+  def on_iterable(a)
+    a.map {|x| do_rstrip(x) }
+  end
+
+  def do_rstrip(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.rstrip : x
+  end
+end

data/lib/puppet/functions/size.rb

@@ -0,0 +1,15 @@
+# The same as length() - returns the size of an Array, Hash, String, or Binary value.
+#
+# @since 6.0.0 - also supporting Binary
+#
+Puppet::Functions.create_function(:size) do
+  dispatch :generic_size do
+    param 'Variant[Collection, String, Binary]', :arg
+  end
+
+
+  def generic_size(arg)
+    call_function('length', arg)
+  end
+
+end

data/lib/puppet/functions/slice.rb

@@ -1,24 +1,34 @@
+# Slices an array or hash into pieces of a given size.
+#
 # 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.
 #
 # 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.
 #
-#     $a.slice(2) |$entry|          { notice "first ${$entry[0]}, second ${$entry[1]}" }
-#     $a.slice(2) |$first, $second| { notice "first ${first}, second ${second}" }
+# @example Slicing a Hash
 #
+# ```puppet
+# $a.slice(2) |$entry|          { notice "first ${$entry[0]}, second ${$entry[1]}" }
+# $a.slice(2) |$first, $second| { notice "first ${first}, second ${second}" }
+# ```
 # 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]]
+# @example Slicing an Array
 #
+# ```puppet
+# 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.
+# @example Passing a lambda to a slice (optional)
 #
-#     $a.slice($n) |$x| { ... }
-#     slice($a) |$x| { ... }
+# ```puppet
+#  $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).
@@ -26,7 +36,11 @@
 # elements. If the lambda has multiple parameters, excess parameters are set to undef for an array, or
 # to empty arrays for a hash.
 #
+# @example Getting individual values of a slice
+#
+# ```puppet
 #     $a.slice(2) |$first, $second| { ... }
+# ```
 #
 # @since 4.0.0
 #
@@ -102,9 +116,8 @@ Puppet::Functions.create_function(:slice) do
       raise ArgumentError, _("slice(): block must define at least one parameter. Block has 0.")
     end
     unless serving_size == 1 || serving_size == slice_size
-      raise ArgumentError, _("slice(): block must define one parameter, or ") +
-        _("the same number of parameters as the given size of the slice (%{slice_size}). Block has %{serving_size}; ") % { slice_size: slice_size, serving_size: serving_size }+
-      pblock.parameter_names.join(', ')
+      raise ArgumentError, _("slice(): block must define one parameter, or the same number of parameters as the given size of the slice (%{slice_size}). Block has %{serving_size}; %{parameter_names}") %
+          { slice_size: slice_size, serving_size: serving_size, parameter_names: pblock.parameter_names.join(', ') }
     end
     serving_size
   end

data/lib/puppet/functions/sort.rb

@@ -0,0 +1,74 @@
+# Sorts an Array numerically or lexicographically or the characters of a String lexicographically.
+# Please note: This function is based on Ruby String comparison and as such may not be entirely UTF8 compatible.
+# To ensure compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085.
+#
+# This function is compatible with the function sort() in stdlib.
+# * Comparison of characters in a string always uses a system locale and may not be what is expected for a particular locale
+# * Sorting is based on Ruby's <=> operator unless a lambda is given that performs the comparison.
+#   * comparison of strings is case dependent (use lambda with `compare($a,$b)` to ignore case)
+#   * comparison of mixed data types raises an error (if there is the need to sort mixed data types use a lambda)
+#
+# Also see the `compare()` function for information about comparable data types in general.
+#
+# @example Sorting a String
+#
+# ```puppet
+# notice(sort("xadb")) # notices 'abdx'
+# ```
+#
+# @example Sorting an Array
+#
+# ```puppet
+# notice(sort([3,6,2])) # notices [2, 3, 6]
+# ```
+#
+# @example Sorting with a lambda
+#
+# ```puppet
+# notice(sort([3,6,2]) |$a,$b| { compare($a, $b) }) # notices [2, 3, 6]
+# notice(sort([3,6,2]) |$a,$b| { compare($b, $a) }) # notices [6, 3, 2]
+# ```
+#
+# @example Case independent sorting with a lambda
+#
+# ```puppet
+# notice(sort(['A','b','C']))                                    # notices ['A', 'C', 'b']
+# notice(sort(['A','b','C']) |$a,$b| { compare($a, $b) })        # notices ['A', 'b', 'C']
+# notice(sort(['A','b','C']) |$a,$b| { compare($a, $b, true) })  # notices ['A', 'b', 'C']
+# notice(sort(['A','b','C']) |$a,$b| { compare($a, $b, false) }) # notices ['A','C', 'b']
+# ```
+#
+# @example Sorting Array with Numeric and String so that numbers are before strings
+#
+# ```puppet
+# notice(sort(['b', 3, 'a', 2]) |$a, $b| {
+#   case [$a, $b] {
+#     [String, Numeric] : { 1 }
+#     [Numeric, String] : { -1 }
+#     default:            { compare($a, $b) }
+#   }
+# })
+# ```
+# Would notice [2,3,'a','b']
+#
+# @since 6.0.0 - supporting a lambda to do compare
+#
+Puppet::Functions.create_function(:sort) do
+  dispatch :sort_string do
+    param 'String', :string_value
+    optional_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :sort_array do
+    param 'Array', :array_value
+    optional_block_param 'Callable[2,2]', :block
+  end
+
+  def sort_string(s, &block)
+    sort_array(s.split(''), &block).join('')
+  end
+
+  def sort_array(a, &block)
+    a.sort(&block)
+  end
+end

data/lib/puppet/functions/split.rb

@@ -1,19 +1,21 @@
-# Split a string variable into an array using the specified pattern.
+# Splits a string into an array using a given pattern.
 # The pattern can be a string, regexp or regexp type.
 #
-# @example
+# @example Splitting a String value
 #
-#     $string     = 'v1.v2:v3.v4'
-#     $array_var1 = split($string, /:/)
-#     $array_var2 = split($string, '[.]')
-#     $array_var3 = split($string, Regexp['[.:]'])
+# ```puppet
+# $string     = 'v1.v2:v3.v4'
+# $array_var1 = split($string, /:/)
+# $array_var2 = split($string, '[.]')
+# $array_var3 = split($string, Regexp['[.:]'])
 #
-# `$array_var1` now holds the result `['v1.v2', 'v3.v4']`,
-# while `$array_var2` holds `['v1', 'v2:v3', 'v4']`, and
-# `$array_var3` holds `['v1', 'v2', 'v3', 'v4']`.
+# #`$array_var1` now holds the result `['v1.v2', 'v3.v4']`,
+# # while `$array_var2` holds `['v1', 'v2:v3', 'v4']`, and
+# # `$array_var3` holds `['v1', 'v2', 'v3', 'v4']`.
+# ```
 #
 # Note that in the second example, we split on a literal string that contains
-# a regexp meta-character (.), which must be escaped.  A simple
+# 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.
 #

data/lib/puppet/functions/step.rb

@@ -1,4 +1,76 @@
-# (Documentation in 3.x stub)
+# Provides stepping with given interval over elements in an iterable and optionally runs a
+# [lambda](https://puppet.com/docs/puppet/latest/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
+#
+# ```puppet
+# $data.step(<n>) |$parameter| { <PUPPET CODE BLOCK> }
+# ```
+#
+# or
+#
+# ```puppet
+# $stepped_data = $data.step(<n>)
+# ```
+#
+# or
+#
+# ```puppet
+# step($data, <n>) |$parameter| { <PUPPET CODE BLOCK> }
+# ```
+#
+# or
+#
+# ```puppet
+# $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.
+#
+# ```puppet
+# # 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
+#
+# ```puppet
+# # 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
 #