puppet 5.0.0 → 6.0.0

data/lib/puppet/functions/abs.rb

@@ -0,0 +1,61 @@
+# Returns the absolute value of a Numeric value, for example -34.56 becomes
+# 34.56. Takes a single `Integer` or `Float` value as an argument.
+#
+# *Deprecated behavior*
+#
+# For backwards compatibility reasons this function also works when given a
+# number in `String` format such that it first attempts to covert it to either a `Float` or
+# an `Integer` and then taking the absolute value of the result. Only strings representing
+# a number in decimal format is supported - an error is raised if
+# value is not decimal (using base 10). Leading 0 chars in the string
+# are ignored. A floating point value in string form can use some forms of
+# scientific notation but not all.
+#
+# Callers should convert strings to `Numeric` before calling
+# this function to have full control over the conversion.
+#
+# @example Converting to Numeric before calling
+# ```puppet
+# abs(Numeric($str_val))
+# ```
+# 
+# It is worth noting that `Numeric` can convert to absolute value
+# directly as in the following examples:
+#
+# @example Absolute value and String to Numeric
+# ```puppet
+# Numeric($strval, true)     # Converts to absolute Integer or Float
+# Integer($strval, 10, true) # Converts to absolute Integer using base 10 (decimal)
+# Integer($strval, 16, true) # Converts to absolute Integer using base 16 (hex)
+# Float($strval, true)       # Converts to absolute Float
+# ```puppet
+#
+Puppet::Functions.create_function(:abs) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  dispatch :on_string do
+    param 'String', :val
+  end
+
+  def on_numeric(x)
+    x.abs
+  end
+
+  def on_string(x)
+    Puppet.warn_once('deprecations', 'abs_function_numeric_coerce_string',
+      _("The abs() function's auto conversion of String to Numeric is deprecated - change to convert input before calling"))
+
+    # These patterns for conversion are backwards compatible with the stdlib
+    # version of this function.
+    #
+    if x =~ %r{^-?(?:\d+)(?:\.\d+){1}$}
+      x.to_f.abs
+    elsif x =~ %r{^-?\d+$}
+      x.to_i.abs
+    else
+      raise(ArgumentError, 'abs(): Requires float or integer to work with - was given non decimal string')
+    end
+  end
+end

data/lib/puppet/functions/alert.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level alert.
+# Logs a message on the server at level `alert`.
 Puppet::Functions.create_function(:alert, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/all.rb

@@ -0,0 +1,104 @@
+# 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 non "truthy" value which
+# makes the function return `false`, or if the end of the iteration is reached, `true` 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 `all` function
+#
+# `$data.all |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `all($data) |$parameter| { <PUPPET CODE BLOCK> }`
+#
+# @example Using the `all` function with an Array and a one-parameter lambda
+#
+# ```puppet
+# # For the array $data, run a lambda that checks that all values are multiples of 10
+# $data = [10, 20, 30]
+# notice $data.all |$item| { $item % 10 == 0 }
+# ```
+#
+# Would notice `true`.
+#
+# 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 `all` 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 = { 'a_0'=> 10, 'b_1' => 20 }
+# notice $data.all |$item| { $item[1] % 10 == 0  }
+# ```
+#
+# Would notice `true` if all values in the hash are multiples of 10.
+#
+# 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 `all` function with a hash and a two-parameter lambda
+#
+# ```puppet
+# # Check that all values are a multiple of 10 and keys start with 'abc'
+# $data = {abc_123 => 10, abc_42 => 20, abc_blue => 30}
+# notice $data.all |$key, $value| { $value % 10 == 0  and $key =~ /^abc/ }
+# ```
+#
+# Would notice true.
+#
+# 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(:all) do
+  dispatch :all_Hash_2 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :all_Hash_1 do
+    param 'Hash[Any, Any]', :hash
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :all_Enumerable_2 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :all_Enumerable_1 do
+    param 'Iterable', :enumerable
+    block_param 'Callable[1,1]', :block
+  end
+
+  def all_Hash_1(hash)
+    hash.each_pair.all? { |x| yield(x) }
+  end
+
+  def all_Hash_2(hash)
+    hash.each_pair.all? { |x,y| yield(x,y) }
+  end
+
+  def all_Enumerable_1(enumerable)
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable).all? { |e| yield(e) }
+  end
+
+  def all_Enumerable_2(enumerable)
+    enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
+    if enum.hash_style?
+      enum.all? { |entry| yield(*entry) }
+    else
+      enum.each_with_index { |e, i| return false unless yield(i, e) }
+      true
+    end
+  end
+end

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

@@ -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

@@ -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
 #
@@ -12,6 +24,7 @@ Puppet::Functions.create_function(:binary_file, Puppet::Functions::InternalFunct
   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))

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 5.6.0
+#
 # @since 5.0.0
 #
 Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
@@ -36,7 +63,17 @@ 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)
   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'].capitalize()
+# capitalize(['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