openvox 7.37.1

data/lib/puppet/functions/hiera_include.rb

@@ -0,0 +1,104 @@
+require 'hiera/puppet_function'
+
+# Assigns classes to a node using an
+# [array merge lookup](https://puppet.com/docs/hiera/latest/lookup_types.html#array-merge)
+# that retrieves the value for a user-specified key from Hiera's data.
+#
+# This function is deprecated in favor of the `lookup` function in combination with `include`.
+# While this function continues to work, it does **not** support:
+# * `lookup_options` stored in the data
+# * lookup across global, environment, and module layers
+#
+# @example Using `lookup` and `include` instead of of the deprecated `hiera_include`
+#
+# ```puppet
+# # In site.pp, outside of any node definitions and below any top-scope variables:
+# lookup('classes', Array[String], 'unique').include
+# ```
+#
+# The `hiera_include` function requires:
+#
+# - A string key name to use for classes.
+# - A call to this function (i.e. `hiera_include('classes')`) in your environment's
+# `sites.pp` manifest, outside of any node definitions and below any top-scope variables
+# that Hiera uses in lookups.
+# - `classes` keys in the appropriate Hiera data sources, with an array for each
+# `classes` key and each value of the array containing the name of a class.
+#
+# The function takes up to three arguments, in this order:
+#
+# 1. A string key that Hiera searches for in the hierarchy. **Required**.
+# 2. An optional default value to return if Hiera doesn't find anything matching the key.
+#     * If this argument isn't provided and this function results in a lookup failure, Puppet
+#     fails with a compilation error.
+# 3. The optional name of an arbitrary
+# [hierarchy level](https://puppet.com/docs/hiera/latest/hierarchy.html) to insert at the
+# top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+#     * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+#     searching the rest of the hierarchy.
+#
+# The function uses an
+# [array merge lookup](https://puppet.com/docs/hiera/latest/lookup_types.html#array-merge)
+# to retrieve the `classes` array, so every node gets every class from the hierarchy.
+#
+# @example Using `hiera_include`
+#
+# ```yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming web01.example.com.yaml:
+# # classes:
+# #   - apache::mod::php
+#
+# # Assuming common.yaml:
+# # classes:
+# #   - apache
+# ```
+#
+# ```puppet
+# # In site.pp, outside of any node definitions and below any top-scope variables:
+# hiera_include('classes', undef)
+#
+# # Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+# ```
+#
+# You can optionally generate the default value with a
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
+# takes one parameter.
+#
+# @example Using `hiera_include` with a lambda
+#
+# ```puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# # In site.pp, outside of any node definitions and below any top-scope variables:
+# hiera_include('classes') | $key | {"Key \'${key}\' not found" }
+#
+# # Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+# # If hiera_include couldn't match its key, it would return the lambda result,
+# # "Key 'classes' not found".
+# ```
+#
+# See
+# [the 'Using the lookup function' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html) for how to perform lookup of data.
+# Also see
+# [the 'Using the deprecated hiera functions' documentation](https://puppet.com/docs/puppet/latest/hiera_automatic.html)
+# for more information about the Hiera 3 functions.
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:hiera_include, Hiera::PuppetFunction) do
+  init_dispatch
+
+  def merge_type
+    :unique
+  end
+
+  def post_lookup(scope, key, value)
+    raise Puppet::ParseError, _("Could not find data item %{key}") % { key: key } if value.nil?
+    call_function_with_scope(scope, 'include', value) unless value.empty?
+  end
+end

data/lib/puppet/functions/hocon_data.rb

@@ -0,0 +1,41 @@
+# The `hocon_data` is a hiera 5 `data_hash` data provider function.
+# See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
+# how to use this function.
+#
+# Note that this function is not supported without a hocon library being present.
+#
+# @since 4.9.0
+#
+Puppet::Functions.create_function(:hocon_data) do
+  unless Puppet.features.hocon?
+    raise Puppet::DataBinding::LookupError, _('Lookup using Hocon data_hash function is not supported without hocon library')
+  end
+
+  require 'hocon'
+  require 'hocon/config_error'
+
+  dispatch :hocon_data do
+    param 'Struct[{path=>String[1]}]', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  argument_mismatch :missing_path do
+    param 'Hash', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  def hocon_data(options, context)
+    path = options['path']
+    context.cached_file_data(path) do |content|
+      begin
+        Hocon.parse(content)
+      rescue Hocon::ConfigError => ex
+        raise Puppet::DataBinding::LookupError, _("Unable to parse (%{path}): %{message}") % { path: path, message: ex.message }
+      end
+    end
+  end
+
+  def missing_path(options, context)
+    "one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this data_hash function"
+  end
+end

data/lib/puppet/functions/import.rb

@@ -0,0 +1,7 @@
+# The import function raises an error when called to inform the user that import is no longer supported.
+#
+Puppet::Functions.create_function(:import) do
+  def import(*args)
+    raise Puppet::Pops::SemanticError.new(Puppet::Pops::Issues::DISCONTINUED_IMPORT)
+  end
+end

data/lib/puppet/functions/include.rb

@@ -0,0 +1,53 @@
+# Declares one or more classes, causing the resources in them to be
+# evaluated and added to the catalog. Accepts a class name, an array of class
+# names, or a comma-separated list of class names.
+#
+# The `include` function can be used multiple times on the same class and will
+# only declare a given class once. If a class declared with `include` has any
+# parameters, Puppet will automatically look up values for them in Hiera, using
+# `<class name>::<parameter name>` as the lookup key.
+#
+# Contrast this behavior with resource-like class declarations
+# (`class {'name': parameter => 'value',}`), which must be used in only one place
+# per class and can directly set parameters. You should avoid using both `include`
+# and resource-like declarations with the same class.
+#
+# The `include` function does not cause classes to be contained in the class
+# where they are declared. For that, see the `contain` function. It also
+# does not create a dependency relationship between the declared class and the
+# surrounding class; for that, see the `require` function.
+#
+# 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
+# the resource and relationship expressions.
+#
+# - Since < 3.0.0
+# - Since 4.0.0 support for class and resource type values, absolute names
+# - Since 4.7.0 returns an `Array[Type[Class]]` of all included classes
+#
+Puppet::Functions.create_function(:include, Puppet::Functions::InternalFunction) do
+  dispatch :include 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 include(scope, *classes)
+    if Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+        {:operation => 'include'})
+    end
+
+    classes = scope.transform_and_assert_classnames(classes.flatten)
+    result = classes.map {|name| Puppet::Pops::Types::TypeFactory.host_class(name) }
+    scope.compiler.evaluate_classes(classes, scope, false)
+
+    # Result is an Array[Class, 1, n] which allows chaining other operations
+    result
+  end
+end

data/lib/puppet/functions/index.rb

@@ -0,0 +1,167 @@
+# Returns the index (or key in a hash) to a first-found value in an `Iterable` value.
+#
+# When called with a  [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+# the lambda is called repeatedly using each value in a data structure until the lambda returns a "truthy" value which
+# makes the function return the index or key, or if the end of the iteration is reached, undef is returned.
+#
+# This function can be called in two different ways; with a value to be searched for, or with
+# a lambda that determines if an entry in the iterable matches.
+#
+# When called with a lambda the function takes two mandatory arguments, in this order:
+#
+# 1. An array, hash, string, 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 (value) or two (index/key, value) parameters.
+#
+# @example Using the `index` function
+#
+# `$data.index |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `index($data) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# @example Using the `index` function with an Array and a one-parameter lambda
+#
+# ```puppet
+# $data = ["routers", "servers", "workstations"]
+# notice $data.index |$value| { $value == 'servers' } # notices 1
+# notice $data.index |$value| { $value == 'hosts'  }  # notices undef
+# ```
+#
+# @example Using the `index` function with a Hash and a one-parameter lambda
+#
+# ```puppet
+# $data = {types => ["routers", "servers", "workstations"], colors => ['red', 'blue', 'green']}
+# notice $data.index |$value| { 'servers' in $value } # notices 'types'
+# notice $data.index |$value| { 'red' in $value }     # notices 'colors'
+# ```
+# Note that the lambda gets the value and not an array with `[key, value]` as in other
+# iterative functions.
+#
+# Using a lambda that accepts two values works the same way, it simply gets the index/key 
+# as the first parameter, and the value as the second.
+#
+# @example Using the `index` function with an Array and a two-parameter lambda
+#
+# ```puppet
+# # Find the first even numbered index that has a non String value
+# $data = [key1, 1, 3, 5]
+# notice $data.index |$idx, $value| { $idx % 2 == 0 and $value !~ String } # notices 2
+# ```
+#
+# When called on a `String`, the lambda is given each character as a value. What is typically wanted is to
+# find a sequence of characters which is achieved by calling the function with a value to search for instead
+# of giving a lambda.
+#
+#
+# @example Using the `index` function with a String, search for first occurrence of a sequence of characters
+#
+# ```puppet
+# # Find first occurrence of 'ah'
+# $data = "blablahbleh"
+# notice $data.index('ah') # notices 5
+# ```
+#
+# @example Using the `index` function with a String, search for first occurrence of a regular expression
+#
+# ```puppet
+# # Find first occurrence of 'la' or 'le'
+# $data = "blablahbleh"
+# notice $data.index(/l(a|e)/ # notices 1
+# ```
+#
+# When searching in a `String` with a given value that is neither `String` nor `Regexp` the answer is always `undef`.
+# When searching in any other iterable, the value is matched against each value in the iteration using strict
+# Ruby `==` semantics. If Puppet Language semantics are wanted (where string compare is case insensitive) use a
+# lambda and the `==` operator in Puppet.
+#
+# @example Using the `index` function to search for a given value in an Array
+#
+# ```puppet
+# $data = ['routers', 'servers', 'WORKstations']
+# notice $data.index('servers')      # notices 1
+# notice $data.index('workstations') # notices undef (not matching case)
+# ```
+#
+# For an general examples that demonstrates iteration, see the Puppet
+# [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
+# documentation.
+#
+# @since 6.3.0
+#
+Puppet::Functions.create_function(:index) do
+  dispatch :index_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :index_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :index_Enumerable_2 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :index_Enumerable_1 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :string_index do
+    param 'String', :str
+    param 'Variant[String,Regexp]', :match
+  end
+
+  dispatch :index_value do
+    param 'Iterable', :enumerable
+    param 'Any', :match
+  end
+
+
+  def index_Hash_1(hash)
+    hash.each_pair { |x, y| return x if yield(y)  }
+    nil
+  end
+
+  def index_Hash_2(hash)
+    hash.each_pair.any? { |x, y| return x if yield(x, y) }
+    nil
+  end
+
+  def index_Enumerable_1(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.each { |entry| return entry[0] if yield(entry[1]) }
+    else
+      enum.each_with_index { |e, i| return i if yield(e) }
+    end
+    nil
+  end
+
+  def index_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.each { |entry| return entry[0] if yield(*entry) }
+    else
+      enum.each_with_index { |e, i| return i if yield(i, e) }
+    end
+    nil
+  end
+
+  def string_index(str, match)
+    str.index(match)
+  end
+
+  def index_value(enumerable, match)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.each { |entry| return entry[0] if entry[1] == match }
+    else
+      enum.each_with_index { |e, i| return i if e == match }
+    end
+    nil
+  end
+end

data/lib/puppet/functions/info.rb

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

data/lib/puppet/functions/inline_epp.rb

@@ -0,0 +1,60 @@
+# Evaluates an Embedded Puppet (EPP) template string and returns the rendered
+# text result as a String.
+#
+# `inline_epp('<EPP TEMPLATE STRING>', <PARAMETER HASH>)`
+#
+# The first argument to this function should be a string containing an EPP
+# template. 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 evaluate an inline EPP template and pass it the `docroot` and
+# `virtual_docroot` parameters, call the `inline_epp` function like this:
+#
+# `inline_epp('docroot: <%= $docroot %> Virtual docroot: <%= $virtual_docroot %>',
+# { '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
+# `inline_epp` function fails to pass any required parameter.
+#
+# An inline EPP template should be written as a single-quoted string or
+# [heredoc](https://puppet.com/docs/puppet/latest/lang_data_string.html#heredocs).
+# A double-quoted string is subject to expression interpolation before the string
+# is parsed as an EPP template.
+#
+# For example, to evaluate an inline EPP template using a heredoc, call the
+# `inline_epp` function like this:
+#
+# ```puppet
+# # Outputs 'Hello given argument planet!'
+# inline_epp(@(END), { x => 'given argument' })
+# <%- | $x, $y = planet | -%>
+# Hello <%= $x %> <%= $y %>!
+# END
+# ```
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:inline_epp, Puppet::Functions::InternalFunction) do
+
+  dispatch :inline_epp do
+    scope_param()
+    param 'String', :template
+    optional_param 'Hash[Pattern[/^\w+$/], Any]', :parameters
+    return_type 'Variant[String, Sensitive[String]]'
+  end
+
+  def inline_epp(scope, template, parameters = nil)
+    Puppet::Pops::Evaluator::EppEvaluator.inline_epp(scope, template, parameters)
+  end
+end

data/lib/puppet/functions/join.rb

@@ -0,0 +1,56 @@
+# Joins the values of an Array into a string with elements separated by a delimiter.
+#
+# Supports up to two arguments
+# * **values** - first argument is required and must be an an `Array`
+# * **delimiter** - second arguments is the delimiter between elements, must be a `String` if given, and defaults to an empty string.
+#
+# @example Typical use of `join`
+#
+# ```puppet
+# join(['a','b','c'], ",")
+# # Would result in: "a,b,c"
+# ```
+#
+# Note that array is flattened before elements are joined, but flattening does not extend to arrays nested in hashes or other objects.
+#
+# @example Arrays nested in hashes are not joined
+#
+# ```puppet
+# $a = [1,2, undef, 'hello', [x,y,z], {a => 2, b => [3, 4]}]
+# notice join($a, ', ')
+#
+# # would result in noticing:
+# # 1, 2, , hello, x, y, z, {"a"=>2, "b"=>[3, 4]}
+# ```
+#
+# For joining iterators and other containers of elements a conversion must first be made to
+# an `Array`. The reason for this is that there are many options how such a conversion should
+# be made.
+#
+# @example Joining the result of a reverse_each converted to an array
+# 
+# ```puppet
+# [1,2,3].reverse_each.convert_to(Array).join(', ')
+# # would result in: "3, 2, 1"
+# ```
+# @example Joining a hash
+#
+# ```puppet
+# {a => 1, b => 2}.convert_to(Array).join(', ')
+# # would result in "a, 1, b, 2"
+# ```
+#
+# For more detailed control over the formatting (including indentations and line breaks, delimiters around arrays
+# and hash entries, between key/values in hash entries, and individual formatting of values in the array)
+# see the `new` function for `String` and its formatting options for `Array` and `Hash`.
+#
+Puppet::Functions.create_function(:join) do
+  dispatch :join do
+    param 'Array', :arg
+    optional_param 'String', :delimiter
+  end
+
+  def join(arg, delimiter = '', puppet_formatting = false)
+      arg.join(delimiter)
+  end
+end

data/lib/puppet/functions/json_data.rb

@@ -0,0 +1,33 @@
+# The `json_data` is a hiera 5 `data_hash` data provider function.
+# See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
+# how to use this function.
+#
+# @since 4.8.0
+#
+Puppet::Functions.create_function(:json_data) do
+  dispatch :json_data do
+    param 'Struct[{path=>String[1]}]', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  argument_mismatch :missing_path do
+    param 'Hash', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  def json_data(options, context)
+    path = options['path']
+    context.cached_file_data(path) do |content|
+      begin
+        Puppet::Util::Json.load(content)
+      rescue Puppet::Util::Json::ParseError => ex
+        # Filename not included in message, so we add it here.
+        raise Puppet::DataBinding::LookupError, "Unable to parse (%{path}): %{message}" % { path: path, message: ex.message }
+      end
+    end
+  end
+
+  def missing_path(options, context)
+    "one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this data_hash function"
+  end
+end

data/lib/puppet/functions/keys.rb

@@ -0,0 +1,25 @@
+# Returns the keys of a hash as an Array
+#
+# @example Using `keys`
+#
+# ```puppet
+# $hsh = {"apples" => 3, "oranges" => 4 }
+# $hsh.keys()
+# keys($hsh)
+# # both results in the array ["apples", "oranges"]
+# ```
+#
+# * Note that a hash in the puppet language accepts any data value (including `undef`) unless
+#   it is constrained with a `Hash` data type that narrows the allowed data types.
+# * For an empty hash, an empty array is returned.
+# * The order of the keys is the same as the order in the hash (typically the order in which they were added).
+#
+Puppet::Functions.create_function(:keys) do
+  dispatch :keys do
+    param 'Hash', :hsh
+  end
+
+  def keys(hsh)
+    hsh.keys
+  end
+end

data/lib/puppet/functions/length.rb

@@ -0,0 +1,44 @@
+# Returns the length of an Array, Hash, String, or Binary value.
+#
+# The returned value is a positive integer indicating the number
+# of elements in the container; counting (possibly multibyte) characters for a `String`,
+# bytes in a `Binary`, number of elements in an `Array`, and number of
+# key-value associations in a Hash.
+#
+# @example Using `length`
+#
+# ```puppet
+# "roses".length()        # 5
+# length("violets")       # 7
+# [10, 20].length         # 2
+# {a => 1, b => 3}.length # 2
+# ```
+#
+# @since 5.5.0 - also supporting Binary
+#
+Puppet::Functions.create_function(:length) do
+  dispatch :collection_length do
+    param 'Collection', :arg
+  end
+
+  dispatch :string_length do
+    param 'String', :arg
+  end
+
+  dispatch :binary_length do
+    param 'Binary', :arg
+  end
+
+  def collection_length(col)
+    col.size
+  end
+
+  def string_length(s)
+    s.length
+  end
+
+  def binary_length(bin)
+    bin.length
+  end
+
+end

data/lib/puppet/functions/lest.rb

@@ -0,0 +1,55 @@
+# Calls a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+# without arguments if the value given to `lest` is `undef`.
+# Returns the result of calling the lambda if the argument is `undef`, otherwise the
+# given argument.
+#
+# The `lest` function is useful in a chain of `then` calls, or in general
+# as a guard against `undef` values. The function can be used to call `fail`, or to
+# return a default value.
+#
+# These two expressions are equivalent:
+#
+# ```puppet
+# if $x == undef { do_things() }
+# lest($x) || { do_things() }
+# ```
+#
+# @example Using the `lest` function
+#
+# ```puppet
+# $data = {a => [ b, c ] }
+# notice $data.dig(a, b, c)
+#  .then |$x| { $x * 2 }
+#  .lest || { fail("no value for $data[a][b][c]" }
+# ```
+#
+# Would fail the operation because `$data[a][b][c]` results in `undef`
+# (there is no `b` key in `a`).
+#
+# In contrast - this example:
+#
+# ```puppet
+# $data = {a => { b => { c => 10 } } }
+# notice $data.dig(a, b, c)
+#  .then |$x| { $x * 2 }
+#  .lest || { fail("no value for $data[a][b][c]" }
+# ```
+#
+# Would notice the value `20`
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:lest) do
+  dispatch :lest do
+    param 'Any', :arg
+    block_param 'Callable[0,0]', :block
+  end
+
+  def lest(arg)
+    if arg.nil?
+      yield()
+    else
+      arg
+    end
+  end
+end