openvox 8.19.0

data/lib/puppet/functions/empty.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Returns `true` if the given argument is an empty collection of values.
+#
+# This function can answer if one of the following is empty:
+# * `Array`, `Hash` - having zero entries
+# * `String`, `Binary` - having zero length
+#
+# For backwards compatibility with the stdlib function with the same name the
+# following data types are also accepted by the function instead of raising an error.
+# Using these is deprecated and will raise a warning:
+#
+# * `Numeric` - `false` is returned for all `Numeric` values.
+# * `Undef` - `true` is returned for all `Undef` values.
+#
+# @example Using `empty`
+#
+# ```puppet
+# notice([].empty)
+# notice(empty([]))
+# # would both notice 'true'
+# ```
+#
+# @since Puppet 5.5.0 - support for Binary
+#
+Puppet::Functions.create_function(:empty) do
+  dispatch :collection_empty do
+    param 'Collection', :coll
+  end
+
+  dispatch :sensitive_string_empty do
+    param 'Sensitive[String]', :str
+  end
+
+  dispatch :string_empty do
+    param 'String', :str
+  end
+
+  dispatch :numeric_empty do
+    param 'Numeric', :num
+  end
+
+  dispatch :binary_empty do
+    param 'Binary', :bin
+  end
+
+  dispatch :undef_empty do
+    param 'Undef', :x
+  end
+
+  def collection_empty(coll)
+    coll.empty?
+  end
+
+  def sensitive_string_empty(str)
+    str.unwrap.empty?
+  end
+
+  def string_empty(str)
+    str.empty?
+  end
+
+  # For compatibility reasons - return false rather than error on floats and integers
+  # (Yes, it is strange)
+  #
+  def numeric_empty(num)
+    deprecation_warning_for('Numeric')
+    false
+  end
+
+  def binary_empty(bin)
+    bin.length == 0
+  end
+
+  # For compatibility reasons - return true rather than error on undef
+  # (Yes, it is strange, but undef was passed as empty string in 3.x API)
+  #
+  def undef_empty(x)
+    true
+  end
+
+  def deprecation_warning_for(arg_type)
+    file, line = Puppet::Pops::PuppetStack.top_of_stack
+    msg = _("Calling function empty() with %{arg_type} value is deprecated.") % { arg_type: arg_type }
+    Puppet.warn_once('deprecations', "empty-from-#{file}-#{line}", msg, file, line)
+  end
+end

data/lib/puppet/functions/epp.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# 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](https://puppet.com/docs/puppet/latest/lang_data_hash.html) that contains parameters to
+# pass to the template.
+#
+# - See the [template](https://puppet.com/docs/puppet/latest/lang_template.html)
+# documentation for general template usage information.
+# - See the [EPP syntax](https://puppet.com/docs/puppet/latest/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' })`
+#
+# This function can also accept an absolute path, which can load a template file
+# from anywhere on disk.
+#
+# 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
+    return_type 'Variant[String, Sensitive[String]]'
+  end
+
+  def epp(scope, path, parameters = nil)
+    Puppet::Pops::Evaluator::EppEvaluator.epp(scope, path, scope.compiler.environment, parameters)
+  end
+end

data/lib/puppet/functions/err.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Logs 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,103 @@
+# frozen_string_literal: true
+
+# The `eyaml_lookup_key` is a hiera 5 `lookup_key` data provider function.
+# See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-hiera-eyaml) for
+# how to use this function.
+#
+# @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')
+      # TRANSLATORS 'eyaml_lookup_key':, 'path', 'paths' 'glob', 'globs', 'mapped_paths', and lookup_key should not be translated
+      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?
+      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, options, key))
+  end
+
+  def load_data_hash(options, context)
+    path = options['path']
+    context.cached_file_data(path) do |content|
+      data = Puppet::Util::Yaml.safe_load(content, [Symbol], path)
+      if data.is_a?(Hash)
+        Puppet::Pops::Lookup::HieraConfig.symkeys_to_string(data)
+      else
+        msg = _("%{path}: file does not contain a valid yaml hash") % { path: path }
+        raise Puppet::DataBinding::LookupError, msg if Puppet[:strict] == :error && data != false
+
+        Puppet.warning(msg)
+        {}
+      end
+    rescue Puppet::Util::Yaml::YamlLoadError => ex
+      # YamlLoadErrors include the absolute path to the file, so no need to add that
+      raise Puppet::DataBinding::LookupError, _("Unable to parse %{message}") % { message: ex.message }
+    end
+  end
+
+  def decrypt_value(value, context, options, key)
+    case value
+    when String
+      decrypt(value, context, options, key)
+    when Hash
+      result = {}
+      value.each_pair { |k, v| result[context.interpolate(k)] = decrypt_value(v, context, options, key) }
+      result
+    when Array
+      value.map { |v| decrypt_value(v, context, options, key) }
+    else
+      value
+    end
+  end
+
+  def decrypt(data, context, options, key)
+    if encrypted?(data)
+      # Options must be set prior to each call to #parse since they end up as static variables in
+      # the Options class. They cannot be set once before #decrypt_value is called, since each #decrypt
+      # might cause a new lookup through interpolation. That lookup in turn, might use a different eyaml
+      # config.
+      #
+      Hiera::Backend::Eyaml::Options.set(options)
+      begin
+        tokens = Hiera::Backend::Eyaml::Parser::ParserFactory.hiera_backend_parser.parse(data)
+        data = tokens.map(&:to_plain_text).join.chomp
+      rescue StandardError => ex
+        raise Puppet::DataBinding::LookupError,
+              _("hiera-eyaml backend error decrypting %{data} when looking up %{key} in %{path}. Error was %{message}") % { data: data, key: key, path: options['path'], message: ex.message }
+      end
+    end
+    context.interpolate(data)
+  end
+
+  def encrypted?(data)
+    /.*ENC\[.*?\]/ =~ data ? true : false
+  end
+end

data/lib/puppet/functions/filter.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+# to every value in a data structure and returns an array or hash containing any elements
+# for which the lambda evaluates to a truthy value (not `false` or `undef`).
+#
+# 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 `filter` function
+#
+# `$filtered_data = $data.filter |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `$filtered_data = filter($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 and returns an array containing the results.
+#
+# @example Using the `filter` function with an array and a one-parameter lambda
+#
+# ```puppet
+# # For the array $data, return an array containing the values that end with "berry"
+# $data = ["orange", "blueberry", "raspberry"]
+# $filtered_data = $data.filter |$items| { $items =~ /berry$/ }
+# # $filtered_data = [blueberry, raspberry]
+# ```
+#
+# 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 a hash containing the results.
+#
+# @example Using the `filter` function with a hash and a one-parameter lambda
+#
+# ```puppet
+# # For the hash $data, return a hash containing all values of keys that end with "berry"
+# $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
+# $filtered_data = $data.filter |$items| { $items[0] =~ /berry$/ }
+# # $filtered_data = {blueberry => 1, raspberry => 2}
+# ```
+#
+# 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 `filter` function with an array and a two-parameter lambda
+#
+# ```puppet
+# # For the array $data, return an array of all keys that both end with "berry" and have
+# # an even-numbered index
+# $data = ["orange", "blueberry", "raspberry"]
+# $filtered_data = $data.filter |$indexes, $values| { $indexes % 2 == 0 and $values =~ /berry$/ }
+# # $filtered_data = [raspberry]
+# ```
+#
+# 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 `filter` function with a hash and a two-parameter lambda
+#
+# ```puppet
+# # For the hash $data, return a hash of all keys that both end with "berry" and have
+# # values less than or equal to 1
+# $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
+# $filtered_data = $data.filter |$keys, $values| { $keys =~ /berry$/ and $values <= 1 }
+# # $filtered_data = {blueberry => 1}
+# ```
+#
+# @since 4.0.0
+# @since 6.0.0 does not filter if truthy value is returned from block
+#
+Puppet::Functions.create_function(:filter) do
+  dispatch :filter_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :filter_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :filter_Enumerable_2 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :filter_Enumerable_1 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[1,1]', :block
+  end
+
+  def filter_Hash_1(hash)
+    result = hash.select { |x, y| yield([x, y]) }
+    # Ruby 1.8.7 returns Array
+    result = result.to_h unless result.is_a? Hash
+    result
+  end
+
+  def filter_Hash_2(hash)
+    result = hash.select { |x, y| yield(x, y) }
+    # Ruby 1.8.7 returns Array
+    result = result.to_h unless result.is_a? Hash
+    result
+  end
+
+  def filter_Enumerable_1(enumerable)
+    result = []
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    begin
+      enum.each do |value|
+        result << value if yield(value)
+      end
+    rescue StopIteration
+    end
+    result
+  end
+
+  def filter_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      result = {}
+      enum.each { |k, v| result[k] = v if yield(k, v) }
+    else
+      result = []
+      begin
+        enum.each_with_index do |value, index|
+          result << value if yield(index, value)
+        end
+      rescue StopIteration
+      end
+    end
+    result
+  end
+end

data/lib/puppet/functions/find_file.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Finds an existing file from a module and returns its path.
+#
+# This function accepts an argument that is a String as a `<MODULE NAME>/<FILE>`
+# reference, which searches for `<FILE>` relative to a module's `files`
+# directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
+# file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+#
+# If this function is run via puppet agent, it checks for file existence on the
+# Puppet Primary server. If run via puppet apply, it checks on the local host.
+# In both cases, the check is performed before any resources are changed.
+#
+# This function can also accept:
+#
+# * An absolute String path, which checks for the existence of a file from anywhere on disk.
+# * Multiple String arguments, which returns the path of the **first** file
+#   found, skipping nonexistent files.
+# * An array of string paths, which returns the path of the **first** file
+#   found from the given paths in the array, skipping nonexistent files.
+#
+# The function returns `undef` if none of the given paths were found.
+#
+# @since 4.8.0
+#
+Puppet::Functions.create_function(:find_file, Puppet::Functions::InternalFunction) do
+  dispatch :find_file do
+    scope_param
+    repeated_param 'String', :paths
+  end
+
+  dispatch :find_file_array do
+    scope_param
+    repeated_param 'Array[String]', :paths_array
+  end
+
+  def find_file_array(scope, array)
+    find_file(scope, *array)
+  end
+
+  def find_file(scope, *args)
+    args.each do |file|
+      found = Puppet::Parser::Files.find_file(file, scope.compiler.environment)
+      if found && Puppet::FileSystem.exist?(found)
+        return found
+      end
+    end
+    nil
+  end
+end

data/lib/puppet/functions/find_template.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Finds an existing template from a module and returns its path.
+#
+# This function accepts an argument that is a String as a `<MODULE NAME>/<TEMPLATE>`
+# reference, which searches for `<TEMPLATE>` relative to a module's `templates`
+# directory on the primary server. (For example, the reference `mymod/secret.conf.epp`
+# will search for the file `<MODULES DIRECTORY>/mymod/templates/secret.conf.epp`.)
+#
+# The primary use case is for agent-side template rendering with late-bound variables
+# resolved, such as from secret stores inaccessible to the primary server, such as
+#
+# ```
+# $variables = {
+#   'password' => Deferred('vault_lookup::lookup',
+#                   ['secret/mymod', 'https://vault.example.com:8200']),
+# }
+#
+# # compile the template source into the catalog
+# file { '/etc/secrets.conf':
+#   ensure  => file,
+#   content => Deferred('inline_epp',
+#                [find_template('mymod/secret.conf.epp').file, $variables]),
+# }
+# ```
+#
+#
+#
+# This function can also accept:
+#
+# * An absolute String path, which checks for the existence of a template from anywhere on disk.
+# * Multiple String arguments, which returns the path of the **first** template
+#   found, skipping nonexistent files.
+# * An array of string paths, which returns the path of the **first** template
+#   found from the given paths in the array, skipping nonexistent files.
+#
+# The function returns `undef` if none of the given paths were found.
+#
+# @since 6.x
+#
+Puppet::Functions.create_function(:find_template, Puppet::Functions::InternalFunction) do
+  dispatch :find_template do
+    scope_param
+    repeated_param 'String', :paths
+  end
+
+  dispatch :find_template_array do
+    scope_param
+    repeated_param 'Array[String]', :paths_array
+  end
+
+  def find_template_array(scope, array)
+    find_template(scope, *array)
+  end
+
+  def find_template(scope, *args)
+    args.each do |file|
+      found = Puppet::Parser::Files.find_template(file, scope.compiler.environment)
+      if found && Puppet::FileSystem.exist?(found)
+        return found
+      end
+    end
+    nil
+  end
+end

data/lib/puppet/functions/flatten.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Returns a flat Array produced from its possibly deeply nested given arguments.
+#
+# One or more arguments of any data type can be given to this function.
+# The result is always a flat array representation where any nested arrays are recursively flattened.
+#
+# @example Typical use of `flatten()`
+#
+# ```puppet
+# flatten(['a', ['b', ['c']]])
+# # Would return: ['a','b','c']
+# ```
+#
+# To flatten other kinds of iterables (for example hashes, or intermediate results like from a `reverse_each`)
+# first convert the result to an array using `Array($x)`, or `$x.convert_to(Array)`. See the `new` function
+# for details and options when performing a conversion.
+#
+# @example Flattening a Hash
+#
+# ```puppet
+# $hsh = { a => 1, b => 2}
+#
+# # -- without conversion
+# $hsh.flatten()
+# # Would return [{a => 1, b => 2}]
+#
+# # -- with conversion
+# $hsh.convert_to(Array).flatten()
+# # Would return [a,1,b,2]
+#
+# flatten(Array($hsh))
+# # Would also return [a,1,b,2]
+# ```
+#
+# @example Flattening and concatenating at the same time
+#
+# ```puppet
+# $a1 = [1, [2, 3]]
+# $a2 = [[4,[5,6]]
+# $x = 7
+# flatten($a1, $a2, $x)
+# # would return [1,2,3,4,5,6,7]
+# ```
+#
+# @example Transforming to Array if not already an Array
+#
+# ```puppet
+# flatten(42)
+# # Would return [42]
+#
+# flatten([42])
+# # Would also return [42]
+# ```
+#
+# @since 5.5.0 support for flattening and concatenating at the same time
+#
+Puppet::Functions.create_function(:flatten) do
+  dispatch :flatten_args do
+    repeated_param 'Any', :args
+  end
+
+  def flatten_args(*args)
+    args.flatten()
+  end
+end

data/lib/puppet/functions/floor.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Returns the largest `Integer` less or equal to the argument.
+# Takes a single numeric value as an argument.
+#
+# This function is backwards compatible with the same function in stdlib
+# and accepts a `Numeric` value. A `String` that can be converted
+# to a floating point number can also be used in this version - but this
+# is deprecated.
+#
+# In general convert string input to `Numeric` before calling this function
+# to have full control over how the conversion is done.
+#
+Puppet::Functions.create_function(:floor) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  dispatch :on_string do
+    param 'String', :val
+  end
+
+  def on_numeric(x)
+    x.floor
+  end
+
+  def on_string(x)
+    Puppet.warn_once('deprecations', 'floor_function_numeric_coerce_string',
+                     _("The floor() function's auto conversion of String to Float is deprecated - change to convert input before calling"))
+
+    begin
+      Float(x).floor
+    rescue TypeError, ArgumentError => _e
+      # TRANSLATORS: 'floor' is a name and should not be translated
+      raise(ArgumentError, _('floor(): cannot convert given value to a floating point value.'))
+    end
+  end
+end