openvox 8.19.0

data/lib/puppet/functions/assert_type.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Returns the given value if it is of the given
+# [data type](https://puppet.com/docs/puppet/latest/lang_data.html), or
+# otherwise either raises an error or executes an optional two-parameter
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html).
+#
+# The function takes two mandatory arguments, in this order:
+#
+# 1. The expected data type.
+# 2. A value to compare against the expected data type.
+#
+# @example Using `assert_type`
+#
+# ```puppet
+# $raw_username = 'Amy Berry'
+#
+# # Assert that $raw_username is a non-empty string and assign it to $valid_username.
+# $valid_username = assert_type(String[1], $raw_username)
+#
+# # $valid_username contains "Amy Berry".
+# # If $raw_username was an empty string or a different data type, the Puppet run would
+# # fail with an "Expected type does not match actual" error.
+# ```
+#
+# You can use an optional lambda to provide enhanced feedback. The lambda takes two
+# mandatory parameters, in this order:
+#
+# 1. The expected data type as described in the function's first argument.
+# 2. The actual data type of the value.
+#
+# @example Using `assert_type` with a warning and default value
+#
+# ```puppet
+# $raw_username = 'Amy Berry'
+#
+# # Assert that $raw_username is a non-empty string and assign it to $valid_username.
+# # If it isn't, output a warning describing the problem and use a default value.
+# $valid_username = assert_type(String[1], $raw_username) |$expected, $actual| {
+#   warning( "The username should be \'${expected}\', not \'${actual}\'. Using 'anonymous'." )
+#   'anonymous'
+# }
+#
+# # $valid_username contains "Amy Berry".
+# # If $raw_username was an empty string, the Puppet run would set $valid_username to
+# # "anonymous" and output a warning: "The username should be 'String[1, default]', not
+# # 'String[0, 0]'. Using 'anonymous'."
+# ```
+#
+# For more information about data types, see the
+# [documentation](https://puppet.com/docs/puppet/latest/lang_data.html).
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:assert_type) do
+  dispatch :assert_type do
+    param 'Type', :type
+    param 'Any', :value
+    optional_block_param 'Callable[Type, Type]', :block
+  end
+
+  dispatch :assert_type_s do
+    param 'String', :type_string
+    param 'Any', :value
+    optional_block_param 'Callable[Type, Type]', :block
+  end
+
+  # @param type [Type] the type the value must be an instance of
+  # @param value [Object] the value to assert
+  #
+  def assert_type(type, value)
+    unless Puppet::Pops::Types::TypeCalculator.instance?(type, value)
+      inferred_type = Puppet::Pops::Types::TypeCalculator.infer_set(value)
+      if block_given?
+        # Give the inferred type to allow richer comparison in the given block (if generalized
+        # information is lost).
+        #
+        value = yield(type, inferred_type)
+      else
+        raise Puppet::Pops::Types::TypeAssertionError.new(
+          Puppet::Pops::Types::TypeMismatchDescriber.singleton.describe_mismatch('assert_type():', type, inferred_type),
+          type, inferred_type
+        )
+      end
+    end
+    value
+  end
+
+  # @param type_string [String] the type the value must be an instance of given in String form
+  # @param value [Object] the value to assert
+  #
+  def assert_type_s(type_string, value, &proc)
+    t = Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
+    block_given? ? assert_type(t, value, &proc) : assert_type(t, value)
+  end
+end

data/lib/puppet/functions/binary_file.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Loads a binary file from a module or file system and returns its contents as a `Binary`.
+# The argument to this function should be a `<MODULE NAME>/<FILE>`
+# reference, which will load `<FILE>` from a module's `files`
+# directory. (For example, the reference `mysql/mysqltuner.pl` will load the
+# file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+#
+# This function also accepts an absolute file path that allows reading
+# binary file content from anywhere on disk.
+#
+# An error is raised if the given file does not exists.
+#
+# To search for the existence of files, use the `find_file()` function.
+#
+# - since 4.8.0
+#
+# @since 4.8.0
+#
+Puppet::Functions.create_function(:binary_file, Puppet::Functions::InternalFunction) do
+  dispatch :binary_file do
+    scope_param
+    param 'String', :path
+  end
+
+  def binary_file(scope, unresolved_path)
+    path = Puppet::Parser::Files.find_file(unresolved_path, scope.compiler.environment)
+    unless path && Puppet::FileSystem.exist?(path)
+      # TRANSLATORS the string "binary_file()" should not be translated
+      raise Puppet::ParseError, _("binary_file(): The given file '%{unresolved_path}' does not exist") % { unresolved_path: unresolved_path }
+    end
+
+    Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(Puppet::FileSystem.binread(path))
+  end
+end

data/lib/puppet/functions/break.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Breaks an innermost iteration as if it encountered an end of input.
+# This function does not return to the caller.
+#
+# The signal produced to stop the iteration bubbles up through
+# the call stack until either terminating the innermost iteration or
+# raising an error if the end of the call stack is reached.
+#
+# The break() function does not accept an argument.
+#
+# @example Using `break`
+#
+# ```puppet
+# $data = [1,2,3]
+# notice $data.map |$x| { if $x == 3 { break() } $x*10 }
+# ```
+#
+# Would notice the value `[10, 20]`
+#
+# @example Using a nested `break`
+#
+# ```puppet
+# function break_if_even($x) {
+#   if $x % 2 == 0 { break() }
+# }
+# $data = [1,2,3]
+# notice $data.map |$x| { break_if_even($x); $x*10 }
+# ```
+# Would notice the value `[10]`
+#
+# * Also see functions `next` and `return`
+#
+# @since 4.8.0
+#
+Puppet::Functions.create_function(:break) do
+  dispatch :break_impl do
+  end
+
+  def break_impl
+    # get file, line if available, else they are set to nil
+    file, line = Puppet::Pops::PuppetStack.top_of_stack
+
+    # PuppetStopIteration contains file and line and is a StopIteration exception
+    # so it can break a Ruby Kernel#loop or enumeration
+    #
+    raise Puppet::Pops::Evaluator::PuppetStopIteration.new(file, line)
+  end
+end

data/lib/puppet/functions/call.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Calls an arbitrary Puppet function by name.
+#
+# This function takes one mandatory argument and one or more optional arguments:
+#
+# 1. A string corresponding to a function name.
+# 2. Any number of arguments to be passed to the called function.
+# 3. An optional lambda, if the function being called supports it.
+#
+# This function can also be used to resolve a `Deferred` given as
+# the only argument to the function (does not accept arguments nor
+# a block).
+#
+# @example Using the `call` function
+#
+# ```puppet
+# $a = 'notice'
+# call($a, 'message')
+# ```
+#
+# @example Using the `call` function with a lambda
+#
+# ```puppet
+# $a = 'each'
+# $b = [1,2,3]
+# call($a, $b) |$item| {
+#  notify { $item: }
+# }
+# ```
+#
+# The `call` function can be used to call either Ruby functions or Puppet language
+# functions.
+#
+# When used with `Deferred` values, the deferred value can either describe
+# a function call, or a dig into a variable.
+#
+# @example Resolving a deferred function call
+#
+# ```puppet
+# $d = Deferred('join', [[1,2,3], ':']) # A future call to join that joins the arguments 1,2,3 with ':'
+# notice($d.call())
+# ```
+#
+# Would notice the string "1:2:3".
+#
+# @example Resolving a deferred variable value with optional dig into its structure
+#
+# ```puppet
+# $d = Deferred('$facts', ['processors', 'count'])
+# notice($d.call())
+# ```
+#
+# Would notice the value of `$facts['processors']['count']` at the time when the `call` is made.
+#
+# * Deferred values supported since Puppet 6.0
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
+  dispatch :call_impl_block do
+    scope_param
+    param 'String', :function_name
+    repeated_param 'Any', :arguments
+    optional_block_param
+  end
+
+  dispatch :call_deferred do
+    scope_param
+    param 'Deferred', :deferred
+  end
+
+  def call_impl_block(scope, function_name, *args, &block)
+    # The call function must be able to call functions loaded by any loader visible from the calling scope.
+    Puppet::Pops::Parser::EvaluatingParser.new.evaluator.external_call_function(function_name, args, scope, &block)
+  end
+
+  def call_deferred(scope, deferred)
+    Puppet::Pops::Evaluator::DeferredResolver.resolve(deferred, scope.compiler)
+  end
+end

data/lib/puppet/functions/camelcase.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Creates a Camel Case version of a String
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion replaces all combinations of `*_<char>*` with an upcased version of the
+#   character following the _.  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").
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is capitalized 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.
+# * The result will not contain any underscore characters.
+#
+# 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 Camelcase a String
+# ```puppet
+# 'hello_friend'.camelcase()
+# camelcase('hello_friend')
+# ```
+# Would both result in `"HelloFriend"`
+#
+# @example Camelcase of strings in an Array
+# ```puppet
+# ['abc_def', 'bcd_xyz'].camelcase()
+# camelcase(['abc_def', 'bcd_xyz'])
+# ```
+# Would both result in `['AbcDef', 'BcdXyz']`
+#
+Puppet::Functions.create_function(:camelcase) 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.split('_').map(&:capitalize).join('')
+  end
+
+  def on_iterable(a)
+    a.map { |x| do_camelcase(x) }
+  end
+
+  def do_camelcase(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? on_string(x) : x
+  end
+end

data/lib/puppet/functions/capitalize.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Capitalizes the first character of a String, or the first character of every String in an Iterable value (such as an Array).
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String`, a string is returned in which the first character is uppercase.
+#   This is done using Ruby system locale which handles some, but not all
+#   special international up-casing rules (for example German double-s ß is capitalized to "Ss").
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is capitalized 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.
+#
+# 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 Capitalizing a String
+# ```puppet
+# 'hello'.capitalize()
+# capitalize('hello')
+# ```
+# Would both result in `"Hello"`
+#
+# @example Capitalizing strings in an Array
+# ```puppet
+# ['abc', 'bcd'].capitalize()
+# capitalize(['abc', 'bcd'])
+# ```
+# Would both result in `['Abc', 'Bcd']`
+#
+Puppet::Functions.create_function(:capitalize) 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.capitalize
+  end
+
+  def on_iterable(a)
+    a.map { |x| do_capitalize(x) }
+  end
+
+  def do_capitalize(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.capitalize : x
+  end
+end

data/lib/puppet/functions/ceiling.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Returns the smallest `Integer` greater 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(:ceiling) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  dispatch :on_string do
+    param 'String', :val
+  end
+
+  def on_numeric(x)
+    x.ceil
+  end
+
+  def on_string(x)
+    Puppet.warn_once('deprecations', 'ceiling_function_numeric_coerce_string',
+                     _("The ceiling() function's auto conversion of String to Float is deprecated - change to convert input before calling"))
+
+    begin
+      Float(x).ceil
+    rescue TypeError, ArgumentError => _e
+      # TRANSLATORS: 'ceiling' is a name and should not be translated
+      raise(ArgumentError, _('ceiling(): cannot convert given value to a floating point value.'))
+    end
+  end
+end

data/lib/puppet/functions/chomp.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Returns a new string with the record separator character(s) removed.
+# The record separator is the line ending characters `\r` and `\n`.
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes `\r\n`, `\n` or `\r` from the end of a string.
+# * 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 line endings
+# ```puppet
+# "hello\r\n".chomp()
+# chomp("hello\r\n")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing line endings in an array
+# ```puppet
+# ["hello\r\n", "hi\r\n"].chomp()
+# chomp(["hello\r\n", "hi\r\n"])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:chomp) 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.chomp
+  end
+
+  def on_iterable(a)
+    a.map { |x| do_chomp(x) }
+  end
+
+  def do_chomp(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.chomp : x
+  end
+end

data/lib/puppet/functions/chop.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Returns a new string with the last character removed.
+# If the string ends with `\r\n`, both characters are removed. Applying chop to an empty
+# string returns an empty string. If you wish to merely remove record
+# separators then you should use the `chomp` function.
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes the last character, or if it ends with \r\n` it removes both. If String is empty
+#   an empty string is returned.
+# * 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 line endings
+# ```puppet
+# "hello\r\n".chop()
+# chop("hello\r\n")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing last char
+# ```puppet
+# "hello".chop()
+# chop("hello")
+# ```
+# Would both result in `"hell"`
+#
+# @example Removing last char in an array
+# ```puppet
+# ["hello\r\n", "hi\r\n"].chop()
+# chop(["hello\r\n", "hi\r\n"])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:chop) 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.chop
+  end
+
+  def on_iterable(a)
+    a.map { |x| do_chop(x) }
+  end
+
+  def do_chop(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.chop : x
+  end
+end

data/lib/puppet/functions/compare.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Compares two values and returns -1, 0 or 1 if first value is smaller, equal or larger than the second value.
+# The compare function accepts arguments of the data types `String`, `Numeric`, `Timespan`, `Timestamp`, and `Semver`,
+# such that:
+#
+# * two of the same data type can be compared
+# * `Timespan` and `Timestamp` can be compared with each other and with `Numeric`
+#
+# When comparing two `String` values the comparison can be made to consider case by passing a third (optional)
+# boolean `false` value - the default is `true` which ignores case as the comparison operators
+# in the Puppet Language.
+#
+Puppet::Functions.create_function(:compare) do
+  local_types do
+    type 'TimeComparable = Variant[Numeric, Timespan, Timestamp]'
+    type 'Comparable = Variant[String, Semver, TimeComparable]'
+  end
+
+  dispatch :on_numeric do
+    param 'Numeric', :a
+    param 'Numeric', :b
+  end
+
+  dispatch :on_string do
+    param 'String', :a
+    param 'String', :b
+    optional_param 'Boolean', :ignore_case
+  end
+
+  dispatch :on_version do
+    param 'Semver', :a
+    param 'Semver', :b
+  end
+
+  dispatch :on_time_num_first do
+    param 'Numeric', :a
+    param 'Variant[Timespan, Timestamp]', :b
+  end
+
+  dispatch :on_timestamp do
+    param 'Timestamp', :a
+    param 'Variant[Timestamp, Numeric]', :b
+  end
+
+  dispatch :on_timespan do
+    param 'Timespan', :a
+    param 'Variant[Timespan, Numeric]', :b
+  end
+
+  argument_mismatch :on_error do
+    param 'Comparable', :a
+    param 'Comparable', :b
+    repeated_param 'Any', :ignore_case
+  end
+
+  argument_mismatch :on_not_comparable do
+    param 'Any', :a
+    param 'Any', :b
+    repeated_param 'Any', :ignore_case
+  end
+
+  def on_numeric(a, b)
+    a <=> b
+  end
+
+  def on_string(a, b, ignore_case = true)
+    if ignore_case
+      a.casecmp(b)
+    else
+      a <=> b
+    end
+  end
+
+  def on_version(a, b)
+    a <=> b
+  end
+
+  def on_time_num_first(a, b)
+    # Time data types can compare against Numeric but not the other way around
+    # the comparison is therefore done in reverse and the answer is inverted.
+    -(b <=> a)
+  end
+
+  def on_timespan(a, b)
+    a <=> b
+  end
+
+  def on_timestamp(a, b)
+    a <=> b
+  end
+
+  def on_not_comparable(a, b, *ignore_case)
+    # TRANSLATORS 'compare' is a name
+    _("compare(): Non comparable type. Only values of the types Numeric, String, Semver, Timestamp and Timestamp can be compared. Got %{type_a} and %{type_b}") % {
+      type_a: type_label(a), type_b: type_label(b)
+    }
+  end
+
+  def on_error(a, b, *ignore_case)
+    unless ignore_case.empty?
+      unless a.is_a?(String) && b.is_a?(String)
+        # TRANSLATORS 'compare' is a name
+        return _("compare(): The third argument (ignore case) can only be used when comparing strings")
+      end
+      unless ignore_case.size == 1
+        # TRANSLATORS 'compare' is a name
+        return _("compare(): Accepts at most 3 arguments, got %{actual_number}") % { actual_number: 2 + ignore_case.size }
+      end
+      unless ignore_case[0].is_a?(Boolean)
+        # TRANSLATORS 'compare' is a name
+        return _("compare(): The third argument (ignore case) must be a Boolean. Got %{type}") % { type: type_label(ignore_case[0]) }
+      end
+    end
+
+    if a.class != b.class
+      # TRANSLATORS 'compare' is a name
+      _("compare(): Can only compare values of the same type (or for Timestamp/Timespan also against Numeric). Got %{type_a} and %{type_b}") % {
+        type_a: type_label(a), type_b: type_label(b)
+      }
+    end
+  end
+
+  def type_label(x)
+    Puppet::Pops::Model::ModelLabelProvider.new.label(x)
+  end
+end