diff options
Diffstat (limited to 'README.markdown')
| -rw-r--r-- | README.markdown | 913 |
1 files changed, 880 insertions, 33 deletions
diff --git a/README.markdown b/README.markdown index 9fa4c38..130753d 100644 --- a/README.markdown +++ b/README.markdown @@ -14,6 +14,9 @@ This module is officially curated and provided by Puppet Labs. The modules Puppet Labs writes and distributes will make heavy use of this standard library. +To report or research a bug with any part of this module, please go to +[http://projects.puppetlabs.com/projects/stdlib](http://projects.puppetlabs.com/projects/stdlib) + # Versions # This module follows semver.org (v1.0.0) versioning guidelines. The standard @@ -25,7 +28,7 @@ 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.2.x (Never released as part of PE, only to the Forge) - * v2.3.x (Scheduled for next PE feature release) + * v2.3.x (Released in PE 2.5.x) * master (mainline development branch) The first Puppet Enterprise version including the stdlib module is Puppet @@ -33,50 +36,894 @@ Enterprise 1.2. # Compatibility # -## stdlib v2.1.x, v2.2.x ## +The stdlib module does not work with Puppet versions released prior to Puppet +2.6.0. + +## stdlib 2.x ## -v2.1.x and v2.2.x of this module are designed to work with Puppet versions -2.6.x and 2.7.x. There are currently no plans for a Puppet 0.25 standard -library module. +All stdlib releases in the 2.0 major version support Puppet 2.6 and Puppet 2.7. -## stdlib v2.3.x ## +## stdlib 3.x ## -While not yet released, the standard library may only work with Puppet 2.7.x. +The 3.0 major release of stdlib drops support for Puppet 2.6. Stdlib 3.x +supports Puppet 2.7. # Functions # - Please see `puppet doc -r function` for documentation on each function. The - current list of functions is: +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. + + +- *Type*: rvalue + +bool2num +-------- +Converts a boolean to a number. Converts the values: +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. + + +- *Type*: rvalue + +capitalize +---------- +Capitalizes the first letter of a string or array of strings. +Requires either a single string or an array as an input. + + +- *Type*: rvalue + +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. + + +- *Type*: rvalue + +chop +---- +Returns a new string with the last character removed. If the string ends +with `\r\n`, both characters are removed. Applying chop to an empty +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. + + +- *Type*: rvalue + +defined_with_params +------------------- +Takes a resource reference and an optional hash of attributes. + +Returns true if a resource with the specified attributes has already been added +to the catalog, and false otherwise. + + user { 'dan': + ensure => present, + } + + if ! defined_with_params(User[dan], {'ensure' => 'present' }) { + user { 'dan': ensure => present, } + } + + +- *Type*: rvalue + +delete +------ +Deletes a selected element from an array. + +*Examples:* + + delete(['a','b','c'], 'b') + +Would return: ['a','c'] + + +- *Type*: rvalue + +delete_at +--------- +Deletes a determined indexed value from an array. + +*Examples:* + + delete_at(['a','b','c'], 1) + +Would return: ['a','c'] + + +- *Type*: rvalue + +downcase +-------- +Converts the case of a string or all strings in an array to lower case. + + +- *Type*: rvalue + +empty +----- +Returns true if the variable is empty. + + +- *Type*: rvalue + +ensure_resource +--------------- +Takes a resource type, title, and a list of attributes that describe a +resource. + + user { 'dan': + ensure => present, + } + +This example only creates the resource if it does not already exist: + + ensure_resource('user, 'dan', {'ensure' => 'present' }) + +If the resource already exists but does not match the specified parameters, +this function will attempt to recreate the resource leading to a duplicate +resource definition error. + + + +- *Type*: statement + +flatten +------- +This function flattens any deeply nested arrays and returns a single flat array +as a result. + +*Examples:* + + flatten(['a', ['b', ['c']]]) + +Would return: ['a','b','c'] + + +- *Type*: rvalue + +fqdn_rotate +----------- +Rotates an array a random number of times based on a nodes fqdn. + + +- *Type*: rvalue + +get_module_path +--------------- +Returns the absolute path of the specified module for the current +environment. + +Example: + $module_path = get_module_path('stdlib') + + +- *Type*: rvalue + +getvar +------ +Lookup a variable in a remote namespace. + +For example: + + $foo = getvar('site::data::foo') + # Equivalent to $foo = $site::data::foo + +This is useful if the namespace itself is stored in a string: + + $datalocation = 'site::data' + $bar = getvar("${datalocation}::bar") + # Equivalent to $bar = $site::data::bar + + +- *Type*: rvalue + +grep +---- +This function searches through an array and returns any elements that match +the provided regular expression. + +*Examples:* + + grep(['aaa','bbb','ccc','aaaddd'], 'aaa') + +Would return: + + ['aaa','aaaddd'] + + +- *Type*: rvalue + +has_key +------- +Determine if a hash has a certain key value. + +Example: + + $my_hash = {'key_one' => 'value_one'} + if has_key($my_hash, 'key_two') { + notice('we will not reach here') + } + if has_key($my_hash, 'key_one') { + notice('this will be printed') + } + + + +- *Type*: rvalue + +hash +---- +This function converts and array into a hash. + +*Examples:* + + hash(['a',1,'b',2,'c',3]) + +Would return: {'a'=>1,'b'=>2,'c'=>3} + + +- *Type*: rvalue + +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_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 +--------- +Returns true if the variable passed to this function is a string. + + +- *Type*: rvalue + +join +---- +This function joins an array into a string using a seperator. + +*Examples:* + + join(['a','b','c'], ",") + +Would result in: "a,b,c" + + +- *Type*: rvalue + +keys +---- +Returns the keys of a hash as an array. + + +- *Type*: rvalue + +loadyaml +-------- +Load a YAML file containing an array, string, or hash, and return the data +in the corresponding native data type. + +For example: + + $myhash = loadyaml('/etc/puppet/data/myhash.yaml') + + +- *Type*: rvalue + +lstrip +------ +Strips leading spaces to the left of a string. + + +- *Type*: rvalue + +member +------ +This function determines if a variable is a member of an array. + +*Examples:* + + member(['a','b'], 'b') + +Would return: true + + member(['a','b'], 'c') + +Would return: false + + +- *Type*: rvalue + +merge +----- +Merges two or more hashes together and returns the resulting hash. + +For example: + + $hash1 = {'one' => 1, 'two', => 2} + $hash2 = {'two' => 'dos', 'three', => 'tres'} + $merged_hash = merge($hash1, $hash2) + # The resulting hash is equivalent to: + # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} + +When there is a duplicate key, the key in the rightmost hash will "win." + + + +- *Type*: rvalue + +num2bool +-------- +This function converts a number into a true boolean. Zero becomes false. Numbers +higher then 0 become true. + + +- *Type*: rvalue + +parsejson +--------- +This function accepts JSON as a string and converts into the correct Puppet +structure. + + +- *Type*: rvalue + +parseyaml +--------- +This function accepts YAML as a string and converts it into the correct +Puppet structure. + + +- *Type*: rvalue + +prefix +------ +This function applies a prefix to all elements in an array. + +*Examles:* + + prefix(['a','b','c'], 'p') + +Will return: ['pa','pb','pc'] + + +- *Type*: rvalue + +range +----- +When given range in the form of (start, stop) it will extrapolate a range as +an array. + +*Examples:* + + range("0", "9") + +Will return: [0,1,2,3,4,5,6,7,8,9] + + range("00", "09") + +Will return: [0,1,2,3,4,5,6,7,8,9] (Zero padded strings are converted to +integers automatically) + + range("a", "c") + +Will return: ["a","b","c"] + + range("host01", "host10") + +Will return: ["host01", "host02", ..., "host09", "host10"] + + +- *Type*: rvalue + +reverse +------- +Reverses the order of a string or array. + + +- *Type*: rvalue + +rstrip +------ +Strips leading spaces to the right of the string. + + +- *Type*: rvalue + +shuffle +------- +Randomizes the order of a string or array elements. + + +- *Type*: rvalue + +size +---- +Returns the number of elements in a string or array. + + +- *Type*: rvalue + +sort +---- +Sorts strings and arrays lexically. + + +- *Type*: rvalue + +squeeze +------- +Returns a new string where runs of the same character that occur in this set +are replaced by a single character. + + +- *Type*: rvalue + +str2bool +-------- +This converts a string to a boolean. This attempt to convert strings that +contain things like: y, 1, t, true to 'true' and strings that contain things +like: 0, f, n, false, no to 'false'. + + +- *Type*: rvalue + +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. + + +- *Type*: rvalue + +strftime +-------- +This function returns formatted time. + +*Examples:* + +To return the time since epoch: + + strftime("%s") + +To return the date: + + strftime("%Y-%m-%d") + +*Format meaning:* + + %a - The abbreviated weekday name (``Sun'') + %A - The full weekday name (``Sunday'') + %b - The abbreviated month name (``Jan'') + %B - The full month name (``January'') + %c - The preferred local date and time representation + %C - Century (20 in 2009) + %d - Day of the month (01..31) + %D - Date (%m/%d/%y) + %e - Day of the month, blank-padded ( 1..31) + %F - Equivalent to %Y-%m-%d (the ISO 8601 date format) + %h - Equivalent to %b + %H - Hour of the day, 24-hour clock (00..23) + %I - Hour of the day, 12-hour clock (01..12) + %j - Day of the year (001..366) + %k - hour, 24-hour clock, blank-padded ( 0..23) + %l - hour, 12-hour clock, blank-padded ( 0..12) + %L - Millisecond of the second (000..999) + %m - Month of the year (01..12) + %M - Minute of the hour (00..59) + %n - Newline ( +) + %N - Fractional seconds digits, default is 9 digits (nanosecond) + %3N millisecond (3 digits) + %6N microsecond (6 digits) + %9N nanosecond (9 digits) + %p - Meridian indicator (``AM'' or ``PM'') + %P - Meridian indicator (``am'' or ``pm'') + %r - time, 12-hour (same as %I:%M:%S %p) + %R - time, 24-hour (%H:%M) + %s - Number of seconds since 1970-01-01 00:00:00 UTC. + %S - Second of the minute (00..60) + %t - Tab character ( ) + %T - time, 24-hour (%H:%M:%S) + %u - Day of the week as a decimal, Monday being 1. (1..7) + %U - Week number of the current year, + starting with the first Sunday as the first + day of the first week (00..53) + %v - VMS date (%e-%b-%Y) + %V - Week number of year according to ISO 8601 (01..53) + %W - Week number of the current year, + starting with the first Monday as the first + day of the first week (00..53) + %w - Day of the week (Sunday is 0, 0..6) + %x - Preferred representation for the date alone, no time + %X - Preferred representation for the time alone, no date + %y - Year without a century (00..99) + %Y - Year with century + %z - Time zone as hour offset from UTC (e.g. +0900) + %Z - Time zone name + %% - Literal ``%'' character + + +- *Type*: rvalue + +strip +----- +This function removes leading and trailing whitespace from a string or from +every string inside an array. + +*Examples:* + + strip(" aaa ") + +Would result in: "aaa" + + +- *Type*: rvalue + +swapcase +-------- +This function will swap the existing case of a string. + +*Examples:* + + swapcase("aBcD") + +Would result in: "AbCd" + + +- *Type*: rvalue + +time +---- +This function will return the current time since epoch as an integer. + +*Examples:* + + time() + +Will return something like: 1311972653 + + +- *Type*: rvalue + +to_bytes +-------- +Converts the argument into bytes, for example 4 kB becomes 4096. +Takes a single string value as an argument. + + +- *Type*: rvalue + +type +---- +Returns the type when passed a variable. Type can be one of: + +* string +* array +* hash +* float +* integer +* boolean + + +- *Type*: rvalue + +unique +------ +This function will remove duplicates from strings and arrays. + +*Examples:* + + unique("aabbcc") + +Will return: + + abc + +You can also use this with arrays: + + unique(["a","a","b","b","c","c"]) + +This returns: + + ["a","b","c"] + + +- *Type*: rvalue + +upcase +------ +Converts a string or an array of strings to uppercase. + +*Examples:* + + upcase("abcd") + +Will return: + + ABCD + + +- *Type*: rvalue + +validate_absolute_path +---------------------- +Validate the string represents an absolute path in the filesystem. This function works +for windows and unix style paths. + +The following values will pass: + + $my_path = "C:/Program Files (x86)/Puppet Labs/Puppet" + validate_absolute_path($my_path) + $my_path2 = "/var/lib/puppet" + validate_absolute_path($my_path2) + + +The following values will fail, causing compilation to abort: + + validate_absolute_path(true) + validate_absolute_path([ 'var/lib/puppet', '/var/foo' ]) + validate_absolute_path([ '/var/lib/puppet', 'var/foo' ]) + $undefined = undef + validate_absolute_path($undefined) + + + +- *Type*: statement + +validate_array +-------------- +Validate that all passed values are array data structures. Abort catalog +compilation if any value fails this check. + +The following values will pass: + + $my_array = [ 'one', 'two' ] + validate_array($my_array) + +The following values will fail, causing compilation to abort: + + validate_array(true) + validate_array('some_string') + $undefined = undef + validate_array($undefined) + + + +- *Type*: statement + +validate_bool +------------- +Validate that all passed values are either true or false. Abort catalog +compilation if any value fails this check. + +The following values will pass: + + $iamtrue = true + validate_bool(true) + validate_bool(true, true, false, $iamtrue) + +The following values will fail, causing compilation to abort: + + $some_array = [ true ] + validate_bool("false") + validate_bool("true") + validate_bool($some_array) + + + +- *Type*: statement + +validate_hash +------------- +Validate that all passed values are hash data structures. Abort catalog +compilation if any value fails this check. + +The following values will pass: + + $my_hash = { 'one' => 'two' } + validate_hash($my_hash) + +The following values will fail, causing compilation to abort: + + validate_hash(true) + validate_hash('some_string') + $undefined = undef + validate_hash($undefined) + + + +- *Type*: statement + +validate_re +----------- +Perform simple validation of a string against one or more regular +expressions. The first argument of this function should be a string to +test, and the second argument should be a stringified regular expression +(without the // delimiters) or an array of regular expressions. If none +of the regular expressions match the string passed in, compilation will +abort with a parse error. + +If a third argument is specified, this will be the error message raised and +seen by the user. + +The following strings will validate against the regular expressions: + + validate_re('one', '^one$') + validate_re('one', [ '^one', '^two' ]) + +The following strings will fail to validate, causing compilation to abort: + + validate_re('one', [ '^two', '^three' ]) + +A helpful error message can be returned like this: + + validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7') + + + +- *Type*: statement + +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. + +The following values will pass: + + validate_slength("discombobulate",17) + validate_slength(["discombobulate","moo"],17) + +The following valueis will not: + + validate_slength("discombobulate",1) + validate_slength(["discombobulate","thermometer"],5) + + + +- *Type*: statement + +validate_string +--------------- +Validate that all passed values are string data structures. Abort catalog +compilation if any value fails this check. + +The following values will pass: + + $my_string = "one two" + validate_string($my_string, 'three') + +The following values will fail, causing compilation to abort: + + validate_string(true) + validate_string([ 'some', 'array' ]) + $undefined = undef + validate_string($undefined) + + + +- *Type*: statement + +values +------ +When given a hash this function will return the values of that hash. + +*Examples:* + + $hash = { + 'a' => 1, + 'b' => 2, + 'c' => 3, + } + values($hash) + +This example would return: + + [1,2,3] + + +- *Type*: rvalue + +values_at +--------- +Finds value inside an array based on location. + +The first argument is the array you want to analyze, and the second element can +be a combination of: + +* A single numeric index +* A range in the form of 'start-stop' (eg. 4-9) +* An array combining the above + +*Examples*: + + values_at(['a','b','c'], 2) + +Would return ['c']. + + values_at(['a','b','c'], ["0-1"]) + +Would return ['a','b']. + + values_at(['a','b','c','d','e'], [0, "2-3"]) + +Would return ['a','c','d']. - * getvar - * has\_key - * loadyaml - * merge.rb - * validate\_array - * validate\_bool - * validate\_hash - * validate\_re - * validate\_string -## validate\_hash ## +- *Type*: rvalue - $somehash = { 'one' => 'two' } - validate\_hash($somehash) +zip +--- +Takes one element from first array and merges corresponding elements from second array. This generates a sequence of n-element arrays, where n is one more than the count of arguments. -## getvar() ## +*Example:* -This function aims to look up variables in user-defined namespaces within -puppet. Note, if the namespace is a class, it should already be evaluated -before the function is used. + zip(['1','2','3'],['4','5','6']) - $namespace = 'site::data' - include "${namespace}" - $myvar = getvar("${namespace}::myvar") +Would result in: -## Facts ## + ["1", "4"], ["2", "5"], ["3", "6"] -Facts in `/etc/facter/facts.d` and `/etc/puppetlabs/facter/facts.d` are now loaded -automatically. This is a direct copy of R.I. Pienaar's custom facter fact -located at: -[https://github.com/ripienaar/facter-facts/tree/master/facts-dot-d](https://github.com/ripienaar/facter-facts/tree/master/facts-dot-d) +- *Type*: rvalue |