openvox 7.37.1

data/lib/puppet/functions/flatten.rb

@@ -0,0 +1,64 @@
+# 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,37 @@
+# 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

data/lib/puppet/functions/get.rb

@@ -0,0 +1,150 @@
+# Digs into a value with dot notation to get a value from within a structure.
+#
+# **To dig into a given value**, call the function with (at least) two arguments:
+#
+# * The **first** argument must be an Array, or Hash. Value can also be `undef`
+#   (which also makes the result `undef` unless a _default value_ is given).
+# * The **second** argument must be a _dot notation navigation string_.
+# * The **optional third** argument can be any type of value and it is used
+#   as the _default value_ if the function would otherwise return `undef`.
+# * An **optional lambda** for error handling taking one `Error` argument.
+#
+# **Dot notation navigation string** -
+# The dot string consists of period `.` separated segments where each
+# segment is either the index into an array or the value of a hash key.
+# If a wanted key contains a period it must be quoted to avoid it being
+# taken as a segment separator. Quoting can be done with either
+# single quotes `'` or double quotes `"`. If a segment is
+# a decimal number it is converted to an Integer index. This conversion
+# can be prevented by quoting the value.
+#
+# @example Navigating into a value
+# ```puppet
+# #get($facts, 'os.family')
+# $facts.get('os.family')
+# ```
+# Would both result in the value of `$facts['os']['family']`
+#
+# @example Getting the value from an expression
+# ```puppet
+# get([1,2,[{'name' =>'waldo'}]], '2.0.name')
+# ```
+# Would result in `'waldo'`
+#
+# @example Using a default value
+# ```puppet
+# get([1,2,[{'name' =>'waldo'}]], '2.1.name', 'not waldo')
+#
+# ```
+# Would result in `'not waldo'`
+#
+# @example Quoting a key with period
+# ```puppet
+# $x = [1, 2, { 'readme.md' => "This is a readme."}]
+# $x.get('2."readme.md"')
+# ```
+#
+# @example Quoting a numeric string
+# ```puppet
+# $x = [1, 2, { '10' => "ten"}]
+# $x.get('2."0"')
+# ```
+#
+# **Error Handling** - There are two types of common errors that can
+# be handled by giving the function a code block to execute.
+# (A third kind or error; when the navigation string has syntax errors
+# (for example an empty segment or unbalanced quotes) will always raise
+# an error).
+#
+# The given block will be given an instance of the `Error` data type,
+# and it has methods to extract `msg`, `issue_code`, `kind`, and
+# `details`.
+#
+# The `msg` will be a preformatted message describing the error.
+# This is the error message that would have surfaced if there was
+# no block to handle the error.
+#
+# The `kind` is the string `'SLICE_ERROR'` for both kinds of errors,
+# and the `issue_code` is either the string `'EXPECTED_INTEGER_INDEX'`
+# for an attempt to index into an array with a String,
+# or `'EXPECTED_COLLECTION'` for an attempt to index into something that
+# is not a Collection.
+#
+# The `details` is a Hash that for both issue codes contain the
+# entry `'walked_path'` which is an Array with each key in the
+# progression of the dig up to the place where the error occurred.
+#
+# For an `EXPECTED_INTEGER_INDEX`-issue the detail `'index_type'` is
+# set to the data type of the index value and for an
+# `'EXPECTED_COLLECTION'`-issue the detail `'value_type'` is set
+# to the type of the value.
+#
+# The logic in the error handling block can inspect the details,
+# and either call `fail()` with a custom error message or produce
+# the wanted value.
+#
+# If the block produces `undef` it will not be replaced with a
+# given default value.
+#
+# @example Ensure `undef` result on error
+# ```puppet
+# $x = 'blue'
+# $x.get('0.color', 'green') |$error| { undef } # result is undef
+#
+# $y = ['blue']
+# $y.get('color', 'green') |$error| { undef } # result is undef
+# ```
+#
+# @example Accessing information in the Error
+# ```puppet
+# $x = [1, 2, ['blue']]
+# $x.get('2.color') |$error| {
+#   notice("Walked path is ${error.details['walked_path']}")
+# }
+# ```
+# Would notice `Walked path is [2, color]`
+#
+# Also see:
+# * `getvar()` that takes the first segment to be the name of a variable
+#   and then delegates to this function.
+# * `dig()` function which is similar but uses an
+#   array of navigation values instead of a dot notation string.
+#
+# @since 6.0.0
+#
+Puppet::Functions.create_function(:get, Puppet::Functions::InternalFunction) do
+  dispatch :get_from_value do
+    param 'Any', :value
+    param 'String', :dotted_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable[1,1]', :block
+  end
+
+  # Gets a result from given value and a navigation string
+  #
+  def get_from_value(value, navigation, default_value = nil, &block)
+    return default_value if value.nil?
+    return value if navigation.empty?
+
+    # Note: split_key always processes the initial segment as a string even if it could be an integer.
+    # This since it is designed for lookup keys. For a numeric first segment
+    # like '0.1' the wanted result is `[0,1]`, not `["0", 1]`. The workaround here is to
+    # prefix the navigation with `"x."` thus giving split_key a first segment that is a string.
+    # The fake segment is then dropped.
+    segments = split_key("x." + navigation) {|err| _("Syntax error in dotted-navigation string")}
+    segments.shift
+
+    begin
+      result = call_function('dig', value, *segments)
+      return result.nil? ? default_value : result
+    rescue Puppet::ErrorWithData => e
+      if block_given?
+        yield(e.error_data)
+      else
+        raise e
+      end
+    end
+  end
+  # reuse the split_key parser used also by lookup
+  include Puppet::Pops::Lookup::SubLookup
+end

data/lib/puppet/functions/getvar.rb

@@ -0,0 +1,87 @@
+# Digs into a variable with dot notation to get a value from a structure.
+#
+# **To get the value from a variable** (that may or may not exist), call the function with
+# one or two arguments:
+#
+# * The **first** argument must be a string, and must start with a variable name without leading `$`,
+#   for example `get('facts')`. The variable name can be followed
+#   by a _dot notation navigation string_ to dig out a value in the array or hash value
+#   of the variable.
+# * The **optional second** argument can be any type of value and it is used as the
+#   _default value_ if the function would otherwise return `undef`.
+# * An **optional lambda** for error handling taking one `Error` argument.
+#
+# **Dot notation navigation string** -
+# The dot string consists of period `.` separated segments where each
+# segment is either the index into an array or the value of a hash key.
+# If a wanted key contains a period it must be quoted to avoid it being
+# taken as a segment separator. Quoting can be done with either
+# single quotes `'` or double quotes `"`. If a segment is
+# a decimal number it is converted to an Integer index. This conversion
+# can be prevented by quoting the value.
+#
+# @example Getting the value of a variable
+# ```puppet
+# getvar('facts') # results in the value of $facts
+# ```
+#
+# @example Navigating into a variable
+# ```puppet
+# getvar('facts.os.family') # results in the value of $facts['os']['family']
+# ```
+#
+# @example Using a default value
+# ```puppet
+# $x = [1,2,[{'name' =>'waldo'}]]
+# getvar('x.2.1.name', 'not waldo')
+# # results in 'not waldo'
+# ```
+#
+# For further examples and how to perform error handling, see the `get()` function
+# which this function delegates to after having resolved the variable value.
+#
+# @since 6.0.0 - the ability to dig into the variable's value with dot notation.
+#
+Puppet::Functions.create_function(:getvar, Puppet::Functions::InternalFunction) do
+  dispatch :get_from_navigation do
+    scope_param
+     param 'Pattern[/\A(?:::)?(?:[a-z]\w*::)*[a-z_]\w*(?:\.|\Z)/]', :get_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable[1,1]', :block
+  end
+
+  argument_mismatch :invalid_variable_error do
+    param 'String', :get_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable', :block
+  end
+
+  def invalid_variable_error(navigation, default_value=nil, &block)
+    _("The given string does not start with a valid variable name")
+  end
+
+  # Gets a result from a navigation string starting with $var
+  #
+  def get_from_navigation(scope, navigation, default_value = nil, &block)
+    # asserted to start with a valid variable name - dig out the variable
+    matches = navigation.match(/^((::)?(\w+::)*\w+)(.*)\z/)
+    navigation = matches[4]
+    if navigation[0] == '.'
+      navigation = navigation[1..-1]
+    else
+      unless navigation.empty?
+        raise ArgumentError, _("First character after var name in get string must be a '.' - got %{char}") % {char: navigation[0]}
+      end
+    end
+    get_from_var_name(scope, matches[1], navigation, default_value, &block)
+  end
+
+  # Gets a result from a $var name and a navigation string
+  #
+  def get_from_var_name(scope, var_string, navigation, default_value = nil, &block)
+    catch(:undefined_variable) do
+      return call_function_with_scope(scope,'get', scope.lookupvar(var_string), navigation, default_value, &block)
+    end
+    default_value
+  end
+end

data/lib/puppet/functions/group_by.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Groups the collection by result of the block. Returns a hash where the keys are the evaluated result from the block
+# and the values are arrays of elements in the collection that correspond to the key.
+Puppet::Functions.create_function(:group_by) do
+  # @param collection A collection of things to group.
+  # @example Group array of strings by length, results in e.g. `{ 1 => [a, b], 2 => [ab] }`
+  #   ```puppet
+  #   [a, b, ab].group_by |$s| { $s.length }
+  #   ```
+  # @example Group array of strings by length and index, results in e.g. `{1 => ['a'], 2 => ['b', 'ab']}`
+  #   ```puppet
+  #   [a, b, ab].group_by |$i, $s| { $i%2 + $s.length }
+  #   ```
+  # @example Group hash iterating by key-value pair, results in e.g. `{ 2 => [['a', [1, 2]]], 1 => [['b', [1]]] }`
+  #   ```puppet
+  #   { a => [1, 2], b => [1] }.group_by |$kv| { $kv[1].length }
+  #   ```
+  # @example Group hash iterating by key and value, results in e.g. `{ 2 => [['a', [1, 2]]], 1 => [['b', [1]]] }`
+  #   ```puppet
+  #    { a => [1, 2], b => [1] }.group_by |$k, $v| { $v.length }
+  #   ```
+  dispatch :group_by_1 do
+    required_param 'Collection', :collection
+    block_param 'Callable[1,1]', :block
+    return_type 'Hash'
+  end
+
+  dispatch :group_by_2a do
+    required_param 'Array', :array
+    block_param 'Callable[2,2]', :block
+    return_type 'Hash'
+  end
+
+  dispatch :group_by_2 do
+    required_param 'Collection', :collection
+    block_param 'Callable[2,2]', :block
+    return_type 'Hash'
+  end
+
+  def group_by_1(collection)
+    collection.group_by do |item|
+      yield(item)
+    end.freeze
+  end
+
+  def group_by_2a(array)
+    grouped = array.size.times.zip(array).group_by do |k, v|
+      yield(k, v)
+    end
+
+    grouped.each_with_object({}) do |(k, v), hsh|
+      hsh[k] = v.map { |item| item[1] }
+    end.freeze
+  end
+
+  def group_by_2(collection)
+    collection.group_by do |k, v|
+      yield(k, v)
+    end.freeze
+  end
+end

data/lib/puppet/functions/hiera.rb

@@ -0,0 +1,89 @@
+require 'hiera/puppet_function'
+
+# Performs a standard priority lookup of the hierarchy and returns the most specific value
+# for a given key. The returned value can be any type of data.
+#
+# This function is deprecated in favor of the `lookup` function. While this function
+# continues to work, it does **not** support:
+# * `lookup_options` stored in the data
+# * lookup across global, environment, and module layers
+#
+# 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 `hiera` function does **not** find all matches throughout a hierarchy, instead
+# returning the first specific value starting at the top of the hierarchy. To search
+# throughout a hierarchy, use the `hiera_array` or `hiera_hash` functions.
+#
+# @example Using `hiera`
+#
+# ```yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming web01.example.com.yaml:
+# # users:
+# #   - "Amy Barry"
+# #   - "Carrie Douglas"
+#
+# # Assuming common.yaml:
+# users:
+#   admins:
+#     - "Edith Franklin"
+#     - "Ginny Hamilton"
+#   regular:
+#     - "Iris Jackson"
+#     - "Kelly Lambert"
+# ```
+#
+# ```puppet
+# # Assuming we are not web01.example.com:
+#
+# $users = hiera('users', undef)
+#
+# # $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
+# #                  regular => ["Iris Jackson", "Kelly Lambert"]}
+# ```
+#
+# 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` with a lambda
+#
+# ```puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# $users = hiera('users') | $key | { "Key \'${key}\' not found" }
+#
+# # $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
+# #                  regular => ["Iris Jackson", "Kelly Lambert"]}
+# # If hiera couldn't match its key, it would return the lambda result,
+# # "Key 'users' not found".
+# ```
+#
+# The returned value's data type depends on the types of the results. In the example
+# above, Hiera matches the 'users' key and returns it as a hash.
+#
+# 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, Hiera::PuppetFunction) do
+  init_dispatch
+end

data/lib/puppet/functions/hiera_array.rb

@@ -0,0 +1,81 @@
+require 'hiera/puppet_function'
+
+# Finds all matches of a key throughout the hierarchy and returns them as a single flattened
+# array of unique values. If any of the matched values are arrays, they're flattened and
+# included in the results. This is called an
+# [array merge lookup](https://puppet.com/docs/hiera/latest/lookup_types.html#array-merge).
+#
+# This function is deprecated in favor of the `lookup` function. While this function
+# continues to work, it does **not** support:
+# * `lookup_options` stored in the data
+# * lookup across global, environment, and module layers
+#
+# The `hiera_array` 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.
+#
+# @example Using `hiera_array`
+#
+# ```yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming common.yaml:
+# # users:
+# #   - 'cdouglas = regular'
+# #   - 'efranklin = regular'
+#
+# # Assuming web01.example.com.yaml:
+# # users: 'abarry = admin'
+# ```
+#
+# ```puppet
+# $allusers = hiera_array('users', undef)
+#
+# # $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+# ```
+#
+# 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_array` with a lambda
+#
+# ```puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# $allusers = hiera_array('users') | $key | { "Key \'${key}\' not found" }
+#
+# # $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+# # If hiera_array couldn't match its key, it would return the lambda result,
+# # "Key 'users' not found".
+# ```
+#
+# `hiera_array` expects that all values returned will be strings or arrays. If any matched
+# value is a hash, Puppet raises a type mismatch error.
+#
+# 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_array, Hiera::PuppetFunction) do
+  init_dispatch
+
+  def merge_type
+    :unique
+  end
+end

data/lib/puppet/functions/hiera_hash.rb

@@ -0,0 +1,92 @@
+require 'hiera/puppet_function'
+
+# Finds all matches of a key throughout the hierarchy and returns them in a merged hash.
+#
+# This function is deprecated in favor of the `lookup` function. While this function
+# continues to work, it does **not** support:
+# * `lookup_options` stored in the data
+# * lookup across global, environment, and module layers
+#
+# If any of the matched hashes share keys, the final hash uses the value from the
+# highest priority match. This is called a
+# [hash merge lookup](https://puppet.com/docs/hiera/latest/lookup_types.html#hash-merge).
+#
+# The merge strategy is determined by Hiera's
+# [`:merge_behavior`](https://puppet.com/docs/hiera/latest/configuring.html#mergebehavior)
+# setting.
+#
+# The `hiera_hash` 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.
+#
+# @example Using `hiera_hash`
+#
+# ```yaml
+# # Assuming hiera.yaml
+# # :hierarchy:
+# #   - web01.example.com
+# #   - common
+#
+# # Assuming common.yaml:
+# # users:
+# #   regular:
+# #     'cdouglas': 'Carrie Douglas'
+#
+# # Assuming web01.example.com.yaml:
+# # users:
+# #   administrators:
+# #     'aberry': 'Amy Berry'
+# ```
+#
+# ```puppet
+# # Assuming we are not web01.example.com:
+#
+# $allusers = hiera_hash('users', undef)
+#
+# # $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+# #                     administrators => {"aberry" => "Amy Berry"}}
+# ```
+#
+# 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_hash` with a lambda
+#
+# ```puppet
+# # Assuming the same Hiera data as the previous example:
+#
+# $allusers = hiera_hash('users') | $key | { "Key \'${key}\' not found" }
+#
+# # $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+# #                     administrators => {"aberry" => "Amy Berry"}}
+# # If hiera_hash couldn't match its key, it would return the lambda result,
+# # "Key 'users' not found".
+# ```
+#
+# `hiera_hash` expects that all values returned will be hashes. If any of the values
+# found in the data sources are strings or arrays, Puppet raises a type mismatch error.
+#
+# 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_hash, Hiera::PuppetFunction) do
+  init_dispatch
+
+  def merge_type
+    :hash
+  end
+end