puppet 4.3.0 → 4.4.0

data/lib/puppet/functions/reduce.rb

@@ -6,7 +6,7 @@
 #
 # This function takes two mandatory arguments, in this order:
 #
-# 1. An array or hash the function will iterate over.
+# 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.
@@ -99,31 +99,23 @@
 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/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

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/type.rb

@@ -0,0 +1,70 @@
+# Returns the data type of a given value with a given degree of generality.
+#
+# @example Using `type()`
+#
+# ~~~ puppet
+# notice type(42) =~ Type[Integer]
+# ~~~
+#
+# Would notice true
+#
+# By default, the best possible inference is made where all details are retained.
+# This is good when the type is used for futher type calculations but is overwhelmingly
+# rich i information if it is used in a error message.
+#
+# The optional argument `inference_method` may be given as (from lowest to highest fidelity):
+#
+# * ´generalized` - reduces to common type and drops size constraints
+# * `reduced` - reduces to common type in collections
+# * `detailed` - (defaut) all details about inferred types is retained
+#
+# @example Using `type()` with different qualities:
+#
+# ~~~ puppet
+# notice type([3.14, 42], generalized)
+# notice type([3.14, 42], reduced)
+# notice type([3.14, 42], detailed)
+# notice type([3.14, 42])
+# ~~~
+#
+# Would notice the four values:
+#
+# 1. 'Array[Numeric]'
+# 2. 'Array[Numeric, 2, 2]'
+# 3. 'Tuple[Float[3.14], Integer[42,42]]]'
+# 4. 'Tuple[Float[3.14], Integer[42,42]]]'
+#
+# @param value [Any] - the value for which data type is returned
+# @param inference_type[Enum[generalized, reduced, detailed]] inference_type
+# @returns [Type] - the inferred type
+#
+# @since 4.4.0
+#
+Puppet::Functions.create_function(:type) do
+  dispatch :type_detailed do
+    param 'Any', :value
+    optional_param 'Enum[detailed]', :inference_method
+  end
+
+  dispatch :type_parameterized do
+    param 'Any', :value
+    param 'Enum[reduced]', :inference_method
+  end
+
+  dispatch :type_generalized do
+    param 'Any', :value
+    param 'Enum[generalized]', :inference_method
+  end
+
+  def type_detailed(value, _ = nil)
+    Puppet::Pops::Types::TypeCalculator.infer_set(value)
+  end
+
+  def type_parameterized(value, _)
+    Puppet::Pops::Types::TypeCalculator.infer(value)
+  end
+
+  def type_generalized(value, _)
+    Puppet::Pops::Types::TypeCalculator.infer(value).generalize
+  end
+end

data/lib/puppet/functions.rb

@@ -153,6 +153,28 @@ module Puppet::Functions
   #
   # @api public
   def self.create_function(func_name, function_base = Function, &block)
+    # Ruby < 2.1.0 does not have method on Binding, can only do eval
+    # and it will fail unless protected with an if defined? if the local
+    # variable does not exist in the block's binder.
+    #
+    loader = block.binding.eval('loader_injected_arg if defined?(loader_injected_arg)')
+    create_loaded_function(func_name, loader, function_base, &block)
+  end
+
+  # Creates a function in, or in a local loader under the given loader.
+  # This method should only be used when manually creating functions 
+  # for the sake of testing. Functions that are autoloaded should
+  # always use the `create_function` method and the autoloader will supply
+  # the correct loader.
+  #
+  # @param func_name [String, Symbol] a simple or qualified function name
+  # @param loader [Puppet::Pops::Loaders::Loader] the loader loading the function
+  # @param block [Proc] the block that defines the methods and dispatch of the
+  #   Function to create
+  # @return [Class<Function>] the newly created Function class
+  #
+  # @api public
+  def self.create_loaded_function(func_name, loader, function_base = Function, &block)
     if function_base.ancestors.none? { |s| s == Puppet::Pops::Functions::Function }
       raise ArgumentError, "Functions must be based on Puppet::Pops::Functions::Function. Got #{function_base}"
     end
@@ -162,7 +184,12 @@ module Puppet::Functions
     # The idea being that it is garbage collected when there are no more
     # references to it.
     #
-    the_class = Class.new(function_base, &block)
+    # (Do not give the class the block here, as instance variables should be set first)
+    the_class = Class.new(function_base)
+
+    unless loader.nil?
+      the_class.instance_variable_set(:'@loader', loader.private_loader)
+    end
 
     # Make the anonymous class appear to have the class-name <func_name>
     # Even if this class is not bound to such a symbol in a global ruby scope and
@@ -175,11 +202,20 @@ module Puppet::Functions
     #
     the_class.instance_eval do
       @func_name = func_name
+
       def name
         @func_name
       end
+
+      def loader
+        @loader
+      end
     end
 
+    # The given block can now be evaluated and have access to name and loader
+    #
+    the_class.class_eval(&block)
+
     # Automatically create an object dispatcher based on introspection if the
     # loaded user code did not define any dispatchers. Fail if function name
     # does not match a given method name in user code.
@@ -238,7 +274,7 @@ module Puppet::Functions
     def self.builder
       @type_parser ||= Puppet::Pops::Types::TypeParser.new
       @all_callables ||= Puppet::Pops::Types::TypeFactory.all_callables
-      DispatcherBuilder.new(dispatcher, @type_parser, @all_callables)
+      DispatcherBuilder.new(dispatcher, @type_parser, @all_callables, loader)
     end
 
     # Dispatch any calls that match the signature to the provided method name.
@@ -269,11 +305,14 @@ module Puppet::Functions
   #
   # @api public
   class DispatcherBuilder
+    attr_reader :loader
+
     # @api private
-    def initialize(dispatcher, type_parser, all_callables)
+    def initialize(dispatcher, type_parser, all_callables, loader)
       @type_parser = type_parser
       @all_callables = all_callables
       @dispatcher = dispatcher
+      @loader = loader
     end
 
     # Defines a required positional parameter with _type_ and _name_.
@@ -356,7 +395,7 @@ module Puppet::Functions
         name = type_and_name[0]
       when 2
         type_string, name = type_and_name
-        type = @type_parser.parse(type_string)
+        type = @type_parser.parse(type_string, loader)
       else
         raise ArgumentError, "block_param accepts max 2 arguments (type, name), got #{type_and_name.size}."
       end
@@ -441,7 +480,7 @@ module Puppet::Functions
     # @api private
     def create_callable(types, block_type, from, to)
       mapped_types = types.map do |t|
-        @type_parser.parse(t)
+        @type_parser.parse(t, loader)
       end
 
       if from != to
@@ -496,7 +535,7 @@ module Puppet::Functions
     def self.builder
       @type_parser ||= Puppet::Pops::Types::TypeParser.new
       @all_callables ||= Puppet::Pops::Types::TypeFactory.all_callables
-      InternalDispatchBuilder.new(dispatcher, @type_parser, @all_callables)
+      InternalDispatchBuilder.new(dispatcher, @type_parser, @all_callables, loader)
     end
 
     # Defines class level injected attribute with reader method

data/lib/puppet/graph/rb_tree_map.rb

@@ -26,7 +26,7 @@
 # iterated over in order. This is useful for many datasets.
 #
 # The implementation is adapted from Robert Sedgewick's Left Leaning Red-Black Tree implementation,
-# which can be found at http://www.cs.princeton.edu/~rs/talks/LLRB/Java/RedBlackBST.java
+# which can be found at https://www.cs.princeton.edu/~rs/talks/LLRB/Java/RedBlackBST.java
 #
 # Most methods have O(log n) complexity.