puppet 4.0.0 → 5.0.0

data/lib/puppet/functions/assert_type.rb

@@ -1,18 +1,54 @@
-# 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.
+# Returns the given value if it is of the given
+# [data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html), or
+# otherwise either raises an error or executes an optional two-parameter
+# [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html).
 #
-# @example how to assert type
-#   # assert that `$b` is a non empty `String` and assign to `$a`
-#   $a = assert_type(String[1], $b)
+# The function takes two mandatory arguments, in this order:
 #
-# @example using custom error message
-#   $a = assert_type(String[1], $b) |$expected, $actual| { fail("The name cannot be empty") }
+# 1. The expected data type.
+# 2. A value to compare against the expected data type.
 #
-# @example using a warning and a default
-#   $a = assert_type(String[1], $b) |$expected, $actual| { warning("Name is empty, using default") 'anonymous' }
+# @example Using `assert_type`
 #
-# See the documentation for "The Puppet Type System" for more information about types.
+# ~~~ puppet
+# $raw_username = 'Amy Berry'
+#
+# # Assert that $raw_username is a non-empty string and assign it to $valid_username.
+# $valid_username = assert_type(String[1], $raw_username)
+#
+# # $valid_username contains "Amy Berry".
+# # If $raw_username was an empty string or a different data type, the Puppet run would
+# # fail with an "Expected type does not match actual" error.
+# ~~~
+#
+# You can use an optional lambda to provide enhanced feedback. The lambda takes two
+# mandatory parameters, in this order:
+#
+# 1. The expected data type as described in the function's first argument.
+# 2. The actual data type of the value.
+#
+# @example Using `assert_type` with a warning and default value
+#
+# ~~~ puppet
+# $raw_username = 'Amy Berry'
+#
+# # Assert that $raw_username is a non-empty string and assign it to $valid_username.
+# # If it isn't, output a warning describing the problem and use a default value.
+# $valid_username = assert_type(String[1], $raw_username) |$expected, $actual| {
+#   warning( "The username should be \'${expected}\', not \'${actual}\'. Using 'anonymous'." )
+#   'anonymous'
+# }
+#
+# # $valid_username contains "Amy Berry".
+# # If $raw_username was an empty string, the Puppet run would set $valid_username to
+# # "anonymous" and output a warning: "The username should be 'String[1, default]', not
+# # 'String[0, 0]'. Using 'anonymous'."
+# ~~~
+#
+# For more information about data types, see the
+# [documentation](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html).
+#
+# @since 4.0.0
 #
 Puppet::Functions.create_function(:assert_type) do
   dispatch :assert_type do
@@ -32,18 +68,16 @@ Puppet::Functions.create_function(:assert_type) do
   #
   def assert_type(type, value)
     unless Puppet::Pops::Types::TypeCalculator.instance?(type,value)
-      inferred_type = Puppet::Pops::Types::TypeCalculator.infer(value)
+      inferred_type = Puppet::Pops::Types::TypeCalculator.infer_set(value)
       if block_given?
-        # Give the inferred type to allow richer comparisson in the given block (if generalized
+        # Give the inferred type to allow richer comparison in the given block (if generalized
         # information is lost).
         #
         value = yield(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::Pops::Types::TypeAssertionError.new("assert_type(): Expected type #{type} does not match actual: #{actual}", type,actual)
+        raise Puppet::Pops::Types::TypeAssertionError.new(
+          Puppet::Pops::Types::TypeMismatchDescriber.singleton.describe_mismatch('assert_type():', type, inferred_type),
+          type, inferred_type)
       end
     end
     value
@@ -53,7 +87,7 @@ Puppet::Functions.create_function(:assert_type) do
   # @param value [Object] the value to assert
   #
   def assert_type_s(type_string, value, &proc)
-    t = Puppet::Pops::Types::TypeParser.new.parse(type_string)
+    t = Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
     block_given? ? assert_type(t, value, &proc) : assert_type(t, value)
   end
 end

data/lib/puppet/functions/binary_file.rb

@@ -0,0 +1,19 @@
+# Loads a binary file from a module or file system and returns its contents as a Binary.
+# (Documented in 3.x stub)
+#
+# @since 4.8.0
+#
+Puppet::Functions.create_function(:binary_file, Puppet::Functions::InternalFunction) do
+  dispatch :binary_file do
+    scope_param
+    param 'String', :path
+  end
+
+  def binary_file(scope, unresolved_path)
+    path = Puppet::Parser::Files.find_file(unresolved_path, scope.compiler.environment)
+    unless path && Puppet::FileSystem.exist?(path)
+      raise Puppet::ParseError, _("binary_file(): The given file '%{unresolved_path}' does not exist") % { unresolved_path: unresolved_path }
+    end
+    Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(Puppet::FileSystem.binread(path))
+  end
+end

data/lib/puppet/functions/break.rb

@@ -0,0 +1,22 @@
+# Make iteration break as if there were no more values to process
+#
+# @since 4.7.0
+#
+Puppet::Functions.create_function(:break) do
+  dispatch :break_impl do
+  end
+
+  def break_impl()
+    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
+    if stacktrace.size > 0
+      file, line = stacktrace[0]
+    else
+      file = nil
+      line = nil
+    end
+    # PuppetStopIteration contains file and line and is a StopIteration exception
+    # so it can break a Ruby Kernel#loop or enumeration
+    #
+    raise Puppet::Pops::Evaluator::PuppetStopIteration.new(file, line)
+  end
+end

data/lib/puppet/functions/call.rb

@@ -0,0 +1,42 @@
+# Calls an arbitrary Puppet function by name.
+#
+# This function takes one mandatory argument and one or more optional arguments:
+#
+# 1. A string corresponding to a function name.
+# 2. Any number of arguments to be passed to the called function.
+# 3. An optional lambda, if the function being called supports it.
+#
+# @example Using the `call` function
+#
+# ~~~ puppet
+# $a = 'notice'
+# call($a, 'message')
+# ~~~
+#
+# @example Using the `call` function with a lambda
+#
+# ~~~ puppet
+# $a = 'each'
+# $b = [1,2,3]
+# call($a, $b) |$item| {
+#  notify { $item: }
+# }
+# ~~~
+#
+# The `call` function can be used to call either Ruby functions or Puppet language
+# functions.
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
+  dispatch :call_impl_block do
+    scope_param
+    param 'String', :function_name
+    repeated_param 'Any', :arguments
+    optional_block_param
+  end
+
+  def call_impl_block(scope, function_name, *args, &block)
+    call_function_with_scope(scope, function_name, *args, &block)
+  end
+end

data/lib/puppet/functions/contain.rb

@@ -0,0 +1,33 @@
+# Called within a class definition, establishes a containment
+# relationship with another class
+# For documentation, see the 3.x stub
+#
+Puppet::Functions.create_function(:contain, Puppet::Functions::InternalFunction) do
+  dispatch :contain 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 contain(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) }
+    containing_resource = scope.resource
+
+    # This is the same as calling the include function but faster and does not rely on the include
+    # function.
+    (scope.compiler.evaluate_classes(classes, scope, false) || []).each do |resource|
+      if ! scope.catalog.edge?(containing_resource, resource)
+        scope.catalog.add_edge(containing_resource, resource)
+      end
+    end
+    # Result is an Array[Class, 1, n] which allows chaining other operations
+    result
+  end
+end

data/lib/puppet/functions/crit.rb

@@ -0,0 +1,14 @@
+# Log a message on the server at level crit.
+Puppet::Functions.create_function(:crit, Puppet::Functions::InternalFunction) do
+  # @param values The values to log.
+  # @return [Undef]
+  dispatch :crit do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def crit(scope, *values)
+    Puppet::Util::Log.log_func(scope, :crit, values)
+  end
+end

data/lib/puppet/functions/debug.rb

@@ -0,0 +1,14 @@
+# Log a message on the server at level debug.
+Puppet::Functions.create_function(:debug, Puppet::Functions::InternalFunction) do
+  # @param values The values to log.
+  # @return [Undef]
+  dispatch :debug do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def debug(scope, *values)
+    Puppet::Util::Log.log_func(scope, :debug, values)
+  end
+end

data/lib/puppet/functions/defined.rb

@@ -0,0 +1,160 @@
+# Determines whether a given class or resource type is defined and returns a Boolean
+# value. You can also use `defined` to determine whether a specific resource is defined,
+# or whether a variable has a value (including `undef`, as opposed to the variable never
+# being declared or assigned).
+#
+# This function takes at least one string argument, which can be a class name, type name,
+# resource reference, or variable reference of the form `'$name'`.
+#
+# The `defined` function checks both native and defined types, including types
+# provided by modules. Types and classes are matched by their names. The function matches
+# resource declarations by using resource references.
+#
+# **Examples**: Different types of `defined` function matches
+#
+# ~~~ puppet
+# # Matching resource types
+# defined("file")
+# defined("customtype")
+#
+# # Matching defines and classes
+# defined("foo")
+# defined("foo::bar")
+#
+# # Matching variables
+# defined('$name')
+#
+# # Matching declared resources
+# defined(File['/tmp/file'])
+# ~~~
+#
+# Puppet depends on the configuration's evaluation order when checking whether a resource
+# is declared.
+#
+# @example Importance of evaluation order when using `defined`
+#
+# ~~~ puppet
+# # Assign values to $is_defined_before and $is_defined_after using identical `defined`
+# # functions.
+#
+# $is_defined_before = defined(File['/tmp/file'])
+#
+# file { "/tmp/file":
+#   ensure => present,
+# }
+#
+# $is_defined_after = defined(File['/tmp/file'])
+#
+# # $is_defined_before returns false, but $is_defined_after returns true.
+# ~~~
+#
+# This order requirement only refers to evaluation order. The order of resources in the
+# configuration graph (e.g. with `before` or `require`) does not affect the `defined`
+# function's behavior.
+#
+# > **Warning:** Avoid relying on the result of the `defined` function in modules, as you
+# > might not be able to guarantee the evaluation order well enough to produce consistent
+# > results. This can cause other code that relies on the function's result to behave
+# > inconsistently or fail.
+#
+# If you pass more than one argument to `defined`, the function returns `true` if _any_
+# of the arguments are defined. You can also match resources by type, allowing you to
+# match conditions of different levels of specificity, such as whether a specific resource
+# is of a specific data type.
+#
+# @example Matching multiple resources and resources by different types with `defined`
+#
+# ~~~ puppet
+# file { "/tmp/file1":
+#   ensure => file,
+# }
+#
+# $tmp_file = file { "/tmp/file2":
+#   ensure => file,
+# }
+#
+# # Each of these statements return `true` ...
+# defined(File['/tmp/file1'])
+# defined(File['/tmp/file1'],File['/tmp/file2'])
+# defined(File['/tmp/file1'],File['/tmp/file2'],File['/tmp/file3'])
+# # ... but this returns `false`.
+# defined(File['/tmp/file3'])
+#
+# # Each of these statements returns `true` ...
+# defined(Type[Resource['file','/tmp/file2']])
+# defined(Resource['file','/tmp/file2'])
+# defined(File['/tmp/file2'])
+# defined('$tmp_file')
+# # ... but each of these returns `false`.
+# defined(Type[Resource['exec','/tmp/file2']])
+# defined(Resource['exec','/tmp/file2'])
+# defined(File['/tmp/file3'])
+# defined('$tmp_file2')
+# ~~~
+#
+# @since 2.7.0
+# @since 3.6.0 variable reference and future parser types
+# @since 3.8.1 type specific requests with future parser
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunction) do
+
+  dispatch :is_defined do
+    scope_param
+    required_repeated_param 'Variant[String, Type[CatalogEntry], Type[Type[CatalogEntry]]]', :vals
+  end
+
+  def is_defined(scope, *vals)
+    env = scope.environment
+    vals.any? do |val|
+      case val
+      when String
+        if val =~ /^\$(.+)$/
+          scope.exist?($1)
+        else
+          case val
+          when ''
+            next nil
+          when 'main'
+            # Find the main class (known as ''), it does not have to be in the catalog
+            Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_main_class(scope)
+          else
+            # Find a resource type, definition or class definition
+            krt = scope.environment.known_resource_types
+            Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_resource_type_or_class(scope, val)
+          end
+        end
+      when Puppet::Resource
+        # Find instance of given resource type and title that is in the catalog
+        scope.compiler.findresource(val.resource_type, val.title)
+
+      when Puppet::Pops::Types::PResourceType
+        raise ArgumentError, _('The given resource type is a reference to all kind of types') if val.type_name.nil?
+        type = Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_resource_type(scope, val.type_name)
+        val.title.nil? ? type : scope.compiler.findresource(type, val.title)
+
+      when Puppet::Pops::Types::PHostClassType
+        raise  ArgumentError, _('The given class type is a reference to all classes') if val.class_name.nil?
+        scope.compiler.findresource(:class, val.class_name)
+
+      when Puppet::Pops::Types::PType
+        case val.type
+        when Puppet::Pops::Types::PResourceType
+          # It is most reasonable to take Type[File] and Type[File[foo]] to mean the same as if not wrapped in a Type
+          # Since the difference between File and File[foo] already captures the distinction of type vs instance.
+          is_defined(scope, val.type)
+
+        when Puppet::Pops::Types::PHostClassType
+          # Interpreted as asking if a class (and nothing else) is defined without having to be included in the catalog
+          # (this is the same as asking for just the class' name, but with the added certainty that it cannot be a defined type.
+          #
+          raise  ArgumentError, _('The given class type is a reference to all classes') if val.type.class_name.nil?
+          Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_hostclass(scope, val.type.class_name)
+          #scope.environment.known_resource_types.find_hostclass(val.type.class_name)
+        end
+      else
+        raise ArgumentError, _("Invalid argument of type '%{value_class}' to 'defined'") % { value_class: val.class }
+      end
+    end
+  end
+end

data/lib/puppet/functions/dig.rb

@@ -0,0 +1,23 @@
+# Digs into a data structure.
+# (Documented in 3.x stub)
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:dig) do
+  dispatch :dig do
+    param 'Optional[Collection]', :data
+    repeated_param 'Any', :arg
+  end
+
+  def dig(data, *args)
+    walked_path = []
+    args.reduce(data) do | d, k |
+      return nil if d.nil? || k.nil?
+      if !(d.is_a?(Array) || d.is_a?(Hash))
+        raise ArgumentError, _("The given data does not contain a Collection at %{walked_path}, got '%{klass}'") % { walked_path: walked_path, klass: d.class }
+      end
+      walked_path << k
+      d[k]
+    end
+  end
+end

data/lib/puppet/functions/each.rb

@@ -1,38 +1,96 @@
-#  Applies a parameterized block to each element in a sequence of selected entries from the first
-#  argument and returns the first argument.
+# Runs a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# repeatedly using each value in a data structure, then returns the values unchanged.
 #
-# 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:
+# This function takes two mandatory arguments, in this order:
 #
-#       $a.each |$x| { ... }
-#       each($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 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.
+# @example Using the `each` function
 #
-#       $a.each |$index, $value| { ... }
-#       each($a) |$index, $value| { ... }
+# `$data.each |$parameter| { <PUPPET CODE BLOCK> }`
 #
-# 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.
+# or
 #
-#       $a.each |$entry|       { ..."key ${$entry[0]}, value ${$entry[1]}" }
-#       $a.each |$key, $value| { ..."key ${key}, value ${value}" }
+# `each($data) |$parameter| { <PUPPET CODE BLOCK> }`
 #
-# @example using each
+# When the first argument (`$data` in the above example) is an array, Puppet passes each
+# value in turn to the lambda, then returns the original values.
 #
-#       [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
+# @example Using the `each` function with an array and a one-parameter lambda
+#
+# ~~~ puppet
+# # For the array $data, run a lambda that creates a resource for each item.
+# $data = ["routers", "servers", "workstations"]
+# $data.each |$item| {
+#  notify { $item:
+#    message => $item
+#  }
+# }
+# # Puppet creates one resource for each of the three items in $data. Each resource is
+# # named after the item's value and uses the item's value in a parameter.
+# ~~~
+#
+# 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]` and returns the original hash.
+#
+# @example Using the `each` function with a hash and a one-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, run a lambda using each item as a key-value array that creates a
+# # resource for each item.
+# $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
+# $data.each |$items| {
+#  notify { $items[0]:
+#    message => $items[1]
+#  }
+# }
+# # Puppet creates one resource for each of the three items in $data, each named after the
+# # item's key and containing a parameter using the item's value.
+# ~~~
+#
+# 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 `each` function with an array and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the array $data, run a lambda using each item's index and value that creates a
+# # resource for each item.
+# $data = ["routers", "servers", "workstations"]
+# $data.each |$index, $value| {
+#  notify { $value:
+#    message => $index
+#  }
+# }
+# # Puppet creates one resource for each of the three items in $data, each named after the
+# # item's value and containing a parameter using the item's index.
+# ~~~
+#
+# 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 `each` function with a hash and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, run a lambda using each item's key and value to create a resource
+# # for each item.
+# $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
+# $data.each |$key, $value| {
+#  notify { $key:
+#    message => $value
+#  }
+# }
+# # Puppet creates one resource for each of the three items in $data, each named after the
+# # item's key and containing a parameter using the item's value.
+# ~~~
+#
+# For an example that demonstrates how to create multiple `file` resources using `each`,
+# see the Puppet
+# [iteration](https://docs.puppetlabs.com/puppet/latest/reference/lang_iteration.html)
+# documentation.
 #
 # @since 4.0.0
 #
@@ -48,12 +106,12 @@ Puppet::Functions.create_function(:each) do
   end
 
   dispatch :foreach_Enumerable_2 do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[2,2]', :block
   end
 
   dispatch :foreach_Enumerable_1 do
-    param 'Any', :enumerable
+    param 'Iterable', :enumerable
     block_param 'Callable[1,1]', :block
   end
 
@@ -76,7 +134,7 @@ Puppet::Functions.create_function(:each) do
   end
 
   def foreach_Enumerable_1(enumerable)
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
       begin
         loop { yield(enum.next) }
       rescue StopIteration
@@ -86,7 +144,7 @@ Puppet::Functions.create_function(:each) do
   end
 
   def foreach_Enumerable_2(enumerable)
-    enum = asserted_enumerable(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     index = 0
     begin
       loop do
@@ -98,12 +156,4 @@ Puppet::Functions.create_function(:each) do
     # 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/emerg.rb

@@ -0,0 +1,14 @@
+# Log a message on the server at level emerg.
+Puppet::Functions.create_function(:emerg, Puppet::Functions::InternalFunction) do
+  # @param values The values to log.
+  # @return [Undef]
+  dispatch :emerg do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def emerg(scope, *values)
+    Puppet::Util::Log.log_func(scope, :emerg, values)
+  end
+end