puppet 3.7.0-x64-mingw32

data/lib/puppet/functions/assert_type.rb

@@ -0,0 +1,59 @@
+# Returns the given value if it is an instance of the given type, and raises an error otherwise.
+# Optionally, if a block is given (accepting two parameters), it will be called instead of raising
+# an error. This to enable giving the user richer feedback, or to supply a default value.
+#
+# @example how to assert type
+#   # assert that `$b` is a non empty `String` and assign to `$a`
+#   $a = assert_type(String[1], $b)
+#
+# @example using custom error message
+#   $a = assert_type(String[1], $b) |$expected, $actual| { fail("The name cannot be empty") }
+#
+# @example using a warning and a default
+#   $a = assert_type(String[1], $b) |$expected, $actual| { warning("Name is empty, using default") 'anonymous' }
+#
+# See the documentation for "The Puppet Type System" for more information about types.
+#
+Puppet::Functions.create_function(:assert_type) do
+  dispatch :assert_type do
+    param 'Type', 'type'
+    param 'Any', 'value'
+    optional_block_param 'Callable[Type, Type]', 'block'
+  end
+
+  dispatch :assert_type_s do
+    param 'String', 'type_string'
+    param 'Any', 'value'
+    optional_block_param 'Callable[Type, Type]', 'block'
+  end
+
+  # @param type [Type] the type the value must be an instance of
+  # @param value [Object] the value to assert
+  #
+  def assert_type(type, value, block=nil)
+    unless Puppet::Pops::Types::TypeCalculator.instance?(type,value)
+      inferred_type = Puppet::Pops::Types::TypeCalculator.infer(value)
+      if block
+        # Give the inferred type to allow richer comparisson in the given block (if generalized
+        # information is lost).
+        #
+        value = block.call(nil, type, inferred_type)
+      else
+        # Do not give all the details - i.e. format as Integer, instead of Integer[n, n] for exact value, which
+        # is just confusing. (OTOH: may need to revisit, or provide a better "type diff" output.
+        #
+        actual = Puppet::Pops::Types::TypeCalculator.generalize!(inferred_type)
+        raise Puppet::ParseError, "assert_type(): Expected type #{type} does not match actual: #{actual}"
+      end
+    end
+    value
+  end
+
+  # @param type_string [String] the type the value must be an instance of given in String form
+  # @param value [Object] the value to assert
+  #
+  def assert_type_s(type_string, value)
+    t = Puppet::Pops::Types::TypeParser.new.parse(type_string)
+    assert_type(t, value)
+  end
+end

data/lib/puppet/functions/each.rb

@@ -0,0 +1,111 @@
+#  Applies a parameterized block to each element in a sequence of selected entries from the first
+#  argument and returns the first argument.
+#
+# This function takes two mandatory arguments: the first should be an Array or a Hash or something that is
+# of enumerable type (integer, Integer range, or String), and the second
+# a parameterized block as produced by the puppet syntax:
+#
+#       $a.each |$x| { ... }
+#       each($a) |$x| { ... }
+#
+# When the first argument is an Array (or of enumerable type other than Hash), the parameterized block
+# should define one or two block parameters.
+# For each application of the block, the next element from the array is selected, and it is passed to
+# the block if the block has one parameter. If the block has two parameters, the first is the elements
+# index, and the second the value. The index starts from 0.
+#
+#       $a.each |$index, $value| { ... }
+#       each($a) |$index, $value| { ... }
+#
+# When the first argument is a Hash, the parameterized block should define one or two parameters.
+# When one parameter is defined, the iteration is performed with each entry as an array of `[key, value]`,
+# and when two parameters are defined the iteration is performed with key and value.
+#
+#       $a.each |$entry|       { ..."key ${$entry[0]}, value ${$entry[1]}" }
+#       $a.each |$key, $value| { ..."key ${key}, value ${value}" }
+#
+# @example using each
+#
+#       [1,2,3].each |$val| { ... }                       # 1, 2, 3
+#       [5,6,7].each |$index, $val| { ... }               # (0, 5), (1, 6), (2, 7)
+#       {a=>1, b=>2, c=>3}].each |$val| { ... }           # ['a', 1], ['b', 2], ['c', 3]
+#       {a=>1, b=>2, c=>3}.each |$key, $val| { ... }      # ('a', 1), ('b', 2), ('c', 3)
+#       Integer[ 10, 20 ].each |$index, $value| { ... }   # (0, 10), (1, 11) ...
+#       "hello".each |$char| { ... }                      # 'h', 'e', 'l', 'l', 'o'
+#       3.each |$number| { ... }                          # 0, 1, 2
+#
+# @since 3.2 for Array and Hash
+# @since 3.5 for other enumerables
+# @note requires `parser = future`
+#
+Puppet::Functions.create_function(:each) do
+  dispatch :foreach_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    required_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :foreach_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    required_block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :foreach_Enumerable_2 do
+    param 'Any', :enumerable
+    required_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :foreach_Enumerable_1 do
+    param 'Any', :enumerable
+    required_block_param 'Callable[1,1]', :block
+  end
+
+  def foreach_Hash_1(hash, pblock)
+    enumerator = hash.each_pair
+    hash.size.times do
+      pblock.call(nil, enumerator.next)
+    end
+    # produces the receiver
+    hash
+  end
+
+  def foreach_Hash_2(hash, pblock)
+    enumerator = hash.each_pair
+    hash.size.times do
+      pblock.call(nil, *enumerator.next)
+    end
+    # produces the receiver
+    hash
+  end
+
+  def foreach_Enumerable_1(enumerable, pblock)
+    enum = asserted_enumerable(enumerable)
+      begin
+        loop { pblock.call(nil, enum.next) }
+      rescue StopIteration
+      end
+    # produces the receiver
+    enumerable
+  end
+
+  def foreach_Enumerable_2(enumerable, pblock)
+    enum = asserted_enumerable(enumerable)
+    index = 0
+    begin
+      loop do
+        pblock.call(nil, index, enum.next)
+        index += 1
+      end
+    rescue StopIteration
+    end
+    # produces the receiver
+    enumerable
+  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/epp.rb

@@ -0,0 +1,54 @@
+# Evaluates an Embedded Puppet Template (EPP) file and returns the rendered text result as a String.
+#
+# The first argument to this function should be a `<MODULE NAME>/<TEMPLATE FILE>`
+# reference, which will load `<TEMPLATE FILE>` from a module's `templates`
+# directory. (For example, the reference `apache/vhost.conf.epp` will load the
+# file `<MODULES DIRECTORY>/apache/templates/vhost.conf.epp`.)
+#
+# The second argument is optional; if present, it should be a hash containing parameters for the
+# template. (See below.)
+#
+# EPP supports the following tags:
+#
+# * `<%= puppet expression %>` - This tag renders the value of the expression it contains.
+# * `<% puppet expression(s) %>` - This tag will execute the expression(s) it contains, but renders nothing.
+# * `<%# comment %>` - The tag and its content renders nothing.
+# * `<%%` or `%%>` - Renders a literal `<%` or `%>` respectively.
+# * `<%-` - Same as `<%` but suppresses any leading whitespace.
+# * `-%>` - Same as `%>` but suppresses any trailing whitespace on the same line (including line break).
+# * `<%- |parameters| -%>` - When placed as the first tag declares the template's parameters.
+#
+# File based EPP supports the following visibilities of variables in scope:
+#
+# * Global scope (i.e. top + node scopes) - global scope is always visible
+# * Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
+# * Global + declared parameters - if the EPP declares parameters, given argument names must match
+#
+# EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example,
+# `<%- |$x, $y, $z = 'unicorn'| -%>` when placed first in the EPP text declares that the parameters `x` and `y` must be
+# given as template arguments when calling `inline_epp`, and that `z` if not given as a template argument
+# defaults to `'unicorn'`. Template parameters are available as variables, e.g.arguments `$x`, `$y` and `$z` in the example.
+# Note that `<%-` must be used or any leading whitespace will be interpreted as text
+#
+# Arguments are passed to the template by calling `epp` with a Hash as the last argument, where parameters
+# are bound to values, e.g. `epp('...', {'x'=>10, 'y'=>20})`. Excess arguments may be given
+# (i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all.
+# Template parameters shadow variables in outer scopes. File based epp does never have access to variables in the
+# scope where the `epp` function is called from.
+#
+# @see function inline_epp for examples of EPP
+# @since 3.5
+# @note Requires Future Parser
+Puppet::Functions.create_function(:epp, Puppet::Functions::InternalFunction) do
+
+  dispatch :epp do
+    scope_param()
+    param 'String', 'path'
+    param 'Hash[Pattern[/^\w+$/], Any]', 'parameters'
+    arg_count(1, 2)
+  end
+
+  def epp(scope, path, parameters = nil)
+    Puppet::Pops::Evaluator::EppEvaluator.epp(scope, path, scope.compiler.environment, parameters)
+  end
+end

data/lib/puppet/functions/filter.rb

@@ -0,0 +1,113 @@
+# Applies a parameterized block to each element in a sequence of entries from the first
+# argument and returns an array or hash (same type as left operand for array/hash, and array for
+# other enumerable types) with the entries for which the block evaluates to `true`.
+#
+# This function takes two mandatory arguments: the first should be an Array, a Hash, or an
+# Enumerable object (integer, Integer range, or String),
+# and the second a parameterized block as produced by the puppet syntax:
+#
+#       $a.filter |$x| { ... }
+#       filter($a) |$x| { ... }
+#
+# When the first argument is something other than a Hash, 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 filter with one parameter
+#
+#       # selects all that end with berry
+#       $a = ["raspberry", "blueberry", "orange"]
+#       $a.filter |$x| { $x =~ /berry$/ }          # rasberry, blueberry
+#
+# If the block defines two parameters, they will be set to `index, value` (with index starting at 0) for all
+# enumerables except Hash, and to `key, value` for a Hash.
+#
+# @example Using filter with two parameters
+#
+#      # selects all that end with 'berry' at an even numbered index
+#      $a = ["raspberry", "blueberry", "orange"]
+#      $a.filter |$index, $x| { $index % 2 == 0 and $x =~ /berry$/ } # raspberry
+#
+#      # selects all that end with 'berry' and value >= 1
+#      $a = {"raspberry"=>0, "blueberry"=>1, "orange"=>1}
+#      $a.filter |$key, $x| { $x =~ /berry$/ and $x >= 1 } # blueberry
+#
+# @since 3.4 for Array and Hash
+# @since 3.5 for other enumerables
+# @note requires `parser = future`
+#
+Puppet::Functions.create_function(:filter) do
+  dispatch :filter_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    required_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :filter_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    required_block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :filter_Enumerable_2 do
+    param 'Any', :enumerable
+    required_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :filter_Enumerable_1 do
+    param 'Any', :enumerable
+    required_block_param 'Callable[1,1]', :block
+  end
+
+  def filter_Hash_1(hash, pblock)
+    result = hash.select {|x, y| pblock.call(self, [x, y]) }
+    # Ruby 1.8.7 returns Array
+    result = Hash[result] unless result.is_a? Hash
+    result
+  end
+
+  def filter_Hash_2(hash, pblock)
+    result = hash.select {|x, y| pblock.call(self, x, y) }
+    # Ruby 1.8.7 returns Array
+    result = Hash[result] unless result.is_a? Hash
+    result
+  end
+
+  def filter_Enumerable_1(enumerable, pblock)
+    result = []
+    index = 0
+    enum = asserted_enumerable(enumerable)
+    begin
+      loop do
+        it = enum.next
+        if pblock.call(nil, it) == true
+          result << it
+        end
+      end
+    rescue StopIteration
+    end
+    result
+  end
+
+  def filter_Enumerable_2(enumerable, pblock)
+    result = []
+    index = 0
+    enum = asserted_enumerable(enumerable)
+    begin
+      loop do
+        it = enum.next
+        if pblock.call(nil, index, it) == true
+          result << it
+        end
+        index += 1
+      end
+    rescue StopIteration
+    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/import.rb

@@ -0,0 +1,7 @@
+# The import function raises an error when called to inform the user that import is no longer supported.
+#
+Puppet::Functions.create_function(:import) do
+  def import(*args)
+    raise Puppet::Pops::SemanticError.new(Puppet::Pops::Issues::DISCONTINUED_IMPORT)
+  end
+end

data/lib/puppet/functions/inline_epp.rb

@@ -0,0 +1,88 @@
+# Evaluates an Embedded Puppet Template (EPP) string and returns the rendered text result as a String.
+#
+# EPP support the following tags:
+#
+# * `<%= puppet expression %>` - This tag renders the value of the expression it contains.
+# * `<% puppet expression(s) %>` - This tag will execute the expression(s) it contains, but renders nothing.
+# * `<%# comment %>` - The tag and its content renders nothing.
+# * `<%%` or `%%>` - Renders a literal `<%` or `%>` respectively.
+# * `<%-` - Same as `<%` but suppresses any leading whitespace.
+# * `-%>` - Same as `%>` but suppresses any trailing whitespace on the same line (including line break).
+# * `<%- |parameters| -%>` - When placed as the first tag declares the template's parameters.
+#
+# Inline EPP supports the following visibilities of variables in scope which depends on how EPP parameters
+# are used - see further below:
+#
+# * Global scope (i.e. top + node scopes) - global scope is always visible
+# * Global + Enclosing scope - if the EPP template does not declare parameters, and no arguments are given
+# * Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
+# * Global + declared parameters - if the EPP declares parameters, given argument names must match
+#
+# EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example,
+# `<%- |$x, $y, $z='unicorn'| -%>` when placed first in the EPP text declares that the parameters `x` and `y` must be
+# given as template arguments when calling `inline_epp`, and that `z` if not given as a template argument
+# defaults to `'unicorn'`. Template parameters are available as variables, e.g.arguments `$x`, `$y` and `$z` in the example.
+# Note that `<%-` must be used or any leading whitespace will be interpreted as text
+#
+# Arguments are passed to the template by calling `inline_epp` with a Hash as the last argument, where parameters
+# are bound to values, e.g. `inline_epp('...', {'x'=>10, 'y'=>20})`. Excess arguments may be given
+# (i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all.
+# Template parameters shadow variables in outer scopes.
+#
+# Note: An inline template is best stated using a single-quoted string, or a heredoc since a double-quoted string
+# is subject to expression interpolation before the string is parsed as an EPP template. Here are examples
+# (using heredoc to define the EPP text):
+#
+# @example Various Examples using `inline_epp`
+#
+#     # produces 'Hello local variable world!'
+#     $x ='local variable'
+#     inline_epptemplate(@(END:epp))
+#     <%- |$x| -%>
+#     Hello <%= $x %> world!
+#     END
+# 
+#     # produces 'Hello given argument world!'
+#     $x ='local variable world'
+#     inline_epptemplate(@(END:epp), { x =>'given argument'})
+#     <%- |$x| -%>
+#     Hello <%= $x %> world!
+#     END
+#
+#     # produces 'Hello given argument world!'
+#     $x ='local variable world'
+#     inline_epptemplate(@(END:epp), { x =>'given argument'})
+#     <%- |$x| -%>
+#     Hello <%= $x %>!
+#     END
+#
+#     # results in error, missing value for y
+#     $x ='local variable world'
+#     inline_epptemplate(@(END:epp), { x =>'given argument'})
+#     <%- |$x, $y| -%>
+#     Hello <%= $x %>!
+#     END
+#
+#     # Produces 'Hello given argument planet'
+#     $x ='local variable world'
+#     inline_epptemplate(@(END:epp), { x =>'given argument'})
+#     <%- |$x, $y=planet| -%>
+#     Hello <%= $x %> <%= $y %>!
+#     END
+#
+# @since 3.5
+# @note Requires Future Parser
+#
+Puppet::Functions.create_function(:inline_epp, Puppet::Functions::InternalFunction) do
+
+  dispatch :inline_epp do
+    scope_param()
+    param 'String', 'template'
+    param 'Hash[Pattern[/^\w+$/], Any]', 'parameters'
+    arg_count(1, 2)
+  end
+
+  def inline_epp(scope, template, parameters = nil)
+    Puppet::Pops::Evaluator::EppEvaluator.inline_epp(scope, template, parameters)
+  end
+end

data/lib/puppet/functions/map.rb

@@ -0,0 +1,97 @@
+# 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.
+#
+# 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:
+#
+#       $a.map |$x| { ... }
+#       map($a) |$x| { ... }
+#
+# 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 map with two arguments
+#
+#      # Turns hash into array of values
+#      $a.map |$x|{ $x[1] }
+#
+#      # Turns hash into array of keys
+#      $a.map |$x| { $x[0] }
+#
+# 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.
+#
+# @example Using map with two arguments
+#
+#      # Turns hash into array of values
+#      $a.map |$key,$val|{ $val }
+#
+#      # Turns hash into array of keys
+#      $a.map |$key,$val|{ $key }
+#
+# @since 3.4 for Array and Hash
+# @since 3.5 for other enumerables, and support for blocks with 2 parameters
+# @note requires `parser = future`
+#
+Puppet::Functions.create_function(:map) do
+  dispatch :map_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    required_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :map_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    required_block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :map_Enumerable_2 do
+    param 'Any', :enumerable
+    required_block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :map_Enumerable_1 do
+    param 'Any', :enumerable
+    required_block_param 'Callable[1,1]', :block
+  end
+
+  def map_Hash_1(hash, pblock)
+    hash.map {|x, y| pblock.call(nil, [x, y]) }
+  end
+
+  def map_Hash_2(hash, pblock)
+      hash.map {|x, y| pblock.call(nil, x, y) }
+  end
+
+  def map_Enumerable_1(enumerable, pblock)
+    result = []
+    index = 0
+    enum = asserted_enumerable(enumerable)
+    begin
+      loop { result << pblock.call(nil, enum.next) }
+    rescue StopIteration
+    end
+    result
+  end
+
+  def map_Enumerable_2(enumerable, pblock)
+    result = []
+    index = 0
+    enum = asserted_enumerable(enumerable)
+    begin
+      loop do
+        result << pblock.call(nil, index, enum.next)
+        index = index +1
+      end
+    rescue StopIteration
+    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