puppet 4.4.0-universal-darwin

data/lib/puppet/functions/assert_type.rb

@@ -0,0 +1,95 @@
+# 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).
+#
+# The function takes two mandatory arguments, in this order:
+#
+# 1. The expected data type.
+# 2. A value to compare against the expected data type.
+#
+# @example Using `assert_type`
+#
+# ~~~ 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, Puppet::Functions::InternalFunction) do
+  dispatch :assert_type do
+    param 'Type', :type
+    param 'Any', :value
+    optional_block_param 'Callable[Type, Type]', :block
+  end
+
+  dispatch :assert_type_s do
+    scope_param
+    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)
+    unless Puppet::Pops::Types::TypeCalculator.instance?(type,value)
+      inferred_type = Puppet::Pops::Types::TypeCalculator.infer(value)
+      if block_given?
+        # Give the inferred type to allow richer comparison in the given block (if generalized
+        # information is lost).
+        #
+        value = yield(type, inferred_type)
+      else
+        raise Puppet::Pops::Types::TypeAssertionError.new(
+          Puppet::Pops::Types::TypeMismatchDescriber.singleton.describe_mismatch('assert_type():', type, inferred_type),
+          type, inferred_type)
+      end
+    end
+    value
+  end
+
+  # @param scope [Puppet::Parser::Scope] scope used when obtaining loader for defined types
+  # @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(scope, type_string, value, &proc)
+    t = Puppet::Pops::Types::TypeParser.new.parse(type_string, scope)
+    block_given? ? assert_type(t, value, &proc) : assert_type(t, value)
+  end
+end

data/lib/puppet/functions/defined.rb

@@ -0,0 +1,161 @@
+# 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)
+    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
+            scope.find_hostclass('')
+          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)
+          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)
+
+      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
+
+      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?
+          scope.find_hostclass(val.type.class_name)
+        end
+      else
+        raise ArgumentError, "Invalid argument of type '#{val.class}' to 'defined'"
+      end
+    end
+  end
+end

data/lib/puppet/functions/each.rb

@@ -0,0 +1,159 @@
+# 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, 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 can
+# request one or two parameters.
+#
+# @example Using the `each` function
+#
+# `$data.each |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `each($data) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# 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.
+#
+# @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
+#
+Puppet::Functions.create_function(:each) do
+  dispatch :foreach_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :foreach_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :foreach_Enumerable_2 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :foreach_Enumerable_1 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[1,1]', :block
+  end
+
+  def foreach_Hash_1(hash)
+    enumerator = hash.each_pair
+    hash.size.times do
+      yield(enumerator.next)
+    end
+    # produces the receiver
+    hash
+  end
+
+  def foreach_Hash_2(hash)
+    enumerator = hash.each_pair
+    hash.size.times do
+      yield(*enumerator.next)
+    end
+    # produces the receiver
+    hash
+  end
+
+  def foreach_Enumerable_1(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+      begin
+        loop { yield(enum.next) }
+      rescue StopIteration
+      end
+    # produces the receiver
+    enumerable
+  end
+
+  def foreach_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    index = 0
+    begin
+      loop do
+        yield(index, enum.next)
+        index += 1
+      end
+    rescue StopIteration
+    end
+    # produces the receiver
+    enumerable
+  end
+end

data/lib/puppet/functions/epp.rb

@@ -0,0 +1,45 @@
+# 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 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/templates/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
+
+  dispatch :epp do
+    scope_param
+    param 'String', :path
+    optional_param 'Hash[Pattern[/^\w+$/], Any]', :parameters
+  end
+
+  def epp(scope, path, parameters = nil)
+    Puppet::Pops::Evaluator::EppEvaluator.epp(scope, path, scope.compiler.environment, parameters)
+  end
+end