Merge branch stdlib 4.0.0 release

* v4:
  Update gemspec for 4.0.0
  Update function documentation for 4.0.0
  Update Modulefile, README, CHANGELOG for stdlib-4.0.0

1 files changed, 281 insertions, 57 deletions

diff --git a/README.markdown b/README.markdown
index 336d0ab..15a5516 100644
--- a/README.markdown
+++ b/README.markdown
@@ -28,9 +28,11 @@ older versions of Puppet Enterprise that Puppet Labs still supports will have
 bugfix maintenance branches periodically "merged up" into master.  The current
 list of integration branches are:
 
- * v2.1.x (v2.1.1 released in PE 1.2, 1.2.1, 1.2.3, 1.2.4)
+ * v2.1.x (v2.1.1 released in PE 1)
  * v2.2.x (Never released as part of PE, only to the Forge)
- * v2.3.x (Released in PE 2.5.x)
+ * v2.3.x (Released in PE 2)
+ * v3.0.x (Never released as part of PE, only to the Forge)
+ * v4.0.x (Drops support for Puppet 2.7)
  * master (mainline development branch)
 
 The first Puppet Enterprise version including the stdlib module is Puppet
@@ -50,12 +52,27 @@ All stdlib releases in the 2.0 major version support Puppet 2.6 and Puppet 2.7.
 The 3.0 major release of stdlib drops support for Puppet 2.6.  Stdlib 3.x
 supports Puppet 2 and Puppet 3.
 
+## stdlib 4.x ##
+
+The 4.0 major release of stdlib drops support for Puppet 2.7.  Stdlib 4.x
+supports Puppet 3.  Notably, ruby 1.8.5 is no longer supported though ruby
+1.8.7, 1.9.3, and 2.0.0 are fully supported.
+
 # Functions #
 
 abs
 ---
-Returns the absolute value of a number, for example -34.56 becomes 34.56. Takes
-a single integer and float value as an argument.
+Returns the absolute value of a number, for example -34.56 becomes
+34.56. Takes a single integer and float value as an argument.
+
+
+- *Type*: rvalue
+
+any2array
+---------
+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.
 
 
 - *Type*: rvalue
@@ -80,9 +97,9 @@ Requires either a single string or an array as an input.
 
 chomp
 -----
-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.
+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.
 
 
 - *Type*: rvalue
@@ -99,8 +116,25 @@ Requires a string or array of strings as input.
 - *Type*: rvalue
 
 concat
+------
+Appends the contents of array 2 onto array 1.
+
+*Example:*
+
+    concat(['1','2','3'],['4','5','6'])
+
+Would result in:
+
+  ['1','2','3','4','5','6']
+
+
+- *Type*: rvalue
+
+count
 -----
-Appends the contents of the second array onto the first array.
+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.
 
 
 - *Type*: rvalue
@@ -125,13 +159,19 @@ to the catalog, and false otherwise.
 
 delete
 ------
-Deletes a selected element from an array.
+Deletes all instances of a given element from an array, substring from a
+string, or key from a hash.
 
 *Examples:*
 
-    delete(['a','b','c'], 'b')
+    delete(['a','b','c','b'], 'b')
+    Would return: ['a','c']
 
-Would return: ['a','c']
+    delete({'a'=>1,'b'=>2,'c'=>3}, 'b')
+    Would return: {'a'=>1,'c'=>3}
+
+    delete('abracadabra', 'bra')
+    Would return: 'acada'
 
 
 - *Type*: rvalue
@@ -163,6 +203,13 @@ Returns true if the variable is empty.
 
 - *Type*: rvalue
 
+ensure_packages
+---------------
+Takes a list of packages and only installs them if they don't already exist.
+
+
+- *Type*: statement
+
 ensure_resource
 ---------------
 Takes a resource type, title, and a list of attributes that describe a
@@ -203,12 +250,6 @@ floor
 Returns the largest integer less or equal to the argument.
 Takes a single numeric value as an argument.
 
-*Examples:*
-
-    floor('3.8')
-
-Would return: '3'
-
 
 - *Type*: rvalue
 
@@ -232,11 +273,10 @@ Example:
 
 getparam
 --------
+Takes a resource reference and name of the parameter and
+returns value of resource's parameter.
 
-Takes a resource reference and name of the parameter and returns
-value of resource's parameter.
-
-For example:
+*Examples:*
 
     define example_resource($param) {
     }
@@ -247,6 +287,9 @@ For example:
 
     getparam(Example_resource["example_resource_instance"], "param")
 
+Would return: param_value
+
+
 - *Type*: rvalue
 
 getvar
@@ -283,6 +326,44 @@ Would return:
 
 - *Type*: rvalue
 
+has_interface_with
+------------------
+Returns boolean based on kind and value:
+* macaddress
+* netmask
+* ipaddress
+* network
+
+has_interface_with("macaddress", "x:x:x:x:x:x")
+has_interface_with("ipaddress", "127.0.0.1")    => true
+etc.
+
+If no "kind" is given, then the presence of the interface is checked:
+has_interface_with("lo")                        => true
+
+
+- *Type*: rvalue
+
+has_ip_address
+--------------
+Returns true if the client has the requested IP address on some interface.
+
+This function iterates through the 'interfaces' fact and checks the
+'ipaddress_IFACE' facts, performing a simple string comparison.
+
+
+- *Type*: rvalue
+
+has_ip_network
+--------------
+Returns true if the client has an IP address within the requested network.
+
+This function iterates through the 'interfaces' fact and checks the
+'network_IFACE' facts, performing a simple string comparision.
+
+
+- *Type*: rvalue
+
 has_key
 -------
 Determine if a hash has a certain key value.
@@ -317,57 +398,39 @@ Would return: {'a'=>1,'b'=>2,'c'=>3}
 is_array
 --------
 Returns true if the variable passed to this function is an array.
-
-
 - *Type*: rvalue
-
 is_domain_name
 --------------
 Returns true if the string passed to this function is a syntactically correct domain name.
-
-
 - *Type*: rvalue
-
 is_float
---------
 Returns true if the variable passed to this function is a float.
-
-
 - *Type*: rvalue
-
+is_function_available
+---------------------
+This function accepts a string as an argument, determines whether the
+Puppet runtime has access to a function by that name.  It returns a
+true if the function exists, false if not.
+- *Type*: rvalue
 is_hash
 -------
 Returns true if the variable passed to this function is a hash.
-
-
-- *Type*: rvalue
-
 is_integer
 ----------
 Returns true if the variable returned to this string is an integer.
-
-
 - *Type*: rvalue
-
 is_ip_address
 -------------
 Returns true if the string passed to this function is a valid IP address.
-
-
 - *Type*: rvalue
-
 is_mac_address
 --------------
 Returns true if the string passed to this function is a valid mac address.
-
-
 - *Type*: rvalue
-
 is_numeric
 ----------
 Returns true if the variable passed to this function is a number.
 
-
 - *Type*: rvalue
 
 is_string
@@ -390,6 +453,21 @@ Would result in: "a,b,c"
 
 - *Type*: rvalue
 
+join_keys_to_values
+-------------------
+This function joins each key of a hash to that key's corresponding value with a
+separator. Keys and values are cast to strings. The return value is an array in
+which each element is one joined key/value pair.
+
+*Examples:*
+
+    join_keys_to_values({'a'=>1,'b'=>2}, " is ")
+
+Would result in: ["a is 1","b is 2"]
+
+
+- *Type*: rvalue
+
 keys
 ----
 Returns the keys of a hash as an array.
@@ -416,6 +494,20 @@ Strips leading spaces to the left of a string.
 
 - *Type*: rvalue
 
+max
+---
+Returns the highest value of all arguments.
+Requires at least one argument.
+
+
+- *Type*: rvalue
+
+md5
+---
+Returns a MD5 hash value from a provided string.
+
+- *Type*: rvalue
+
 member
 ------
 This function determines if a variable is a member of an array.
@@ -451,10 +543,25 @@ When there is a duplicate key, the key in the rightmost hash will "win."
 
 - *Type*: rvalue
 
+min
+---
+Returns the lowest value of all arguments.
+Requires at least one argument.
+
+
+- *Type*: rvalue
+
+notice
+------
+Log a message on the server at level notice.
+
+- *Type*: statement
+
 num2bool
 --------
-This function converts a number into a true boolean. Zero becomes false. Numbers
-higher then 0 become true.
+This function converts a number or a string representation of a number into a
+true boolean. Zero or anything non-numeric becomes false. Numbers higher then 0
+become true.
 
 
 - *Type*: rvalue
@@ -475,6 +582,25 @@ Puppet structure.
 
 - *Type*: rvalue
 
+pick
+----
+This function is similar to a coalesce function in SQL in that it will return
+the first value in a list of values that is not undefined or an empty string
+(two things in Puppet that will return a boolean false value). Typically,
+this function is used to check for a value in the Puppet Dashboard/Enterprise
+Console, and failover to a default value like the following:
+
+  $real_jenkins_version = pick($::jenkins_version, '1.449')
+
+The value of $real_jenkins_version will first look for a top-scope variable
+called 'jenkins_version' (note that parameters set in the Puppet Dashboard/
+Enterprise Console are brought into Puppet as top-scope variables), and,
+failing that, will use a default value of 1.449.
+
+
+
+- *Type*: rvalue
+
 prefix
 ------
 This function applies a prefix to all elements in an array.
@@ -515,6 +641,94 @@ Will return: ["host01", "host02", ..., "host09", "host10"]
 
 - *Type*: rvalue
 
+realize
+-------
+Make a virtual object real.  This is useful
+when you want to know the name of the virtual object and don't want to
+bother with a full collection.  It is slightly faster than a collection,
+and, of course, is a bit shorter.  You must pass the object using a
+reference; e.g.: `realize User[luke]`.
+
+- *Type*: statement
+
+regsubst
+--------
+Perform regexp replacement on a string or array of strings.
+
+* *Parameters* (in order):
+    * _target_  The string or array of strings to operate on.  If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array.
+    * _regexp_  The regular expression matching the target string.  If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself.
+    * _replacement_  Replacement string. Can contain backreferences to what was matched using \0 (whole match), \1 (first set of parentheses), and so on.
+    * _flags_  Optional. String of single letter flags for how the regexp is interpreted:
+        - *E*         Extended regexps
+        - *I*         Ignore case in regexps
+        - *M*         Multiline regexps
+        - *G*         Global replacement; all occurrences of the regexp in each target string will be replaced.  Without this, only the first occurrence will be replaced.
+    * _encoding_  Optional.  How to handle multibyte characters.  A single-character string with the following values:
+        - *N*         None
+        - *E*         EUC
+        - *S*         SJIS
+        - *U*         UTF-8
+
+* *Examples*
+
+Get the third octet from the node's IP address:
+
+    $i3 = regsubst($ipaddress,'^(\d+)\.(\d+)\.(\d+)\.(\d+)$','\3')
+
+Put angle brackets around each octet in the node's IP address:
+
+    $x = regsubst($ipaddress, '([0-9]+)', '<\1>', 'G')
+
+
+- *Type*: rvalue
+
+reject
+------
+This function searches through an array and rejects all elements that match
+the provided regular expression.
+
+*Examples:*
+
+    reject(['aaa','bbb','ccc','aaaddd'], 'aaa')
+
+Would return:
+
+    ['bbb','ccc']
+
+
+- *Type*: rvalue
+
+require
+-------
+Evaluate one or more classes,  adding the required class as a dependency.
+
+The relationship metaparameters work well for specifying relationships
+between individual resources, but they can be clumsy for specifying
+relationships between classes.  This function is a superset of the
+'include' function, adding a class relationship so that the requiring
+class depends on the required class.
+
+Warning: using require in place of include can lead to unwanted dependency cycles.
+
+For instance the following manifest, with 'require' instead of 'include' would produce a nasty dependence cycle, because notify imposes a before between File[/foo] and Service[foo]:
+
+    class myservice {
+      service { foo: ensure => running }
+    }
+
+    class otherstuff {
+      include myservice
+      file { '/foo': notify => Service[foo] }
+    }
+
+Note that this function only works with clients 0.25 and later, and it will
+fail if used with earlier clients.
+
+
+
+- *Type*: statement
+
 reverse
 -------
 Reverses the order of a string or array.
@@ -529,6 +743,7 @@ Strips leading spaces to the right of the string.
 
 - *Type*: rvalue
 
+search
 shuffle
 -------
 Randomizes the order of a string or array elements.
@@ -552,8 +767,7 @@ Sorts strings and arrays lexically.
 
 squeeze
 -------
-Returns a new string where runs of the same character that occur in this set
-are replaced by a single character.
+Returns a new string where runs of the same character that occur in this set are replaced by a single character.
 
 
 - *Type*: rvalue
@@ -569,10 +783,10 @@ like: 0, f, n, false, no to 'false'.
 
 str2saltedsha512
 ----------------
-This converts a string to a salted-SHA512 password hash (which is used for OS X
-versions >= 10.7). Given any simple string, you will get a hex version of a
-salted-SHA512 password hash that can be inserted into your Puppet manifests as
-a valid password attribute.
+This converts a string to a salted-SHA512 password hash (which is used for
+OS X versions >= 10.7). Given any simple string, you will get a hex version
+of a salted-SHA512 password hash that can be inserted into your Puppet
+manifests as a valid password attribute.
 
 
 - *Type*: rvalue
@@ -755,7 +969,15 @@ Converts a string or an array of strings to uppercase.
 
 Will return:
 
-    ABCD
+    ASDF
+
+
+- *Type*: rvalue
+
+uriescape
+---------
+Urlencodes a string or array of strings.
+Requires either a single string or an array as an input.
 
 
 - *Type*: rvalue
@@ -807,7 +1029,7 @@ The following values will fail, causing compilation to abort:
 - *Type*: statement
 
 validate_augeas
---------------
+---------------
 Perform validation of a string using an Augeas lens
 The first argument of this function should be a string to
 test, and the second argument should be the name of the Augeas lens to use.
@@ -836,6 +1058,7 @@ A helpful error message can be returned like this:
     validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas')
 
 
+
 - *Type*: statement
 
 validate_bool
@@ -860,9 +1083,8 @@ The following values will fail, causing compilation to abort:
 
 - *Type*: statement
 
-
 validate_cmd
--------------
+------------
 Perform validation of a string with an external command.
 The first argument of this function should be a string to
 test, and the second argument should be a path to a test command
@@ -1037,3 +1259,5 @@ Would result in:
 
 
 - *Type*: rvalue
+
+*This page autogenerated on 2013-04-11 13:54:25 -0700*