puppet 4.1.0 → 4.10.0

data/lib/puppet/functions/defined.rb

@@ -1,70 +1,101 @@
-# Determines whether
-# a given class or resource type is defined. This function can also determine whether a
-# specific resource has been declared, or whether a variable has been assigned a value
-# (including undef...as opposed to never having been assigned anything). Returns true
-# or false. Accepts class names, type names, resource references, and variable
-# reference strings of the form '$name'.  When more than one argument is
-# supplied, defined() returns true if any are defined.
+# 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 as plugins via modules. Types and classes are both checked using their names:
+# 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')
 #
-#     defined("file")
-#     defined("customtype")
-#     defined("foo")
-#     defined("foo::bar")
-#     defined('$name')
+# # Matching declared resources
+# defined(File['/tmp/file'])
+# ~~~
 #
-# Resource declarations are checked using resource references, e.g.
-# `defined( File['/tmp/myfile'] )`, or `defined( Class[myclass] )`.
-# Checking whether a given resource
-# has been declared is, unfortunately, dependent on the evaluation order of
-# the configuration, and the following code will not work:
+# Puppet depends on the configuration's evaluation order when checking whether a resource
+# is declared.
 #
-#     if defined(File['/tmp/foo']) {
-#         notify { "This configuration includes the /tmp/foo file.":}
-#     }
-#     file { "/tmp/foo":
-#         ensure => present,
-#     }
+# @example Importance of evaluation order when using `defined`
 #
-# However, this order requirement refers to evaluation order only, and ordering of
-# resources in the configuration graph (e.g. with `before` or `require`) does not
-# affect the behavior of `defined`.
+# ~~~ puppet
+# # Assign values to $is_defined_before and $is_defined_after using identical `defined`
+# # functions.
 #
-# You may also search using types:
+# $is_defined_before = defined(File['/tmp/file'])
 #
-#     defined(Resource['file','/some/file'])
-#     defined(File['/some/file'])
-#     defined(Class['foo'])
+# file { "/tmp/file":
+#   ensure => present,
+# }
 #
-# The `defined` function does not answer if data types (e.g. `Integer`) are defined. If
-# given the string 'integer' the result is false, and if given a non CatalogEntry type,
-# an error is raised.
+# $is_defined_after = defined(File['/tmp/file'])
 #
-# The rules for asking for undef, empty strings, and the main class are different from 3.x
-# (non future parser) and 4.x (with future parser or in Puppet 4.0.0 and later):
+# # $is_defined_before returns false, but $is_defined_after returns true.
+# ~~~
 #
-#     defined('')     # 3.x => true,  4.x => false
-#     defined(undef)  # 3.x => true,  4.x => error
-#     defined('main') # 3.x => false, 4.x => 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.
 #
-# With the future parser, it is also possible to ask specifically if a name is
-# a resource type (built in or defined), or a class, by giving its type:
+# > **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.
 #
-#     defined(Type[Class['foo']])
-#     defined(Type[Resource['foo']])
+# 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.
 #
-# Which is different from asking:
+# @example Matching multiple resources and resources by different types with `defined`
 #
-#     defined('foo')
+# ~~~ puppet
+# file { "/tmp/file1":
+#   ensure => file,
+# }
 #
-# Since the later returns true if 'foo' is either a class, a built-in resource type, or a user defined
-# resource type, and a specific request like `Type[Class['foo']]` only returns true if `'foo'` is a class.
+# $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.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
 
@@ -74,6 +105,7 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
   end
 
   def is_defined(scope, *vals)
+    env = scope.environment
     vals.any? do |val|
       case val
       when String
@@ -85,24 +117,21 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
             next nil
           when 'main'
             # Find the main class (known as ''), it does not have to be in the catalog
-            scope.find_hostclass('')
+            Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_main_class(scope)
           else
             # Find a resource type, definition or class definition
-            scope.find_resource_type(val) || scope.find_definition(val) || scope.find_hostclass(val)
-            #scope.compiler.findresource(:class, val)
+            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.type, val.title)
+        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?
-        if val.title.nil?
-          scope.find_builtin_resource_type(val.type_name) || scope.find_definition(val.type_name)
-        else
-          scope.compiler.findresource(val.type_name, val.title)
-        end
+        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?
@@ -120,7 +149,8 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
           # (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?
-          scope.find_hostclass(val.type.class_name)
+          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 '#{val.class}' to 'defined'"

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 '#{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

data/lib/puppet/functions/epp.rb

@@ -1,42 +1,34 @@
-# Evaluates an Embedded Puppet Template (EPP) file and returns the rendered text result as a String.
+# Evaluates an Embedded Puppet (EPP) template file and returns the rendered text
+# result as a String.
+#
+# `epp('<MODULE NAME>/<TEMPLATE FILE>', <PARAMETER HASH>)`
 #
 # 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
+# reference, which loads `<TEMPLATE FILE>` from `<MODULE NAME>`'s `templates`
+# directory. In most cases, the last argument is optional; if used, it should be a
+# [hash](/puppet/latest/reference/lang_data_hash.html) that contains parameters to
+# pass to the template.
+#
+# - See the [template](/puppet/latest/reference/lang_template.html) documentation
+# for general template usage information.
+# - See the [EPP syntax](/puppet/latest/reference/lang_template_epp.html)
+# documentation for examples of EPP.
+#
+# For example, to call the apache module's `templates/vhost/_docroot.epp`
+# template and pass the `docroot` and `virtual_docroot` parameters, call the `epp`
+# function like this:
+#
+# `epp('apache/vhost/_docroot.epp', { 'docroot' => '/var/www/html',
+# 'virtual_docroot' => '/var/www/example' })`
+#
+# Puppet produces a syntax error if you pass more parameters than are declared in
+# the template's parameter tag. When passing parameters to a template that
+# contains a parameter tag, use the same names as the tag's declared parameters.
+#
+# Parameters are required only if they are declared in the called template's
+# parameter tag without default values. Puppet produces an error if the `epp`
+# function fails to pass any required parameter.
+#
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:epp, Puppet::Functions::InternalFunction) do

data/lib/puppet/functions/err.rb

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

data/lib/puppet/functions/eyaml_lookup_key.rb

@@ -0,0 +1,90 @@
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:eyaml_lookup_key) do
+  unless Puppet.features.hiera_eyaml?
+    raise Puppet::DataBinding::LookupError, 'Lookup using eyaml lookup_key function is only supported when the hiera_eyaml library is present'
+  end
+
+  require 'hiera/backend/eyaml/encryptor'
+  require 'hiera/backend/eyaml/utils'
+  require 'hiera/backend/eyaml/options'
+  require 'hiera/backend/eyaml/parser/parser'
+
+  dispatch :eyaml_lookup_key do
+    param 'String[1]', :key
+    param 'Hash[String[1],Any]', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  def eyaml_lookup_key(key, options, context)
+    return context.cached_value(key) if context.cache_has_key(key)
+
+    # Can't do this with an argument_mismatch dispatcher since there is no way to declare a struct that at least
+    # contains some keys but may contain other arbitrary keys.
+    unless options.include?('path')
+      raise ArgumentError,
+        "'eyaml_lookup_key': one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this lookup_key function"
+    end
+
+    # nil key is used to indicate that the cache contains the raw content of the eyaml file
+    raw_data = context.cached_value(nil)
+    if raw_data.nil?
+      options.each_pair do |k, v|
+        unless k == 'path'
+          Hiera::Backend::Eyaml::Options[k.to_sym] = v
+          context.explain { "Setting Eyaml option '#{k}' to '#{v}'" }
+        end
+      end
+      raw_data = load_data_hash(options, context)
+      context.cache(nil, raw_data)
+    end
+    context.not_found unless raw_data.include?(key)
+    context.cache(key, decrypt_value(raw_data[key], context))
+  end
+
+  def load_data_hash(options, context)
+    path = options['path']
+    context.cached_file_data(path) do |content|
+      begin
+        data = YAML.load(content, path)
+        if data.is_a?(Hash)
+          Puppet::Pops::Lookup::HieraConfig.symkeys_to_string(data)
+        else
+          Puppet.warning("#{path}: file does not contain a valid yaml hash")
+          {}
+        end
+      rescue YAML::SyntaxError => ex
+        # Psych errors includes the absolute path to the file, so no need to add that
+        # to the message
+        raise Puppet::DataBinding::LookupError, "Unable to parse #{ex.message}"
+      end
+    end
+  end
+
+  def decrypt_value(value, context)
+    case value
+    when String
+      decrypt(value, context)
+    when Hash
+      result = {}
+      value.each_pair { |k, v| result[context.interpolate(k)] = decrypt_value(v, context) }
+      result
+    when Array
+      value.map { |v| decrypt_value(v, context) }
+    else
+      value
+    end
+  end
+
+  def decrypt(data, context)
+    if encrypted?(data)
+      tokens = Hiera::Backend::Eyaml::Parser::ParserFactory.hiera_backend_parser.parse(data)
+      data = tokens.map(&:to_plain_text).join.chomp
+    end
+    context.interpolate(data)
+  end
+
+  def encrypted?(data)
+    /.*ENC\[.*?\]/ =~ data ? true : false
+  end
+end