From 31b02f84922d29ee063fbfc3d6f4d9621c7cc424 Mon Sep 17 00:00:00 2001
From: Matthew Haughton <3flex@users.noreply.github.com>
Date: Thu, 17 Jul 2014 10:48:25 -0400
Subject: (MODULES-927) Add missing functions to README

* anchor
* bool2str
* camelcase
* deep_merge
* pick_default
* validate_ipv4_address
* validate_ipv6_address
---
 README.markdown | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/README.markdown b/README.markdown
index e9ad53b..e3bc490 100644
--- a/README.markdown
+++ b/README.markdown
@@ -77,6 +77,43 @@ Returns the absolute value of a number, for example -34.56 becomes
 
 - *Type*: rvalue
 
+anchor
+------
+A simple resource type intended to be used as an anchor in a composite class.
+
+In Puppet 2.6, when a class declares another class, the resources in the
+interior class are not contained by the exterior class. This interacts badly
+with the pattern of composing complex modules from smaller classes, as it
+makes it impossible for end users to specify order relationships between the
+exterior class and other modules.
+
+The anchor type lets you work around this. By sandwiching any interior
+classes between two no-op resources that _are_ contained by the exterior
+class, you can ensure that all resources in the module are contained.
+
+    class ntp {
+      # These classes will have the correct order relationship with each
+      # other. However, without anchors, they won't have any order
+      # relationship to Class['ntp'].
+      class { 'ntp::package': }
+      -> class { 'ntp::config': }
+      -> class { 'ntp::service': }
+    
+      # These two resources "anchor" the composed classes within the ntp
+      # class.
+      anchor { 'ntp::begin': } -> Class['ntp::package']
+      Class['ntp::service'] -> anchor { 'ntp::end': }
+    }
+
+This allows the end user of the ntp module to establish require and before
+relationships with Class['ntp']:
+
+    class { 'ntp': } -> class { 'mcollective': }
+    class { 'mcollective': } -> class { 'ntp': }
+
+
+- *Type*: resource
+
 any2array
 ---------
 This converts any object to an array containing that object. Empty argument
@@ -103,6 +140,19 @@ true, t, 1, y, and yes to 1
     Requires a single boolean or string as an input.
 
 
+- *Type*: rvalue
+
+bool2str
+--------
+Converts a boolean to a string.
+Requires a single boolean as an input.
+
+- *Type*: rvalue
+
+camelcase
+---------
+Converts the case of a string or all strings in an array to camel case.
+
 - *Type*: rvalue
 
 capitalize
@@ -160,6 +210,23 @@ 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
+
+deep_merge
+----------
+Recursively merges two or more hashes together and returns the resulting hash.
+
+*Example:*
+
+    $hash1 = {'one' => 1, 'two' => 2, 'three' => { 'four' => 4 } }
+    $hash2 = {'two' => 'dos', 'three' => { 'five' => 5 } }
+    $merged_hash = deep_merge($hash1, $hash2)
+    # The resulting hash is equivalent to:
+    # $merged_hash = { 'one' => 1, 'two' => 'dos', 'three' => { 'four' => 4, 'five' => 5 } }
+
+When there is a duplicate key that is a hash, they are recursively merged.
+When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
+
 - *Type*: rvalue
 
 defined_with_params
@@ -713,6 +780,30 @@ failing that, will use a default value of 1.449.
 
 - *Type*: rvalue
 
+pick_default
+------------
+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). If no value is
+found, it will return the last argument.
+
+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_default($::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.
+
+Note that, contrary to the pick() function, the pick_default does not fail if
+all arguments are empty. This allows pick_default to use an empty value as
+default.
+
+- *Type*: rvalue
+
 prefix
 ------
 This function applies a prefix to all elements in an array.
@@ -1166,6 +1257,43 @@ The following values will fail, causing compilation to abort:
 
 
 
+- *Type*: statement
+
+validate_ipv4_address
+---------------------
+Validate that all values passed are valid IPv4 addresses.
+Fail compilation if any value fails this check.
+
+The following values will pass:
+
+    $my_ip = "1.2.3.4"
+    validate_ipv4_address($my_ip)
+    validate_bool("8.8.8.8", "172.16.0.1", $my_ip)
+
+The following values will fail, causing compilation to abort:
+
+    $some_array = [ 1, true, false, "garbage string", "3ffe:505:2" ]
+    validate_ipv4_address($some_array)
+
+- *Type*: statement
+
+validate_ipv6_address
+---------------------
+ Validate that all values passed are valid IPv6 addresses.
+Fail compilation if any value fails this check.
+
+The following values will pass:
+
+    $my_ip = "3ffe:505:2"
+    validate_ipv6_address(1)
+    validate_ipv6_address($my_ip)
+    validate_bool("fe80::baf6:b1ff:fe19:7507", $my_ip)
+
+The following values will fail, causing compilation to abort:
+
+    $some_array = [ true, false, "garbage string", "1.2.3.4" ]
+    validate_ipv6_address($some_array)
+
 - *Type*: statement
 
 validate_re
-- 
cgit v1.2.3