openvox 8.19.0

data/lib/puppet/functions/contain.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Makes one or more classes be contained inside the current class.
+# If any of these classes are undeclared, they will be declared as if
+# there were declared with the `include` function.
+# Accepts a class name, an array of class names, or a comma-separated
+# list of class names.
+#
+# A contained class will not be applied before the containing class is
+# begun, and will be finished before the containing class is finished.
+#
+# You must use the class's full name;
+# relative names are not allowed. In addition to names in string form,
+# you may also directly use `Class` and `Resource` `Type`-values that are produced by
+# evaluating resource and relationship expressions.
+#
+# The function returns an array of references to the classes that were contained thus
+# allowing the function call to `contain` to directly continue.
+#
+# - Since 4.0.0 support for `Class` and `Resource` `Type`-values, absolute names
+# - Since 4.7.0 a value of type `Array[Type[Class[n]]]` is returned with all the contained classes
+#
+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)
+    if Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+        { :operation => 'contain' }
+      )
+    end
+
+    # 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|
+      unless 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/convert_to.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The `convert_to(value, type)` is a convenience function that does the same as `new(type, value)`.
+# The difference in the argument ordering allows it to be used in chained style for
+# improved readability "left to right".
+#
+# When the function is given a lambda, it is called with the converted value, and the function
+# returns what the lambda returns, otherwise the converted value.
+#
+# @example 'convert_to' instead of 'new'
+#
+# ```puppet
+#   # The harder to read variant:
+#   # Using new operator - that is "calling the type" with operator ()
+#   Hash(Array("abc").map |$i,$v| { [$i, $v] })
+#
+#   # The easier to read variant:
+#   # using 'convert_to'
+#   "abc".convert_to(Array).map |$i,$v| { [$i, $v] }.convert_to(Hash)
+# ```
+#
+# @since 5.4.0
+#
+Puppet::Functions.create_function(:convert_to) do
+  dispatch :convert_to do
+    param 'Any', :value
+    param 'Type', :type
+    optional_repeated_param 'Any', :args
+    optional_block_param 'Callable[1,1]', :block
+  end
+
+  def convert_to(value, type, *args, &block)
+    result = call_function('new', type, value, *args)
+    block_given? ? yield(result) : result
+  end
+end

data/lib/puppet/functions/crit.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Logs 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,16 @@
+# frozen_string_literal: true
+
+# Logs 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,163 @@
+# frozen_string_literal: true
+
+# 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'`. (Note that the `$` sign
+# is included in the string which must be in single quotes to prevent the `$` character
+# to be interpreted as interpolation.
+#
+# 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.
+#
+# @example 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 (note the single quotes)
+# 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) # rubocop:disable Naming/PredicateName
+    vals.any? do |val|
+      case val
+      when String
+        if val =~ /^\$(.+)$/
+          scope.exist?(Regexp.last_match(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
+            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::PClassType
+        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::PTypeType
+        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::PClassType
+          # 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)
+        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,70 @@
+# frozen_string_literal: true
+
+# Returns a value for a sequence of given keys/indexes into a structure, such as
+# an array or hash.
+#
+# This function is used to "dig into" a complex data structure by
+# using a sequence of keys / indexes to access a value from which
+# the next key/index is accessed recursively.
+#
+# The first encountered `undef` value or key stops the "dig" and `undef` is returned.
+#
+# An error is raised if an attempt is made to "dig" into
+# something other than an `undef` (which immediately returns `undef`), an `Array` or a `Hash`.
+#
+# @example Using `dig`
+#
+# ```puppet
+# $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
+# notice $data.dig('a', 'b', 1, 'x')
+# ```
+#
+# Would notice the value 100.
+#
+# This is roughly equivalent to `$data['a']['b'][1]['x']`. However, a standard
+# index will return an error and cause catalog compilation failure if any parent
+# of the final key (`'x'`) is `undef`. The `dig` function will return `undef`,
+# rather than failing catalog compilation. This allows you to check if data
+# exists in a structure without mandating that it always exists.
+#
+# @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?
+
+      unless d.is_a?(Array) || d.is_a?(Hash)
+        t = Puppet::Pops::Types::TypeCalculator.infer(d)
+        msg = _("The given data does not contain a Collection at %{walked_path}, got '%{type}'") % { walked_path: walked_path, type: t }
+        error_data = Puppet::DataTypes::Error.new(
+          msg,
+          'SLICE_ERROR',
+          { 'walked_path' => walked_path, 'value_type' => t },
+          'EXPECTED_COLLECTION'
+        )
+        raise Puppet::ErrorWithData.new(error_data, msg)
+      end
+
+      walked_path << k
+      if d.is_a?(Array) && !k.is_a?(Integer)
+        t = Puppet::Pops::Types::TypeCalculator.infer(k)
+        msg = _("The given data requires an Integer index at %{walked_path}, got '%{type}'") % { walked_path: walked_path, type: t }
+        error_data = Puppet::DataTypes::Error.new(
+          msg,
+          'SLICE_ERROR',
+          { 'walked_path' => walked_path, 'index_type' => t },
+          'EXPECTED_INTEGER_INDEX'
+        )
+        raise Puppet::ErrorWithData.new(error_data, msg)
+      end
+      d[k]
+    end
+  end
+end

data/lib/puppet/functions/downcase.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Converts a String, Array or Hash (recursively) into lower case.
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String`, its lower case version is returned. This is done using Ruby system locale which handles some, but not all
+#   special international up-casing rules (for example German double-s ß is upcased to "SS", whereas upper case double-s
+#   is downcased to ß).
+# * For `Array` and `Hash` the conversion to lower case is recursive and each key and value must be convertible by
+#   this function.
+# * When a `Hash` is converted, some keys could result in the same key - in those cases, the
+#   latest key-value wins. For example if keys "aBC", and "abC" where both present, after downcase there would only be one
+#   key "abc".
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# Please note: This function relies directly on Ruby's String implementation and as such may not be entirely UTF8 compatible.
+# To ensure best compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085.
+#
+# @example Converting a String to lower case
+# ```puppet
+# 'HELLO'.downcase()
+# downcase('HEllO')
+# ```
+# Would both result in `"hello"`
+#
+# @example Converting an Array to lower case
+# ```puppet
+# ['A', 'B'].downcase()
+# downcase(['A', 'B'])
+# ```
+# Would both result in `['a', 'b']`
+#
+# @example Converting a Hash to lower case
+# ```puppet
+# {'A' => 'HEllO', 'B' => 'GOODBYE'}.downcase()
+# ```
+# Would result in `{'a' => 'hello', 'b' => 'goodbye'}`
+#
+# @example Converting a recursive structure
+# ```puppet
+# ['A', 'B', ['C', ['D']], {'X' => 'Y'}].downcase
+# ```
+# Would result in `['a', 'b', ['c', ['d']], {'x' => 'y'}]`
+#
+Puppet::Functions.create_function(:downcase) do
+  local_types do
+    type 'StringData = Variant[String, Numeric, Array[StringData], Hash[StringData, StringData]]'
+  end
+
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_array do
+    param 'Array[StringData]', :arg
+  end
+
+  dispatch :on_hash do
+    param 'Hash[StringData, StringData]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.downcase
+  end
+
+  def on_array(a)
+    a.map { |x| do_downcase(x) }
+  end
+
+  def on_hash(h)
+    result = {}
+    h.each_pair { |k, v| result[do_downcase(k)] = do_downcase(v) }
+    result
+  end
+
+  def do_downcase(x)
+    x.is_a?(String) ? x.downcase : call_function('downcase', x)
+  end
+end

data/lib/puppet/functions/each.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# Runs a [lambda](https://puppet.com/docs/puppet/latest/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://puppet.com/docs/puppet/latest/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)
+    begin
+      hash.each_pair do |pair|
+        yield(pair)
+      end
+    rescue StopIteration
+    end
+    # produces the receiver
+    hash
+  end
+
+  def foreach_Hash_2(hash)
+    begin
+      hash.each_pair do |pair|
+        yield(*pair)
+      end
+    rescue StopIteration
+    end
+    # produces the receiver
+    hash
+  end
+
+  def foreach_Enumerable_1(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    begin
+      enum.each do |value|
+        yield value
+      end
+    rescue StopIteration
+    end
+    # produces the receiver
+    enumerable
+  end
+
+  def foreach_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.each { |entry| yield(*entry) }
+    else
+      begin
+        enum.each_with_index do |value, index|
+          yield(index, value)
+        end
+      rescue StopIteration
+      end
+    end
+    # produces the receiver
+    enumerable
+  end
+end

data/lib/puppet/functions/emerg.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Logs 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