(docs) update documentation wrt functions moved to puppet

lib/puppet/functions/length.rb

@@ -1,4 +1,9 @@
-# A function to eventually replace the old size() function for stdlib - The original size function did not handle Puppets new type capabilities, so this function is a Puppet 4 compatible solution.
+# A function to eventually replace the old size() function for stdlib
+# The original size function did not handle Puppets new type capabilities, so this function is a Puppet 4 compatible solution.
+#
+# Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+# will be used instead of this function.
+#
 Puppet::Functions.create_function(:length) do
   dispatch :length do
     param 'Variant[String,Array,Hash]', :value

lib/puppet/functions/sprintf_hash.rb

@@ -12,6 +12,9 @@
 #                          { 'foo' => 'a string', 'number' => 5 })
 #   # $output = 'String: a string / number converted to binary: 101'
 #
+# Note that since Puppet 4.10.10, and 5.3.4 this functionality is supported by the
+# `sprintf` function in puppet core.
+#
 Puppet::Functions.create_function(:sprintf_hash) do
   # @param format The format to use.
   # @param arguments Hash with parameters.

lib/puppet/parser/functions/abs.rb

@@ -5,6 +5,9 @@ module Puppet::Parser::Functions
   newfunction(:abs, :type => :rvalue, :doc => <<-DOC
     Returns the absolute value of a number, for example -34.56 becomes
     34.56. Takes a single integer and float value as an argument.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/any2array.rb

@@ -6,6 +6,23 @@ module Puppet::Parser::Functions
     This converts any object to an array containing that object. Empty argument
     lists are converted to an empty array. Arrays are left untouched. Hashes are
     converted to arrays of alternating keys and values.
+
+    Note that since Puppet 5.0.0 it is possible to create new data types for almost any
+    datatype using the type system and the built-in
+    [`Array.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-array-and-tuple)
+    function is used to create a new Array..
+
+        $hsh = {'key' => 42, 'another-key' => 100}
+        notice(Array($hsh))
+
+    Would notice `[['key', 42], ['another-key', 100]]`
+
+    The Array data type also has a special mode to "create an array if not already an array"
+
+        notice(Array({'key' => 42, 'another-key' => 100}, true))
+
+    Would notice `[{'key' => 42, 'another-key' => 100}]`, as the `true` flag prevents the hash from being
+    transformed into an array.
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/any2bool.rb

@@ -11,6 +11,9 @@ module Puppet::Parser::Functions
     * Number (or a string representation of a number) > 0 will return true, otherwise false
     * undef will return false
     * Anything else will return true
+
+    Also see the built-in [`Boolean.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-boolean)
+    function.
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/base64.rb

@@ -13,6 +13,15 @@ module Puppet::Parser::Functions
       $encodestring = base64('encode', 'thestring', $method)
       $decodestring = base64('decode', 'dGhlc3RyaW5n', $method)
 
+    Note: Since Puppet 4.8.0, the Binary data type can be used to produce base 64 encoded strings.
+    See the `new()` function for the Binary and String types for documentation. Also see `binary_file()`
+    function for reading a file with binary (non UTF-8) content.
+
+       # encode a string as if it was binary
+       $encodestring = String(Binary('thestring', '%s'))
+       # decode a Binary assuming it is an UTF-8 String
+       $decodestring = String(Binary("dGhlc3RyaW5n"), "%s")
+
     DOC
 
     require 'base64'

lib/puppet/parser/functions/bool2num.rb

@@ -7,6 +7,16 @@ module Puppet::Parser::Functions
       false, f, 0, n, and no to 0
       true, t, 1, y, and yes to 1
     Requires a single boolean or string as an input.
+
+    Note that since Puppet 5.0.0 it is possible to create new data types for almost any
+    datatype using the type system and the built-in
+    [`Numeric.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-numeric),
+    [`Integer.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-integer), and
+    [`Float.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-float)
+    function are used to convert to numeric values.
+
+        notice(Integer(false)) # Notices 0
+        notice(Float(true))    # Notices 1.0
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/bool2str.rb

@@ -15,6 +15,17 @@ module Puppet::Parser::Functions
     bool2str(false, 't', 'f')         => 'f'
 
     Requires a single boolean as an input.
+
+    Note that since Puppet 5.0.0 it is possible to create new data types for almost any
+    datatype using the type system and the built-in
+    [`String.new`](https://puppet.com/docs/puppet/latest/function.html#boolean-to-string)
+    function is used to convert to String with many different format options.
+
+        notice(String(false))         # Notices 'false'
+        notice(String(true))          # Notices 'true'
+        notice(String(false, '%y'))   # Notices 'yes'
+        notice(String(true, '%y'))    # Notices 'no'
+
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/camelcase.rb

@@ -5,6 +5,9 @@
 module Puppet::Parser::Functions
   newfunction(:camelcase, :type => :rvalue, :doc => <<-DOC
     Converts the case of a string or all strings in an array to camel case.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/capitalize.rb

@@ -6,6 +6,9 @@ module Puppet::Parser::Functions
   newfunction(:capitalize, :type => :rvalue, :doc => <<-DOC
     Capitalizes the first letter of a string or array of strings.
     Requires either a single string or an array as an input.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/ceiling.rb

@@ -5,6 +5,9 @@ module Puppet::Parser::Functions
   newfunction(:ceiling, :type => :rvalue, :doc => <<-DOC
     Returns the smallest integer greater or equal to the argument.
     Takes a single numeric value as an argument.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/chomp.rb

@@ -6,6 +6,9 @@ module Puppet::Parser::Functions
     Removes the record separator from the end of a string or an array of
     strings, for example `hello\n` becomes `hello`.
     Requires a single string or array as an input.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/chop.rb

@@ -8,6 +8,9 @@ module Puppet::Parser::Functions
     string returns an empty string. If you wish to merely remove record
     separators then you should use the `chomp` function.
     Requires a string or array of strings as input.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/clamp.rb

@@ -4,6 +4,9 @@
 module Puppet::Parser::Functions
   newfunction(:clamp, :type => :rvalue, :arity => -2, :doc => <<-DOC
     Clamps value to a range.
+
+    Note: From Puppet 6.0.0 this can be done with only core Puppet like this:
+      [$minval, $maxval, $value_to_clamp].sort[1]
     DOC
              ) do |args|
 

lib/puppet/parser/functions/concat.rb

@@ -12,6 +12,10 @@ module Puppet::Parser::Functions
     Would result in:
 
       ['1','2','3','4','5','6','7','8','9']
+
+    Note: Since Puppet 4.0 concatenation of arrays and hashes can be done with the + operator.
+
+      ['1','2','3'] + ['4','5','6'] + ['7','8','9']
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/convert_base.rb

@@ -10,6 +10,11 @@ module Puppet::Parser::Functions
       $binary_repr = convert_base(5, 2)  # $binary_repr is now set to "101"
       $hex_repr = convert_base("254", "16")  # $hex_repr is now set to "fe"
 
+     Note: Since Puppet 4.5.0 this can be done with String.new() and its many formatting options:
+
+       $binary_repr = String(5, '%b') # results in "101"
+       $hex_repr = String(254, "%x")  # results in "fe"
+       $hex_repr = String(254, "%#x")  # results in "0xfe"
     DOC
 
     raise Puppet::ParseError, 'convert_base(): First argument must be either a string or an integer' unless args[0].is_a?(Integer) || args[0].is_a?(String)

lib/puppet/parser/functions/count.rb

@@ -4,8 +4,20 @@
 module Puppet::Parser::Functions
   newfunction(:count, :type => :rvalue, :arity => -2, :doc => <<-DOC
     Takes an array as first argument and an optional second argument.
-    Count the number of elements in array that matches second argument.
-    If called with only an array it counts the number of elements that are not nil/undef.
+    Count the number of elements in array that is equal to the second argument.
+    If called with only an array it counts the number of elements that are not nil/undef/empty-string.
+
+    Note: equality is tested with a Ruby method and it is therefore subject to what Ruby considers
+    to be equal. For strings this means that equality is case sensitive.
+
+    In Puppet core, counting can be done in general by using a combination of the core functions
+    filter() (since Puppet 4.0.0) and length() (since Puppet 5.5.0, before that in stdlib).
+    Example below shows counting values that are not undef.
+
+      notice([42, "hello", undef].filter |$x| { $x =~ NotUndef }.length)
+
+    Would notice the value 2.
+
   DOC
              ) do |args|
 

lib/puppet/parser/functions/delete.rb

@@ -19,6 +19,22 @@ module Puppet::Parser::Functions
 
         delete('abracadabra', 'bra')
         Would return: 'acada'
+
+    Note that from Puppet 4.0.0 the minus (-) operator deletes values from arrays and keys from a hash:
+
+        ['a', 'b', 'c', 'b'] - 'b'
+        # would return ['a', 'c']
+
+        {'a'=>1,'b'=>2,'c'=>3} - ['b','c'])
+        # would return {'a' => '1'}
+
+    A global delete from a string can be performed with the regsubst() function:
+
+        'abracadabra'.regsubst(/bra/, '', 'G')
+        # would return 'acada'
+
+    In general, the filter() function can filter out entries from arrays and hashes based on keys and/or values.
+
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/delete_at.rb

@@ -10,6 +10,17 @@ module Puppet::Parser::Functions
         delete_at(['a','b','c'], 1)
 
     Would return: ['a','c']
+
+    Note that since Puppet 4 this can be done in general with the filter function:
+
+        ['a', 'b', 'c'].filter |$pos, $val | { $pos != 1 }
+
+    Or if a delete is wanted from the beginning or end of the array, by using the slice operator [ ]:
+
+        $array[0, -1] # the same as all the values
+        $array[2, -1] # all but the first 2 elements
+        $array[0, -3] # all but the last 2 elements
+        $array[1, -2] # all but the first and last element
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/delete_regex.rb

@@ -22,6 +22,12 @@ module Puppet::Parser::Functions
         delete_regex({'a'=>1,'b'=>2,'c'=>3}, '^a$')
         Would return: {'b'=>2,'c'=>3}
 
+     Note that since Puppet 4 this can be done in general with the filter function:
+
+        ["aaa", "aba", "aca"].filter |$val| { $val !~ /b/ }
+        # Would return: ['aaa', 'aca']
+
+
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/delete_undef_values.rb

@@ -15,6 +15,11 @@ module Puppet::Parser::Functions
 
     Would return: ['A','',false]
 
+    Note that since Puppet 4.0.0 the equivalent can be performed with the filter() function in Puppet:
+
+        $array.filter |$val| { $val =~ NotUndef }
+        $hash.filter |$key, $val| { $val =~ NotUndef }
+
       DOC
              ) do |args|
 

lib/puppet/parser/functions/delete_values.rb

@@ -11,6 +11,11 @@ module Puppet::Parser::Functions
 
     Would return: {'a'=>'A','c'=>'C','B'=>'D'}
 
+    Note that since Puppet 4.0.0 the equivalent can be performed with the filter() function in Puppet:
+
+        $array.filter |$val| { $val != 'B' }
+        $hash.filter |$key, $val| { $val != 'B' }
+
       DOC
              ) do |arguments|
 

lib/puppet/parser/functions/difference.rb

@@ -12,6 +12,12 @@ module Puppet::Parser::Functions
         difference(["a","b","c"],["b","c","d"])
 
     Would return: ["a"]
+
+    Note: Since Puppet 4 the minus (-) operator in the Puppet language does the same thing:
+
+      ['a', 'b', 'c'] - ['b', 'c', 'd']
+      # would return ['a']
+
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/dig44.rb

@@ -7,7 +7,7 @@ module Puppet::Parser::Functions
     :type => :rvalue,
     :arity => -2,
     :doc => <<-DOC
-    DEPRECATED: This function has been replaced in puppet 4.5.0.
+    DEPRECATED: This function has been replaced in Puppet 4.5.0.
 
     Looks up into a complex structure of arrays and hashes and returns a value
     or the default value if nothing was found.

lib/puppet/parser/functions/downcase.rb

@@ -5,6 +5,9 @@
 module Puppet::Parser::Functions
   newfunction(:downcase, :type => :rvalue, :doc => <<-DOC
     Converts the case of a string or all strings in an array to lower case.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/empty.rb

@@ -4,6 +4,9 @@
 module Puppet::Parser::Functions
   newfunction(:empty, :type => :rvalue, :doc => <<-DOC
     Returns true if the variable is empty.
+
+    Note: from Puppet 5.5.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/flatten.rb

@@ -11,6 +11,9 @@ module Puppet::Parser::Functions
         flatten(['a', ['b', ['c']]])
 
     Would return: ['a','b','c']
+
+    Note: from Puppet 5.5.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
   DOC
              ) do |arguments|
 

lib/puppet/parser/functions/floor.rb

@@ -5,6 +5,9 @@ module Puppet::Parser::Functions
   newfunction(:floor, :type => :rvalue, :doc => <<-DOC
     Returns the largest integer less or equal to the argument.
     Takes a single numeric value as an argument.
+
+    Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+    will be used instead of this function.
     DOC
              ) do |arguments|
 

lib/puppet/parser/functions/get_module_path.rb

@@ -8,6 +8,9 @@ module Puppet::Parser::Functions
 
     Example:
       $module_path = get_module_path('stdlib')
+
+    Note that since Puppet 5.4.0 the function `module_directory()` in Puppet does the same thing and will return
+    the path to the first found module if given multiple values or an array.
   DOC
              ) do |args|
     raise(Puppet::ParseError, 'get_module_path(): Wrong number of arguments, expects one') unless args.size == 1