openvox 7.37.1

data/lib/puppet/functions/annotate.rb

@@ -0,0 +1,108 @@
+# Handles annotations on objects. The function can be used in four different ways.
+#
+# With two arguments, an `Annotation` type and an object, the function returns the annotation
+# for the object of the given type, or `undef` if no such annotation exists.
+#
+# @example Using `annotate` with two arguments
+#
+# ```puppet
+# $annotation = Mod::NickNameAdapter.annotate(o)
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o)
+# ```
+#
+# With three arguments, an `Annotation` type, an object, and a block, the function returns the
+# annotation for the object of the given type, or annotates it with a new annotation initialized
+# from the hash returned by the given block when no such annotation exists. The block will not
+# be called when an annotation of the given type is already present.
+#
+# @example Using `annotate` with two arguments and a block
+#
+# ```puppet
+# $annotation = Mod::NickNameAdapter.annotate(o) || { { 'nick_name' => 'Buddy' } }
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o) || { { 'nick_name' => 'Buddy' } }
+# ```
+#
+# With three arguments, an `Annotation` type, an object, and an `Hash`, the function will annotate
+# the given object with a new annotation of the given type that is initialized from the given hash.
+# An existing annotation of the given type is discarded.
+#
+# @example Using `annotate` with three arguments where third argument is a Hash
+#
+# ```puppet
+# $annotation = Mod::NickNameAdapter.annotate(o, { 'nick_name' => 'Buddy' })
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o, { 'nick_name' => 'Buddy' })
+# ```
+#
+# With three arguments, an `Annotation` type, an object, and an the string `clear`, the function will
+# clear the annotation of the given type in the given object. The old annotation is returned if
+# it existed.
+#
+# @example Using `annotate` with three arguments where third argument is the string 'clear'
+#
+# ```puppet
+# $annotation = Mod::NickNameAdapter.annotate(o, clear)
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o, clear)
+# ```
+#
+# With three arguments, the type `Pcore`, an object, and a Hash of hashes keyed by `Annotation` types,
+# the function will annotate the given object with all types used as keys in the given hash. Each annotation
+# is initialized with the nested hash for the respective type. The annotated object is returned.
+#
+# @example Add multiple annotations to a new instance of `Mod::Person` using the `Pcore` type.
+#
+# ```puppet
+#   $person = Pcore.annotate(Mod::Person({'name' => 'William'}), {
+#     Mod::NickNameAdapter >= { 'nick_name' => 'Bill' },
+#     Mod::HobbiesAdapter => { 'hobbies' => ['Ham Radio', 'Philatelist'] }
+#   })
+# ```
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:annotate) do
+  dispatch :annotate do
+    param 'Type[Annotation]', :type
+    param 'Any', :value
+    optional_block_param 'Callable[0, 0]', :block
+  end
+
+  dispatch :annotate_new do
+    param 'Type[Annotation]', :type
+    param 'Any', :value
+    param 'Variant[Enum[clear],Hash[Pcore::MemberName,Any]]', :annotation_hash
+  end
+
+  dispatch :annotate_multi do
+    param 'Type[Pcore]', :type
+    param 'Any', :value
+    param 'Hash[Type[Annotation], Hash[Pcore::MemberName,Any]]', :annotations
+  end
+
+  # @param type [Annotation] the annotation type
+  # @param value [Object] the value to annotate
+  # @param block [Proc] optional block to produce the annotation hash
+  #
+  def annotate(type, value, &block)
+    type.implementation_class.annotate(value, &block)
+  end
+
+  # @param type [Annotation] the annotation type
+  # @param value [Object] the value to annotate
+  # @param annotation_hash [Hash{String => Object}] the annotation hash
+  #
+  def annotate_new(type, value, annotation_hash)
+    type.implementation_class.annotate_new(value, annotation_hash)
+  end
+
+  # @param type [Type] the Pcore type
+  # @param value [Object] the value to annotate
+  # @param annotations [Hash{Annotation => Hash{String => Object}}] hash of annotation hashes
+  #
+  def annotate_multi(type, value, annotations)
+    type.implementation_class.annotate(value, annotations)
+  end
+end

data/lib/puppet/functions/any.rb

@@ -0,0 +1,109 @@
+# Runs a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+# repeatedly using each value in a data structure until the lambda returns a "truthy" value which
+# makes the function return `true`, or if the end of the iteration is reached, false is returned.
+#
+# 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 `any` function
+#
+# `$data.any |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `any($data) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# @example Using the `any` function with an Array and a one-parameter lambda
+#
+# ```puppet
+# # For the array $data, run a lambda that checks if an unknown hash contains those keys
+# $data = ["routers", "servers", "workstations"]
+# $looked_up = lookup('somekey', Hash)
+# notice $data.any |$item| { $looked_up[$item] }
+# ```
+#
+# Would notice `true` if the looked up hash had a value that is neither `false` nor `undef` for at least
+# one of the keys. That is, it is equivalent to the expression
+# `$looked_up[routers] || $looked_up[servers] || $looked_up[workstations]`.
+#
+# 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 `any` function with a `Hash` and a one-parameter lambda
+#
+# ```puppet
+# # For the hash $data, run a lambda using each item as a key-value array.
+# $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
+# $looked_up = lookup('somekey', Hash)
+# notice $data.any |$item| { $looked_up[$item[0]] }
+# ```
+#
+# Would notice `true` if the looked up hash had a value for one of the wanted key that is
+# neither `false` nor `undef`.
+#
+# When the lambda accepts two arguments, the first argument gets the index in an array
+# or the key from a hash, and the second argument the value.
+#
+#
+# @example Using the `any` function with an array and a two-parameter lambda
+#
+# ```puppet
+# # Check if there is an even numbered index that has a non String value
+# $data = [key1, 1, 2, 2]
+# notice $data.any |$index, $value| { $index % 2 == 0 and $value !~ String }
+# ```
+#
+# Would notice true as the index `2` is even and not a `String`
+#
+# For an general examples that demonstrates iteration, see the Puppet
+# [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
+# documentation.
+#
+# @since 5.2.0
+#
+Puppet::Functions.create_function(:any) do
+  dispatch :any_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :any_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :any_Enumerable_2 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :any_Enumerable_1 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[1,1]', :block
+  end
+
+  def any_Hash_1(hash)
+    hash.each_pair.any? { |x| yield(x) }
+  end
+
+  def any_Hash_2(hash)
+    hash.each_pair.any? { |x,y| yield(x, y) }
+  end
+
+  def any_Enumerable_1(enumerable)
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable).any? { |e| yield(e) }
+  end
+
+  def any_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.any? { |entry| yield(*entry) }
+    else
+      enum.each_with_index { |e, i| return true if yield(i, e) }
+      false
+    end
+  end
+end

data/lib/puppet/functions/assert_type.rb

@@ -0,0 +1,93 @@
+# 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,32 @@
+# 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,47 @@
+# 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,80 @@
+# 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,62 @@
+# 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 {|x| x.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,61 @@
+# 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 with its first character in upper case version is returned. 
+#   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,37 @@
+# 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,57 @@
+# 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