puppet 4.0.0 → 4.9.1

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

@@ -0,0 +1,38 @@
+Puppet::Parser::Functions::newfunction(
+  :next,
+  :arity => -2,
+  :doc => <<-DOC
+Immediately returns the given optional value from a block (lambda), function, class body or user defined type body.
+If a value is not given, an `undef` value is returned. This function does not return to the immediate caller.
+
+The signal produced to return a value bubbles up through
+the call stack until reaching a code block (lambda), function, class definition or
+definition of a user defined type at which point the value given to the function will
+be produced as the result of that body of code. An error is raised
+if the signal to return a value reaches the end of the call stack.
+
+**Example:** Using `next` in `each`
+
+```puppet
+$data = [1,2,3]
+$data.each |$x| { if $x == 2 { next() } notice $x }
+```
+
+Would notice the values `1` and `3`
+
+**Example:** Using `next` to produce a value
+
+If logic consists of deeply nested conditionals it may be complicated to get out of the innermost conditional.
+A call to `next` can then simplify the logic. This example however, only shows the principle.
+```puppet
+$data = [1,2,3]
+notice $data.map |$x| { if $x == 2 { next($x*100) }; $x*10 }
+```
+Would notice the value `[10, 200, 30]`
+
+* Also see functions `return` and `break`
+* Since 4.8.0
+DOC
+) do |args|
+  Error.is4x('next')
+end

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

@@ -3,67 +3,104 @@ 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"])
+  Error.is4x('reduce')
 end

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

@@ -24,7 +24,8 @@
 # other dealings in this Software without prior written authorization
 # from Thomas Bellman.
 
-Puppet::Parser::Functions::newfunction(
+module Puppet::Parser::Functions
+  newfunction(
   :regsubst, :type => :rvalue,
   :arity => -4,
 
@@ -56,5 +57,6 @@ Put angle brackets around each octet in the node's IP address:
 
     $x = regsubst($ipaddress, '([0-9]+)', '<\\1>', 'G')
 ") do |args|
-    function_fail(['regsubst() has been converted to 4x API'])
+    Error.is4x('regsubst')
+end
 end

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

@@ -33,31 +33,8 @@ you may also directly use Class and Resource Type values that are produced when
 resource and relationship expressions.
 
 - Since 4.0.0 Class and Resource types, absolute names
-") do |vals|
-  # Make call patterns uniform and protected against nested arrays, also make
-  # names absolute if so desired.
-  vals = transform_and_assert_classnames(vals.is_a?(Array) ? vals.flatten : [vals])
-
-  # This is the same as calling the include function (but faster) since it again
-  # would otherwise need to perform the optional absolute name transformation
-  # (for no reason since they are already made absolute here).
-  #
-  compiler.evaluate_classes(vals, self, false)
-
-  vals.each do |klass|
-    # lookup the class in the scopes
-    if classobj = find_hostclass(klass)
-      klass = classobj.name
-    else
-      raise Puppet::ParseError, "Could not find class #{klass}"
-    end
-
-    # This is a bit hackish, in some ways, but it's the only way
-    # to configure a dependency that will make it to the client.
-    # The 'obvious' way is just to add an edge in the catalog,
-    # but that is considered a containment edge, not a dependency
-    # edge, so it usually gets lost on the client.
-    ref = Puppet::Resource.new(:class, klass)
-    resource.set_parameter(:require, [resource[:require]].flatten.compact << ref)
-  end
+- Since 4.7.0 Returns an Array[Type[Class]] with references to the required classes
+") do |classes|
+  Puppet.warn_once(:deprecation, '3xfunction#require', "Calling function_require via the Scope class is deprecated. Use Scope#call_function instead")
+  call_function('require', classes)
 end

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

@@ -0,0 +1,71 @@
+Puppet::Parser::Functions::newfunction(
+  :return,
+  :arity => -2,
+  :doc => <<-DOC
+Immediately returns the given optional value from a function, class body or user defined type body.
+If a value is not given, an `undef` value is returned. This function does not return to the immediate caller.
+If called from within a lambda the return will return from the function evaluating the lambda.
+
+The signal produced to return a value bubbles up through
+the call stack until reaching a function, class definition or
+definition of a user defined type at which point the value given to the function will
+be produced as the result of that body of code. An error is raised
+if the signal to return a value reaches the end of the call stack.
+
+**Example:** Using `return`
+
+```puppet
+function example($x) {
+  # handle trivial cases first for better readability of
+  # what follows
+  if $x == undef or $x == [] or $x == '' {
+    return false
+  }
+  # complex logic to determine if value is true
+  true 
+}
+notice example([]) # would notice false
+notice example(42) # would notice true
+```
+
+**Example:** Using `return` in a class
+
+```puppet
+class example($x) {
+  # handle trivial cases first for better readability of
+  # what follows
+  if $x == undef or $x == [] or $x == '' {
+    # Do some default configuration of this class
+    notice 'foo'
+    return()
+  }
+  # complex logic configuring the class if something more interesting
+  # was given in $x
+  notice 'bar'
+}
+```
+
+When used like this:
+
+```puppet
+class { example: x => [] }
+```
+
+The code would notice `'foo'`, but not `'bar'`.
+
+When used like this:
+
+```puppet
+class { example: x => [some_value] }
+```
+
+The code would notice `'bar'` but not `'foo'`
+
+Note that the returned value is ignored if used in a class or user defined type.
+
+* Also see functions `return` and `break`
+* Since 4.8.0
+DOC
+) do |args|
+  Error.is4x('return')
+end

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

@@ -0,0 +1,83 @@
+Puppet::Parser::Functions::newfunction(
+  :reverse_each,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<-DOC
+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
+
+```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 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.
+
+```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
+
+DOC
+) do |args|
+  Error.is4x('reverse_each')
+end

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

@@ -5,37 +5,31 @@ Puppet::Parser::Functions::newfunction(
   :type => :rvalue,
   :arity => 2,
   :doc => <<-DOC
-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. 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.
-
-      scanf("42", "%i")[0] == 42
-
-
-When used with the future parser, an optional parameterized block may be given.
-The block 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 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:
-
-      "42".scanf("%i")
-      "42".scanf("%i") |$x| {
-        unless $x[0] =~ Integer {
-          fail "Expected a well formed integer value, got '$x[0]'"
-        }
-        $x[0]
-      }
-
-- since 3.7.4 with `parser = future`
-- since 3.7.5 with classic parser
+Scans a string and returns an array of one or more converted values based on the given format string.
+See the documentation 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 successfully scanned and transformed value.
+The scanning stops if a scan is unsuccessful, and the scanned result up to that point is returned. If there
+was no successful scan, the result is an empty array.
+
+```puppet
+"42".scanf("%i")
+```
+
+You can also optionally pass a lambda to scanf, to do additional validation or processing.
+
+```puppet
+"42".scanf("%i") |$x| {
+  unless $x[0] =~ Integer {
+    fail "Expected a well formed integer value, got '$x[0]'"
+  }
+  $x[0]
+}
+```
+
+- Since 4.0.0
 DOC
 ) do |args|
   data = args[0]

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

@@ -3,44 +3,37 @@ Puppet::Parser::Functions::newfunction(
   :type => :rvalue,
   :arity => -3,
   :doc => <<-DOC
-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
 DOC
 ) do |args|
-  function_fail(["slice() is only available when parser/evaluator future is in effect"])
+  Error.is4x('slice')
 end

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

@@ -12,7 +12,7 @@ Split a string variable into an array using the specified split regexp.
     $string     = 'v1.v2:v3.v4'
     $array_var1 = split($string, ':')
     $array_var2 = split($string, '[.]')
-    $array_var3 = 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
@@ -23,6 +23,6 @@ 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|
 
-    function_fail(['split() has been converted to 4x API'])
+    Error.is4x('split')
   end
 end

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

@@ -0,0 +1,84 @@
+Puppet::Parser::Functions::newfunction(
+  :step,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<-DOC
+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
+
+```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
+
+DOC
+) do |args|
+  Error.is4x('step')
+end