puppet 4.1.0 → 4.10.0

data/lib/puppet/functions/map.rb

@@ -1,33 +1,68 @@
-# Applies a parameterized block to each element in a sequence of entries from the first
-# argument and returns an array with the result of each invocation of the parameterized block.
+# Applies a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# to every value in a data structure and returns an array containing the results.
 #
-# This function takes two mandatory arguments: the first should be an Array, Hash, or of Enumerable type
-# (integer, Integer range, or String), and the second a parameterized block as produced by the puppet syntax:
+# This function takes two mandatory arguments, in this order:
 #
-#       $a.map |$x| { ... }
-#       map($a) |$x| { ... }
+# 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 can
+# request one or two parameters.
 #
-# When the first argument `$a` is an Array or of enumerable type, the block is called with each entry in turn.
-# When the first argument is a hash the entry is an array with `[key, value]`.
+# @example Using the `map` function
 #
-# @example Using map with two arguments
+# `$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
 #
-#      # Turns hash into array of values
-#      $a.map |$x|{ $x[1] }
+# or
 #
-#      # Turns hash into array of keys
-#      $a.map |$x| { $x[0] }
+# `$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
 #
-# When using a block with 2 parameters, the element's index (starting from 0) for an array, and the key for a hash
-# is given to the block's first parameter, and the value is given to the block's second parameter.args.
+# When the first argument (`$data` in the above example) is an array, Puppet passes each
+# value in turn to the lambda.
 #
-# @example Using map with two arguments
+# @example Using the `map` function with an array and a one-parameter lambda
 #
-#      # Turns hash into array of values
-#      $a.map |$key,$val|{ $val }
+# ~~~ puppet
+# # For the array $data, return an array containing each value multiplied by 10
+# $data = [1,2,3]
+# $transformed_data = $data.map |$items| { $items * 10 }
+# # $transformed_data contains [10,20,30]
+# ~~~
 #
-#      # Turns hash into array of keys
-#      $a.map |$key,$val|{ $key }
+# When the first argument is a hash, Puppet passes each key and value pair to the lambda
+# as an array in the form `[key, value]`.
+#
+# @example Using the `map` function with a hash and a one-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, return an array containing the keys
+# $data = {'a'=>1,'b'=>2,'c'=>3}
+# $transformed_data = $data.map |$items| { $items[0] }
+# # $transformed_data contains ['a','b','c']
+# ~~~
+#
+# When the first argument is an array and the lambda has two parameters, Puppet passes the
+# array's indexes (enumerated from 0) in the first parameter and its values in the second
+# parameter.
+#
+# @example Using the `map` function with an array and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the array $data, return an array containing the indexes
+# $data = [1,2,3]
+# $transformed_data = $data.map |$index,$value| { $index }
+# # $transformed_data contains [0,1,2]
+# ~~~
+#
+# When the first argument is a hash, Puppet passes its keys to the first parameter and its
+# values to the second parameter.
+#
+# @example Using the `map` function with a hash and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, return an array containing each value
+# $data = {'a'=>1,'b'=>2,'c'=>3}
+# $transformed_data = $data.map |$key,$value| { $value }
+# # $transformed_data contains [1,2,3]
+# ~~~
 #
 # @since 4.0.0
 #
@@ -43,12 +78,12 @@ Puppet::Functions.create_function(:map) do
   end
 
   dispatch :map_Enumerable_2 do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[2,2]', :block
   end
 
   dispatch :map_Enumerable_1 do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[1,1]', :block
   end
 
@@ -57,13 +92,13 @@ Puppet::Functions.create_function(:map) do
   end
 
   def map_Hash_2(hash)
-      hash.map {|x, y| yield(x, y) }
+    hash.map {|x, y| yield(x, y) }
   end
 
   def map_Enumerable_1(enumerable)
     result = []
     index = 0
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     begin
       loop { result << yield(enum.next) }
     rescue StopIteration
@@ -74,7 +109,7 @@ Puppet::Functions.create_function(:map) do
   def map_Enumerable_2(enumerable)
     result = []
     index = 0
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     begin
       loop do
         result << yield(index, enum.next)
@@ -84,12 +119,4 @@ Puppet::Functions.create_function(:map) do
     end
     result
   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/match.rb

@@ -1,19 +1,37 @@
-# Returns the match result of matching a String or Array[String] with one of:
+# Matches a regular expression against a string and returns an array containing the match
+# and any matched capturing groups.
 #
-# * Regexp
-# * String - transformed to a Regexp
-# * Pattern type
-# * Regexp type
+# The first argument is a string or array of strings. The second argument is either a
+# regular expression, regular expression represented as a string, or Regex or Pattern
+# data type that the function matches against the first argument.
 #
-# Returns An Array with the entire match at index 0, and each subsequent submatch at index 1-n.
-# If there was no match, nil (ie. undef) is returned. If the value to match is an Array, a array
-# with mapped match results is returned.
+# The returned array contains the entire match at index 0, and each captured group at
+# subsequent index values. If the value or expression being matched is an array, the
+# function returns an array with mapped match results.
 #
-# @example matching
-#   "abc123".match(/([a-z]+)[1-9]+/)  # => ["abc"]
-#   "abc123".match(/([a-z]+)([1-9]+)/)  # => ["abc", "123"]
+# If the function doesn't find a match, it returns 'undef'.
+#
+# @example Matching a regular expression in a string
+#
+# ~~~ ruby
+# $matches = "abc123".match(/[a-z]+[1-9]+/)
+# # $matches contains [abc123]
+# ~~~
+#
+# @example Matching a regular expressions with grouping captures in a string
+#
+# ~~~ ruby
+# $matches = "abc123".match(/([a-z]+)([1-9]+)/)
+# # $matches contains [abc123, abc, 123]
+# ~~~
+#
+# @example Matching a regular expression with grouping captures in an array of strings
+#
+# ~~~ ruby
+# $matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
+# # $matches contains [[abc123, abc, 123], [def456, def, 456]]
+# ~~~
 #
-# See the documentation for "The Puppet Type System" for more information about types.
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:match) do

data/lib/puppet/functions/new.rb

@@ -0,0 +1,31 @@
+# Returns a new instance of a data type.
+# (The documentation is maintained in the corresponding 3.x stub)
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:new, Puppet::Functions::InternalFunction) do
+
+  dispatch :new_instance do
+    scope_param
+    param          'Type', :type
+    repeated_param 'Any',  :args
+    optional_block_param
+  end
+
+  def new_instance(scope, t, *args)
+    result = catch :undefined_value do
+      new_function_for_type(t, scope).call(scope, *args)
+    end
+    assert_type(t, result)
+    return block_given? ? yield(result) : result
+  end
+
+  def new_function_for_type(t, scope)
+    @new_function_cache ||= Hash.new() {|hsh, key| hsh[key] = key.new_function(loader).new(scope, loader) }
+    @new_function_cache[t]
+  end
+
+  def assert_type(type, value)
+    Puppet::Pops::Types::TypeAsserter.assert_instance_of(['Converted value from %s.new()', type], type, value)
+  end
+end

data/lib/puppet/functions/next.rb

@@ -0,0 +1,23 @@
+# Make iteration continue with the next value optionally given a value for this iteration.
+# If a value is not given it defaults to `undef`
+#
+# @since 4.7.0
+#
+Puppet::Functions.create_function(:next) do
+  dispatch :next_impl do
+    optional_param 'Any', :value
+  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
+
+    exc = Puppet::Pops::Evaluator::Next.new(value, file, line)
+    raise exc
+  end
+end

data/lib/puppet/functions/notice.rb

@@ -0,0 +1,14 @@
+# Log 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]
+  dispatch :notice do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def notice(scope, *values)
+    Puppet::Util::Log.log_func(scope, :notice, values)
+  end
+end

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

@@ -1,54 +1,51 @@
 # Perform regexp replacement on a string or array of strings.
 #
-# @example
-#
-# Get the third octet from the node's IP address:
-#
-#   $i3 = regsubst($ipaddress,'^(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$','\\3')
-#
-# Put angle brackets around each octet in the node's IP address:
-#
-#   $x = regsubst($ipaddress, /([0-9]+)/, '<\\1>', 'G')
-#
-# @param target [Array[String]|String]
+# @param target [String, Array[String]]
 #      The string or array of strings to operate on.  If an array, the replacement will be
 #      performed on each of the elements in the array, and the return value will be an array.
-# @param regexp [String|Regexp|Type[Regexp]]
+# @param pattern [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.
-# @param flags [String]
+#      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 [Optional[Pattern[/^[GEIM]*$/]], Pattern[/^G?$/]]
 #      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):
 #        - *E*         Extended regexps
 #        - *I*         Ignore case in regexps
 #        - *M*         Multiline regexps
 #        - *G*         Global replacement; all occurrences of the regexp in each target string will be replaced.  Without this, only the first occurrence will be replaced.
-# @param encoding [String]
+# @param encoding [Enum['N','E','S','U']]
 #      Optional. How to handle multibyte characters when compiling the regexp (must not be used when pattern is a
 #      precompiled regexp). A single-character string with the following values:
 #        - *N*         None
 #        - *E*         EUC
 #        - *S*         SJIS
 #        - *U*         UTF-8
-# @return [Array[String]|String] The result of the substitution. Result type is the same as for the target parameter.
+# @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')
+#
+# @example Put angle brackets around each octet in the node's IP address:
+#     $x = regsubst($ipaddress, /([0-9]+)/, '<\\1>', 'G')
 #
 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)

data/lib/puppet/functions/require.rb

@@ -0,0 +1,37 @@
+# Requires the specified classes
+# For documentation see the 3.x function stub
+Puppet::Functions.create_function(:require, Puppet::Functions::InternalFunction) do
+  dispatch :require_impl do
+    scope_param
+    # The function supports what the type system sees as Ruby runtime objects, and
+    # they cannot be parameterized to find what is actually valid instances.
+    # The validation is instead done in the function body itself via a call to
+    # `transform_and_assert_classnames` on the calling scope.
+    required_repeated_param 'Any', :names
+  end
+
+  def require_impl(scope, *classes)
+    # Make call patterns uniform and protected against nested arrays, also make
+    # names absolute if so desired.
+    classes = scope.transform_and_assert_classnames(classes.flatten)
+
+    result = classes.map {|name| Puppet::Pops::Types::TypeFactory.host_class(name) }
+
+    # 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).
+    #
+    scope.compiler.evaluate_classes(classes, scope, false)
+    krt = scope.environment.known_resource_types
+
+    classes.each do |klass|
+      # lookup the class in the scopes
+      klass = (classobj = krt.find_hostclass(klass)) ? classobj.name : nil
+      raise Puppet::ParseError.new("Could not find class #{klass}") unless klass
+      ref = Puppet::Resource.new(:class, klass)
+      resource = scope.resource
+      resource.set_parameter(:require, [resource[:require]].flatten.compact << ref)
+    end
+    result
+  end
+end

data/lib/puppet/functions/return.rb

@@ -0,0 +1,22 @@
+# Make iteration continue with the next value optionally given a value for this iteration.
+# If a value is not given it defaults to `undef`
+#
+# @since 4.7.0
+#
+Puppet::Functions.create_function(:return, Puppet::Functions::InternalFunction) do
+  dispatch :return_impl do
+    optional_param 'Any', :value
+  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
+
+    raise Puppet::Pops::Evaluator::Return.new(value, file, line)
+  end
+end

data/lib/puppet/functions/reverse_each.rb

@@ -0,0 +1,25 @@
+# Reverses the order of the elements of something that is iterable.
+# (Documentation in 3.x stub)
+#
+# @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