puppet 5.3.4 → 6.29.0

data/lib/puppet/functions/annotate.rb

@@ -5,11 +5,11 @@
 #
 # @example Using `annotate` with two arguments
 #
-# ~~~ puppet
+# ```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
@@ -18,11 +18,11 @@
 #
 # @example Using `annotate` with two arguments and a block
 #
-# ~~~ puppet
+# ```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.
@@ -30,23 +30,23 @@
 #
 # @example Using `annotate` with three arguments where third argument is a Hash
 #
-# ~~~ puppet
+# ```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 annotatation of the given type in the given object. The old annotation is returned if
+# 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
+# ```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
@@ -54,12 +54,12 @@
 #
 # @example Add multiple annotations to a new instance of `Mod::Person` using the `Pcore` type.
 #
-# ~~~ puppet
+# ```puppet
 #   $person = Pcore.annotate(Mod::Person({'name' => 'William'}), {
 #     Mod::NickNameAdapter >= { 'nick_name' => 'Bill' },
 #     Mod::HobbiesAdapter => { 'hobbies' => ['Ham Radio', 'Philatelist'] }
 #   })
-# ~~~
+# ```
 #
 # @since 5.0.0
 #

data/lib/puppet/functions/any.rb

@@ -1,4 +1,4 @@
-# Runs a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# 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.
 #
@@ -18,28 +18,28 @@
 #
 # @example Using the `any` function with an Array and a one-parameter lambda
 #
-# ~~~ puppet
+# ```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
-# `$lookued_up[routers] || $looked_up[servers] || $looked_up[workstations]`.
+# `$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
+# ```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`.
@@ -50,16 +50,16 @@
 #
 # @example Using the `any` function with an array and a two-parameter lambda
 #
-# ~~~ puppet
+# ```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://docs.puppetlabs.com/puppet/latest/reference/lang_iteration.html)
+# [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
 # documentation.
 #
 # @since 5.2.0
@@ -99,7 +99,11 @@ Puppet::Functions.create_function(:any) do
 
   def any_Enumerable_2(enumerable)
     enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
-    enum.each_with_index { |e, i| return true if yield(i, e) }
-    false
+    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

@@ -1,7 +1,7 @@
 # Returns the given value if it is of the given
-# [data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html), or
+# [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://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html).
+# [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html).
 #
 # The function takes two mandatory arguments, in this order:
 #
@@ -10,7 +10,7 @@
 #
 # @example Using `assert_type`
 #
-# ~~~ puppet
+# ```puppet
 # $raw_username = 'Amy Berry'
 #
 # # Assert that $raw_username is a non-empty string and assign it to $valid_username.
@@ -19,7 +19,7 @@
 # # $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:
@@ -29,7 +29,7 @@
 #
 # @example Using `assert_type` with a warning and default value
 #
-# ~~~ puppet
+# ```puppet
 # $raw_username = 'Amy Berry'
 #
 # # Assert that $raw_username is a non-empty string and assign it to $valid_username.
@@ -43,10 +43,10 @@
 # # 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://docs.puppetlabs.com/puppet/latest/reference/lang_data.html).
+# [documentation](https://puppet.com/docs/puppet/latest/lang_data.html).
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/binary_file.rb

@@ -1,5 +1,17 @@
-# Loads a binary file from a module or file system and returns its contents as a Binary.
-# (Documented in 3.x stub)
+# 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
 #

data/lib/puppet/functions/break.rb

@@ -1,19 +1,44 @@
-# Make iteration break as if there were no more values to process
+# Breaks an innermost iteration as if it encountered an end of input.
+# This function does not return to the caller.
 #
-# @since 4.7.0
+# 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()
-    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
-    if stacktrace.size > 0
-      file, line = stacktrace[0]
-    else
-      file = nil
-      line = nil
-    end
+    # 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
     #

data/lib/puppet/functions/call.rb

@@ -6,26 +6,53 @@
 # 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
+# ```puppet
 # $a = 'notice'
 # call($a, 'message')
-# ~~~
+# ```
 #
 # @example Using the `call` function with a lambda
 #
-# ~~~ puppet
+# ```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
@@ -36,7 +63,18 @@ Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
     optional_block_param
   end
 
+  dispatch :call_deferred do
+    scope_param
+    param 'Deferred', :deferred
+  end
+
   def call_impl_block(scope, function_name, *args, &block)
-    call_function_with_scope(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()
+# upcase('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

data/lib/puppet/functions/chop.rb

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