Merge pull request #302 from 3flex/update-readme

(MODULES-927) Update readme

1 files changed, 180 insertions, 12 deletions

diff --git a/README.markdown b/README.markdown
index e9ad53b..e033b15 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
@@ -105,6 +142,19 @@ true, t, 1, y, and yes to 1
 
 - *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
 ----------
 Capitalizes the first letter of a string or array of strings.
@@ -162,6 +212,23 @@ If called with only an array it counts the number of elements that are not nil/u
 
 - *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
 -------------------
 Takes a resource reference and an optional hash of attributes.
@@ -314,8 +381,11 @@ the type and parameters specified if it doesn't already exist.
 
 file_line
 ---------
-This resource ensures that a given line is contained within a file. You can also use 
-"match" to replace existing lines.
+Ensures that a given line is contained within a file. The implementation
+matches the full line, including whitespace at the beginning and end. If
+the line is not contained in the given file, Puppet will add the line to
+ensure the desired state. Multiple resources may be declared to manage
+multiple lines in the same file.
 
 *Examples:*
 
@@ -323,13 +393,42 @@ This resource ensures that a given line is contained within a file. You can also
       path => '/etc/sudoers',
       line => '%sudo ALL=(ALL) ALL',
     }
-
-    file_line { 'change_mount':
-      path  => '/etc/fstab',
-      line  => '10.0.0.1:/vol/data /opt/data nfs defaults 0 0',
-      match => '^172.16.17.2:/vol/old',
+    file_line { 'sudo_rule_nopw':
+      path => '/etc/sudoers',
+      line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
     }
 
+In this example, Puppet will ensure both of the specified lines are
+contained in the file /etc/sudoers.
+
+*Parameters within `file_line`:*
+
+**`after`**
+
+An optional value used to specify the line after which we will add any new
+lines. (Existing lines are added in place)
+
+**`line`**
+
+The line to be appended to the file located by the path parameter.
+
+**`match`**
+
+An optional regular expression to run against existing lines in the file;
+if a match is found, we replace that line rather than adding a new line.
+
+**`multiple`**
+
+An optional value to determine if match can change multiple lines.
+
+**`name`**
+
+An arbitrary name used as the identity of the resource.
+
+**`path`**
+
+The file Puppet will ensure contains the line specified by the line parameter.
+
 - *Type*: resource
 
 flatten
@@ -713,6 +812,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.
@@ -749,6 +872,13 @@ Will return: ["a","b","c"]
 
 Will return: ["host01", "host02", ..., "host09", "host10"]
 
+Passing a third argument will cause the generated range to step by that
+interval, e.g.
+
+    range("0", "9", "2")
+
+Will return: [0,2,4,6,8]
+
 - *Type*: rvalue
 
 reject
@@ -1168,6 +1298,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
 -----------
 Perform simple validation of a string against one or more regular
@@ -1200,21 +1367,22 @@ A helpful error message can be returned like this:
 validate_slength
 ----------------
 Validate that the first argument is a string (or an array of strings), and
-less/equal to than the length of the second argument.  It fails if the first
-argument is not a string or array of strings, and if arg 2 is not convertable
-to a number.
+less/equal to than the length of the second argument. An optional third
+parameter can be given a the minimum length. It fails if the first
+argument is not a string or array of strings, and if arg 2 and arg 3 are
+not convertable to a number.
 
 The following values will pass:
 
     validate_slength("discombobulate",17)
     validate_slength(["discombobulate","moo"],17)
+    validate_slength(["discombobulate","moo"],17,3)
 
 The following values will not:
 
     validate_slength("discombobulate",1)
     validate_slength(["discombobulate","thermometer"],5)
-
-
+    validate_slength(["discombobulate","moo"],17,10)
 
 - *Type*: statement