openvox 8.19.0

data/lib/puppet/functions/lookup.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+# Uses the Puppet lookup system to retrieve a value for a given key. By default,
+# this returns the first value found (and fails compilation if no values are
+# available), but you can configure it to merge multiple values into one, fail
+# gracefully, and more.
+#
+# When looking up a key, Puppet will search up to three tiers of data, in the
+# following order:
+#
+# 1. Hiera.
+# 2. The current environment's data provider.
+# 3. The indicated module's data provider, if the key is of the form
+#    `<MODULE NAME>::<SOMETHING>`.
+#
+# #### Arguments
+#
+# You must provide the name of a key to look up, and can optionally provide other
+# arguments. You can combine these arguments in the following ways:
+#
+# * `lookup( <NAME>, [<VALUE TYPE>], [<MERGE BEHAVIOR>], [<DEFAULT VALUE>] )`
+# * `lookup( [<NAME>], <OPTIONS HASH> )`
+# * `lookup( as above ) |$key| { # lambda returns a default value }`
+#
+# Arguments in `[square brackets]` are optional.
+#
+# The arguments accepted by `lookup` are as follows:
+#
+# 1. `<NAME>` (string or array) --- The name of the key to look up.
+#     * This can also be an array of keys. If Puppet doesn't find anything for the
+#     first key, it will try again with the subsequent ones, only resorting to a
+#     default value if none of them succeed.
+# 2. `<VALUE TYPE>` (data type) --- A
+# [data type](https://puppet.com/docs/puppet/latest/lang_data_type.html)
+# that must match the retrieved value; if not, the lookup (and catalog
+# compilation) will fail. Defaults to `Data` (accepts any normal value).
+# 3. `<MERGE BEHAVIOR>` (string or hash; see **"Merge Behaviors"** below) ---
+# Whether (and how) to combine multiple values. If present, this overrides any
+# merge behavior specified in the data sources. Defaults to no value; Puppet will
+# use merge behavior from the data sources if present, and will otherwise do a
+# first-found lookup.
+# 4. `<DEFAULT VALUE>` (any normal value) --- If present, `lookup` returns this
+# when it can't find a normal value. Default values are never merged with found
+# values. Like a normal value, the default must match the value type. Defaults to
+# no value; if Puppet can't find a normal value, the lookup (and compilation) will
+# fail.
+# 5. `<OPTIONS HASH>` (hash) --- Alternate way to set the arguments above, plus
+# some less-common extra options. If you pass an options hash, you can't combine
+# it with any regular arguments (except `<NAME>`). An options hash can have the
+# following keys:
+#     * `'name'` --- Same as `<NAME>` (argument 1). You can pass this as an
+#     argument or in the hash, but not both.
+#     * `'value_type'` --- Same as `<VALUE TYPE>` (argument 2).
+#     * `'merge'` --- Same as `<MERGE BEHAVIOR>` (argument 3).
+#     * `'default_value'` --- Same as `<DEFAULT VALUE>` (argument 4).
+#     * `'default_values_hash'` (hash) --- A hash of lookup keys and default
+#     values. If Puppet can't find a normal value, it will check this hash for the
+#     requested key before giving up. You can combine this with `default_value` or
+#     a lambda, which will be used if the key isn't present in this hash. Defaults
+#     to an empty hash.
+#     * `'override'` (hash) --- A hash of lookup keys and override values. Puppet
+#     will check for the requested key in the overrides hash _first;_ if found, it
+#     returns that value as the _final_ value, ignoring merge behavior. Defaults
+#     to an empty hash.
+#
+# Finally, `lookup` can take a lambda, which must accept a single parameter.
+# This is yet another way to set a default value for the lookup; if no results are
+# found, Puppet will pass the requested key to the lambda and use its result as
+# the default value.
+#
+# #### Merge Behaviors
+#
+# Puppet lookup uses a hierarchy of data sources, and a given key might have
+# values in multiple sources. By default, Puppet returns the first value it finds,
+# but it can also continue searching and merge all the values together.
+#
+# > **Note:** Data sources can use the special `lookup_options` metadata key to
+# request a specific merge behavior for a key. The `lookup` function will use that
+# requested behavior unless you explicitly specify one.
+#
+# The valid merge behaviors are:
+#
+# * `'first'` --- Returns the first value found, with no merging. Puppet lookup's
+# default behavior.
+# * `'unique'` (called "array merge" in classic Hiera) --- Combines any number of
+# arrays and scalar values to return a merged, flattened array with all duplicate
+# values removed. The lookup will fail if any hash values are found.
+# * `'hash'` --- Combines the keys and values of any number of hashes to return a
+# merged hash. If the same key exists in multiple source hashes, Puppet will use
+# the value from the highest-priority data source; it won't recursively merge the
+# values.
+# * `'deep'` --- Combines the keys and values of any number of hashes to return a
+# merged hash. If the same key exists in multiple source hashes, Puppet will
+# recursively merge hash or array values (with duplicate values removed from
+# arrays). For conflicting scalar values, the highest-priority value will win.
+# * `{'strategy' => 'first'}`, `{'strategy' => 'unique'}`,
+# or `{'strategy' => 'hash'}` --- Same as the string versions of these merge behaviors.
+# * `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
+# but can adjust the merge with additional options. The available options are:
+#     * `'knockout_prefix'` (string) --- A string prefix to indicate a
+#     value should be _removed_ from the final result. If a value is exactly equal
+#     to the prefix, it will knockout the entire element. Defaults to `undef`, which
+#     disables this feature.
+#     * `'sort_merged_arrays'` (boolean) --- Whether to sort all arrays that are
+#     merged together. Defaults to `false`.
+#     * `'merge_hash_arrays'` (boolean) --- Whether to merge hashes within arrays.
+#     Defaults to `false`.
+#
+# @example Look up a key and return the first value found
+#
+#     lookup('ntp::service_name')
+#
+# @example Do a unique merge lookup of class names, then add all of those classes to the catalog (like `hiera_include`)
+#
+#     lookup('classes', Array[String], 'unique').include
+#
+# @example Do a deep hash merge lookup of user data, but let higher priority sources remove values by prefixing them with `--`
+#
+#     lookup( { 'name'  => 'users',
+#               'merge' => {
+#                 'strategy'        => 'deep',
+#                 'knockout_prefix' => '--',
+#               },
+#     })
+#
+# @since 4.0.0
+Puppet::Functions.create_function(:lookup, Puppet::Functions::InternalFunction) do
+  local_types do
+    type 'NameType         = Variant[String, Array[String]]'
+    type 'ValueType        = Type'
+    type 'DefaultValueType = Any'
+    type 'MergeType        = Variant[String[1], Hash[String, Scalar]]'
+    type 'BlockType        = Callable[NameType]'
+    type "OptionsWithName  = Struct[{\
+      name                => NameType,\
+      value_type          => Optional[ValueType],\
+      default_value       => Optional[DefaultValueType],\
+      override            => Optional[Hash[String,Any]],\
+      default_values_hash => Optional[Hash[String,Any]],\
+      merge               => Optional[MergeType]\
+    }]"
+    type "OptionsWithoutName = Struct[{\
+      value_type          => Optional[ValueType],\
+      default_value       => Optional[DefaultValueType],\
+      override            => Optional[Hash[String,Any]],\
+      default_values_hash => Optional[Hash[String,Any]],\
+      merge               => Optional[MergeType]\
+    }]"
+  end
+
+  dispatch :lookup_1 do
+    scope_param
+    param           'NameType',       :name
+    optional_param  'ValueType',      :value_type
+    optional_param  'MergeType',      :merge
+  end
+
+  dispatch :lookup_2 do
+    scope_param
+    param 'NameType',                 :name
+    param 'Optional[ValueType]',      :value_type
+    param 'Optional[MergeType]',      :merge
+    param 'DefaultValueType',         :default_value
+  end
+
+  dispatch :lookup_3 do
+    scope_param
+    param                'NameType',   :name
+    optional_param       'ValueType',  :value_type
+    optional_param       'MergeType',  :merge
+    required_block_param 'BlockType',  :block
+  end
+
+  # Lookup without name. Name then becomes a required entry in the options hash
+  dispatch :lookup_4 do
+    scope_param
+    param                'OptionsWithName', :options_hash
+    optional_block_param 'BlockType',       :block
+  end
+
+  # Lookup using name and options hash.
+  dispatch :lookup_5 do
+    scope_param
+    param                'Variant[String,Array[String]]', :name
+    param                'OptionsWithoutName',            :options_hash
+    optional_block_param 'BlockType',                     :block
+  end
+
+  def lookup_1(scope, name, value_type = nil, merge = nil)
+    do_lookup(scope, name, value_type, nil, false, {}, {}, merge)
+  end
+
+  def lookup_2(scope, name, value_type, merge, default_value)
+    do_lookup(scope, name, value_type, default_value, true, {}, {}, merge)
+  end
+
+  def lookup_3(scope, name, value_type = nil, merge = nil, &block)
+    do_lookup(scope, name, value_type, nil, false, {}, {}, merge, &block)
+  end
+
+  def lookup_4(scope, options_hash, &block)
+    do_lookup(scope, options_hash['name'], *hash_args(options_hash), &block)
+  end
+
+  def lookup_5(scope, name, options_hash, &block)
+    do_lookup(scope, name, *hash_args(options_hash), &block)
+  end
+
+  def do_lookup(scope, name, value_type, default_value, has_default, override, default_values_hash, merge, &block)
+    Puppet::Pops::Lookup.lookup(name, value_type, default_value, has_default, merge,
+                                Puppet::Pops::Lookup::Invocation.new(scope, override, default_values_hash), &block)
+  end
+
+  def hash_args(options_hash)
+    [
+      options_hash['value_type'],
+      options_hash['default_value'],
+      options_hash.include?('default_value'),
+      options_hash['override'] || {},
+      options_hash['default_values_hash'] || {},
+      options_hash['merge']
+    ]
+  end
+end

data/lib/puppet/functions/lstrip.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Strips leading spaces from a String
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes all leading ASCII white space characters such as space, tab, newline, and return.
+#   It does not remove other space-like characters like hard space (Unicode U+00A0). (Tip, `/^[[:space:]]/` regular expression
+#   matches all space-like characters).
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is processed and the conversion is not recursive.
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# @example Removing leading space from a String
+# ```puppet
+# "\n\thello ".lstrip()
+# lstrip("\n\thello ")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing leading space from strings in an Array
+# ```puppet
+# ["\n\thello ", "\n\thi "].lstrip()
+# lstrip(["\n\thello ", "\n\thi "])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:lstrip) do
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_iterable do
+    param 'Iterable[Variant[String, Numeric]]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.lstrip
+  end
+
+  def on_iterable(a)
+    a.map { |x| do_lstrip(x) }
+  end
+
+  def do_lstrip(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.lstrip : x
+  end
+end

data/lib/puppet/functions/map.rb

@@ -0,0 +1,137 @@
+# 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 containing the results.
+#
+# 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 `map` function
+#
+# `$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `$transformed_data = map($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.
+#
+# @example Using the `map` function with an array and a one-parameter lambda
+#
+# ```puppet
+# # For the array $data, return an array containing each value multiplied by 10
+# $data = [1,2,3]
+# $transformed_data = $data.map |$items| { $items * 10 }
+# # $transformed_data contains [10,20,30]
+# ```
+#
+# 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]`.
+#
+# @example Using the `map` function with a hash and a one-parameter lambda
+#
+# ```puppet
+# # For the hash $data, return an array containing the keys
+# $data = {'a'=>1,'b'=>2,'c'=>3}
+# $transformed_data = $data.map |$items| { $items[0] }
+# # $transformed_data contains ['a','b','c']
+# ```
+#
+# 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 `map` function with an array and a two-parameter lambda
+#
+# ```puppet
+# # For the array $data, return an array containing the indexes
+# $data = [1,2,3]
+# $transformed_data = $data.map |$index,$value| { $index }
+# # $transformed_data contains [0,1,2]
+# ```
+#
+# 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 `map` function with a hash and a two-parameter lambda
+#
+# ```puppet
+# # For the hash $data, return an array containing each value
+# $data = {'a'=>1,'b'=>2,'c'=>3}
+# $transformed_data = $data.map |$key,$value| { $value }
+# # $transformed_data contains [1,2,3]
+# ```
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:map) do
+  dispatch :map_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :map_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :map_Enumerable_2 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :map_Enumerable_1 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[1,1]', :block
+  end
+
+  def map_Hash_1(hash)
+    result = []
+    begin
+      hash.each { |x, y| result << yield([x, y]) }
+    rescue StopIteration
+    end
+    result
+  end
+
+  def map_Hash_2(hash)
+    result = []
+    begin
+      hash.each { |x, y| result << yield(x, y) }
+    rescue StopIteration
+    end
+    result
+  end
+
+  def map_Enumerable_1(enumerable)
+    result = []
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    begin
+      enum.each do |val|
+        result << yield(val)
+      end
+    rescue StopIteration
+    end
+    result
+  end
+
+  def map_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.map { |entry| yield(*entry) }
+    else
+      result = []
+      begin
+        enum.each_with_index do |val, index|
+          result << yield(index, val)
+        end
+      rescue StopIteration
+      end
+      result
+    end
+  end
+end

data/lib/puppet/functions/match.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# Matches a regular expression against a string and returns an array containing the match
+# and any matched capturing groups.
+#
+# The first argument is a string or array of strings. The second argument is either a
+# regular expression, regular expression represented as a string, or Regex or Pattern
+# data type that the function matches against the first argument.
+#
+# The returned array contains the entire match at index 0, and each captured group at
+# subsequent index values. If the value or expression being matched is an array, the
+# function returns an array with mapped match results.
+#
+# If the function doesn't find a match, it returns 'undef'.
+#
+# @example Matching a regular expression in a string
+#
+# ```puppet
+# $matches = "abc123".match(/[a-z]+[1-9]+/)
+# # $matches contains [abc123]
+# ```
+#
+# @example Matching a regular expressions with grouping captures in a string
+#
+# ```puppet
+# $matches = "abc123".match(/([a-z]+)([1-9]+)/)
+# # $matches contains [abc123, abc, 123]
+# ```
+#
+# @example Matching a regular expression with grouping captures in an array of strings
+#
+# ```puppet
+# $matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
+# # $matches contains [[abc123, abc, 123], [def456, def, 456]]
+# ```
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:match) do
+  dispatch :match do
+    param 'String', :string
+    param 'Variant[Any, Type]', :pattern
+  end
+
+  dispatch :enumerable_match do
+    param 'Array[String]', :string
+    param 'Variant[Any, Type]', :pattern
+  end
+
+  def initialize(closure_scope, loader)
+    super
+
+    # Make this visitor shared among all instantiations of this function since it is faster.
+    # This can be used because it is not possible to replace
+    # a puppet runtime (where this function is) without a reboot. If you model a function in a module after
+    # this class, use a regular instance variable instead to enable reloading of the module without reboot
+    #
+    @@match_visitor ||= Puppet::Pops::Visitor.new(self, "match", 1, 1)
+  end
+
+  # Matches given string against given pattern and returns an Array with matches.
+  # @param string [String] the string to match
+  # @param pattern [String, Regexp, Puppet::Pops::Types::PPatternType, Puppet::Pops::PRegexpType, Array] the pattern
+  # @return [Array<String>] matches where first match is the entire match, and index 1-n are captures from left to right
+  #
+  def match(string, pattern)
+    @@match_visitor.visit_this_1(self, pattern, string)
+  end
+
+  # Matches given Array[String] against given pattern and returns an Array with mapped match results.
+  #
+  # @param array [Array<String>] the array of strings to match
+  # @param pattern [String, Regexp, Puppet::Pops::Types::PPatternType, Puppet::Pops::PRegexpType, Array] the pattern
+  # @return [Array<Array<String, nil>>] Array with matches (see {#match}), non matching entries produce a nil entry
+  #
+  def enumerable_match(array, pattern)
+    array.map { |s| match(s, pattern) }
+  end
+
+  protected
+
+  def match_Object(obj, s)
+    msg = _("match() expects pattern of T, where T is String, Regexp, Regexp[r], Pattern[p], or Array[T]. Got %{klass}") % { klass: obj.class }
+    raise ArgumentError, msg
+  end
+
+  def match_String(pattern_string, s)
+    do_match(s, Regexp.new(pattern_string))
+  end
+
+  def match_Regexp(regexp, s)
+    do_match(s, regexp)
+  end
+
+  def match_PTypeAliasType(alias_t, s)
+    match(s, alias_t.resolved_type)
+  end
+
+  def match_PVariantType(var_t, s)
+    # Find first matching type (or error out if one of the variants is not acceptable)
+    result = nil
+    var_t.types.find { |t| result = match(s, t) }
+    result
+  end
+
+  def match_PRegexpType(regexp_t, s)
+    raise ArgumentError, _("Given Regexp Type has no regular expression") unless regexp_t.pattern
+
+    do_match(s, regexp_t.regexp)
+  end
+
+  def match_PPatternType(pattern_t, s)
+    # Since we want the actual match result (not just a boolean), an iteration over
+    # Pattern's regular expressions is needed. (They are of PRegexpType)
+    result = nil
+    pattern_t.patterns.find { |pattern| result = match(s, pattern) }
+    result
+  end
+
+  # Returns the first matching entry
+  def match_Array(array, s)
+    result = nil
+    array.flatten.find { |entry| result = match(s, entry) }
+    result
+  end
+
+  private
+
+  def do_match(s, regexp)
+    result = regexp.match(s)
+    result.to_a if result
+  end
+end