Merge pull request #922 from hlindberg/(docs)_update-documentation-wrt-functions-moved-to-puppet

(docs) update documentation wrt functions moved to puppet

Author: pmcmaw

README.md

@@ -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/length.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/functions/sprintf_hash.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/abs.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/any2array.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/any2bool.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/base64.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/bool2num.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/bool2str.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|