From 260c1f4b92113a1da3b30562a11d20a79e5b08db Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 4 Dec 2014 22:33:15 +0100 Subject: Add new functions validate_numeric() and validate_integer(). --- README.markdown | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 78839c6..69c5d3d 100644 --- a/README.markdown +++ b/README.markdown @@ -579,6 +579,76 @@ The first argument of this function should be the string to test, and the second *Type*: statement +* `validate_integer`: Validate that the first argument is an integer (or an array of integers). Abort catalog compilation if any of the checks fail. + + The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. + + The third argument is optional and passes a minimum. (All elements of) the first argument has to be greater or equal to this min. + If, and only if, a minimum is given, the second argument may be an empty string or undef, which will be handled to just check + if (all elements of) the first argument are greater or equal to the given minimum. + + It will fail if the first argument is not an integer or array of integers, and if arg 2 and arg 3 are not convertable to an integer. + + The following values will pass: + + ``` + validate_integer(1) + validate_integer(1, 2) + validate_integer(1, 1) + validate_integer(1, 2, 0) + validate_integer(2, 2, 2) + validate_integer(2, '', 0) + validate_integer(2, undef, 0) + $foo = undef + validate_integer(2, $foo, 0) + validate_integer([1,2,3,4,5], 6) + validate_integer([1,2,3,4,5], 6, 0) + ``` + + * Plus all of the above, but any combination of values passed as strings ('1' or "1"). + * Plus all of the above, but with (correct) combinations of negative integer values. + + The following values will fail, causing compilation to abort: + + ``` + validate_integer(true) + validate_integer(false) + validate_integer(7.0) + validate_integer({ 1 => 2 }) + $foo = undef + validate_integer($foo) + validate_integer($foobaridontexist) + + validate_integer(1, 0) + validate_integer(1, true) + validate_integer(1, '') + validate_integer(1, undef) + validate_integer(1, , 0) + validate_integer(1, 2, 3) + validate_integer(1, 3, 2) + validate_integer(1, 3, true) + ``` + + * Plus all of the above, but any combination of values passed as strings ('false' or "false"). + * Plus all of the above, but with incorrect combinations of negative integer values. + * Plus all of the above, but with non-integer crap in arrays or maximum / minimum argument. + + *Type*: statement + +* `validate_numeric`: Validate that the first argument is a numeric value (or an array of numeric values). Abort catalog compilation if any of the checks fail. + + The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. + + The third argument is optional and passes a minimum. (All elements of) the first argument has to be greater or equal to this min. + If, and only if, a minimum is given, the second argument may be an empty string or undef, which will be handled to just check + if (all elements of) the first argument are greater or equal to the given minimum. + + It will fail if the first argument is not a numeric (Integer or Float) or array of numerics, and if arg 2 and arg 3 are not convertable to a numeric. + + For passing and failing usage, see `validate_integer()`. It is all the same for validate_numeric, yet now floating point values are allowed, too. + + *Type*: statement + * `validate_re`: Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the string to test, and the second argument should be a stringified regular expression (without the // delimiters) or an array of regular expressions. If none -- cgit v1.2.3 From 53b1802a92010c9f2ef557005c57977cb219cb64 Mon Sep 17 00:00:00 2001 From: Adam Crews Date: Sun, 1 Feb 2015 22:46:16 -0800 Subject: Add a ceiling function to complement the floor function. --- README.markdown | 3 +++ 1 file changed, 3 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index e9a1f4e..3292d3e 100644 --- a/README.markdown +++ b/README.markdown @@ -124,6 +124,9 @@ string. *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 +* `ceiling`: Returns the smallest integer greater than or equal to the argument. +Takes a single numeric value as an argument. *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 -- cgit v1.2.3 From ef539388cbcb68ac5a59a7efb92fadbdb9fcdc72 Mon Sep 17 00:00:00 2001 From: Spencer Krum Date: Thu, 19 Feb 2015 13:58:14 -0800 Subject: Remove travis badge --- README.markdown | 2 -- 1 file changed, 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index e9a1f4e..3d2d1b9 100644 --- a/README.markdown +++ b/README.markdown @@ -1,7 +1,5 @@ #stdlib -[![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-stdlib.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-stdlib) - ####Table of Contents 1. [Overview](#overview) -- cgit v1.2.3 From 85e81f9bdf9d482338c504ff3c658993a24978a0 Mon Sep 17 00:00:00 2001 From: Travis Fields Date: Fri, 27 Feb 2015 17:40:32 -0800 Subject: Loosen the restrictions of upcase and allow for recursion of the objects and only worry if the object responds to upcase --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 3d2d1b9..0ea0c4e 100644 --- a/README.markdown +++ b/README.markdown @@ -475,7 +475,7 @@ Takes a single string value as an argument. *Type*: rvalue You can also use this with arrays. For example, `unique(["a","a","b","b","c","c"])` returns ["a","b","c"]. *Type*: rvalue -* `upcase`: Converts a string or an array of strings to uppercase. For example, `upcase("abcd")` returns 'ABCD'. *Type*: rvalue +* `upcase`: Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase("abcd")` returns 'ABCD'. *Type*: rvalue * `uriescape`: Urlencodes a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue -- cgit v1.2.3 From 0236cd51bc2724b4ac68b91dda01d1b58b572df8 Mon Sep 17 00:00:00 2001 From: Stefan Goethals Date: Wed, 4 Jun 2014 06:12:22 -0700 Subject: Add support for hashes in the prefix function Signed-off-by: Julien Pivotto --- README.markdown | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index ac0cae6..3a33d48 100644 --- a/README.markdown +++ b/README.markdown @@ -360,7 +360,7 @@ returns the value of the resource's parameter. For example, the following code r *Type*: rvalue -* `prefix`: This function applies a prefix to all elements in an array. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc']. *Type*: rvalue +* `prefix`: This function applies a prefix to all elements in an array or to the keys in a hash. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'], and `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue * `private`: This function sets the current class or definition as private. @@ -453,7 +453,6 @@ manifests as a valid password attribute. *Type*: rvalue * `%Z`: Time zone name * `%%`: Literal '%' character - * `strip`: This function removes leading and trailing whitespace from a string or from every string inside an array. For example, `strip(" aaa ")` results in "aaa". *Type*: rvalue * `suffix`: This function applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue -- cgit v1.2.3 From 380cb02a65f51a520dc5ee000b605d3b7dbe9bd4 Mon Sep 17 00:00:00 2001 From: robruma Date: Wed, 11 Feb 2015 20:27:30 -0500 Subject: Adding markdown for the range() function's 3rd argument Adding markdown for the range() function's 3rd argument Adding markdown for the range() function's 3rd argument --- README.markdown | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index ac0cae6..26a6b94 100644 --- a/README.markdown +++ b/README.markdown @@ -382,6 +382,8 @@ Calling the class or definition from outside the current module will fail. For e Non-integer strings are accepted; `range("a", "c")` returns ["a","b","c"], and `range("host01", "host10")` returns ["host01", "host02", ..., "host09", "host10"]. + Passing a third argument will cause the generated range to step by that interval, e.g. `range("0", "9", "2")` returns ["0","2","4","6","8"] + *Type*: rvalue * `reject`: This function searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *Type*: rvalue -- cgit v1.2.3 From 56d815bcfc5f57d8dff974fd8bba192c6b141f89 Mon Sep 17 00:00:00 2001 From: Franz Pletz Date: Fri, 19 Dec 2014 12:25:21 +0100 Subject: Rename private() to assert_private() As mentioned in #270, private is a reserved keyword in the future parser which is to be released with Puppet 4. As it stands, this function is not useable with the future parser so it needs to renamed. This is a breaking change. --- README.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 32d3b18..5adabf7 100644 --- a/README.markdown +++ b/README.markdown @@ -363,8 +363,8 @@ returns the value of the resource's parameter. For example, the following code r * `prefix`: This function applies a prefix to all elements in an array or to the keys in a hash. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'], and `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue -* `private`: This function sets the current class or definition as private. -Calling the class or definition from outside the current module will fail. For example, `private()` called in class `foo::bar` outputs the following message if class is called from outside module `foo`: +* `assert_private`: This function sets the current class or definition as private. +Calling the class or definition from outside the current module will fail. For example, `assert_private()` called in class `foo::bar` outputs the following message if class is called from outside module `foo`: ``` Class foo::bar is private @@ -373,7 +373,7 @@ Calling the class or definition from outside the current module will fail. For e You can specify the error message you want to use: ``` - private("You're not supposed to do that!") + assert_private("You're not supposed to do that!") ``` *Type*: statement -- cgit v1.2.3 From c297bd80e38c73618c0c706783386fef63bf0682 Mon Sep 17 00:00:00 2001 From: Spencer Krum Date: Sat, 28 Mar 2015 20:27:06 -0700 Subject: Make each function a link in the readme Using a ####, github will create a link. This makes it so I can link someone directly to the function I want to show them. --- README.markdown | 388 ++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 291 insertions(+), 97 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 9c6a54b..293a81a 100644 --- a/README.markdown +++ b/README.markdown @@ -99,44 +99,68 @@ If you want to use a standardized set of run stages for Puppet, `include stdlib` ### 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. *Type*: rvalue +#### `abs` -* `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 +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 -* `base64`: Converts a string to and from base64 encoding. +#### `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 + +#### `base64` + +Converts a string to and from base64 encoding. Requires an action ('encode', 'decode') and either a plain or base64-encoded string. *Type*: rvalue -* `basename`: Returns the `basename` of a path (optionally stripping an extension). For example: +#### `basename` + +Returns the `basename` of a path (optionally stripping an extension). For example: * ('/path/to/a/file.ext') returns 'file.ext' * ('relative/path/file.ext') returns 'file.ext' * ('/path/to/a/file.ext', '.ext') returns 'file' *Type*: rvalue -* `bool2num`: Converts a boolean to a number. Converts values: +#### `bool2num` + +Converts a boolean to a number. Converts 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. +#### `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 -* `ceiling`: Returns the smallest integer greater than or equal to the argument. +#### `ceiling` + +Returns the smallest integer greater than or equal to the argument. Takes a single numeric value as an argument. *Type*: rvalue -* `chomp`: Removes the record separator from the end of a string or an array of +#### `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 want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as 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 want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as input. *Type*: rvalue + +#### `concat` -* `concat`: Appends the contents of multiple arrays onto array 1. For example: +Appends the contents of multiple arrays onto array 1. For example: * `concat(['1','2','3'],'4')` results in: ['1','2','3','4']. * `concat(['1','2','3'],'4',['5','6','7'])` results in: ['1','2','3','4','5','6','7']. -* `count`: 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 +#### `count` -* `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. Returns 'false' otherwise. +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 + +#### `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. Returns 'false' otherwise. ``` user { 'dan': @@ -150,28 +174,48 @@ strings; for example, 'hello\n' becomes 'hello'. Requires a single string or arr *Type*: rvalue -* `delete`: Deletes all instances of a given element from an array, substring from a +#### `delete` + +Deletes all instances of a given element from an array, substring from a string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1} *Type*: rvalue -* `delete_at`: Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue +#### `delete_at` -* `delete_values`: Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue +Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue -* `delete_undef_values`: Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue +#### `delete_values` -* `difference`: Returns the difference between two arrays. +Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue + +#### `delete_undef_values` + +Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue + +#### `difference` + +Returns the difference between two arrays. The returned array is a copy of the original array, removing any items that also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. -* `dirname`: Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. +#### `dirname` + +Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. + +#### `downcase` -* `downcase`: Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue +Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue -* `empty`: Returns 'true' if the variable is empty. *Type*: rvalue +#### `empty` -* `ensure_packages`: Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement +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. +#### `ensure_packages` + +Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement + +#### `ensure_resource` + +Takes a resource type, title, and a list of attributes that describe a resource. ``` user { 'dan': @@ -191,20 +235,30 @@ also appear in the second array. For example, `difference(["a","b","c"],["b","c" *Type*: statement -* `flatten`: This function flattens any deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue +#### `flatten` -* `floor`: Returns the largest integer less than or equal to the argument. +This function flattens any deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue + +#### `floor` + +Returns the largest integer less than or equal to the argument. Takes a single numeric value as an argument. *Type*: rvalue -* `fqdn_rotate`: Rotates an array a random number of times based on a node's fqdn. *Type*: rvalue +#### `fqdn_rotate` + +Rotates an array a random number of times based on a node's fqdn. *Type*: rvalue -* `get_module_path`: Returns the absolute path of the specified module for the current environment. +#### `get_module_path` + +Returns the absolute path of the specified module for the current environment. `$module_path = get_module_path('stdlib')` *Type*: rvalue -* `getparam`: Takes a resource reference and the name of the parameter and +#### `getparam` + +Takes a resource reference and the name of the parameter and returns the value of the resource's parameter. For example, the following code returns 'param_value'. *Example:* @@ -222,7 +276,9 @@ returns the value of the resource's parameter. For example, the following code r *Type*: rvalue -* `getvar`: Lookup a variable in a remote namespace. +#### `getvar` + +Lookup a variable in a remote namespace. For example: @@ -241,9 +297,13 @@ returns the value of the resource's parameter. For example, the following code r *Type*: rvalue -* `grep`: This function searches through an array and returns any elements that match the provided regular expression. For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd']. *Type*: rvalue +#### `grep` -* `has_interface_with`: Returns boolean based on kind and value: +This function searches through an array and returns any elements that match the provided regular expression. For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd']. *Type*: rvalue + +#### `has_interface_with` + +Returns boolean based on kind and value: * macaddress * netmask * ipaddress @@ -264,11 +324,17 @@ returns the value of the resource's parameter. For example, the following code r *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_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_ip_network` -* `has_key`: Determine if a hash has a certain key value. +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. *Example*: @@ -284,39 +350,73 @@ returns the value of the resource's parameter. For example, the following code r *Type*: rvalue -* `hash`: This function converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}. *Type*: rvalue +#### `hash` + +This function converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}. *Type*: rvalue + +#### `intersection` + +This function returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. + +#### `is_array` + +Returns 'true' if the variable passed to this function is an array. *Type*: rvalue + +#### `is_bool` + +Returns 'true' if the variable passed to this function is a boolean. *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 and determines whether the Puppet runtime has access to a function by that name. It returns '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` -* `intersection`: This function returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. +Returns 'true' if the variable returned to this string is an integer. *Type*: rvalue -* `is_array`: Returns 'true' if the variable passed to this function is an array. *Type*: rvalue +#### `is_ip_address` -* `is_bool`: Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue +Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue -* `is_domain_name`: Returns 'true' if the string passed to this function is a syntactically correct domain name. *Type*: rvalue +#### `is_mac_address` -* `is_float`: Returns 'true' if the variable passed to this function is a float. *Type*: rvalue +Returns 'true' if the string passed to this function is a valid MAC address. *Type*: rvalue -* `is_function_available`: This function accepts a string as an argument and determines whether the Puppet runtime has access to a function by that name. It returns 'true' if the function exists, 'false' if not. *Type*: rvalue +#### `is_numeric` -* `is_hash`: Returns 'true' if the variable passed to this function is a hash. *Type*: rvalue +Returns 'true' if the variable passed to this function is a number. *Type*: rvalue -* `is_integer`: Returns 'true' if the variable returned to this string is an integer. *Type*: rvalue +#### `is_string` -* `is_ip_address`: Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue +Returns 'true' if the variable passed to this function is a string. *Type*: rvalue -* `is_mac_address`: Returns 'true' if the string passed to this function is a valid MAC address. *Type*: rvalue +#### `join` -* `is_numeric`: Returns 'true' if the variable passed to this function is a number. *Type*: rvalue +This function joins an array into a string using a separator. For example, `join(['a','b','c'], ",")` results in: "a,b,c". *Type*: rvalue -* `is_string`: Returns 'true' if the variable passed to this function is a string. *Type*: rvalue +#### `join_keys_to_values` -* `join`: This function joins an array into a string using a separator. For example, `join(['a','b','c'], ",")` results in: "a,b,c". *Type*: rvalue +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. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *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. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *Type*: rvalue +#### `keys` -* `keys`: Returns the keys of a hash as an array. *Type*: rvalue +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: +#### `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') @@ -324,13 +424,21 @@ returns the value of the resource's parameter. For example, the following code r *Type*: rvalue -* `lstrip`: Strips leading spaces to the left of a string. *Type*: rvalue +#### `lstrip` + +Strips leading spaces to the left of a string. *Type*: rvalue + +#### `max` -* `max`: Returns the highest value of all arguments. Requires at least one argument. *Type*: rvalue +Returns the highest value of all arguments. Requires at least one argument. *Type*: rvalue -* `member`: This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Type*: rvalue +#### `member` -* `merge`: Merges two or more hashes together and returns the resulting hash. +This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Type*: rvalue + +#### `merge` + +Merges two or more hashes together and returns the resulting hash. *Example*: @@ -344,15 +452,25 @@ returns the value of the resource's parameter. For example, the following code r When there is a duplicate key, the key in the rightmost hash "wins." *Type*: rvalue -* `min`: Returns the lowest value of all arguments. Requires at least one argument. *Type*: rvalue +#### `min` + +Returns the lowest value of all arguments. Requires at least one argument. *Type*: rvalue -* `num2bool`: This function converts a number or a string representation of a number into a true boolean. Zero or anything non-numeric becomes 'false'. Numbers greater than 0 become 'true'. *Type*: rvalue +#### `num2bool` -* `parsejson`: This function accepts JSON as a string and converts into the correct Puppet structure. *Type*: rvalue +This function converts a number or a string representation of a number into a true boolean. Zero or anything non-numeric becomes 'false'. Numbers greater than 0 become 'true'. *Type*: rvalue -* `parseyaml`: This function accepts YAML as a string and converts it into the correct Puppet structure. *Type*: rvalue +#### `parsejson` -* `pick`: From a list of values, returns the first value that is not undefined or an empty string. Takes any number of arguments, and raises an error if all values are undefined or empty. +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 + +#### `pick` + +From a list of values, returns the first value that is not undefined or an empty string. Takes any number of arguments, and raises an error if all values are undefined or empty. ``` $real_jenkins_version = pick($::jenkins_version, '1.449') @@ -360,10 +478,14 @@ returns the value of the resource's parameter. For example, the following code r *Type*: rvalue -* `prefix`: This function applies a prefix to all elements in an array or to the keys in a hash. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'], and `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue +#### `prefix` + +This function applies a prefix to all elements in an array or to the keys in a hash. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'], and `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue + +#### `assert_private` -* `assert_private`: This function sets the current class or definition as private. +This function sets the current class or definition as private. Calling the class or definition from outside the current module will fail. For example, `assert_private()` called in class `foo::bar` outputs the following message if class is called from outside module `foo`: ``` @@ -378,7 +500,9 @@ Calling the class or definition from outside the current module will fail. For e *Type*: statement -* `range`: When given range in the form of '(start, stop)', `range` extrapolates a range as an array. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9]. +#### `range` + +When given range in the form of '(start, stop)', `range` extrapolates a range as an array. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9]. Non-integer strings are accepted; `range("a", "c")` returns ["a","b","c"], and `range("host01", "host10")` returns ["host01", "host02", ..., "host09", "host10"]. @@ -386,26 +510,46 @@ Calling the class or definition from outside the current module will fail. For e *Type*: rvalue -* `reject`: This function searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *Type*: rvalue +#### `reject` + +This function searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *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 -* `reverse`: Reverses the order of a string or array. *Type*: rvalue +#### `shuffle` -* `rstrip`: Strips leading spaces to the right of the string.*Type*: rvalue +Randomizes the order of a string or array elements. *Type*: rvalue -* `shuffle`: Randomizes the order of a string or array elements. *Type*: rvalue +#### `size` -* `size`: Returns the number of elements in a string or array. *Type*: rvalue +Returns the number of elements in a string or array. *Type*: rvalue -* `sort`: Sorts strings and arrays lexically. *Type*: rvalue +#### `sort` -* `squeeze`: Returns a new string where runs of the same character that occur in this set are replaced by a single character. *Type*: rvalue +Sorts strings and arrays lexically. *Type*: rvalue -* `str2bool`: This converts a string to a boolean. This attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue +#### `squeeze` -* `str2saltedsha512`: This converts a string to a salted-SHA512 password hash, used for OS X versions >= 10.7. Given any string, this function returns a hex version of a salted-SHA512 password hash, which can be inserted into your Puppet +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 attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue + +#### `str2saltedsha512` + +This converts a string to a salted-SHA512 password hash, used for OS X versions >= 10.7. Given any string, this function returns a hex version of a salted-SHA512 password hash, which can be inserted into your Puppet manifests as a valid password attribute. *Type*: rvalue -* `strftime`: This function returns formatted time. For example, `strftime("%s")` returns the time since epoch, and `strftime("%Y=%m-%d")` returns the date. *Type*: rvalue +#### `strftime` + +This function returns formatted time. For example, `strftime("%s")` returns the time since epoch, and `strftime("%Y=%m-%d")` returns the date. *Type*: rvalue *Format:* @@ -455,35 +599,59 @@ manifests as a valid password attribute. *Type*: rvalue * `%Z`: Time zone name * `%%`: Literal '%' character -* `strip`: This function removes leading and trailing whitespace from a string or from every string inside an array. For example, `strip(" aaa ")` results in "aaa". *Type*: rvalue +#### `strip` + +This function removes leading and trailing whitespace from a string or from every string inside an array. For example, `strip(" aaa ")` results in "aaa". *Type*: rvalue -* `suffix`: This function applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue +#### `suffix` -* `swapcase`: This function swaps the existing case of a string. For example, `swapcase("aBcD")` results in "AbCd". *Type*: rvalue +This function applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue -* `time`: This function returns the current time since epoch as an integer. For example, `time()` returns something like '1311972653'. *Type*: rvalue +#### `swapcase` -* `to_bytes`: Converts the argument into bytes, for example 4 kB becomes 4096. +This function swaps the existing case of a string. For example, `swapcase("aBcD")` results in "AbCd". *Type*: rvalue + +#### `time` + +This function returns the current time since epoch as an integer. For example, `time()` returns 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 -* `type3x`: Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when puppet 3 support is dropped and the new type system may be used. *Type*: rvalue +#### `type3x` + +Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when puppet 3 support is dropped and the new type system may be used. *Type*: rvalue + +#### `type_of` -* `type_of`: Returns the literal type when passed a value. Requires the new +Returns the literal type when passed a value. Requires the new parser. Useful for comparison of types with `<=` such as in `if type_of($some_value) <= Array[String] { ... }` (which is equivalent to `if $some_value =~ Array[String] { ... }`) *Type*: rvalue -* `union`: This function returns a union of two arrays. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. +#### `union` -* `unique`: This function removes duplicates from strings and arrays. For example, `unique("aabbcc")` returns 'abc'. +This function returns a union of two arrays. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. + +#### `unique` + +This function removes duplicates from strings and arrays. For example, `unique("aabbcc")` returns 'abc'. You can also use this with arrays. For example, `unique(["a","a","b","b","c","c"])` returns ["a","b","c"]. *Type*: rvalue -* `upcase`: Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase("abcd")` returns 'ABCD'. *Type*: rvalue +#### `upcase` + +Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase("abcd")` returns 'ABCD'. *Type*: rvalue -* `uriescape`: Urlencodes a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue +#### `uriescape` -* `validate_absolute_path`: Validate the string represents an absolute path in the filesystem. This function works for Windows and Unix style paths. +Urlencodes a string or array of strings. Requires either a single string or an array as an input. *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: @@ -512,7 +680,9 @@ You can also use this with arrays. For example, `unique(["a","a","b","b","c","c" *Type*: statement -* `validate_array`: Validate that all passed values are array data structures. Abort catalog compilation if any value fails this check. +#### `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: @@ -532,7 +702,9 @@ You can also use this with arrays. For example, `unique(["a","a","b","b","c","c" *Type*: statement -* `validate_augeas`: Performs validation of a string using an Augeas lens. +#### `validate_augeas` + +Performs validation of a string using an Augeas lens. The first argument of this function should be the string to test, and the second argument should be the name of the Augeas lens to use. If Augeas fails to parse the string with the lens, the compilation aborts with a parse error. A third optional argument lists paths which should **not** be found in the file. The `$file` variable points to the location of the temporary file being tested in the Augeas tree. @@ -557,7 +729,9 @@ The first argument of this function should be the string to test, and the second *Type*: statement -* `validate_bool`: Validate that all passed values are either true or false. Abort catalog compilation if any value fails this check. +#### `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: @@ -578,7 +752,9 @@ The first argument of this function should be the string to test, and the second *Type*: statement -* `validate_cmd`: Performs 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 taking a % as a placeholder for the file path (will default to the end of the command if no % placeholder given). If the command, launched against a tempfile containing the passed string, returns a non-null value, compilation will abort with a parse error. +#### `validate_cmd` + +Performs 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 taking a % as a placeholder for the file path (will default to the end of the command if no % placeholder given). If the command, launched against a tempfile containing the passed string, returns a non-null value, 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. @@ -593,7 +769,9 @@ If a third argument is specified, this will be the error message raised and seen *Type*: statement -* `validate_hash`: Validates that all passed values are hash data structures. Abort catalog compilation if any value fails this check. +#### `validate_hash` + +Validates that all passed values are hash data structures. Abort catalog compilation if any value fails this check. The following values will pass: @@ -613,7 +791,9 @@ If a third argument is specified, this will be the error message raised and seen *Type*: statement -* `validate_integer`: Validate that the first argument is an integer (or an array of integers). Abort catalog compilation if any of the checks fail. +#### `validate_integer` + +Validate that the first argument is an integer (or an array of integers). Abort catalog compilation if any of the checks fail. The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. @@ -669,7 +849,9 @@ If a third argument is specified, this will be the error message raised and seen *Type*: statement -* `validate_numeric`: Validate that the first argument is a numeric value (or an array of numeric values). Abort catalog compilation if any of the checks fail. +#### `validate_numeric` + +Validate that the first argument is a numeric value (or an array of numeric values). Abort catalog compilation if any of the checks fail. The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. @@ -683,7 +865,9 @@ If a third argument is specified, this will be the error message raised and seen *Type*: statement -* `validate_re`: Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the string to +#### `validate_re` + +Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the 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 aborts with a parse error. @@ -711,7 +895,9 @@ of the regular expressions match the string passed in, compilation aborts with a *Type*: statement -* `validate_slength`: Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if arg 2 is not convertable to a number. +#### `validate_slength` + +Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if arg 2 is not convertable to a number. The following values pass: @@ -729,7 +915,9 @@ of the regular expressions match the string passed in, compilation aborts with a *Type*: statement -* `validate_string`: Validates that all passed values are string data structures. Aborts catalog compilation if any value fails this check. +#### `validate_string` + +Validates that all passed values are string data structures. Aborts catalog compilation if any value fails this check. The following values pass: @@ -749,7 +937,9 @@ of the regular expressions match the string passed in, compilation aborts with a *Type*: statement -* `values`: When given a hash, this function returns the values of that hash. +#### `values` + +When given a hash, this function returns the values of that hash. *Examples:* @@ -766,7 +956,9 @@ of the regular expressions match the string passed in, compilation aborts with a *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: +#### `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) @@ -776,7 +968,9 @@ of the regular expressions match the string passed in, compilation aborts with a *Type*: rvalue -* `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. For example, `zip(['1','2','3'],['4','5','6'])` results in ["1", "4"], ["2", "5"], ["3", "6"]. *Type*: rvalue +#### `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. For example, `zip(['1','2','3'],['4','5','6'])` results in ["1", "4"], ["2", "5"], ["3", "6"]. *Type*: rvalue ##Limitations -- cgit v1.2.3 From a82266c256784c4af229e026b00a4dcf9e779270 Mon Sep 17 00:00:00 2001 From: Eli Young Date: Mon, 26 Jan 2015 19:17:53 -0800 Subject: (MODULES-1715) Add fqdn_rand string generators --- README.markdown | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 293a81a..724a48e 100644 --- a/README.markdown +++ b/README.markdown @@ -244,6 +244,23 @@ This function flattens any deeply nested arrays and returns a single flat array Returns the largest integer less than or equal to the argument. Takes a single numeric value as an argument. *Type*: rvalue +#### `fqdn_rand_string` + +Generates a random alphanumeric string using an optionally-specified character set (default is alphanumeric), combining the `$fqdn` fact and an optional seed for repeatable randomness. + +*Usage:* +``` +fqdn_rand_string(LENGTH, [CHARSET], [SEED]) +``` +*Examples:* +``` +fqdn_rand_string(10) +fqdn_rand_string(10, 'ABCDEF!@#$%^') +fqdn_rand_string(10, '', 'custom seed') +``` + +*Type*: rvalue + #### `fqdn_rotate` Rotates an array a random number of times based on a node's fqdn. *Type*: rvalue -- cgit v1.2.3 From 23be4020ddd4f95dc589ecebe57cd1b27d85248b Mon Sep 17 00:00:00 2001 From: Eli Young Date: Mon, 2 Feb 2015 16:41:38 -0800 Subject: (MODULES-1737) Add pw_hash() function --- README.markdown | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 293a81a..d6be689 100644 --- a/README.markdown +++ b/README.markdown @@ -500,6 +500,24 @@ Calling the class or definition from outside the current module will fail. For e *Type*: statement +#### `pw_hash` + +Hashes a password using the crypt function. Provides a hash usable on most POSIX systems. + +The first argument to this function is the password to hash. If it is undef or an empty string, this function returns undef. + +The second argument to this function is which type of hash to use. It will be converted into the appropriate crypt(3) hash specifier. Valid hash types are: + +|Hash type |Specifier| +|---------------------|---------| +|MD5 |1 | +|SHA-256 |5 | +|SHA-512 (recommended)|6 | + +The third argument to this function is the salt to use. + +Note: this uses the Puppet Master's implementation of crypt(3). If your environment contains several different operating systems, ensure that they are compatible before using this function. + #### `range` When given range in the form of '(start, stop)', `range` extrapolates a range as an array. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9]. -- cgit v1.2.3 From 593f74ced794dd461f4483fc32eecba8ac2e1f5a Mon Sep 17 00:00:00 2001 From: Jorie Tappa Date: Mon, 4 May 2015 17:23:16 -0700 Subject: DOC-1504: README edits --- README.markdown | 654 +++++++++++++++++++++++++++----------------------------- 1 file changed, 319 insertions(+), 335 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 3889088..a7a2d3a 100644 --- a/README.markdown +++ b/README.markdown @@ -16,8 +16,7 @@ Adds a standard library of resources for Puppet modules. ##Module Description -This module provides a standard library of resources for the development of Puppet -modules. Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet: +This module provides a standard library of resources for the development of Puppet modules. Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet: * Stages * Facts @@ -38,23 +37,11 @@ After you've installed stdlib, all of its functions, facts, and resources are av If you want to use a standardized set of run stages for Puppet, `include stdlib` in your manifest. -## Reference - -### Classes - -#### Public Classes - * `stdlib`: Most of stdlib's features are automatically loaded by Puppet. To use standardized run stages in Puppet, declare this class in your manifest with `include stdlib`. When declared, stdlib declares all other classes in the module. The only other class currently included in the module is `stdlib::stages`. - The stdlib class has no parameters. - -#### Private Classes - -* `stdlib::stages`: This class manages a standard set of run stages for Puppet. It is managed by the stdlib class and should not be declared independently. - - The `stdlib::stages` class declares various run stages for deploying infrastructure, language runtimes, and application layers. The high level stages are (in order): +The `stdlib::stages` class declares various run stages for deploying infrastructure, language runtimes, and application layers. The high level stages are (in order): * setup * main @@ -67,18 +54,31 @@ If you want to use a standardized set of run stages for Puppet, `include stdlib` Sample usage: - ``` + ~~~ node default { include stdlib class { java: stage => 'runtime' } } - ``` + ~~~ -### Resources +## Reference -* `file_line`: This resource ensures that a given line, including whitespace at the beginning and end, is contained within a file. If the line is not contained in the given file, Puppet will add the line. Multiple resources can be declared to manage multiple lines in the same file. You can also use match to replace existing lines. +### Classes + +#### Public Classes - ``` + The stdlib class has no parameters. + +#### Private Classes + +* `stdlib::stages`: Manages a standard set of run stages for Puppet. It is managed by the stdlib class and should not be declared independently. + +### Types + +#### `file_line` + Ensures that a given line, including whitespace at the beginning and end, is contained within a file. If the line is not contained in the given file, Puppet will add the line. Multiple resources can be declared to manage multiple lines in the same file. You can also use `match` to replace existing lines. + + ~~~ file_line { 'sudo_rule': path => '/etc/sudoers', line => '%sudo ALL=(ALL) ALL', @@ -87,31 +87,33 @@ If you want to use a standardized set of run stages for Puppet, `include stdlib` path => '/etc/sudoers', line => '%sudonopw ALL=(ALL) NOPASSWD: ALL', } - ``` + ~~~ + +##### Parameters +All parameters are optional, unless otherwise noted. + +* `after`: Specifies the line after which Puppet will add any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined. +* `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'. +* `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined. +* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. Valid options: String containing a regex. Default: Undefined. +* `multiple`: Determines if `match` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. +* `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. +* `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file. - * `after`: Specify the line after which Puppet will add any new lines. (Existing lines are added in place.) Optional. - * `ensure`: Ensures whether the resource is present. Valid values are 'present', 'absent'. - * `line`: The line to be added to the file located by the `path` parameter. - * `match`: A 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. Optional. - * `multiple`: Determine if match can change multiple lines. Valid values are 'true', 'false'. Optional. - * `name`: An arbitrary name used as the identity of the resource. - * `path`: The file in which Puppet will ensure the line specified by the line parameter. ### 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. *Type*: rvalue +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 +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. #### `base64` -Converts a string to and from base64 encoding. -Requires an action ('encode', 'decode') and either a plain or base64-encoded -string. *Type*: rvalue +Converts a string to and from base64 encoding. Requires an action ('encode', 'decode') and either a plain or base64-encoded string. *Type*: rvalue. #### `basename` @@ -120,49 +122,47 @@ Returns the `basename` of a path (optionally stripping an extension). For exampl * ('relative/path/file.ext') returns 'file.ext' * ('/path/to/a/file.ext', '.ext') returns 'file' - *Type*: rvalue +*Type*: rvalue. #### `bool2num` Converts a boolean to a number. Converts 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 + 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 +Capitalizes the first letter of a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue. #### `ceiling` -Returns the smallest integer greater than or equal to the argument. -Takes a single numeric value as an argument. *Type*: rvalue +Returns the smallest integer greater than or equal to the argument. Takes a single numeric value as an argument. *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 +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 want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as input. *Type*: rvalue +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 want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as input. *Type*: rvalue. #### `concat` -Appends the contents of multiple arrays onto array 1. For example: - * `concat(['1','2','3'],'4')` results in: ['1','2','3','4']. - * `concat(['1','2','3'],'4',['5','6','7'])` results in: ['1','2','3','4','5','6','7']. +Appends the contents of multiple arrays onto the first array given. For example: + * `concat(['1','2','3'],'4')` returns ['1','2','3','4']. + * `concat(['1','2','3'],'4',['5','6','7'])` returns ['1','2','3','4','5','6','7']. + *Type*: rvalue. #### `count` -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 +If called with only an array, it counts the number of elements that are **not** nil/undef. If called with a second argument, counts the number of elements in an array that matches the second argument. *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. Returns 'false' otherwise. - ``` + ~~~ user { 'dan': ensure => present, } @@ -170,100 +170,96 @@ Takes a resource reference and an optional hash of attributes. Returns 'true' if if ! defined_with_params(User[dan], {'ensure' => 'present' }) { user { 'dan': ensure => present, } } - ``` + ~~~ - *Type*: rvalue +*Type*: rvalue. #### `delete` -Deletes all instances of a given element from an array, substring from a -string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1} *Type*: rvalue +Deletes all instances of a given element from an array, substring from a string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}. *Type*: rvalue. #### `delete_at` -Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue +Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue. #### `delete_values` -Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue +Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue. #### `delete_undef_values` -Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue +Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue. #### `difference` -Returns the difference between two arrays. -The returned array is a copy of the original array, removing any items that -also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. +Returns the difference between two arrays. The returned array is a copy of the original array, removing any items that also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. *Type*: rvalue. #### `dirname` -Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. +Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. *Type*: rvalue. #### `downcase` -Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue +Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue. #### `empty` -Returns 'true' if the variable is empty. *Type*: rvalue +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. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement +Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement. #### `ensure_resource` Takes a resource type, title, and a list of attributes that describe a resource. - ``` - user { 'dan': - ensure => present, - } - ``` +~~~ +user { 'dan': + ensure => present, +} +~~~ - This example only creates the resource if it does not already exist: +This example only creates the resource if it does not already exist: - `ensure_resource('user', 'dan', {'ensure' => 'present' })` + `ensure_resource('user', 'dan', {'ensure' => 'present' })` - If the resource already exists, but does not match the specified parameters, this function attempts to recreate the resource, leading to a duplicate resource definition error. +If the resource already exists, but does not match the specified parameters, this function attempts to recreate the resource, leading to a duplicate resource definition error. - An array of resources can also be passed in, and each will be created with the type and parameters specified if it doesn't already exist. +An array of resources can also be passed in, and each will be created with the type and parameters specified if it doesn't already exist. `ensure_resource('user', ['dan','alex'], {'ensure' => 'present'})` - *Type*: statement +*Type*: statement. #### `flatten` -This function flattens any deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue +Flattens deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue. #### `floor` -Returns the largest integer less than or equal to the argument. -Takes a single numeric value as an argument. *Type*: rvalue +Takes a single numeric value as an argument, and returns the largest integer less than or equal to the argument. *Type*: rvalue. #### `fqdn_rand_string` Generates a random alphanumeric string using an optionally-specified character set (default is alphanumeric), combining the `$fqdn` fact and an optional seed for repeatable randomness. *Usage:* -``` +~~~ fqdn_rand_string(LENGTH, [CHARSET], [SEED]) -``` +~~~ *Examples:* -``` +~~~ fqdn_rand_string(10) fqdn_rand_string(10, 'ABCDEF!@#$%^') fqdn_rand_string(10, '', 'custom seed') -``` +~~~ -*Type*: rvalue +*Type*: rvalue. #### `fqdn_rotate` -Rotates an array a random number of times based on a node's fqdn. *Type*: rvalue +Rotates an array a random number of times, based on a node's fqdn. *Type*: rvalue. #### `get_module_path` @@ -271,16 +267,15 @@ Returns the absolute path of the specified module for the current environment. `$module_path = get_module_path('stdlib')` - *Type*: rvalue +*Type*: rvalue. #### `getparam` -Takes a resource reference and the name of the parameter and -returns the value of the resource's parameter. For example, the following code returns 'param_value'. +Takes a resource reference and the name of the parameter, and returns the value of the resource's parameter. - *Example:* +For example, the following returns 'param_value': - ``` + ~~~ define example_resource($param) { } @@ -289,73 +284,73 @@ returns the value of the resource's parameter. For example, the following code r } getparam(Example_resource["example_resource_instance"], "param") - ``` + ~~~ - *Type*: rvalue +*Type*: rvalue. #### `getvar` -Lookup a variable in a remote namespace. +Looks up a variable in a remote namespace. - For example: +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: +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 +*Type*: rvalue. #### `grep` -This function searches through an array and returns any elements that match the provided regular expression. For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd']. *Type*: rvalue +Searches through an array and returns any elements that match the provided regular expression. For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd']. *Type*: rvalue. #### `has_interface_with` -Returns boolean based on kind and value: +Returns a boolean based on kind and value: * macaddress * netmask * ipaddress * network - *Examples:* +*Examples:* - ``` + ~~~ has_interface_with("macaddress", "x:x:x:x:x:x") has_interface_with("ipaddress", "127.0.0.1") => true - ``` + ~~~ - If no kind is given, then the presence of the interface is checked: +If no kind is given, then the presence of the interface is checked: - ``` + ~~~ has_interface_with("lo") => true - ``` + ~~~ - *Type*: rvalue +*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 +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 +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. +Determines if a hash has a certain key value. - *Example*: +*Example*: - ``` + ~~~ $my_hash = {'key_one' => 'value_one'} if has_key($my_hash, 'key_two') { notice('we will not reach here') @@ -363,159 +358,166 @@ Determine if a hash has a certain key value. if has_key($my_hash, 'key_one') { notice('this will be printed') } - ``` + ~~~ - *Type*: rvalue +*Type*: rvalue. #### `hash` -This function converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}. *Type*: rvalue +Converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}. *Type*: rvalue. #### `intersection` -This function returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. +Returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. *Type*: rvalue. #### `is_array` -Returns 'true' if the variable passed to this function is an array. *Type*: rvalue +Returns 'true' if the variable passed to this function is an array. *Type*: rvalue. #### `is_bool` -Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue +Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue. #### `is_domain_name` -Returns 'true' if the string passed to this function is a syntactically correct domain name. *Type*: rvalue +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 +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 and determines whether the Puppet runtime has access to a function by that name. It returns 'true' if the function exists, 'false' if not. *Type*: rvalue +Accepts a string as an argument and determines whether the Puppet runtime has access to a function by that name. It returns '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 +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 +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 +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 +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 +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 +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 separator. For example, `join(['a','b','c'], ",")` results in: "a,b,c". *Type*: rvalue +Joins an array into a string using a separator. For example, `join(['a','b','c'], ",")` results 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. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *Type*: rvalue +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. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *Type*: rvalue. #### `keys` -Returns the keys of a hash as an array. *Type*: rvalue +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: +Loads a YAML file containing an array, string, or hash, and returns the data in the corresponding native data type. For example: - ``` + ~~~ $myhash = loadyaml('/etc/puppet/data/myhash.yaml') - ``` + ~~~ - *Type*: rvalue +*Type*: rvalue. #### `lstrip` -Strips leading spaces to the left of a string. *Type*: rvalue +Strips spaces to the left of a string. *Type*: rvalue. #### `max` -Returns the highest value of all arguments. Requires at least one argument. *Type*: rvalue +Returns the highest value of all arguments. Requires at least one argument. *Type*: rvalue. #### `member` -This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Type*: rvalue +This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Note*: This function does not support nested arrays. If the first argument contains nested arrays, it will not recurse through them. + +*Type*: rvalue. #### `merge` Merges two or more hashes together and returns the resulting hash. - *Example*: +*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 "wins." *Type*: rvalue +When there is a duplicate key, the key in the rightmost hash "wins." *Type*: rvalue. #### `min` -Returns the lowest value of all arguments. Requires at least one argument. *Type*: rvalue +Returns the lowest value of all arguments. Requires at least one argument. *Type*: rvalue. #### `num2bool` -This function converts a number or a string representation of a number into a true boolean. Zero or anything non-numeric becomes 'false'. Numbers greater than 0 become 'true'. *Type*: rvalue +Converts a number or a string representation of a number into a true boolean. Zero or anything non-numeric becomes 'false'. Numbers greater than 0 become 'true'. *Type*: rvalue. #### `parsejson` -This function accepts JSON as a string and converts into the correct Puppet structure. *Type*: rvalue +Converts a string of JSON 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 +Converts a string of YAML into the correct Puppet structure. *Type*: rvalue. #### `pick` From a list of values, returns the first value that is not undefined or an empty string. Takes any number of arguments, and raises an error if all values are undefined or empty. - ``` + ~~~ $real_jenkins_version = pick($::jenkins_version, '1.449') - ``` + ~~~ - *Type*: rvalue +*Type*: rvalue. #### `prefix` -This function applies a prefix to all elements in an array or to the keys in a hash. For example, `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'], and `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue +Applies a prefix to all elements in an array, or to the keys in a hash. +For example: +* `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'] +* `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. +*Type*: rvalue. #### `assert_private` -This function sets the current class or definition as private. -Calling the class or definition from outside the current module will fail. For example, `assert_private()` called in class `foo::bar` outputs the following message if class is called from outside module `foo`: +Sets the current class or definition as private. Calling the class or definition from outside the current module will fail. - ``` +For example, `assert_private()` called in class `foo::bar` outputs the following message if class is called from outside module `foo`: + + ~~~ Class foo::bar is private - ``` + ~~~ - You can specify the error message you want to use: + To specify the error message you want to use: - ``` + ~~~ assert_private("You're not supposed to do that!") - ``` + ~~~ - *Type*: statement +*Type*: statement. #### `pw_hash` @@ -533,65 +535,65 @@ The second argument to this function is which type of hash to use. It will be co The third argument to this function is the salt to use. -Note: this uses the Puppet Master's implementation of crypt(3). If your environment contains several different operating systems, ensure that they are compatible before using this function. +**Note:** this uses the Puppet master's implementation of crypt(3). If your environment contains several different operating systems, ensure that they are compatible before using this function. #### `range` -When given range in the form of '(start, stop)', `range` extrapolates a range as an array. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9]. +Extrapolates a range as an array when given in the form of '(start, stop)'. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9]. - Non-integer strings are accepted; `range("a", "c")` returns ["a","b","c"], and `range("host01", "host10")` returns ["host01", "host02", ..., "host09", "host10"]. +Non-integer strings are accepted; `range("a", "c")` returns ["a","b","c"], and `range("host01", "host10")` returns ["host01", "host02", ..., "host09", "host10"]. - Passing a third argument will cause the generated range to step by that interval, e.g. `range("0", "9", "2")` returns ["0","2","4","6","8"] +Passing a third argument will cause the generated range to step by that interval, e.g. `range("0", "9", "2")` returns ["0","2","4","6","8"]. - *Type*: rvalue +*Type*: rvalue. #### `reject` -This function searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *Type*: rvalue +Searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *Type*: rvalue. #### `reverse` -Reverses the order of a string or array. *Type*: rvalue +Reverses the order of a string or array. *Type*: rvalue. #### `rstrip` -Strips leading spaces to the right of the string.*Type*: rvalue +Strips spaces to the right of the string. *Type*: rvalue. #### `shuffle` -Randomizes the order of a string or array elements. *Type*: rvalue +Randomizes the order of a string or array elements. *Type*: rvalue. #### `size` -Returns the number of elements in a string or array. *Type*: rvalue +Returns the number of elements in a string or an array. *Type*: rvalue. #### `sort` -Sorts strings and arrays lexically. *Type*: rvalue +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 +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 attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue +Converts a string to a boolean. This attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue. #### `str2saltedsha512` -This converts a string to a salted-SHA512 password hash, used for OS X versions >= 10.7. Given any string, this function returns a hex version of a salted-SHA512 password hash, which can be inserted into your Puppet -manifests as a valid password attribute. *Type*: rvalue +Converts a string to a salted-SHA512 password hash, used for OS X versions >= 10.7. Given any string, this function returns a hex version of a salted-SHA512 password hash, which can be inserted into your Puppet +manifests as a valid password attribute. *Type*: rvalue. #### `strftime` -This function returns formatted time. For example, `strftime("%s")` returns the time since epoch, and `strftime("%Y=%m-%d")` returns the date. *Type*: rvalue +Returns formatted time. For example, `strftime("%s")` returns the time since Unix epoch, and `strftime("%Y-%m-%d")` returns the date. *Type*: rvalue. *Format:* * `%a`: The abbreviated weekday name ('Sun') - * `%A`: The full weekday name ('Sunday') + * `%A`: The full weekday name ('Sunday') * `%b`: The abbreviated month name ('Jan') - * `%B`: The full month name ('January') + * `%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) @@ -612,227 +614,220 @@ This function returns formatted time. For example, `strftime("%s")` returns the * `%3N`: Millisecond (3 digits) * `%6N`: Microsecond (6 digits) * `%9N`: Nanosecond (9 digits) - * `%p`: Meridian indicator ('AM' or 'PM') - * `%P`: Meridian indicator ('am' or 'pm') + * `%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`: Number of seconds since the Unix epoch, 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) + * `%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`: 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 as hour offset from UTC (e.g. +0900) * `%Z`: Time zone name * `%%`: Literal '%' character #### `strip` -This function removes leading and trailing whitespace from a string or from every string inside an array. For example, `strip(" aaa ")` results in "aaa". *Type*: rvalue +Removes leading and trailing whitespace from a string or from every string inside an array. For example, `strip(" aaa ")` results in "aaa". *Type*: rvalue. #### `suffix` -This function applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue +Applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue. #### `swapcase` -This function swaps the existing case of a string. For example, `swapcase("aBcD")` results in "AbCd". *Type*: rvalue +Swaps the existing case of a string. For example, `swapcase("aBcD")` results in "AbCd". *Type*: rvalue. #### `time` -This function returns the current time since epoch as an integer. For example, `time()` returns something like '1311972653'. *Type*: rvalue +Returns the current Unix epoch time as an integer. For example, `time()` returns 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 +Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a single string value as an argument. *Type*: rvalue. #### `type3x` -Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when puppet 3 support is dropped and the new type system may be used. *Type*: rvalue +Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when Puppet 3 support is dropped and the new type system can be used. *Type*: rvalue. #### `type_of` -Returns the literal type when passed a value. Requires the new - parser. Useful for comparison of types with `<=` such as in `if - type_of($some_value) <= Array[String] { ... }` (which is equivalent to `if - $some_value =~ Array[String] { ... }`) *Type*: rvalue +Returns the literal type when passed a value. Requires the new parser. Useful for comparison of types with `<=` such as in `if type_of($some_value) <= Array[String] { ... }` (which is equivalent to `if $some_value =~ Array[String] { ... }`) *Type*: rvalue. #### `union` -This function returns a union of two arrays. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. +Returns a union of two arrays, without duplicates. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. #### `unique` -This function removes duplicates from strings and arrays. For example, `unique("aabbcc")` returns 'abc'. - -You can also use this with arrays. For example, `unique(["a","a","b","b","c","c"])` returns ["a","b","c"]. *Type*: rvalue +Removes duplicates from strings and arrays. For example, `unique("aabbcc")` returns 'abc', and `unique(["a","a","b","b","c","c"])` returns ["a","b","c"]. *Type*: rvalue. #### `upcase` -Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase("abcd")` returns 'ABCD'. *Type*: rvalue +Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase('abcd')` returns 'ABCD'. *Type*: rvalue. #### `uriescape` -Urlencodes a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue +URLEncodes a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue. #### `validate_absolute_path` -Validate the string represents an absolute path in the filesystem. This function works for Windows and Unix style paths. +Validates that a given string represents an absolute path in the filesystem. Works for Windows and Unix style paths. - The following values will pass: +The following values 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) - $my_path3 = ['C:/Program Files (x86)/Puppet Labs/Puppet','C:/Program Files/Puppet Labs/Puppet'] - validate_absolute_path($my_path3) - $my_path4 = ['/var/lib/puppet','/usr/share/puppet'] - validate_absolute_path($my_path4) - ``` +~~~ +$my_path = 'C:/Program Files (x86)/Puppet Labs/Puppet' +validate_absolute_path($my_path) +$my_path2 = '/var/lib/puppet' +validate_absolute_path($my_path2) +$my_path3 = ['C:/Program Files (x86)/Puppet Labs/Puppet','C:/Program Files/Puppet Labs/Puppet'] +validate_absolute_path($my_path3) +$my_path4 = ['/var/lib/puppet','/usr/share/puppet'] +validate_absolute_path($my_path4) +~~~ - The following values will fail, causing compilation to abort: +The following values fail, causing compilation to abort: - ``` - validate_absolute_path(true) - validate_absolute_path('../var/lib/puppet') - validate_absolute_path('var/lib/puppet') - validate_absolute_path([ 'var/lib/puppet', '/var/foo' ]) - validate_absolute_path([ '/var/lib/puppet', 'var/foo' ]) - $undefined = undef - validate_absolute_path($undefined) - ``` +~~~ +validate_absolute_path(true) +validate_absolute_path('../var/lib/puppet') +validate_absolute_path('var/lib/puppet') +validate_absolute_path([ 'var/lib/puppet', '/var/foo' ]) +validate_absolute_path([ '/var/lib/puppet', 'var/foo' ]) +$undefined = undef +validate_absolute_path($undefined) +~~~ - *Type*: statement +*Type*: statement. #### `validate_array` -Validate that all passed values are array data structures. Abort catalog compilation if any value fails this check. +Validates that all passed values are array data structures. Aborts catalog compilation if any value fails this check. - The following values will pass: +The following values pass: - ``` - $my_array = [ 'one', 'two' ] - validate_array($my_array) - ``` +~~~ +$my_array = [ 'one', 'two' ] +validate_array($my_array) +~~~ - The following values will fail, causing compilation to abort: +The following values fail, causing compilation to abort: - ``` - validate_array(true) - validate_array('some_string') - $undefined = undef - validate_array($undefined) - ``` +~~~ +validate_array(true) +validate_array('some_string') +$undefined = undef +validate_array($undefined) +~~~ - *Type*: statement +*Type*: statement. #### `validate_augeas` -Performs validation of a string using an Augeas lens. -The first argument of this function should be the string to test, and the second argument should be the name of the Augeas lens to use. If Augeas fails to parse the string with the lens, the compilation aborts with a parse error. +Performs validation of a string using an Augeas lens. The first argument of this function should be the string to test, and the second argument should be the name of the Augeas lens to use. If Augeas fails to parse the string with the lens, the compilation aborts with a parse error. - A third optional argument lists paths which should **not** be found in the file. The `$file` variable points to the location of the temporary file being tested in the Augeas tree. +A third optional argument lists paths which should **not** be found in the file. The `$file` variable points to the location of the temporary file being tested in the Augeas tree. - For example, to make sure your passwd content never contains user `foo`: +For example, to make sure your $passwdcontent never contains user `foo`: - ``` - validate_augeas($passwdcontent, 'Passwd.lns', ['$file/foo']) - ``` +~~~ +validate_augeas($passwdcontent, 'Passwd.lns', ['$file/foo']) +~~~ - To ensure that no users use the '/bin/barsh' shell: +To ensure that no users use the '/bin/barsh' shell: - ``` - validate_augeas($passwdcontent, 'Passwd.lns', ['$file/*[shell="/bin/barsh"]'] - ``` +~~~ +validate_augeas($passwdcontent, 'Passwd.lns', ['$file/*[shell="/bin/barsh"]'] +~~~ - You can pass a fourth argument as the error message raised and shown to the user: +You can pass a fourth argument as the error message raised and shown to the user: - ``` - validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas') - ``` +~~~ +validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas') +~~~ - *Type*: statement +*Type*: statement. #### `validate_bool` -Validate that all passed values are either true or false. Abort catalog compilation if any value fails this check. +Validates that all passed values are either true or false. Aborts catalog compilation if any value fails this check. - The following values will pass: +The following values will pass: - ``` - $iamtrue = true - validate_bool(true) - validate_bool(true, true, false, $iamtrue) - ``` +~~~ +$iamtrue = true +validate_bool(true) +validate_bool(true, true, false, $iamtrue) +~~~ - The following values will fail, causing compilation to abort: +The following values will fail, causing compilation to abort: - ``` - $some_array = [ true ] - validate_bool("false") - validate_bool("true") - validate_bool($some_array) - ``` +~~~ +$some_array = [ true ] +validate_bool("false") +validate_bool("true") +validate_bool($some_array) +~~~ - *Type*: statement +*Type*: statement. #### `validate_cmd` -Performs 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 taking a % as a placeholder for the file path (will default to the end of the command if no % placeholder given). If the command, launched against a tempfile containing the passed string, returns a non-null value, compilation will abort with a parse error. +Performs 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 taking a % as a placeholder for the file path (will default to the end of the command if no % placeholder given). If the command is launched against a tempfile containing the passed string, or returns a non-null value, 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. - ``` - # Defaults to end of path - validate_cmd($sudoerscontent, '/usr/sbin/visudo -c -f', 'Visudo failed to validate sudoers content') - ``` - ``` - # % as file location - validate_cmd($haproxycontent, '/usr/sbin/haproxy -f % -c', 'Haproxy failed to validate config content') - ``` +~~~ +# Defaults to end of path +validate_cmd($sudoerscontent, '/usr/sbin/visudo -c -f', 'Visudo failed to validate sudoers content') +~~~ +~~~ +# % as file location +validate_cmd($haproxycontent, '/usr/sbin/haproxy -f % -c', 'Haproxy failed to validate config content') +~~~ - *Type*: statement +*Type*: statement. #### `validate_hash` -Validates that all passed values are hash data structures. Abort catalog compilation if any value fails this check. +Validates that all passed values are hash data structures. Aborts 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 +*Type*: statement. #### `validate_integer` -Validate that the first argument is an integer (or an array of integers). Abort catalog compilation if any of the checks fail. - +Validates that the first argument is an integer (or an array of integers). Aborts catalog compilation if any of the checks fail. + The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. - The third argument is optional and passes a minimum. (All elements of) the first argument has to be greater or equal to this min. + The third argument is optional and passes a minimum. (All elements of) the first argument has to be greater or equal to this min. If, and only if, a minimum is given, the second argument may be an empty string or undef, which will be handled to just check if (all elements of) the first argument are greater or equal to the given minimum. @@ -840,7 +835,7 @@ Validate that the first argument is an integer (or an array of integers). Abort The following values will pass: - ``` + ~~~ validate_integer(1) validate_integer(1, 2) validate_integer(1, 1) @@ -852,14 +847,14 @@ Validate that the first argument is an integer (or an array of integers). Abort validate_integer(2, $foo, 0) validate_integer([1,2,3,4,5], 6) validate_integer([1,2,3,4,5], 6, 0) - ``` + ~~~ * Plus all of the above, but any combination of values passed as strings ('1' or "1"). * Plus all of the above, but with (correct) combinations of negative integer values. The following values will fail, causing compilation to abort: - ``` + ~~~ validate_integer(true) validate_integer(false) validate_integer(7.0) @@ -876,21 +871,21 @@ Validate that the first argument is an integer (or an array of integers). Abort validate_integer(1, 2, 3) validate_integer(1, 3, 2) validate_integer(1, 3, true) - ``` + ~~~ * Plus all of the above, but any combination of values passed as strings ('false' or "false"). * Plus all of the above, but with incorrect combinations of negative integer values. * Plus all of the above, but with non-integer crap in arrays or maximum / minimum argument. - *Type*: statement + *Type*: statement. #### `validate_numeric` -Validate that the first argument is a numeric value (or an array of numeric values). Abort catalog compilation if any of the checks fail. +Validates that the first argument is a numeric value (or an array of numeric values). Aborts catalog compilation if any of the checks fail. The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. - The third argument is optional and passes a minimum. (All elements of) the first argument has to be greater or equal to this min. + The third argument is optional and passes a minimum. (All elements of) the first argument has to be greater or equal to this min. If, and only if, a minimum is given, the second argument may be an empty string or undef, which will be handled to just check if (all elements of) the first argument are greater or equal to the given minimum. @@ -898,37 +893,35 @@ Validate that the first argument is a numeric value (or an array of numeric valu For passing and failing usage, see `validate_integer()`. It is all the same for validate_numeric, yet now floating point values are allowed, too. - *Type*: statement +*Type*: statement. #### `validate_re` Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the 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 aborts with a parse error. +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 aborts with a parse error. You can pass a third argument as the error message raised and shown to the user. The following strings validate against the regular expressions: - ``` + ~~~ validate_re('one', '^one$') validate_re('one', [ '^one', '^two' ]) - ``` + ~~~ The following string fails to validate, causing compilation to abort: - ``` + ~~~ validate_re('one', [ '^two', '^three' ]) - ``` + ~~~ To set the error message: - ``` + ~~~ validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7') - ``` + ~~~ - *Type*: statement +*Type*: statement. #### `validate_slength` @@ -936,64 +929,59 @@ Validates that the first argument is a string (or an array of strings), and is l The following values pass: - ``` + ~~~ validate_slength("discombobulate",17) validate_slength(["discombobulate","moo"],17) - ``` + ~~~ The following values fail: - ``` + ~~~ validate_slength("discombobulate",1) validate_slength(["discombobulate","thermometer"],5) - ``` + ~~~ - *Type*: statement +*Type*: statement. #### `validate_string` Validates that all passed values are string data structures. Aborts catalog compilation if any value fails this check. - The following values pass: +The following values pass: - ``` + ~~~ $my_string = "one two" validate_string($my_string, 'three') - ``` + ~~~ The following values fail, causing compilation to abort: - ``` + ~~~ validate_string(true) validate_string([ 'some', 'array' ]) - $undefined = undef - validate_string($undefined) - ``` + ~~~ - *Type*: statement +*Note:* validate_string(undef) will not fail in this version of the functions API (incl. current and future parser). -#### `values` +Instead, use: -When given a hash, this function returns the values of that hash. + ~~~ + if $var == undef { + fail('...') + } + ~~~ - *Examples:* +*Type*: statement. - ``` - $hash = { - 'a' => 1, - 'b' => 2, - 'c' => 3, - } - values($hash) - ``` +#### `values` - The example above returns [1,2,3]. +Returns the values of a given hash. For example, given `$hash = {'a'=1, 'b'=2, 'c'=3} values($hash)` returns [1,2,3]. - *Type*: rvalue +*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: +Finds values inside an array based on location. The first argument is the array you want to analyze, and the second argument can be a combination of: * A single numeric index * A range in the form of 'start-stop' (eg. 4-9) @@ -1001,15 +989,15 @@ Finds value inside an array based on location. The first argument is the array y For example, `values_at(['a','b','c'], 2)` returns ['c']; `values_at(['a','b','c'], ["0-1"])` returns ['a','b']; and `values_at(['a','b','c','d','e'], [0, "2-3"])` returns ['a','c','d']. - *Type*: rvalue +*Type*: rvalue. #### `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. For example, `zip(['1','2','3'],['4','5','6'])` results in ["1", "4"], ["2", "5"], ["3", "6"]. *Type*: rvalue +Takes one element from first array given and merges corresponding elements from second array given. This generates a sequence of n-element arrays, where *n* is one more than the count of arguments. For example, `zip(['1','2','3'],['4','5','6'])` results in ["1", "4"], ["2", "5"], ["3", "6"]. *Type*: rvalue. ##Limitations -As of Puppet Enterprise version 3.7, the stdlib module is no longer included in PE. PE users should install the most recent release of stdlib for compatibility with Puppet modules. +As of Puppet Enterprise 3.7, the stdlib module is no longer included in PE. PE users should install the most recent release of stdlib for compatibility with Puppet modules. ###Version Compatibility @@ -1024,11 +1012,7 @@ Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x | ##Development -Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve. - -We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. - -You can read the complete module contribution guide on the [Puppet Labs wiki](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing). +Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html) To report or research a bug with any part of this module, please go to [http://tickets.puppetlabs.com/browse/PUP](http://tickets.puppetlabs.com/browse/PUP). -- cgit v1.2.3 From 72089f3d134a00e64f0b3d81237a266131d40412 Mon Sep 17 00:00:00 2001 From: Raymond Maika Date: Fri, 29 May 2015 00:27:08 -0400 Subject: (MODULES-2071) Refactor file_line provider to contain logic to handle parameter multiple in function handle_create_with_after Without this, file_line resource without the `match` parameter but with the `after` param will throw an error if there are multiple matches for the after expression. This patch creates the handling for the `multiple` parameter in handle_create_with_after. This allows you to add a line after the `after` expression if it appears at multiple points in a file. Updated reference to `file_line` in the README to reflect that the multiple parameter can be set when using `after` and/or `match` as the matching regex. --- README.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index a7a2d3a..c140af4 100644 --- a/README.markdown +++ b/README.markdown @@ -96,8 +96,8 @@ All parameters are optional, unless otherwise noted. * `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'. * `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined. * `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. Valid options: String containing a regex. Default: Undefined. -* `multiple`: Determines if `match` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. -* `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. +* `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. +* `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. * `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file. -- cgit v1.2.3 From d7c846035321774e824e3424f59cb24703fcfb2a Mon Sep 17 00:00:00 2001 From: Eli Young Date: Mon, 1 Jun 2015 16:09:47 -0700 Subject: fqdn_rotate: Improve documentation --- README.markdown | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index c140af4..8ed3d9b 100644 --- a/README.markdown +++ b/README.markdown @@ -259,7 +259,20 @@ fqdn_rand_string(10, '', 'custom seed') #### `fqdn_rotate` -Rotates an array a random number of times, based on a node's fqdn. *Type*: rvalue. +Rotates an array or string a random number of times, combining the `$fqdn` fact and an optional seed for repeatable randomness. + +*Usage:* +~~~ +fqdn_rotate(VALUE, [SEED]) +~~~ +*Examples:* +~~~ +fqdn_rotate(['a', 'b', 'c', 'd']) +fqdn_rotate('abcd') +fqdn_rotate([1, 2, 3], 'custom seed') +~~~ + +*Type*: rvalue. #### `get_module_path` -- cgit v1.2.3 From 771320a8305a7e2cad427f52fcca576dc63e4f37 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Thu, 18 Jun 2015 14:49:28 +0100 Subject: Document puppet 4 compatability in 4.6 --- README.markdown | 1 + 1 file changed, 1 insertion(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 8ed3d9b..4fab8c8 100644 --- a/README.markdown +++ b/README.markdown @@ -1019,6 +1019,7 @@ Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x | **stdlib 2.x** | **yes** | **yes** | no | no **stdlib 3.x** | no | **yes** | **yes** | no **stdlib 4.x** | no | **yes** | **yes** | no +**stdlib 4.6+** | no | **yes** | **yes** | **yes** **stdlib 5.x** | no | no | **yes** | **yes** **stdlib 5.x**: When released, stdlib 5.x will drop support for Puppet 2.7.x. Please see [this discussion](https://github.com/puppetlabs/puppetlabs-stdlib/pull/176#issuecomment-30251414). -- cgit v1.2.3 From c64ecfb0c39b633675269ab02f323f7eb486dad4 Mon Sep 17 00:00:00 2001 From: Alexander Fisher Date: Mon, 6 Jul 2015 17:03:49 +0100 Subject: Add validate_slength's optional 3rd arg to README --- README.markdown | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 8ed3d9b..4dcdc2e 100644 --- a/README.markdown +++ b/README.markdown @@ -938,13 +938,14 @@ test, and the second argument should be a stringified regular expression (withou #### `validate_slength` -Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if arg 2 is not convertable to a number. +Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if arg 2 is not convertable to a number. Optionally, a minimum string length can be given as the third argument. The following values pass: ~~~ validate_slength("discombobulate",17) validate_slength(["discombobulate","moo"],17) + validate_slength(["discombobulate","moo"],17,3) ~~~ The following values fail: @@ -952,6 +953,7 @@ Validates that the first argument is a string (or an array of strings), and is l ~~~ validate_slength("discombobulate",1) validate_slength(["discombobulate","thermometer"],5) + validate_slength(["discombobulate","moo"],17,10) ~~~ *Type*: statement. -- cgit v1.2.3 From f485e6e2eb1d2ffa8c16402249bec96e0886b86b Mon Sep 17 00:00:00 2001 From: Garrett Honeycutt Date: Sun, 12 Jul 2015 20:11:36 -0400 Subject: Clarify that third argument to ensure_resource() is a hash --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 3d1e663..7eed5d7 100644 --- a/README.markdown +++ b/README.markdown @@ -212,7 +212,7 @@ Takes a list of packages and only installs them if they don't already exist. It #### `ensure_resource` -Takes a resource type, title, and a list of attributes that describe a resource. +Takes a resource type, title, and a hash of attributes that describe the resource(s). ~~~ user { 'dan': -- cgit v1.2.3 From 5c79107863a42a9d347637146f0c0f728f9b92ad Mon Sep 17 00:00:00 2001 From: gcmalloc Date: Tue, 21 Jul 2015 19:25:27 +0200 Subject: adding support for hash in the size function --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 7eed5d7..eef538a 100644 --- a/README.markdown +++ b/README.markdown @@ -578,7 +578,7 @@ Randomizes the order of a string or array elements. *Type*: rvalue. #### `size` -Returns the number of elements in a string or an array. *Type*: rvalue. +Returns the number of elements in a string, an array or a hash. *Type*: rvalue. #### `sort` -- cgit v1.2.3 From 35e92645f727f02ef9ace8948154079bc0fff05a Mon Sep 17 00:00:00 2001 From: Raymond Maika Date: Thu, 30 Jul 2015 14:05:39 -0400 Subject: (MODULES-2024) Adding replace attribute to file_line --- README.markdown | 1 + 1 file changed, 1 insertion(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index eef538a..090bb09 100644 --- a/README.markdown +++ b/README.markdown @@ -99,6 +99,7 @@ All parameters are optional, unless otherwise noted. * `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. * `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. * `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file. +* `replace`: Defines whether the resource will overwrite an existing line that matches the `match` parameter. If set to false and a line is found matching the `match` param, the line will not be placed in the file. Valid options: true, false, yes, no. Default: true ### Functions -- cgit v1.2.3 From aca29129cb0fada02cd4590eba30b560dc08ac64 Mon Sep 17 00:00:00 2001 From: Zee Alexander Date: Thu, 30 Jul 2015 15:11:26 -0700 Subject: Remove colorful language from module. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 090bb09..9f40e28 100644 --- a/README.markdown +++ b/README.markdown @@ -889,7 +889,7 @@ Validates that the first argument is an integer (or an array of integers). Abort * Plus all of the above, but any combination of values passed as strings ('false' or "false"). * Plus all of the above, but with incorrect combinations of negative integer values. - * Plus all of the above, but with non-integer crap in arrays or maximum / minimum argument. + * Plus all of the above, but with non-integer items in arrays or maximum / minimum argument. *Type*: statement. -- cgit v1.2.3 From f411ee7119cab1277baffee2fe2b2f978f402072 Mon Sep 17 00:00:00 2001 From: Spencer Krum Date: Thu, 9 Jul 2015 10:53:56 -0700 Subject: Add load_metadata_json function This function loads the metadata.json into a puppet variable. This enables a number of neat things such as: * Which version of the module am I using? 2.x? 3.x? * Which author of the module am I using? puppetlabs? example42? --- README.markdown | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 7eed5d7..9853da8 100644 --- a/README.markdown +++ b/README.markdown @@ -449,6 +449,17 @@ Loads a YAML file containing an array, string, or hash, and returns the data in *Type*: rvalue. +#### `load_module_metadata` + +Loads the metadata.json of a target module. Can be used to determine module version and authorship for dynamic support of modules. + + ~~~ + $metadata = load_module_metadata('archive') + notify { $metadata['author']: } + ~~~ + +*Type*: rvalue. + #### `lstrip` Strips spaces to the left of a string. *Type*: rvalue. -- cgit v1.2.3 From 4cbe846750c40dec57c55dbe6382dfa57c4d79af Mon Sep 17 00:00:00 2001 From: Nigel Gibbs Date: Fri, 14 Aug 2015 09:33:46 +0100 Subject: (MODULES-2410) Add new functions dos2unix and unix2dos --- README.markdown | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 594a55f..f949dca 100644 --- a/README.markdown +++ b/README.markdown @@ -199,6 +199,19 @@ Returns the difference between two arrays. The returned array is a copy of the o Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. *Type*: rvalue. +#### `dos2unix` + +Returns the Unix version of the given string. Very useful when using a File resource with a cross-platform template. *Type*: rvalue. + +~~~ +file{$config_file: + ensure => file, + content => dos2unix(template('my_module/settings.conf.erb')), +} +~~~ + +See also [unix2dos](#unix2dos). + #### `downcase` Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue. @@ -471,7 +484,7 @@ Returns the highest value of all arguments. Requires at least one argument. *Typ #### `member` -This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Note*: This function does not support nested arrays. If the first argument contains nested arrays, it will not recurse through them. +This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Note*: This function does not support nested arrays. If the first argument contains nested arrays, it will not recurse through them. *Type*: rvalue. @@ -520,7 +533,7 @@ From a list of values, returns the first value that is not undefined or an empty #### `prefix` Applies a prefix to all elements in an array, or to the keys in a hash. -For example: +For example: * `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'] * `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. @@ -697,6 +710,19 @@ Returns a union of two arrays, without duplicates. For example, `union(["a","b", Removes duplicates from strings and arrays. For example, `unique("aabbcc")` returns 'abc', and `unique(["a","a","b","b","c","c"])` returns ["a","b","c"]. *Type*: rvalue. +#### `unix2dos` + +Returns the DOS version of the given string. Very useful when using a File resource with a cross-platform template. *Type*: rvalue. + +~~~ +file{$config_file: + ensure => file, + content => unix2dos(template('my_module/settings.conf.erb')), +} +~~~ + +See also [dos2unix](#dos2unix). + #### `upcase` Converts an object, array or hash of objects that respond to upcase to uppercase. For example, `upcase('abcd')` returns 'ABCD'. *Type*: rvalue. @@ -1002,7 +1028,7 @@ Instead, use: #### `values` -Returns the values of a given hash. For example, given `$hash = {'a'=1, 'b'=2, 'c'=3} values($hash)` returns [1,2,3]. +Returns the values of a given hash. For example, given `$hash = {'a'=1, 'b'=2, 'c'=3} values($hash)` returns [1,2,3]. *Type*: rvalue. @@ -1048,7 +1074,3 @@ To report or research a bug with any part of this module, please go to ##Contributors The list of contributors can be found at: https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors - - - - -- cgit v1.2.3 From 1d9189d860f28067b72093cbe4027cf49b7d612c Mon Sep 17 00:00:00 2001 From: Jetroid Date: Mon, 24 Aug 2015 12:01:29 +0100 Subject: (MODULE-2456) Modify union to accept more than two arrays Add spec tests to test the new functionality: *Case for 3 arrays. *Case for 4 arrays. Modify README to note new functionality. This is for issue MODULE-2456, follow the precedent of MODULE-444. This change allows union to be much more useful, unioning many arrays in one line rather than in n lines. Additionally, as this is only added functionality, and does not affect the 2 array case that all modules currently using array are using, it should not affect any existing modules utilizing union. This is now useful, for example, for merging many arrays of resources (eg: packages.) to generate just one list with no duplicates, to avoid duplicate resource declarations. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f949dca..e71241f 100644 --- a/README.markdown +++ b/README.markdown @@ -704,7 +704,7 @@ Returns the literal type when passed a value. Requires the new parser. Useful fo #### `union` -Returns a union of two arrays, without duplicates. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. +Returns a union of two or more arrays, without duplicates. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. #### `unique` -- cgit v1.2.3 From ba345abfb75e0d6840a174f4d6c9b1967105385d Mon Sep 17 00:00:00 2001 From: Jetroid Date: Tue, 25 Aug 2015 10:35:57 +0100 Subject: Add consistent *Type* information Remove trailing whitespace Two functions had not been given any *Type* information. This commit fixes that. --- README.markdown | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index e71241f..591c27b 100644 --- a/README.markdown +++ b/README.markdown @@ -532,10 +532,10 @@ From a list of values, returns the first value that is not undefined or an empty #### `prefix` -Applies a prefix to all elements in an array, or to the keys in a hash. +Applies a prefix to all elements in an array, or to the keys in a hash. For example: * `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'] -* `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. +* `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}. *Type*: rvalue. @@ -573,6 +573,8 @@ The second argument to this function is which type of hash to use. It will be co The third argument to this function is the salt to use. +*Type*: rvalue. + **Note:** this uses the Puppet master's implementation of crypt(3). If your environment contains several different operating systems, ensure that they are compatible before using this function. #### `range` @@ -704,7 +706,7 @@ Returns the literal type when passed a value. Requires the new parser. Useful fo #### `union` -Returns a union of two or more arrays, without duplicates. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. +Returns a union of two or more arrays, without duplicates. For example, `union(["a","b","c"],["b","c","d"])` returns ["a","b","c","d"]. *Type*: rvalue. #### `unique` -- cgit v1.2.3 From eb948c4a0dc36790c5444fc236b0154c3d716c58 Mon Sep 17 00:00:00 2001 From: Dmitry Ilyin Date: Mon, 24 Aug 2015 22:00:18 +0300 Subject: [MODULES-2462] Improve parseyaml function * Add default value support Second argument will be returned if yaml cannot be parsed instead of false value * Update tests --- README.markdown | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 8ed3d9b..2f84a24 100644 --- a/README.markdown +++ b/README.markdown @@ -490,10 +490,12 @@ Converts a number or a string representation of a number into a true boolean. Ze #### `parsejson` Converts a string of JSON into the correct Puppet structure. *Type*: rvalue. +The optional second argument will be returned if the data was not correct. #### `parseyaml` Converts a string of YAML into the correct Puppet structure. *Type*: rvalue. +The optional second argument will be returned if the data was not correct. #### `pick` -- cgit v1.2.3 From 2d4f5aa4d943e27ffeae524469f9c6eb18ce64d8 Mon Sep 17 00:00:00 2001 From: fhats Date: Thu, 27 Aug 2015 10:40:20 +0100 Subject: Adds a convert_base function, which can convert numbers between bases Squashed, improved docs, updated error handling and unit tests by David S. --- README.markdown | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 591c27b..ccbceab 100644 --- a/README.markdown +++ b/README.markdown @@ -155,6 +155,12 @@ Appends the contents of multiple arrays onto the first array given. For example: * `concat(['1','2','3'],'4',['5','6','7'])` returns ['1','2','3','4','5','6','7']. *Type*: rvalue. +#### `convert_base` + +Converts a given integer or base 10 string representing an integer to a specified base, as a string. For example: + * `convert_base(5, 2)` results in: '101' + * `convert_base('254', '16')` results in: 'fe' + #### `count` If called with only an array, it counts the number of elements that are **not** nil/undef. If called with a second argument, counts the number of elements in an array that matches the second argument. *Type*: rvalue. -- cgit v1.2.3 From 823a352f0f47d4481844bb6b6a6c00224ed556b8 Mon Sep 17 00:00:00 2001 From: Dmitry Ilyin Date: Tue, 1 Sep 2015 21:39:16 +0300 Subject: Add a new function "try_get_value" * Extracts a value from a deeply-nested data structure * Returns default if a value could not be extracted --- README.markdown | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 8ed3d9b..22bece8 100644 --- a/README.markdown +++ b/README.markdown @@ -669,6 +669,40 @@ Returns the current Unix epoch time as an integer. For example, `time()` returns Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a single string value as an argument. *Type*: rvalue. +#### `try_get_value` + +*Type*: rvalue. + +Looks up into a complex structure of arrays and hashes and returns a value +or the default value if nothing was found. + +Key can contain slashes to describe path components. The function will go down +the structure and try to extract the required value. + +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = try_get_value($data, 'a/b/2', 'not_found', '/') +=> $value = 'b3' + +a -> first hash key +b -> second hash key +2 -> array index starting with 0 + +not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil. +/ -> (optional) path delimiter. Defaults to '/'. + +In addition to the required "key" argument, "try_get_value" accepts default +argument. It will be returned if no value was found or a path component is +missing. And the fourth argument can set a variable path separator. + #### `type3x` Returns a string description of the type when passed a value. Type can be a string, array, hash, float, integer, or boolean. This function will be removed when Puppet 3 support is dropped and the new type system can be used. *Type*: rvalue. -- cgit v1.2.3 From f2f2db4795fc0e3b9387e1e6c003e8e75efde903 Mon Sep 17 00:00:00 2001 From: Corey Osman Date: Thu, 3 Sep 2015 10:31:51 -0700 Subject: accept any case of boolean strings * previously the str2bool function did not accept 'TRUE' as a bool type. This causes the function to now accept TRUE, FALSE strings as a boolean type in order to be converted to a proper boolean. * This would also cause Y,N, YES, NO to be accepted as boolean types as well. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index a880222..3cc47a5 100644 --- a/README.markdown +++ b/README.markdown @@ -623,7 +623,7 @@ Returns a new string where runs of the same character that occur in this set are #### `str2bool` -Converts a string to a boolean. This attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue. +Converts a string to a boolean regardless of case. This attempts to convert strings that contain values such as '1', 't', 'y', 'Y', 'YES','yes', and 'TRUE' to 'true' and strings that contain values such as '0', 'f','F', 'N','n', 'NO','FALSE', and 'no' to 'false'. *Type*: rvalue. #### `str2saltedsha512` -- cgit v1.2.3 From 411978db322cefda4e156537491b15dddbf2698f Mon Sep 17 00:00:00 2001 From: Dmitry Ilyin Date: Fri, 4 Sep 2015 19:12:21 +0300 Subject: [MAINT] Improve 'try_get_value' readme --- README.markdown | 51 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 18 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index a880222..d345947 100644 --- a/README.markdown +++ b/README.markdown @@ -706,12 +706,18 @@ Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a sin *Type*: rvalue. -Looks up into a complex structure of arrays and hashes and returns a value -or the default value if nothing was found. - -Key can contain slashes to describe path components. The function will go down -the structure and try to extract the required value. - +Looks up into a complex structure of arrays and hashes to extract a value by +its path in the structure. The path is a string of hash keys or array indexes +starting with zero, separated by the path separator character (default "/"). +The function will go down the structure by each path component and will try to +return the value at the end of the path. + +In addition to the required "path" argument the function accepts the default +argument. It will be returned if the path is not correct, no value was found or +a any other error have occurred. And the last argument can set the path +separator character. + +```ruby $data = { 'a' => { 'b' => [ @@ -722,19 +728,28 @@ $data = { } } -$value = try_get_value($data, 'a/b/2', 'not_found', '/') -=> $value = 'b3' - -a -> first hash key -b -> second hash key -2 -> array index starting with 0 - -not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil. -/ -> (optional) path delimiter. Defaults to '/'. +$value = try_get_value($data, 'a/b/2') +# $value = 'b3' -In addition to the required "key" argument, "try_get_value" accepts default -argument. It will be returned if no value was found or a path component is -missing. And the fourth argument can set a variable path separator. +# with all possible options +$value = try_get_value($data, 'a/b/2', 'not_found', '/') +# $value = 'b3' + +# using the default value +$value = try_get_value($data, 'a/b/c/d', 'not_found') +# $value = 'not_found' + +# using custom separator +$value = try_get_value($data, 'a|b', [], '|') +# $value = ['b1','b2','b3'] +``` + +1. **$data** The data structure we are working with. +2. **'a/b/2'** The path string. +3. **'not_found'** The default value. It will be returned if nothing is found. + (optional, defaults to *undef*) +4. **'/'** The path separator character. + (optional, defaults to *'/'*) #### `type3x` -- cgit v1.2.3 From 00c881d0dabe77fd2401beb0d39c7386b50bb791 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Mon, 14 Sep 2015 18:26:25 +0100 Subject: (MODULES-2516) Adds an is_a() function The data type system is very hard to understand. Many people don't understand why type_of([1,2,3]) == Array will fail, but type_of([1,2,3]) <= Array passes. This does a simpler validation that doesn't rely on explicit data types. Instead, use $foo = [1,2,3] if $foo.is_a(Array) { notify { 'This is an array': } } This is based on code by Ben Ford . * Added acceptance tests * Added dispatch * Improved unit tests * Added docs to README --- README.markdown | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f95d37d..aeacfdc 100644 --- a/README.markdown +++ b/README.markdown @@ -403,6 +403,29 @@ Converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns Returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. *Type*: rvalue. +#### `is_a` + +Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. + + ~~~ + foo = 3 + $bar = [1,2,3] + $baz = 'A string!' + + if $foo.is_a(Integer) { + notify { 'foo!': } + } + if $bar.is_a(Array) { + notify { 'bar!': } + } + if $baz.is_a(String) { + notify { 'baz!': } + } + ~~~ + +See the documentation for "The Puppet Type System" for more information about types. +See the `assert_type()` function for flexible ways to assert the type of a value. + #### `is_array` Returns 'true' if the variable passed to this function is an array. *Type*: rvalue. -- cgit v1.2.3 From 55ece7815a8718507ef096db53a1e186102f1c8a Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Thu, 17 Sep 2015 18:48:32 +0100 Subject: (MAINT) validate_re: Clarify docs and error message --- README.markdown | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 8dd57f1..1cf7b32 100644 --- a/README.markdown +++ b/README.markdown @@ -1054,6 +1054,13 @@ test, and the second argument should be a stringified regular expression (withou validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7') ~~~ + Note: Compilation will also abort, if the first argument is not a String. Always use + quotes to force stringification: + + ~~~ + validate_re("${::operatingsystemmajrelease}", '^[57]$') + ~~~ + *Type*: statement. #### `validate_slength` -- cgit v1.2.3 From 92b068ad20b2f3a0a8ef8847eb45124a95c395d9 Mon Sep 17 00:00:00 2001 From: Helen Campbell Date: Wed, 23 Sep 2015 11:27:48 +0100 Subject: Adding update to empty function readme --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 1cf7b32..27dd0a7 100644 --- a/README.markdown +++ b/README.markdown @@ -224,7 +224,7 @@ Converts the case of a string or of all strings in an array to lowercase. *Type* #### `empty` -Returns 'true' if the variable is empty. *Type*: rvalue. +Returns true if the argument is an array or hash that contains no elements, or an empty string. *Type*: rvalue. #### `ensure_packages` -- cgit v1.2.3 From bfa21edbaeebd61b356f51a7586da64f8d5d757a Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Mon, 28 Sep 2015 11:12:25 +0100 Subject: (FM-3701) Update README for is_a --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 27dd0a7..f919323 100644 --- a/README.markdown +++ b/README.markdown @@ -405,7 +405,7 @@ Returns an array an intersection of two. For example, `intersection(["a","b","c" #### `is_a` -Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. +Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. This function is only available in Puppet 4, or when using the "future" parser. ~~~ foo = 3 -- cgit v1.2.3 From c7c4d41a8286ab05af65afc1207c8cea4c11ffff Mon Sep 17 00:00:00 2001 From: Helen Campbell Date: Mon, 28 Sep 2015 16:18:56 +0100 Subject: Added acceptance test and updated readme --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f919323..d023f23 100644 --- a/README.markdown +++ b/README.markdown @@ -224,7 +224,7 @@ Converts the case of a string or of all strings in an array to lowercase. *Type* #### `empty` -Returns true if the argument is an array or hash that contains no elements, or an empty string. *Type*: rvalue. +Returns true if the argument is an array or hash that contains no elements, or an empty string. Returns false when the argument is a numerical value. *Type*: rvalue. #### `ensure_packages` -- cgit v1.2.3 From ad173f2d0552ad9ed42950aea7df8d2b22677904 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Tue, 13 Oct 2015 15:02:04 +0100 Subject: (MODULES-2421) improve description of file_line This mostly needed extraction of the existing doc strings from the type. --- README.markdown | 66 +++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 52 insertions(+), 14 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index d023f23..b6f586e 100644 --- a/README.markdown +++ b/README.markdown @@ -76,18 +76,56 @@ The `stdlib::stages` class declares various run stages for deploying infrastruct ### Types #### `file_line` - Ensures that a given line, including whitespace at the beginning and end, is contained within a file. If the line is not contained in the given file, Puppet will add the line. Multiple resources can be declared to manage multiple lines in the same file. You can also use `match` to replace existing lines. - ~~~ - file_line { 'sudo_rule': - path => '/etc/sudoers', - line => '%sudo ALL=(ALL) ALL', - } - file_line { 'sudo_rule_nopw': - path => '/etc/sudoers', - line => '%sudonopw ALL=(ALL) NOPASSWD: ALL', - } - ~~~ +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 append the line to +the end of the file to ensure the desired state. Multiple resources may +be declared to manage multiple lines in the same file. + +Example: + + file_line { 'sudo_rule': + path => '/etc/sudoers', + line => '%sudo ALL=(ALL) ALL', + } + + 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. + +Match Example: + + file_line { 'bashrc_proxy': + ensure => present, + path => '/etc/bashrc', + line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128', + match => '^export\ HTTP_PROXY\=', + } + +In this code example match will look for a line beginning with export +followed by HTTP_PROXY and replace it with the value in line. + +Match Example With `ensure => absent`: + + file_line { 'bashrc_proxy': + ensure => absent, + path => '/etc/bashrc', + line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128', + match => '^export\ HTTP_PROXY\=', + match_for_absence => true, + } + +In this code example match will look for a line beginning with export +followed by HTTP_PROXY and delete it. If multiple lines match, an +error will be raised unless the `multiple => true` parameter is set. + +**Autorequires:** If Puppet is managing the file that will contain the line +being managed, the file_line resource will autorequire that file. ##### Parameters All parameters are optional, unless otherwise noted. @@ -95,13 +133,13 @@ All parameters are optional, unless otherwise noted. * `after`: Specifies the line after which Puppet will add any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined. * `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'. * `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined. -* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. Valid options: String containing a regex. Default: Undefined. +* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. A regex comparison is performed against the line value and if it does not match an exception will be raised. Valid options: String containing a regex. Default: Undefined. +* `match_for_absence`: An optional value to determine if match should be applied when `ensure => absent`. If set to true and match is set, the line that matches match will be deleted. If set to false (the default), match is ignored when `ensure => absent` and the value of `line` is used instead. Default: false. * `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. * `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. * `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file. * `replace`: Defines whether the resource will overwrite an existing line that matches the `match` parameter. If set to false and a line is found matching the `match` param, the line will not be placed in the file. Valid options: true, false, yes, no. Default: true - ### Functions #### `abs` @@ -405,7 +443,7 @@ Returns an array an intersection of two. For example, `intersection(["a","b","c" #### `is_a` -Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. This function is only available in Puppet 4, or when using the "future" parser. +Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. This function is only available in Puppet 4, or when using the "future" parser. ~~~ foo = 3 -- cgit v1.2.3 From 25410c4598d3c0029fcd05adc2e305dbf5f8d902 Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Wed, 14 Oct 2015 16:09:05 -0700 Subject: Let load_module_metadata succeed on empty file Some modules or module versions don't have a metadata.json file, but we might still want to use the load_module_metadata function on them. The lack of a file can still give us important information. For example, it might tell us that the version of the module installed is "very old" even if we can't read the version number directly. This patch adds a parameter to let the user specify if an empty file is acceptable. To preserve backwards compatibility it does not change the current default behavior, which is to raise an error if metadata.json does not exist. --- README.markdown | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index b6f586e..d86d91f 100644 --- a/README.markdown +++ b/README.markdown @@ -539,6 +539,15 @@ Loads the metadata.json of a target module. Can be used to determine module vers notify { $metadata['author']: } ~~~ +If you do not want to fail the catalog compilation if the metadata file for a module is not present: + + ~~~ + $metadata = load_module_metadata('mysql', true) + if empty($metadata) { + notify { "This module does not have a metadata.json file.": } + } + ~~~ + *Type*: rvalue. #### `lstrip` -- cgit v1.2.3 From 6de1a6e0622f69ec22c64e72fd53ec12ae8c9111 Mon Sep 17 00:00:00 2001 From: Mark McKinstry Date: Thu, 15 Oct 2015 22:22:10 -0400 Subject: add functionality to bool2str to return strings of your choice for a boolean --- README.markdown | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index b6f586e..0933215 100644 --- a/README.markdown +++ b/README.markdown @@ -170,6 +170,22 @@ Converts a boolean to a number. Converts values: * '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 using optionally supplied arguments. The optional +second and third arguments represent what true and false will be converted to +respectively. If only one argument is given, it will be converted from a boolean +to a string containing 'true' or 'false'. + +*Examples:* +~~~ +bool2str(true) => 'true' +bool2str(true, 'yes', 'no') => 'yes' +bool2str(false, 't', 'f') => 'f' +~~~ + +Requires a single boolean as 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. -- cgit v1.2.3 From 2c3c6fde98e28cc3afd7f846d3176982f39ebc39 Mon Sep 17 00:00:00 2001 From: marrero984 Date: Thu, 22 Oct 2015 13:58:57 -0700 Subject: (#2183) updated str2bool readme wording --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f9c9425..67b2b17 100644 --- a/README.markdown +++ b/README.markdown @@ -711,7 +711,7 @@ Returns a new string where runs of the same character that occur in this set are #### `str2bool` -Converts a string to a boolean regardless of case. This attempts to convert strings that contain values such as '1', 't', 'y', 'Y', 'YES','yes', and 'TRUE' to 'true' and strings that contain values such as '0', 'f','F', 'N','n', 'NO','FALSE', and 'no' to 'false'. *Type*: rvalue. +Converts certain strings to a boolean. This attempts to convert strings that contain the values '1', 't', 'y', and 'yes' to 'true'. Strings that contain values '0', 'f', 'n', and 'no', or are an an empty string or undefined are converted to 'false'. Any other value will cause an error. *Type*: rvalue. #### `str2saltedsha512` -- cgit v1.2.3 From 1421aa4a87e557957bc528b63aea6748f86af120 Mon Sep 17 00:00:00 2001 From: Matt Flaschen Date: Tue, 27 Oct 2015 18:09:18 -0400 Subject: Fix capitalize docs Capitalize lower-cases the remaining characters (due to the Ruby function having this behavior); document this, and make minor wording tweaks. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 67b2b17..57a62b6 100644 --- a/README.markdown +++ b/README.markdown @@ -188,7 +188,7 @@ Requires a single boolean as 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. +Capitalizes the first character of a string or array of strings, and lower-cases the remaining characters of each string. Requires either a single string or an array as an input. *Type*: rvalue. #### `ceiling` -- cgit v1.2.3 From 99db9827412f93e5f2d74eb86f6a25cd214823ae Mon Sep 17 00:00:00 2001 From: Helen Campbell Date: Mon, 9 Nov 2015 15:14:34 +0000 Subject: pick_default addition to readme --- README.markdown | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 57a62b6..9ff242c 100644 --- a/README.markdown +++ b/README.markdown @@ -624,6 +624,10 @@ From a list of values, returns the first value that is not undefined or an empty *Type*: rvalue. +#### `pick_default` + +Will return the first value in a list of values. Contrary to the 'pick()' function, the 'pick_default()' does not fail if all arguments are empty. This allows it to use an empty value as default. *Type*: rvalue. + #### `prefix` Applies a prefix to all elements in an array, or to the keys in a hash. -- cgit v1.2.3 From fe23e01a4b8b0cc0d9ea1a958e2be5a947fb7aed Mon Sep 17 00:00:00 2001 From: Jaume Devesa Date: Thu, 19 Nov 2015 12:47:01 +0100 Subject: Add validator for any IP address Provide a validator for IP addresses, regardless they are IPv4 or IPv6, and its documentation. --- README.markdown | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 9ff242c..526b573 100644 --- a/README.markdown +++ b/README.markdown @@ -1079,6 +1079,39 @@ Validates that the first argument is an integer (or an array of integers). Abort *Type*: statement. +#### `validate_ip_address` + +Validates that argument is an IP address, regardless of it is an IPv4 or an IPv6 +address. It validates as well IP address with netmask. It must be an String, as +well. + +The following values will pass: + + ~~~ + validate_ip_address('0.0.0.0') + validate_ip_address('8.8.8.8') + validate_ip_address('127.0.0.1') + validate_ip_address('194.232.104.150') + validate_ip_address('3ffe:0505:0002::') + validate_ip_address('::1/64') + validate_ip_address('fe80::a00:27ff:fe94:44d6/64') + validate_ip_address('8.8.8.8/32') + ~~~ + +The following values will fail, causing compilation to abort: + + ~~~ + validate_ip_address(1) + validate_ip_address(true) + validate_ip_address(0.0.0.256) + validate_ip_address('::1', {}) + validate_ip_address('0.0.0.0.0') + validate_ip_address('3.3.3') + validate_ip_address('23.43.9.22/64') + validate_ip_address('260.2.32.43') + ~~~ + + #### `validate_numeric` Validates that the first argument is a numeric value (or an array of numeric values). Aborts catalog compilation if any of the checks fail. -- cgit v1.2.3 From 8aecd63378f6dc3aeafe71d91212f613aa0bb829 Mon Sep 17 00:00:00 2001 From: Kjetil Torgrim Homme Date: Tue, 8 Dec 2015 14:59:12 +0100 Subject: (#2886) seeded_rand: new function seeded_rand is needed for repeatable randomness across nodes in a cluster --- README.markdown | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 526b573..9348a3a 100644 --- a/README.markdown +++ b/README.markdown @@ -697,6 +697,12 @@ Reverses the order of a string or array. *Type*: rvalue. Strips spaces to the right of the string. *Type*: rvalue. +#### `seeded_rand` + +Takes an integer max value and a string seed value and returns a +repeatable random integer smaller than max. Like `fqdn_rand`, but +this does not add node specific data to the seed. *Type*: rvalue. + #### `shuffle` Randomizes the order of a string or array elements. *Type*: rvalue. -- cgit v1.2.3 From 4abc6e6e3b12a55996623ca7544a2d65bbea93d1 Mon Sep 17 00:00:00 2001 From: jbondpdx Date: Mon, 14 Dec 2015 11:19:53 -0800 Subject: edits to README --- README.markdown | 90 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 46 insertions(+), 44 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 9348a3a..c073b30 100644 --- a/README.markdown +++ b/README.markdown @@ -77,10 +77,10 @@ The `stdlib::stages` class declares various run stages for deploying infrastruct #### `file_line` -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 append the line to -the end of the file to ensure the desired state. Multiple resources may +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 appends the line to +the end of the file to ensure the desired state. Multiple resources can be declared to manage multiple lines in the same file. Example: @@ -95,8 +95,8 @@ Example: line => '%sudonopw ALL=(ALL) NOPASSWD: ALL', } -In this example, Puppet will ensure both of the specified lines are -contained in the file /etc/sudoers. +In this example, Puppet ensures that both of the specified lines are +contained in the file `/etc/sudoers`. Match Example: @@ -107,8 +107,8 @@ Match Example: match => '^export\ HTTP_PROXY\=', } -In this code example match will look for a line beginning with export -followed by HTTP_PROXY and replace it with the value in line. +In this code example, `match` looks for a line beginning with export +followed by HTTP_PROXY and replaces it with the value in line. Match Example With `ensure => absent`: @@ -120,20 +120,21 @@ Match Example With `ensure => absent`: match_for_absence => true, } -In this code example match will look for a line beginning with export +In this code example, `match` looks for a line beginning with export followed by HTTP_PROXY and delete it. If multiple lines match, an error will be raised unless the `multiple => true` parameter is set. -**Autorequires:** If Puppet is managing the file that will contain the line -being managed, the file_line resource will autorequire that file. +**Autorequires:** If Puppet is managing the file that contains the line +being managed, the `file_line` resource autorequires that file. ##### Parameters + All parameters are optional, unless otherwise noted. -* `after`: Specifies the line after which Puppet will add any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined. +* `after`: Specifies the line after which Puppet adds any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined. * `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'. * `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined. -* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. A regex comparison is performed against the line value and if it does not match an exception will be raised. Valid options: String containing a regex. Default: Undefined. +* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. A regex comparison is performed against the line value, and if it does not match, an exception is raised. Valid options: String containing a regex. Default: Undefined. * `match_for_absence`: An optional value to determine if match should be applied when `ensure => absent`. If set to true and match is set, the line that matches match will be deleted. If set to false (the default), match is ignored when `ensure => absent` and the value of `line` is used instead. Default: false. * `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. * `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. @@ -173,8 +174,8 @@ Converts a boolean to a number. Converts values: #### `bool2str` Converts a boolean to a string using optionally supplied arguments. The optional -second and third arguments represent what true and false will be converted to -respectively. If only one argument is given, it will be converted from a boolean +second and third arguments represent what true and false are converted to +respectively. If only one argument is given, it is converted from a boolean to a string containing 'true' or 'false'. *Examples:* @@ -188,7 +189,7 @@ Requires a single boolean as input. *Type*: rvalue. #### `capitalize` -Capitalizes the first character of a string or array of strings, and lower-cases the remaining characters of each string. Requires either a single string or an array as an input. *Type*: rvalue. +Capitalizes the first character of a string or array of strings and lowercases the remaining characters of each string. Requires either a single string or an array as an input. *Type*: rvalue. #### `ceiling` @@ -336,10 +337,13 @@ fqdn_rand_string(10, '', 'custom seed') Rotates an array or string a random number of times, combining the `$fqdn` fact and an optional seed for repeatable randomness. *Usage:* + ~~~ fqdn_rotate(VALUE, [SEED]) ~~~ + *Examples:* + ~~~ fqdn_rotate(['a', 'b', 'c', 'd']) fqdn_rotate('abcd') @@ -459,7 +463,7 @@ Returns an array an intersection of two. For example, `intersection(["a","b","c" #### `is_a` -Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. This function is only available in Puppet 4, or when using the "future" parser. +Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. This function is available only in Puppet 4 or in Puppet 3 with the "future" parser. ~~~ foo = 3 @@ -477,8 +481,8 @@ Boolean check to determine whether a variable is of a given data type. This is e } ~~~ -See the documentation for "The Puppet Type System" for more information about types. -See the `assert_type()` function for flexible ways to assert the type of a value. +See the [the Puppet type system](https://docs.puppetlabs.com/references/latest/type.html#about-resource-types) for more information about types. +See the [`assert_type()`](https://docs.puppetlabs.com/references/latest/function.html#asserttype) function for flexible ways to assert the type of a value. #### `is_array` @@ -555,7 +559,7 @@ Loads the metadata.json of a target module. Can be used to determine module vers notify { $metadata['author']: } ~~~ -If you do not want to fail the catalog compilation if the metadata file for a module is not present: +If you do not want to fail the catalog compilation when a module's metadata file is absent: ~~~ $metadata = load_module_metadata('mysql', true) @@ -607,12 +611,12 @@ Converts a number or a string representation of a number into a true boolean. Ze #### `parsejson` Converts a string of JSON into the correct Puppet structure. *Type*: rvalue. -The optional second argument will be returned if the data was not correct. +The optional second argument is returned if the data was not correct. #### `parseyaml` Converts a string of YAML into the correct Puppet structure. *Type*: rvalue. -The optional second argument will be returned if the data was not correct. +The optional second argument is returned if the data was not correct. #### `pick` @@ -626,7 +630,7 @@ From a list of values, returns the first value that is not undefined or an empty #### `pick_default` -Will return the first value in a list of values. Contrary to the 'pick()' function, the 'pick_default()' does not fail if all arguments are empty. This allows it to use an empty value as default. *Type*: rvalue. +Returns the first value in a list of values. Contrary to the `pick()` function, the `pick_default()` does not fail if all arguments are empty. This allows it to use an empty value as default. *Type*: rvalue. #### `prefix` @@ -700,8 +704,8 @@ Strips spaces to the right of the string. *Type*: rvalue. #### `seeded_rand` Takes an integer max value and a string seed value and returns a -repeatable random integer smaller than max. Like `fqdn_rand`, but -this does not add node specific data to the seed. *Type*: rvalue. +repeatable random integer smaller than max. Like `fqdn_rand`, but +does not add node specific data to the seed. *Type*: rvalue. #### `shuffle` @@ -721,7 +725,7 @@ Returns a new string where runs of the same character that occur in this set are #### `str2bool` -Converts certain strings to a boolean. This attempts to convert strings that contain the values '1', 't', 'y', and 'yes' to 'true'. Strings that contain values '0', 'f', 'n', and 'no', or are an an empty string or undefined are converted to 'false'. Any other value will cause an error. *Type*: rvalue. +Converts certain strings to a boolean. This attempts to convert strings that contain the values '1', 't', 'y', or 'yes' to true. Strings that contain values '0', 'f', 'n', or 'no', or that are an empty string or undefined are converted to false. Any other value causes an error. *Type*: rvalue. #### `str2saltedsha512` @@ -804,18 +808,17 @@ Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a sin *Type*: rvalue. -Looks up into a complex structure of arrays and hashes to extract a value by -its path in the structure. The path is a string of hash keys or array indexes +Retrieves a value within multiple layers of hashes and arrays via a string containing a path. The path is a string of hash keys or array indexes starting with zero, separated by the path separator character (default "/"). -The function will go down the structure by each path component and will try to +The function goes through the structure by each path component and tries to return the value at the end of the path. -In addition to the required "path" argument the function accepts the default -argument. It will be returned if the path is not correct, no value was found or -a any other error have occurred. And the last argument can set the path +In addition to the required path argument, the function accepts the default +argument. It is returned if the path is not correct, if no value was found, or +if any other error has occurred. The last argument can set the path separator character. -```ruby +~~~ruby $data = { 'a' => { 'b' => [ @@ -840,7 +843,7 @@ $value = try_get_value($data, 'a/b/c/d', 'not_found') # using custom separator $value = try_get_value($data, 'a|b', [], '|') # $value = ['b1','b2','b3'] -``` +~~~ 1. **$data** The data structure we are working with. 2. **'a/b/2'** The path string. @@ -1087,9 +1090,8 @@ Validates that the first argument is an integer (or an array of integers). Abort #### `validate_ip_address` -Validates that argument is an IP address, regardless of it is an IPv4 or an IPv6 -address. It validates as well IP address with netmask. It must be an String, as -well. +Validates that the argument is an IP address, regardless of it is an IPv4 or an IPv6 +address. It also validates IP address with netmask. The argument must be given as a string. The following values will pass: @@ -1160,7 +1162,7 @@ test, and the second argument should be a stringified regular expression (withou validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7') ~~~ - Note: Compilation will also abort, if the first argument is not a String. Always use + Note: Compilation terminates if the first argument is not a string. Always use quotes to force stringification: ~~~ @@ -1171,7 +1173,7 @@ test, and the second argument should be a stringified regular expression (withou #### `validate_slength` -Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if arg 2 is not convertable to a number. Optionally, a minimum string length can be given as the third argument. +Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if the second argument is not convertable to a number. Optionally, a minimum string length can be given as the third argument. The following values pass: @@ -1243,7 +1245,7 @@ Finds values inside an array based on location. The first argument is the array Takes one element from first array given and merges corresponding elements from second array given. This generates a sequence of n-element arrays, where *n* is one more than the count of arguments. For example, `zip(['1','2','3'],['4','5','6'])` results in ["1", "4"], ["2", "5"], ["3", "6"]. *Type*: rvalue. -##Limitations +## Limitations As of Puppet Enterprise 3.7, the stdlib module is no longer included in PE. PE users should install the most recent release of stdlib for compatibility with Puppet modules. @@ -1259,13 +1261,13 @@ Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x | **stdlib 5.x**: When released, stdlib 5.x will drop support for Puppet 2.7.x. Please see [this discussion](https://github.com/puppetlabs/puppetlabs-stdlib/pull/176#issuecomment-30251414). -##Development +## Development -Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html) +Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide](https://docs.puppetlabs.com/forge/contributing.html). To report or research a bug with any part of this module, please go to [http://tickets.puppetlabs.com/browse/PUP](http://tickets.puppetlabs.com/browse/PUP). -##Contributors +## Contributors -The list of contributors can be found at: https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors +The list of contributors can be found at: [https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors](https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors). -- cgit v1.2.3 From d00bccc96f0bad9fd312453c4d50a6a864286b74 Mon Sep 17 00:00:00 2001 From: jbondpdx Date: Mon, 14 Dec 2015 11:50:51 -0800 Subject: removing mid-line carriage returns --- README.markdown | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index c073b30..68de87a 100644 --- a/README.markdown +++ b/README.markdown @@ -77,11 +77,7 @@ The `stdlib::stages` class declares various run stages for deploying infrastruct #### `file_line` -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 appends the line to -the end of the file to ensure the desired state. Multiple resources can -be declared to manage multiple lines in the same file. +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 appends the line to the end of the file to ensure the desired state. Multiple resources can be declared to manage multiple lines in the same file. Example: @@ -610,13 +606,11 @@ Converts a number or a string representation of a number into a true boolean. Ze #### `parsejson` -Converts a string of JSON into the correct Puppet structure. *Type*: rvalue. -The optional second argument is returned if the data was not correct. +Converts a string of JSON into the correct Puppet structure. *Type*: rvalue. The optional second argument is returned if the data was not correct. #### `parseyaml` -Converts a string of YAML into the correct Puppet structure. *Type*: rvalue. -The optional second argument is returned if the data was not correct. +Converts a string of YAML into the correct Puppet structure. *Type*: rvalue. The optional second argument is returned if the data was not correct. #### `pick` @@ -703,9 +697,7 @@ Strips spaces to the right of the string. *Type*: rvalue. #### `seeded_rand` -Takes an integer max value and a string seed value and returns a -repeatable random integer smaller than max. Like `fqdn_rand`, but -does not add node specific data to the seed. *Type*: rvalue. +Takes an integer max value and a string seed value and returns a repeatable random integer smaller than max. Like `fqdn_rand`, but does not add node specific data to the seed. *Type*: rvalue. #### `shuffle` @@ -808,15 +800,9 @@ Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a sin *Type*: rvalue. -Retrieves a value within multiple layers of hashes and arrays via a string containing a path. The path is a string of hash keys or array indexes -starting with zero, separated by the path separator character (default "/"). -The function goes through the structure by each path component and tries to -return the value at the end of the path. +Retrieves a value within multiple layers of hashes and arrays via a string containing a path. The path is a string of hash keys or array indexes starting with zero, separated by the path separator character (default "/"). The function goes through the structure by each path component and tries to return the value at the end of the path. -In addition to the required path argument, the function accepts the default -argument. It is returned if the path is not correct, if no value was found, or -if any other error has occurred. The last argument can set the path -separator character. +In addition to the required path argument, the function accepts the default argument. It is returned if the path is not correct, if no value was found, or if any other error has occurred. The last argument can set the path separator character. ~~~ruby $data = { -- cgit v1.2.3 From 802e3adf1660bfa9ea8bdf388cc6ea5b08d79bde Mon Sep 17 00:00:00 2001 From: jbondpdx Date: Mon, 14 Dec 2015 11:57:01 -0800 Subject: more carriage returns, no --- README.markdown | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 68de87a..2f46c9f 100644 --- a/README.markdown +++ b/README.markdown @@ -91,8 +91,7 @@ Example: line => '%sudonopw ALL=(ALL) NOPASSWD: ALL', } -In this example, Puppet ensures that both of the specified lines are -contained in the file `/etc/sudoers`. +In this example, Puppet ensures that both of the specified lines are contained in the file `/etc/sudoers`. Match Example: @@ -103,8 +102,7 @@ Match Example: match => '^export\ HTTP_PROXY\=', } -In this code example, `match` looks for a line beginning with export -followed by HTTP_PROXY and replaces it with the value in line. +In this code example, `match` looks for a line beginning with export followed by HTTP_PROXY and replaces it with the value in line. Match Example With `ensure => absent`: @@ -120,8 +118,7 @@ In this code example, `match` looks for a line beginning with export followed by HTTP_PROXY and delete it. If multiple lines match, an error will be raised unless the `multiple => true` parameter is set. -**Autorequires:** If Puppet is managing the file that contains the line -being managed, the `file_line` resource autorequires that file. +**Autorequires:** If Puppet is managing the file that contains the line being managed, the `file_line` resource autorequires that file. ##### Parameters @@ -169,10 +166,7 @@ Converts a boolean to a number. Converts values: #### `bool2str` -Converts a boolean to a string using optionally supplied arguments. The optional -second and third arguments represent what true and false are converted to -respectively. If only one argument is given, it is converted from a boolean -to a string containing 'true' or 'false'. +Converts a boolean to a string using optionally supplied arguments. The optional second and third arguments represent what true and false are converted to respectively. If only one argument is given, it is converted from a boolean to a string containing 'true' or 'false'. *Examples:* ~~~ -- cgit v1.2.3 From 8fcefcfdb195c964b8fdd07b84378659598f2e1e Mon Sep 17 00:00:00 2001 From: jbondpdx Date: Mon, 14 Dec 2015 13:35:23 -0800 Subject: more carriage returns --- README.markdown | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 2f46c9f..221de6e 100644 --- a/README.markdown +++ b/README.markdown @@ -1142,8 +1142,7 @@ test, and the second argument should be a stringified regular expression (withou validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7') ~~~ - Note: Compilation terminates if the first argument is not a string. Always use - quotes to force stringification: + Note: Compilation terminates if the first argument is not a string. Always use quotes to force stringification: ~~~ validate_re("${::operatingsystemmajrelease}", '^[57]$') -- cgit v1.2.3 From 1b048ff9d689fcd0ff8e67640598cb0a1aa00887 Mon Sep 17 00:00:00 2001 From: Corey Osman Date: Mon, 7 Dec 2015 16:38:26 -0800 Subject: adds new parser called is_absolute_path * is_absolute_path returns boolean true if the given path is absolute, returns false otherwise. * works for windows and unix --- README.markdown | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 221de6e..a6ed1fb 100644 --- a/README.markdown +++ b/README.markdown @@ -474,6 +474,10 @@ Boolean check to determine whether a variable is of a given data type. This is e See the [the Puppet type system](https://docs.puppetlabs.com/references/latest/type.html#about-resource-types) for more information about types. See the [`assert_type()`](https://docs.puppetlabs.com/references/latest/function.html#asserttype) function for flexible ways to assert the type of a value. +#### `is_absolute_path` + +Returns 'true' if the given path is absolute. *Type*: rvalue. + #### `is_array` Returns 'true' if the variable passed to this function is an array. *Type*: rvalue. -- cgit v1.2.3 From 27782242bc27dced7bed316a01c21fffd94e34f8 Mon Sep 17 00:00:00 2001 From: Michael Polenchuk Date: Wed, 18 Nov 2015 14:32:24 +0300 Subject: Add clamp function Clamp keeps value within the range. Employ of soft() makes the whole thing is independant of order. --- README.markdown | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 9ff242c..0931e63 100644 --- a/README.markdown +++ b/README.markdown @@ -202,6 +202,14 @@ Removes the record separator from the end of a string or an array of strings; fo 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 want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as input. *Type*: rvalue. +#### `clamp` + +Keeps value within the range [Min, X, Max] by sort based on integer value (order of params doesn't matter). Takes strings, arrays or numerics. Strings are converted and compared numerically. Arrays of values are flattened into a list for further handling. For example: + * `clamp('24', [575, 187])` returns 187. + * `clamp(16, 88, 661)` returns 88. + * `clamp([4, 3, '99'])` returns 4. + *Type*: rvalue. + #### `concat` Appends the contents of multiple arrays onto the first array given. For example: -- cgit v1.2.3 From 97320ab42121a10b76c642b8378c82a888148e4b Mon Sep 17 00:00:00 2001 From: Matt Bostock Date: Mon, 23 Nov 2015 23:45:23 +0000 Subject: Add a function to validate an x509 RSA key pair Add a function to validate an x509 RSA certificate and key pair, as commonly used for TLS certificates. The rationale behind this is that we store our TLS certificates and private keys in Hiera YAML files, and poor indentation or formatting in the YAML file could cause a valid certificate to be considered invalid. Will cause the Puppet run to fail if: - an invalid certificate is detected - an invalid RSA key is detected - the certificate does not match the key, i.e. the certificate has not been signed by the supplied key The test certificates I've used in the spec tests were generated using the Go standard library: $ go run $GOROOT/src/crypto/tls/generate_cert.go -host localhost Example output: ==> cache-1.router: Error: Not a valid RSA key: Neither PUB key nor PRIV key:: nested asn1 error at /var/govuk/puppet/modules/nginx/manifests/config/ssl.pp:30 on node cache-1.router.dev.gov.uk --- README.markdown | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 9ff242c..e126e5d 100644 --- a/README.markdown +++ b/README.markdown @@ -1182,6 +1182,22 @@ Instead, use: *Type*: statement. +#### `validate_x509_rsa_key_pair` + +Validates a PEM-formatted X.509 certificate and private key using OpenSSL. +Verifies that the certficate's signature was created from the supplied key. + +Fails catalog compilation if any value fails this check. + +Takes two arguments, the first argument must be a X.509 certificate and the +second must be an RSA private key: + + ~~~ + validate_x509_rsa_key_pair($cert, $key) + ~~~ + +*Type*: statement. + #### `values` Returns the values of a given hash. For example, given `$hash = {'a'=1, 'b'=2, 'c'=3} values($hash)` returns [1,2,3]. -- cgit v1.2.3 From d85aec41a3b57a13f16086cc1ff7ed2fe09602b8 Mon Sep 17 00:00:00 2001 From: Giulio Fidente Date: Fri, 22 Jan 2016 17:55:03 +0100 Subject: Add is_ipv4_address and is_ipv6_address functions These are useful when making decisions based on the type of IP address received. --- README.markdown | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 559a6a0..4417733 100644 --- a/README.markdown +++ b/README.markdown @@ -518,6 +518,14 @@ Returns 'true' if the variable returned to this string is an integer. *Type*: rv Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue. +#### `is_ipv6_address` + +Returns 'true' if the string passed to this function is a valid IPv6 address. *Type*: rvalue. + +#### `is_ipv4_address` + +Returns 'true' if the string passed to this function is a valid IPv4 address. *Type*: rvalue. + #### `is_mac_address` Returns 'true' if the string passed to this function is a valid MAC address. *Type*: rvalue. -- cgit v1.2.3 From 3169a43f4c24d01c64c90ab9537da284f587c726 Mon Sep 17 00:00:00 2001 From: Maksym Melnychok Date: Mon, 8 Feb 2016 07:50:35 -0800 Subject: Add dig() function Deprecates #try_get_value() --- README.markdown | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 559a6a0..c2d8388 100644 --- a/README.markdown +++ b/README.markdown @@ -254,6 +254,42 @@ Deletes all instances of the undef value from an array or hash. For example, `$h Returns the difference between two arrays. The returned array is a copy of the original array, removing any items that also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. *Type*: rvalue. +#### `dig` + +*Type*: rvalue. + +Retrieves a value within multiple layers of hashes and arrays via an array of keys containing a path. The function goes through the structure by each path component and tries to return the value at the end of the path. + +In addition to the required path argument, the function accepts the default argument. It is returned if the path is not correct, if no value was found, or if any other error has occurred. + +~~~ruby +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = dig($data, ['a', 'b', 2]) +# $value = 'b3' + +# with all possible options +$value = dig($data, ['a', 'b', 2], 'not_found') +# $value = 'b3' + +# using the default value +$value = dig($data, ['a', 'b', 'c', 'd'], 'not_found') +# $value = 'not_found' +~~~ + +1. **$data** The data structure we are working with. +2. **['a', 'b', 2]** The path array. +3. **'not_found'** The default value. It will be returned if nothing is found. + (optional, defaults to *undef*) + #### `dirname` Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. *Type*: rvalue. @@ -806,6 +842,8 @@ Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a sin *Type*: rvalue. +DEPRECATED: replaced by `dig()`. + Retrieves a value within multiple layers of hashes and arrays via a string containing a path. The path is a string of hash keys or array indexes starting with zero, separated by the path separator character (default "/"). The function goes through the structure by each path component and tries to return the value at the end of the path. In addition to the required path argument, the function accepts the default argument. It is returned if the path is not correct, if no value was found, or if any other error has occurred. The last argument can set the path separator character. -- cgit v1.2.3 From dc64e721ee0e5e49dd3b446aa3c90dab19654c21 Mon Sep 17 00:00:00 2001 From: guessi Date: Wed, 17 Feb 2016 17:00:41 +0800 Subject: Extend Base64() function support --- README.markdown | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index c2d8388..602eaf7 100644 --- a/README.markdown +++ b/README.markdown @@ -146,7 +146,36 @@ Converts any object to an array containing that object. Empty argument lists are #### `base64` -Converts a string to and from base64 encoding. Requires an action ('encode', 'decode') and either a plain or base64-encoded string. *Type*: rvalue. +Converts a string to and from base64 encoding. +Requires an `action` ('encode', 'decode') and either a plain or base64-encoded `string`, +and an optional `method` ('default', 'strict', 'urlsafe') + +for backward compatibility, `metohd` will be set as `default` if not specified. + +*Examples:* +~~~ +base64('encode', 'hello') +base64('encode', 'hello', 'default') +# return: "aGVsbG8=\n" + +base64('encode', 'hello', 'strict') +# return: "aGVsbG8=" + +base64('decode', 'aGVsbG8=') +base64('decode', 'aGVsbG8=\n') +base64('decode', 'aGVsbG8=', 'default') +base64('decode', 'aGVsbG8=\n', 'default') +base64('decode', 'aGVsbG8=', 'strict') +# return: "hello" + +base64('encode', 'https://puppetlabs.com', 'urlsafe') +# return: "aHR0cHM6Ly9wdXBwZXRsYWJzLmNvbQ==" + +base64('decode', 'aHR0cHM6Ly9wdXBwZXRsYWJzLmNvbQ==', 'urlsafe') +# return: "https://puppetlabs.com" +~~~ + +*Type*: rvalue. #### `basename` -- cgit v1.2.3 From 0378336f9cefea65675d03f1d7107c75cb950fb6 Mon Sep 17 00:00:00 2001 From: Emilien Macchi Date: Sun, 13 Mar 2016 18:20:49 -0400 Subject: Add enclose_ipv6 function Copy a function from puppetlabs/apache, created by Benedikt Bock by 55cc3b4e8f4bc859a1255cb57be2c7923005d822 . This function enclose IPv6 addresses in square brackets. It takes an array of ip addresses and encloses the ipv6 addresses with square brackets. Co-Authored-By: Benedikt Bock --- README.markdown | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 994c22e..c9bbdad 100644 --- a/README.markdown +++ b/README.markdown @@ -344,6 +344,11 @@ Converts the case of a string or of all strings in an array to lowercase. *Type* Returns true if the argument is an array or hash that contains no elements, or an empty string. Returns false when the argument is a numerical value. *Type*: rvalue. +#### `enclose_ipv6` + +Takes an array of ip addresses and encloses the ipv6 addresses with square +brackets. *Type*: rvalue. + #### `ensure_packages` Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement. -- cgit v1.2.3 From 0da9ca7e4a78df49c08873f55caf7c88cdd9bc32 Mon Sep 17 00:00:00 2001 From: Nikhil Yadav Date: Thu, 10 Mar 2016 10:33:35 +0530 Subject: Add ensure_resources() function New function "ensure_resources()" to support passing hash as parameter OR from hiera backend This new function is extension of ensure_resource() which will now support to pass multiple values as hash/array OR from hiera backend variables in title argument with additional parameters needed. It will process multiple values for a resource type from the passed argument & pass each entry (type, title, params) to ensure_resource() in required format for further processing. Now user can have duplicate resource check functionality extended to multiple entries with this new function. Use: For multiple resources using hash: ensure_resources('user', {'dan' => { gid => 'mygroup', uid =>'600' } , 'alex' => { gid => 'mygroup' }}, {'ensure' =>'present'}) From Hiera Backend: userlist: dan: gid: 'mygroup' uid: '600' alex: gid: 'mygroup' Call: ensure_resources('user',hiera_hash('userlist'), {'ensure' => 'present'}) ensure_packages() Modified to also support Hash type argument for packages This modification will call newly added ensure_resources() for processing Hash as second argument. The original functionality remains same for Array type arguments. Use: hiera: packagelist: ksh: ensure: latest mlocate: {} myrpm: provider: rpm source: "/tmp/myrpm-1.0.0.x86_64.rpm" install_options: --prefix: /users/home openssl: provider: rpm source: "/tmp/openssl-1.0.1e-42.el7.x86_64.rpm" Call: ensure_packages($packagelist) --- README.markdown | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 994c22e..b6ead96 100644 --- a/README.markdown +++ b/README.markdown @@ -346,7 +346,15 @@ Returns true if the argument is an array or hash that contains no elements, or a #### `ensure_packages` -Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement. +Takes a list of packages array/hash and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` or `ensure_resources()` function. *Type*: statement. + +For Array: + + ensure_packages(['ksh','openssl'], {'ensure' => 'present'}) + +For Hash: + + ensure_packages({'ksh' => { enure => '20120801-1' } , 'mypackage' => { source => '/tmp/myrpm-1.0.0.x86_64.rpm', provider => "rpm" }}, {'ensure' => 'present'}) #### `ensure_resource` @@ -370,7 +378,37 @@ An array of resources can also be passed in, and each will be created with the t *Type*: statement. -#### `flatten` +#### `ensure_resources` + +Takes a resource type, title (only hash), and a hash of attributes that describe the resource(s). + +~~~ +user { 'dan': + gid => 'mygroup', + ensure => present, +} + +ensure_resources($user) +~~~ + +An hash of resources should be passed in and each will be created with the type and parameters specified if it doesn't already exist: + + ensure_resources('user', {'dan' => { gid => 'mygroup', uid => '600' } , 'alex' => { gid => 'mygroup' }}, {'ensure' => 'present'}) + +From Hiera Backend: + +~~~ +userlist: +dan: + gid: 'mygroup' +uid: '600' +alex: +gid: 'mygroup' + +ensure_resources('user', hiera_hash('userlist'), {'ensure' => 'present'}) +~~~ + +### `flatten` Flattens deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue. -- cgit v1.2.3 From 85ff2a28a83984c827985181d58c55ca8c524ed6 Mon Sep 17 00:00:00 2001 From: Reinhard Vicinus Date: Tue, 22 Mar 2016 15:06:31 +0100 Subject: improve suffix function to support the same feature set as prefix --- README.markdown | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index e346f4f..6cedc2a 100644 --- a/README.markdown +++ b/README.markdown @@ -904,7 +904,12 @@ Removes leading and trailing whitespace from a string or from every string insid #### `suffix` -Applies a suffix to all elements in an array. For example, `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp']. *Type*: rvalue. +Applies a suffix to all elements in an array, or to the keys in a hash. +For example: +* `suffix(['a','b','c'], 'p')` returns ['ap','bp','cp'] +* `suffix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'ap'=>'b','bp'=>'c','cp'=>'d'}. + +*Type*: rvalue. #### `swapcase` -- cgit v1.2.3 From 0d46515b57cea60d4d5f1e4d81a75a448a7a73a8 Mon Sep 17 00:00:00 2001 From: Joseph Yaworski Date: Mon, 11 Apr 2016 22:09:24 -0400 Subject: Add support for regular expressions to delete --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 6cedc2a..2f5faf3 100644 --- a/README.markdown +++ b/README.markdown @@ -265,7 +265,7 @@ Takes a resource reference and an optional hash of attributes. Returns 'true' if #### `delete` -Deletes all instances of a given element from an array, substring from a string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}. *Type*: rvalue. +Deletes all instances of a given element from an array, substring from a string, or key from a hash. Arrays and hashes may also match on regular expressions. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}, `delete(['abf', 'ab', 'ac'], '^ab.*')` returns ['ac']. *Type*: rvalue. #### `delete_at` -- cgit v1.2.3 From 232de137f1018060b256b1f3f649be0b6d7d9952 Mon Sep 17 00:00:00 2001 From: Hunter Haugen Date: Mon, 25 Apr 2016 14:33:43 -0700 Subject: Revert "Add support for regular expressions to delete" This reverts commit 0d46515b57cea60d4d5f1e4d81a75a448a7a73a8. It introduced backwards-incompatible functionality. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 2f5faf3..6cedc2a 100644 --- a/README.markdown +++ b/README.markdown @@ -265,7 +265,7 @@ Takes a resource reference and an optional hash of attributes. Returns 'true' if #### `delete` -Deletes all instances of a given element from an array, substring from a string, or key from a hash. Arrays and hashes may also match on regular expressions. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}, `delete(['abf', 'ab', 'ac'], '^ab.*')` returns ['ac']. *Type*: rvalue. +Deletes all instances of a given element from an array, substring from a string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}. *Type*: rvalue. #### `delete_at` -- cgit v1.2.3 From 870a272cee6889934d60c4bfd7a814bcf47011f1 Mon Sep 17 00:00:00 2001 From: Dmitry Ilyin Date: Tue, 26 Apr 2016 21:51:43 +0300 Subject: Add the default value to the "loadyaml" function This value will be returned if the is no file to load or a file could not be parsed. It's similar to the "parseyaml" function's default value. Add the "loadjson" function too --- README.markdown | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 6cedc2a..eff3b28 100644 --- a/README.markdown +++ b/README.markdown @@ -660,12 +660,42 @@ Returns the keys of a hash as an array. *Type*: rvalue. #### `loadyaml` -Loads a YAML file containing an array, string, or hash, and returns the data in the corresponding native data type. For example: +Loads a YAML file containing an array, string, or hash, and returns the data in the corresponding native data type. + +For example: ~~~ $myhash = loadyaml('/etc/puppet/data/myhash.yaml') ~~~ +The second parameter will be returned if the file was not found or could not be parsed. + +For example: + + ~~~ + $myhash = loadyaml('no-file.yaml', {'default'=>'value'}) + ~~~ + +*Type*: rvalue. + +#### `loadjson` + +Loads a JSON file containing an array, string, or hash, and returns the data in the corresponding native data type. + +For example: + + ~~~ + $myhash = loadjson('/etc/puppet/data/myhash.json') + ~~~ + +The second parameter will be returned if the file was not found or could not be parsed. + +For example: + + ~~~ + $myhash = loadjson('no-file.json', {'default'=>'value'}) + ~~~ + *Type*: rvalue. #### `load_module_metadata` -- cgit v1.2.3 From db6e2f81b470afc3e0c2c96a47cf9e68b9c7afc7 Mon Sep 17 00:00:00 2001 From: Hunter Haugen Date: Wed, 27 Apr 2016 15:34:19 -0700 Subject: Remove hard linebreaks --- README.markdown | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 6cedc2a..ba1f5f8 100644 --- a/README.markdown +++ b/README.markdown @@ -146,11 +146,9 @@ Converts any object to an array containing that object. Empty argument lists are #### `base64` -Converts a string to and from base64 encoding. -Requires an `action` ('encode', 'decode') and either a plain or base64-encoded `string`, -and an optional `method` ('default', 'strict', 'urlsafe') +Converts a string to and from base64 encoding. Requires an `action` ('encode', 'decode') and either a plain or base64-encoded `string`, and an optional `method` ('default', 'strict', 'urlsafe') -for backward compatibility, `metohd` will be set as `default` if not specified. +For backward compatibility, `method` will be set as `default` if not specified. *Examples:* ~~~ @@ -346,8 +344,7 @@ Returns true if the argument is an array or hash that contains no elements, or a #### `enclose_ipv6` -Takes an array of ip addresses and encloses the ipv6 addresses with square -brackets. *Type*: rvalue. +Takes an array of ip addresses and encloses the ipv6 addresses with square brackets. *Type*: rvalue. #### `ensure_packages` -- cgit v1.2.3 From 9e1f74f3fcac4aeaccade3ea92e6cafbaf71a64f Mon Sep 17 00:00:00 2001 From: Joris Date: Thu, 28 Apr 2016 19:44:30 +0200 Subject: Expose the functions of ruby's built-in Shellwords module (#580) * Add shell_escape function, shell_join function & shell_split function --- README.markdown | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 2f5faf3..9e62d1c 100644 --- a/README.markdown +++ b/README.markdown @@ -821,6 +821,40 @@ Strips spaces to the right of the string. *Type*: rvalue. Takes an integer max value and a string seed value and returns a repeatable random integer smaller than max. Like `fqdn_rand`, but does not add node specific data to the seed. *Type*: rvalue. +#### `shell_escape` + +Escapes a string so that it can be safely used in a Bourne shell command line. Note that the resulting string should be used unquoted and is not intended for use in double quotes nor in single quotes. This function behaves the same as ruby's `Shellwords.shellescape()` function, also see the [ruby documentation](http://ruby-doc.org/stdlib-2.3.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shellescape). + +*Example:* +~~~ +shell_escape('foo b"ar') => 'foo\ b\"ar' +~~~ + +*Type*: rvalue. + +#### `shell_join` + +Builds a command line string from the given array of strings. Each array item is escaped for Bourne shell. All items are +then joined together, with a single space in between. This function behaves the same as ruby's `Shellwords.shelljoin()` function, also see the [ruby documentation](http://ruby-doc.org/stdlib-2.3.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shelljoin). + +*Example:* +~~~ +shell_join(['foo bar', 'ba"z']) => 'foo\ bar ba\"z' +~~~ + +*Type*: rvalue. + +#### `shell_split` + +Splits a string into an array of tokens in the same way the Bourne shell does. This function behaves the same as ruby's `Shellwords.shellsplit()` function, also see the [ruby documentation](http://ruby-doc.org/stdlib-2.3.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shellsplit). + +*Example:* +~~~ +shell_split('foo\ bar ba\"z') => ['foo bar', 'ba"z'] +~~~ + +*Type*: rvalue. + #### `shuffle` Randomizes the order of a string or array elements. *Type*: rvalue. -- cgit v1.2.3 From 540546b9b41745bbc4821f9966ae301dc0b5056a Mon Sep 17 00:00:00 2001 From: Joseph Yaworski Date: Tue, 12 Apr 2016 16:53:07 -0400 Subject: Use reject instead of delete_if --- README.markdown | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 1ef6509..298b852 100644 --- a/README.markdown +++ b/README.markdown @@ -263,7 +263,11 @@ Takes a resource reference and an optional hash of attributes. Returns 'true' if #### `delete` -Deletes all instances of a given element from an array, substring from a string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}. *Type*: rvalue. +Deletes all instances of a given element from an array, substring from a string, or key from a hash. Arrays and hashes may also match on regular expressions by providing a full regular expression. + +For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}, `delete(['abf', 'ab', 'ac'], '^ab.*')` returns ['ac']. `delete(['ab', 'b'], 'b')` returns ['ab']. + +*Type*: rvalue. #### `delete_at` -- cgit v1.2.3 From 8f1efdad22e81c448b2c259e55d3d05a2c0040a2 Mon Sep 17 00:00:00 2001 From: bob Date: Wed, 11 May 2016 10:52:25 +0100 Subject: Add a missing s in the ensure_packages hash example --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 298b852..e4efa9e 100644 --- a/README.markdown +++ b/README.markdown @@ -360,7 +360,7 @@ For Array: For Hash: - ensure_packages({'ksh' => { enure => '20120801-1' } , 'mypackage' => { source => '/tmp/myrpm-1.0.0.x86_64.rpm', provider => "rpm" }}, {'ensure' => 'present'}) + ensure_packages({'ksh' => { ensure => '20120801-1' } , 'mypackage' => { source => '/tmp/myrpm-1.0.0.x86_64.rpm', provider => "rpm" }}, {'ensure' => 'present'}) #### `ensure_resource` -- cgit v1.2.3 From dd71c0288052dd3a96e730ff198f5c0a8d640946 Mon Sep 17 00:00:00 2001 From: Joseph Yaworski Date: Wed, 11 May 2016 13:21:24 -0400 Subject: Add a delete_regex function To maintain backwards compatibility, add a delete_regex function instead of modifying delete itself. --- README.markdown | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 6a64b79..373b08c 100644 --- a/README.markdown +++ b/README.markdown @@ -263,9 +263,9 @@ Takes a resource reference and an optional hash of attributes. Returns 'true' if #### `delete` -Deletes all instances of a given element from an array, substring from a string, or key from a hash. Arrays and hashes may also match on regular expressions by providing a full regular expression. +Deletes all instances of a given element from an array, substring from a string, or key from a hash. -For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}, `delete(['abf', 'ab', 'ac'], '^ab.*')` returns ['ac']. `delete(['ab', 'b'], 'b')` returns ['ab']. +For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}, `delete(['ab', 'b'], 'b')` returns ['ab']. *Type*: rvalue. @@ -273,6 +273,14 @@ For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abraca Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue. +#### `delete_regex` + +Deletes all instances of a given element from an array or hash that match a provided regular expression. A string will be treated as a one-item array. + +For example, `delete_regex(['a','b','c','b'], 'b')` returns ['a','c']; `delete_regex({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}, `delete_regex(['abf', 'ab', 'ac'], '^ab.*')` returns ['ac']. `delete_regex(['ab', 'b'], 'b')` returns ['ab']. + +*Type*: rvalue. + #### `delete_values` Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue. -- cgit v1.2.3 From a2f980d44d6703561769c5e0ef25a7f531417643 Mon Sep 17 00:00:00 2001 From: Nate Potter Date: Thu, 7 Jul 2016 21:10:22 -0700 Subject: (MODULES-3568) Move dig to dig44 and deprecate dig A new version of dig was introduced in Puppet 4.5.0 that isn't compatible with the stdlib version of dig. To maintain backwards compatibility and ensure that tests for stdlib aren't broken, this patch renames dig to dig44 and adds a deprecation warning to the stdlib dig function. --- README.markdown | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 373b08c..1368b2f 100644 --- a/README.markdown +++ b/README.markdown @@ -295,6 +295,8 @@ Returns the difference between two arrays. The returned array is a copy of the o #### `dig` +DEPRECATED: This function has been replaced in Puppet 4.5.0, use dig44() for backwards compatibility or use the new version. + *Type*: rvalue. Retrieves a value within multiple layers of hashes and arrays via an array of keys containing a path. The function goes through the structure by each path component and tries to return the value at the end of the path. @@ -324,6 +326,42 @@ $value = dig($data, ['a', 'b', 'c', 'd'], 'not_found') # $value = 'not_found' ~~~ +1. **$data** The data structure we are working with. +2. **['a', 'b', 2]** The path array. +3. **'not_found'** The default value. It will be returned if nothing is found. + (optional, defaults to *undef*) + +#### `dig44` + +*Type*: rvalue. + +Retrieves a value within multiple layers of hashes and arrays via an array of keys containing a path. The function goes through the structure by each path component and tries to return the value at the end of the path. + +In addition to the required path argument, the function accepts the default argument. It is returned if the path is not correct, if no value was found, or if any other error has occurred. + +~~~ruby +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = dig44($data, ['a', 'b', 2]) +# $value = 'b3' + +# with all possible options +$value = dig44($data, ['a', 'b', 2], 'not_found') +# $value = 'b3' + +# using the default value +$value = dig44($data, ['a', 'b', 'c', 'd'], 'not_found') +# $value = 'not_found' +~~~ + 1. **$data** The data structure we are working with. 2. **['a', 'b', 2]** The path array. 3. **'not_found'** The default value. It will be returned if nothing is found. -- cgit v1.2.3 From 72d23659513517389880ba13663a1d6380d538ca Mon Sep 17 00:00:00 2001 From: tphoney Date: Tue, 5 Jul 2016 09:56:42 +0100 Subject: (MODULES-3529)add deprecation function --- README.markdown | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 373b08c..8252ab5 100644 --- a/README.markdown +++ b/README.markdown @@ -289,6 +289,10 @@ Deletes all instances of a given value from a hash. For example, `delete_values( Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue. +#### `deprecation` + +Function to print deprecation warnings, Logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message text including any positional information that is formatted by the user/caller of the method It is affected by the puppet setting 'strict', which can be set to :error (outputs as an error message), :off (no message / error is displayed) and :warning (default, outputs a warning) *Type*: String, String. + #### `difference` Returns the difference between two arrays. The returned array is a copy of the original array, removing any items that also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. *Type*: rvalue. -- cgit v1.2.3 From ef935bb287c54ac615f7f538a6f89190b4d2c4d7 Mon Sep 17 00:00:00 2001 From: tphoney Date: Tue, 19 Jul 2016 11:42:47 +0100 Subject: (MODULES-2143) document edge behaviour of range. --- README.markdown | 1 + 1 file changed, 1 insertion(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f176d98..45b4482 100644 --- a/README.markdown +++ b/README.markdown @@ -881,6 +881,7 @@ The third argument to this function is the salt to use. Extrapolates a range as an array when given in the form of '(start, stop)'. For example, `range("0", "9")` returns [0,1,2,3,4,5,6,7,8,9]. Zero-padded strings are converted to integers automatically, so `range("00", "09")` returns [0,1,2,3,4,5,6,7,8,9]. Non-integer strings are accepted; `range("a", "c")` returns ["a","b","c"], and `range("host01", "host10")` returns ["host01", "host02", ..., "host09", "host10"]. +NB Be explicit in including trailing zeros. Otherwise the underlying ruby function will fail. Passing a third argument will cause the generated range to step by that interval, e.g. `range("0", "9", "2")` returns ["0","2","4","6","8"]. -- cgit v1.2.3 From 41a46b67aed703cd9311aa0c4e4b18ff81a75fa8 Mon Sep 17 00:00:00 2001 From: tphoney Date: Tue, 19 Jul 2016 11:56:09 +0100 Subject: (MODULES-3306) document deep_merge --- README.markdown | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f176d98..24f493c 100644 --- a/README.markdown +++ b/README.markdown @@ -245,6 +245,19 @@ Converts a given integer or base 10 string representing an integer to a specifie If called with only an array, it counts the number of elements that are **not** nil/undef. If called with a second argument, counts the number of elements in an array that matches the second argument. *Type*: rvalue. +#### `deep_merge` + +Recursively merges two or more hashes together and returns the resulting hash. + $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, 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. Returns 'false' otherwise. -- cgit v1.2.3 From db92a082c15c11d4d069a821be8aaddc5537020b Mon Sep 17 00:00:00 2001 From: Steve Moore Date: Tue, 26 Jul 2016 15:39:50 -0400 Subject: Added documentation for regexpescape function. --- README.markdown | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 158f55b..6352473 100644 --- a/README.markdown +++ b/README.markdown @@ -900,6 +900,10 @@ Passing a third argument will cause the generated range to step by that interval *Type*: rvalue. +#### `regexpescape` + +Regexp escape a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue. + #### `reject` Searches through an array and rejects all elements that match the provided regular expression. For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc']. *Type*: rvalue. -- cgit v1.2.3 From 9031fc149ad9acc4c51ceb343864705003f93867 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Romain=20Tarti=C3=A8re?= Date: Fri, 5 Aug 2016 10:58:14 +0200 Subject: Fix markdown indentation The old indentation is weird. --- README.markdown | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 6352473..0666b37 100644 --- a/README.markdown +++ b/README.markdown @@ -468,11 +468,11 @@ From Hiera Backend: ~~~ userlist: -dan: - gid: 'mygroup' -uid: '600' -alex: -gid: 'mygroup' + dan: + gid: 'mygroup' + uid: '600' + alex: + gid: 'mygroup' ensure_resources('user', hiera_hash('userlist'), {'ensure' => 'present'}) ~~~ -- cgit v1.2.3 From 17a49baae33a78d6aa781aaaadafc08b43def040 Mon Sep 17 00:00:00 2001 From: Chris Edester Date: Fri, 5 Aug 2016 15:38:59 -0400 Subject: Handle array values in join_keys_to_values function --- README.markdown | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 0666b37..90addee 100644 --- a/README.markdown +++ b/README.markdown @@ -716,7 +716,9 @@ Joins an array into a string using a separator. For example, `join(['a','b','c'] #### `join_keys_to_values` -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. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *Type*: rvalue. +Joins each key of a hash to that key's corresponding value with a separator. Keys are cast to strings. +If values are arrays, multiple keys are added for each element. +The return value is an array in which each element is one joined key/value pair. For example, `join_keys_to_values({'a'=>1,'b'=>[2,3]}, " is ")` results in ["a is 1","b is 2","b is 3"]. *Type*: rvalue. #### `keys` -- cgit v1.2.3 From adf922c28441bc95f5cbac1f0951256c080b3298 Mon Sep 17 00:00:00 2001 From: Helen Campbell Date: Wed, 10 Aug 2016 14:17:16 +0100 Subject: (WIP) Addition of validate legacy function --- README.markdown | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 0666b37..26fe55f 100644 --- a/README.markdown +++ b/README.markdown @@ -1368,6 +1368,17 @@ The following values will fail, causing compilation to abort: ~~~ +#### `validate_legacy` + +Validates a value against both a specified type and a deprecated validation function. Silently passes if both pass, errors if one validation passes and the other does not, fails if both validations return false. +Arguments include the type to check the value against, the full name of the previous validation function, the value itself to be checked, and an unspecified amount of arguments needed for the previous validation function. + +Example: + + ~~~ + validate_legacy("Optional[String]", "validate_re", "Value to be validated", ["."]) + ~~~ + #### `validate_numeric` Validates that the first argument is a numeric value (or an array of numeric values). Aborts catalog compilation if any of the checks fail. -- cgit v1.2.3 From cf2015de88961f7290399c2416a40ed9105bc3a2 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Mon, 15 Aug 2016 13:38:46 +0100 Subject: Update documentation for validate_legacy This adds a in-depth explanation of the process to migrate to Puppet 4 data types. --- README.markdown | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 26fe55f..13a5b74 100644 --- a/README.markdown +++ b/README.markdown @@ -1370,6 +1370,61 @@ The following values will fail, causing compilation to abort: #### `validate_legacy` +This function supports updating modules to upgrade from Puppet 3 style argument validation (using the stdlib `validate_*` functions) to Puppet 4 data types, without breaking the world. + +##### For module users + +You are probably here, because you're receiving loads of deprecation warnings about `validate_*` functions. If you're still on Puppet 3, use the options described in [`deprecation`](#deprecation) to silence the messages for now, and avoid upgrading to module versions which already have dropped Puppet 3 support. If you're already running Puppet 4 (shipped in Puppet Enterprise 2015.2 or later), please read on to understand the required steps to fix those issues. + +The `validate_*` functions were the only way on Puppet 3 to easily check the types of class and define arguments. Additionally some of the functions provided additional helpers like [validate_numeric](#validate_numeric), which would not only allow numbers, but also arrays of numbers. Puppet 4 now allows much better defined type checking using [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html), without such surprises. To avoid breaking the world for people depending on those surprises, `validate_legacy` provides a way to make those edge-cases visible, and assist people with getting onto the clearer Puppet 4 syntax. + +Depending on the current state of development of the modules you use and the data you feed them, you'll encounter different messages: + +* "Notice: Accepting previously invalid value for target type ''": Nothing to worry, you're already using values allowed by the new type, that would have been invalid by the old validation function. This is informational only. +* "Warning: This method is deprecated, please use the stdlib validate_legacy function": The module you're using hasn't yet upgraded to validate_legacy, use the options from [deprecation()](#deprecation) to silence the warnings for now, or submit a patch with you module's developer. See below for details. +* "Warning: validate_legacy() expected value, got ": Your code is passing a value to the module that was accepted by the Puppet v3 style validation, but that will not be accepted by the next version of the module. Most often this can be fixed by removing quotes from numbers, or booleans. +* "Error: Evaluation Error: Error while evaluating a Resource Statement, Evaluation Error: Error while evaluating a Function Call, validate_legacy() expected value, got ": Your code is passing a value that is not acceptable to either the new, or the old style validation. + + + + +##### For module developers + +Many `validate_*` functions have surprising holes in their validation. For example, [validate_numeric](#validate_numeric) would not only allow numbers, but also arrays of numbers, or strings that look like numbers, without giving you any control over the specifics. Contrast that to Puppet 4 [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html) which allow you to choose between `Numeric`, `Array[Numeric]`, or `Optional[Numeric]`. To get from here to there, without leaving your users behind, the validate_legacy function will provide you with a tool to make this migration as painless as possible. + +To start out, for each parameter of your classes and defines, you'll have to decide on a new Puppet 4 data type to use. In most cases the new data type will allow a different set of values than the original `validate_*` function (which is the point of the whole exercise). The situation then looks like this: + +| | `validate_` pass | `validate_` fail | +| matches type | pass | pass, notice | +| fails type | pass, deprecated | fail | + +The code after the validation will still have to deal with all possible values for now, but users of your code can now change their manifests to only pass values that will match the new type. + +To effect those checks, given a class like this: +~~~ +class example($value) { + validate_numeric($value) +~~~ +which should only accept numbers, the resulting validation code looks like this: +~~~ +class example( + Variant[Stdlib::Compat::Numeric, Numeric] $value +) { + validate_legacy(Numeric, 'validate_numeric', $value) +~~~ + +The type of `$value` is defined as `Variant[Stdlib::Compat::Numeric, Numeric]`, which will allow any `Numeric` (the new type), and all values previously accepted by validate_numeric (through `Stdlib::Compat::Numeric`). For each `validate_*` function in stdlib, there is a matching `Stdlib::Compat::*` type that will allow the appropriate set of values through. See the documentation in the `types/` directory in the stdlib source code for caveats. + +The call to `validate_legacy` will take care of triggering the correct log or fail message for you. It requires the new type, the previous validation function name, and all arguments to that function. + +If you were previously still supporting Puppet 3, this is a breaking change. You'll need to update your `metadata.json` to not support Puppet 3 anymore in the `requirements` section, and bump the major version of your module. This should still pass all previously existing tests your module has. Do not forget to add more tests for the newly possible values. This is also a good time to start calling [`deprecation()`](#deprecation) for all parameters you always wanted to get rid of, or add additional constraints on your parameters. + +After releasing this version, you can at any time release another breaking change release where you remove all compat types, and all calls to `validate_legacy`. At this time you can also go through your code and remove all leftovers dealing with the previously possible values. + +At all times note in the CHANGELOG and the README at what stage of the process your modules currently are. + +##### Reference + Validates a value against both a specified type and a deprecated validation function. Silently passes if both pass, errors if one validation passes and the other does not, fails if both validations return false. Arguments include the type to check the value against, the full name of the previous validation function, the value itself to be checked, and an unspecified amount of arguments needed for the previous validation function. -- cgit v1.2.3 From 5ed9aaa80967f3e4a3cf4a171c9e0fe68f5a280d Mon Sep 17 00:00:00 2001 From: Dominic Cleal Date: Fri, 2 Sep 2016 10:19:44 +0100 Subject: Fix validate_legacy docs table formatting --- README.markdown | 1 + 1 file changed, 1 insertion(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 13a5b74..fc11a84 100644 --- a/README.markdown +++ b/README.markdown @@ -1395,6 +1395,7 @@ Many `validate_*` functions have surprising holes in their validation. For examp To start out, for each parameter of your classes and defines, you'll have to decide on a new Puppet 4 data type to use. In most cases the new data type will allow a different set of values than the original `validate_*` function (which is the point of the whole exercise). The situation then looks like this: | | `validate_` pass | `validate_` fail | +| ------------ | ---------------- | ---------------- | | matches type | pass | pass, notice | | fails type | pass, deprecated | fail | -- cgit v1.2.3 From b2d05e9b3f5da65ad3dc39b95b342e9085e52346 Mon Sep 17 00:00:00 2001 From: Helen Campbell Date: Tue, 6 Sep 2016 12:30:46 +0100 Subject: Deprecation README update --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 26fe55f..aee4e90 100644 --- a/README.markdown +++ b/README.markdown @@ -304,7 +304,7 @@ Deletes all instances of the undef value from an array or hash. For example, `$h #### `deprecation` -Function to print deprecation warnings, Logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message text including any positional information that is formatted by the user/caller of the method It is affected by the puppet setting 'strict', which can be set to :error (outputs as an error message), :off (no message / error is displayed) and :warning (default, outputs a warning) *Type*: String, String. +A function to print deprecation warnings, logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message text including any positional information that is formatted by the user/caller of the method. It is affected by the puppet setting 'strict', which can be set to :error (outputs as an error message), :off (no message / error is displayed) and :warning (default, outputs a warning). In Puppet version less than 4.0 an environment variable can be set to decide whether or not to log deprecation warnings (ENV[STDLIB_LOG_DEPRECATION]). If this environment variable is set to true, the functions will log a warning. *Type*: String, String. #### `difference` -- cgit v1.2.3 From 58111160708546bcbbc4f920c165fbcb47da5a0f Mon Sep 17 00:00:00 2001 From: Paula McMaw Date: Wed, 14 Sep 2016 15:28:35 +0100 Subject: Change in readme for numerical string --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 5130f64..667da33 100644 --- a/README.markdown +++ b/README.markdown @@ -1437,7 +1437,7 @@ Example: #### `validate_numeric` -Validates that the first argument is a numeric value (or an array of numeric values). Aborts catalog compilation if any of the checks fail. +Validates that the first argument is a numeric value (or an array or string of numeric values). Aborts catalog compilation if any of the checks fail. The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. -- cgit v1.2.3 From 6ebb58623c49f738e2fe857974d54eb5c8638cea Mon Sep 17 00:00:00 2001 From: jbondpdx Date: Wed, 28 Sep 2016 15:22:45 +0100 Subject: MODULES-3774: stdlib validate_legacy review --- README.markdown | 67 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 30 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 667da33..d27668b 100644 --- a/README.markdown +++ b/README.markdown @@ -304,7 +304,7 @@ Deletes all instances of the undef value from an array or hash. For example, `$h #### `deprecation` -A function to print deprecation warnings, logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message text including any positional information that is formatted by the user/caller of the method. It is affected by the puppet setting 'strict', which can be set to :error (outputs as an error message), :off (no message / error is displayed) and :warning (default, outputs a warning). In Puppet version less than 4.0 an environment variable can be set to decide whether or not to log deprecation warnings (ENV[STDLIB_LOG_DEPRECATION]). If this environment variable is set to true, the functions will log a warning. *Type*: String, String. +Prints deprecation warnings and logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message text, including any positional information that is formatted by the user or caller of the method. The Puppet setting 'strict' affects this function. Set 'strict' to :error to output an error message, :off to output no message or error, or :warning (default) to output a warning. In Puppet versions lower than 4.0, you can set an environment variable to decide whether or not to log deprecation warnings (`ENV[STDLIB_LOG_DEPRECATION]`). If this environment variable is set to true, the functions log a warning. *Type*: String, String. #### `difference` @@ -1370,43 +1370,59 @@ The following values will fail, causing compilation to abort: #### `validate_legacy` -This function supports updating modules to upgrade from Puppet 3 style argument validation (using the stdlib `validate_*` functions) to Puppet 4 data types, without breaking the world. +Validates a value against both a specified type and a deprecated validation function. Silently passes if both pass, errors if only one validation passes, and fails if both validations return false. -##### For module users +Accepts arguments for: +* the type to check the value against, +* the full name of the previous validation function, +* the value to be checked, +* an unspecified number of arguments needed for the previous validation function. + +Example: -You are probably here, because you're receiving loads of deprecation warnings about `validate_*` functions. If you're still on Puppet 3, use the options described in [`deprecation`](#deprecation) to silence the messages for now, and avoid upgrading to module versions which already have dropped Puppet 3 support. If you're already running Puppet 4 (shipped in Puppet Enterprise 2015.2 or later), please read on to understand the required steps to fix those issues. +``` +validate_legacy("Optional[String]", "validate_re", "Value to be validated", ["."]) +``` -The `validate_*` functions were the only way on Puppet 3 to easily check the types of class and define arguments. Additionally some of the functions provided additional helpers like [validate_numeric](#validate_numeric), which would not only allow numbers, but also arrays of numbers. Puppet 4 now allows much better defined type checking using [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html), without such surprises. To avoid breaking the world for people depending on those surprises, `validate_legacy` provides a way to make those edge-cases visible, and assist people with getting onto the clearer Puppet 4 syntax. +This function supports updating modules from Puppet 3 style argument validation (using the stdlib `validate_*` functions) to Puppet 4 data types, without breaking functionality for those depending on Puppet 3 style validation. -Depending on the current state of development of the modules you use and the data you feed them, you'll encounter different messages: +##### For module users -* "Notice: Accepting previously invalid value for target type ''": Nothing to worry, you're already using values allowed by the new type, that would have been invalid by the old validation function. This is informational only. -* "Warning: This method is deprecated, please use the stdlib validate_legacy function": The module you're using hasn't yet upgraded to validate_legacy, use the options from [deprecation()](#deprecation) to silence the warnings for now, or submit a patch with you module's developer. See below for details. -* "Warning: validate_legacy() expected value, got ": Your code is passing a value to the module that was accepted by the Puppet v3 style validation, but that will not be accepted by the next version of the module. Most often this can be fixed by removing quotes from numbers, or booleans. -* "Error: Evaluation Error: Error while evaluating a Resource Statement, Evaluation Error: Error while evaluating a Function Call, validate_legacy() expected value, got ": Your code is passing a value that is not acceptable to either the new, or the old style validation. +If you are running Puppet 4 and receiving deprecation warnings about `validate_*` functions, the `validate_legacy` function can help you find and resolve the deprecated code. +In Puppet 3, the `validate_*` functions were the only way to easily check the types of class and defined type arguments. Some of the functions provided additional helpers like [validate_numeric](#validate_numeric), which unintentionally allowed not only numbers, but also arrays of numbers. Puppet 4 allows much better defined type checking using [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html), without such unintentional effects. The `validate_legacy` function makes these differences visible and makes it easier to move to the clearer Puppet 4 syntax. +Depending on the current state of development of the modules you use and the data you feed those modules, you'll encounter different messages: +* `Notice: Accepting previously invalid value for target type ''`: This message is informational only. You're using values that are allowed by the new type, but would have been invalid by the old validation function. +* `Warning: This method is deprecated, please use the stdlib validate_legacy function`: The module has not yet upgraded to `validate_legacy`. Use the [deprecation](#deprecation) options to silence warnings for now, or submit a fix with the module's developer. See the information [for module developers](#for-module-developers) below for how to fix the issue. +* `Warning: validate_legacy() expected value, got _`: Your code passes a value that was accepted by the Puppet 3 style validation, but will not be accepted by the next version of the module. Most often, you can fix this by removing quotes from numbers or booleans. +* `Error: Evaluation Error: Error while evaluating a Resource Statement, Evaluation Error: Error while evaluating a Function Call, validate_legacy() expected value, got `: Your code passes a value that is not acceptable to either the new or the old style validation. ##### For module developers -Many `validate_*` functions have surprising holes in their validation. For example, [validate_numeric](#validate_numeric) would not only allow numbers, but also arrays of numbers, or strings that look like numbers, without giving you any control over the specifics. Contrast that to Puppet 4 [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html) which allow you to choose between `Numeric`, `Array[Numeric]`, or `Optional[Numeric]`. To get from here to there, without leaving your users behind, the validate_legacy function will provide you with a tool to make this migration as painless as possible. +Many `validate_*` functions have surprising holes in their validation. For example, [validate_numeric](#validate_numeric) allows not only numbers, but also arrays of numbers or strings that look like numbers, without giving you any control over the specifics. In contrast, Puppet 4 [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html) allows you to choose between `Numeric`, `Array[Numeric]`, or `Optional[Numeric]`. The `validate_legacy` function helps you move from Puppet 3 style validation to Puppet 4 validation without breaking functionality your module's users depend on. -To start out, for each parameter of your classes and defines, you'll have to decide on a new Puppet 4 data type to use. In most cases the new data type will allow a different set of values than the original `validate_*` function (which is the point of the whole exercise). The situation then looks like this: +For each parameter of your classes and defined types, choose a new Puppet 4 data type to use. In most cases, the new data type allows a different set of values than the original `validate_*` function. The situation then looks like this: | | `validate_` pass | `validate_` fail | | ------------ | ---------------- | ---------------- | | matches type | pass | pass, notice | | fails type | pass, deprecated | fail | -The code after the validation will still have to deal with all possible values for now, but users of your code can now change their manifests to only pass values that will match the new type. +The code after the validation still has to handle all possible values for now, but users of your code can change their manifests to pass only values that match the new type. + +For each `validate_*` function in stdlib, there is a matching `Stdlib::Compat::*` type that allows the appropriate set of values. See the documentation in the `types/` directory in the stdlib source code for caveats. + +For example, given a class that should accept only numbers, like this: -To effect those checks, given a class like this: ~~~ class example($value) { validate_numeric($value) ~~~ -which should only accept numbers, the resulting validation code looks like this: + +the resulting validation code looks like this: + ~~~ class example( Variant[Stdlib::Compat::Numeric, Numeric] $value @@ -1414,26 +1430,17 @@ class example( validate_legacy(Numeric, 'validate_numeric', $value) ~~~ -The type of `$value` is defined as `Variant[Stdlib::Compat::Numeric, Numeric]`, which will allow any `Numeric` (the new type), and all values previously accepted by validate_numeric (through `Stdlib::Compat::Numeric`). For each `validate_*` function in stdlib, there is a matching `Stdlib::Compat::*` type that will allow the appropriate set of values through. See the documentation in the `types/` directory in the stdlib source code for caveats. - -The call to `validate_legacy` will take care of triggering the correct log or fail message for you. It requires the new type, the previous validation function name, and all arguments to that function. +Here, the type of `$value` is defined as `Variant[Stdlib::Compat::Numeric, Numeric]`, which allows any `Numeric` (the new type), as well as all values previously accepted by `validate_numeric` (through `Stdlib::Compat::Numeric`). -If you were previously still supporting Puppet 3, this is a breaking change. You'll need to update your `metadata.json` to not support Puppet 3 anymore in the `requirements` section, and bump the major version of your module. This should still pass all previously existing tests your module has. Do not forget to add more tests for the newly possible values. This is also a good time to start calling [`deprecation()`](#deprecation) for all parameters you always wanted to get rid of, or add additional constraints on your parameters. +The call to `validate_legacy` takes care of triggering the correct log or fail message for you. It requires the new type, the previous validation function name, and all arguments to that function. -After releasing this version, you can at any time release another breaking change release where you remove all compat types, and all calls to `validate_legacy`. At this time you can also go through your code and remove all leftovers dealing with the previously possible values. +If your module still supported Puppet 3, this is a breaking change. Update your `metadata.json` requirements section to indicate that your module no longer supports Puppet 3, and bump the major version of your module. With this change, all existing tests for your module should still pass. Create additional tests for the new possible values. -At all times note in the CHANGELOG and the README at what stage of the process your modules currently are. +As a breaking change, this is also a good time to call [`deprecation`](#deprecation) for any parameters you want to get rid of, or to add additional constraints on your parameters. -##### Reference +After releasing this version, you can release another breaking change release where you remove all compat types and all calls to `validate_legacy`. At that time, you can also go through your code and remove any leftovers dealing with the previously possible values. -Validates a value against both a specified type and a deprecated validation function. Silently passes if both pass, errors if one validation passes and the other does not, fails if both validations return false. -Arguments include the type to check the value against, the full name of the previous validation function, the value itself to be checked, and an unspecified amount of arguments needed for the previous validation function. - -Example: - - ~~~ - validate_legacy("Optional[String]", "validate_re", "Value to be validated", ["."]) - ~~~ +Always note such changes in your CHANGELOG and README. #### `validate_numeric` -- cgit v1.2.3 From bcab71ded8507de4fd9f89b4dcf798b3d98ace59 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 6 Oct 2016 15:23:35 -0700 Subject: (MODULES-3590) Fix match_for_absence parameter Prior to this commit, due to a bug in the exists? method in the file_line provider, match_for_absence didn't work as described (or at all really). Update the exists? logic so that match_for_absence works as described. Additionally add a unit test to prevent regressions and update the documentation for the parameter to reflect the fact that it is ignored when `ensure => present`. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index d27668b..34d26a8 100644 --- a/README.markdown +++ b/README.markdown @@ -128,7 +128,7 @@ All parameters are optional, unless otherwise noted. * `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'. * `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined. * `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. A regex comparison is performed against the line value, and if it does not match, an exception is raised. Valid options: String containing a regex. Default: Undefined. -* `match_for_absence`: An optional value to determine if match should be applied when `ensure => absent`. If set to true and match is set, the line that matches match will be deleted. If set to false (the default), match is ignored when `ensure => absent` and the value of `line` is used instead. Default: false. +* `match_for_absence`: An optional value to determine if match should be applied when `ensure => absent`. If set to true and match is set, the line that matches match will be deleted. If set to false (the default), match is ignored when `ensure => absent` and the value of `line` is used instead. Ignored when `ensure => present`. Default: false. * `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined. * `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined. * `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file. -- cgit v1.2.3 From 83539371e5b1e6ff412eda48c3a725653c506ece Mon Sep 17 00:00:00 2001 From: Helen Campbell Date: Thu, 6 Oct 2016 14:22:13 +0100 Subject: Addition of several new types --- README.markdown | 48 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index d27668b..210e9f3 100644 --- a/README.markdown +++ b/README.markdown @@ -22,7 +22,7 @@ This module provides a standard library of resources for the development of Pupp * Facts * Functions * Defined resource types - * Types + * Data Types * Providers > *Note:* As of version 3.7, Puppet Enterprise no longer includes the stdlib module. If you're running Puppet Enterprise, you should install the most recent release of stdlib for compatibility with Puppet modules. @@ -73,7 +73,7 @@ The `stdlib::stages` class declares various run stages for deploying infrastruct * `stdlib::stages`: Manages a standard set of run stages for Puppet. It is managed by the stdlib class and should not be declared independently. -### Types +### Resource Types #### `file_line` @@ -134,6 +134,46 @@ All parameters are optional, unless otherwise noted. * `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file. * `replace`: Defines whether the resource will overwrite an existing line that matches the `match` parameter. If set to false and a line is found matching the `match` param, the line will not be placed in the file. Valid options: true, false, yes, no. Default: true +### Data Types + +#### `absolutepath` + +A strict absolute path type. Uses a Variant of Unixpath and Windowspath types. + +Acceptable input examples: /usr2/username/bin:/usr/local/bin:/usr/bin:. + C:\\WINDOWS\\System32 + +#### `httpsurl` + +Matches https URLs. +Acceptable input example: https://hello.com +Unacceptable input example: httds://notquiteright.org + +#### `httpurl` + +Matches both https and http URLs. + +Acceptable input example: https://hello.com + http://hello.com +Unacceptable input example: httds://notquiteright.org + +#### `unixpath` + +Matches paths on Unix type Operating Systems. + +Acceptable input example: /usr2/username/bin:/usr/local/bin:/usr/bin:. + /var/tmp +Unacceptable input example: C:/whatever + +#### `windowspath` + +Matches paths on Windows Operating systems. + +Acceptable input example: C:\\WINDOWS\\System32 + C:\\ + \\\\host\\windows +Unacceptable input example: /usr2/username/bin:/usr/local/bin:/usr/bin:. + ### Functions #### `abs` @@ -1372,7 +1412,7 @@ The following values will fail, causing compilation to abort: Validates a value against both a specified type and a deprecated validation function. Silently passes if both pass, errors if only one validation passes, and fails if both validations return false. -Accepts arguments for: +Accepts arguments for: * the type to check the value against, * the full name of the previous validation function, * the value to be checked, @@ -1430,7 +1470,7 @@ class example( validate_legacy(Numeric, 'validate_numeric', $value) ~~~ -Here, the type of `$value` is defined as `Variant[Stdlib::Compat::Numeric, Numeric]`, which allows any `Numeric` (the new type), as well as all values previously accepted by `validate_numeric` (through `Stdlib::Compat::Numeric`). +Here, the type of `$value` is defined as `Variant[Stdlib::Compat::Numeric, Numeric]`, which allows any `Numeric` (the new type), as well as all values previously accepted by `validate_numeric` (through `Stdlib::Compat::Numeric`). The call to `validate_legacy` takes care of triggering the correct log or fail message for you. It requires the new type, the previous validation function name, and all arguments to that function. -- cgit v1.2.3 From 9debb12b2d6190045a11d2277c7b730ac5732f96 Mon Sep 17 00:00:00 2001 From: Nate Potter Date: Tue, 28 Jun 2016 20:30:41 -0700 Subject: (MODULES-3407) Clarify that 'after' in file_line accepts regex. This patch updates the README to specify that the 'after' parameter in the file_line class accepts a regular expression. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index d445cc5..838a065 100644 --- a/README.markdown +++ b/README.markdown @@ -124,7 +124,7 @@ error will be raised unless the `multiple => true` parameter is set. All parameters are optional, unless otherwise noted. -* `after`: Specifies the line after which Puppet adds any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined. +* `after`: Specifies the line after which Puppet adds any new lines using a regular expression. (Existing lines are added in place.) Valid options: String containing a regex. Default: Undefined. * `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'. * `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined. * `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. A regex comparison is performed against the line value, and if it does not match, an exception is raised. Valid options: String containing a regex. Default: Undefined. -- cgit v1.2.3 From bec521e6b79dd612a73e742d1cb6371e17ade1a9 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Sat, 8 Oct 2016 18:28:22 +0100 Subject: Update deprecation() so warnings can be disabled for CI --- README.markdown | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 838a065..c90c9c3 100644 --- a/README.markdown +++ b/README.markdown @@ -344,7 +344,20 @@ Deletes all instances of the undef value from an array or hash. For example, `$h #### `deprecation` -Prints deprecation warnings and logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message text, including any positional information that is formatted by the user or caller of the method. The Puppet setting 'strict' affects this function. Set 'strict' to :error to output an error message, :off to output no message or error, or :warning (default) to output a warning. In Puppet versions lower than 4.0, you can set an environment variable to decide whether or not to log deprecation warnings (`ENV[STDLIB_LOG_DEPRECATION]`). If this environment variable is set to true, the functions log a warning. *Type*: String, String. +Prints deprecation warnings and logs a warning once for a given key: + +``` +deprecation(key, message) +``` + +* key: to keep the number of messages low, during the lifetime of a puppet process, only one message per key is logged. +* message: the text to be logged. + +The Puppet settings '[disable_warnings](https://docs.puppet.com/puppet/latest/reference/configuration.html#disablewarnings)', '[max_deprecations](https://docs.puppet.com/puppet/latest/reference/configuration.html#maxdeprecations)', and '[strict](https://docs.puppet.com/puppet/latest/reference/configuration.html#strict)' affect this function. Set 'strict' to `error` to fail immediately with the deprecation message, `off` to output emit no messages at all, or `warning` (default) to log all warnings. + +Additionally you can set the environment variable `STDLIB_LOG_DEPRECATION` to decide whether or not to log deprecation warnings: if this environment variable is set to `true`, the functions log a warning, if it is set to `false`, no warnings are logged. If no value is set at all, Puppet 4 will emit warnings, while Puppet 3 will not. Using this setting is especially useful for automated tests to avoid flooding your logs before you are ready to migrate. + +*Type*: String, String. #### `difference` -- cgit v1.2.3 From c2dd2898f2d965614d9fa0ccc5ade57df910f800 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Mon, 10 Oct 2016 10:42:05 +0100 Subject: Release prep for 4.13.0 * Changelog & Thanks * Add known issues/version compatiblity to README * Whitespace fixes * Update version and dependency information * Fix issue tracker URL --- README.markdown | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index c90c9c3..c0b3155 100644 --- a/README.markdown +++ b/README.markdown @@ -1,6 +1,6 @@ -#stdlib +# stdlib -####Table of Contents +#### Table of Contents 1. [Overview](#overview) 2. [Module Description - What the module does and why it is useful](#module-description) @@ -10,11 +10,11 @@ 5. [Limitations - OS compatibility, etc.](#limitations) 6. [Development - Guide for contributing to the module](#development) -##Overview +## Overview Adds a standard library of resources for Puppet modules. -##Module Description +## Module Description This module provides a standard library of resources for the development of Puppet modules. Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet: @@ -27,11 +27,11 @@ This module provides a standard library of resources for the development of Pupp > *Note:* As of version 3.7, Puppet Enterprise no longer includes the stdlib module. If you're running Puppet Enterprise, you should install the most recent release of stdlib for compatibility with Puppet modules. -##Setup +## Setup Installing the stdlib module adds the functions, facts, and resources of this standard library to Puppet. -##Usage +## Usage After you've installed stdlib, all of its functions, facts, and resources are available for module use or development. @@ -136,20 +136,23 @@ All parameters are optional, unless otherwise noted. ### Data Types -#### `absolutepath` +#### `Stdlib::Absolutepath` A strict absolute path type. Uses a Variant of Unixpath and Windowspath types. -Acceptable input examples: /usr2/username/bin:/usr/local/bin:/usr/bin:. +Acceptable input examples: /var/log + /usr2/username/bin:/usr/local/bin:/usr/bin:. C:\\WINDOWS\\System32 +Unacceptable input example: ../relative_path -#### `httpsurl` +#### `Stdlib::Httpsurl` Matches https URLs. + Acceptable input example: https://hello.com Unacceptable input example: httds://notquiteright.org -#### `httpurl` +#### `Stdlib::Httpurl` Matches both https and http URLs. @@ -157,7 +160,7 @@ Acceptable input example: https://hello.com http://hello.com Unacceptable input example: httds://notquiteright.org -#### `unixpath` +#### `Stdlib::Unixpath` Matches paths on Unix type Operating Systems. @@ -165,7 +168,7 @@ Acceptable input example: /usr2/username/bin:/usr/local/bin:/usr/bin:. /var/tmp Unacceptable input example: C:/whatever -#### `windowspath` +#### `Stdlib::Windowspath` Matches paths on Windows Operating systems. @@ -1439,6 +1442,8 @@ validate_legacy("Optional[String]", "validate_re", "Value to be validated", ["." This function supports updating modules from Puppet 3 style argument validation (using the stdlib `validate_*` functions) to Puppet 4 data types, without breaking functionality for those depending on Puppet 3 style validation. +> Note: This function relies on internal APIs from Puppet 4.4.0 (PE 2016.1) onwards, and doesn't work on earlier versions. + ##### For module users If you are running Puppet 4 and receiving deprecation warnings about `validate_*` functions, the `validate_legacy` function can help you find and resolve the deprecated code. @@ -1656,7 +1661,7 @@ Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x | Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide](https://docs.puppetlabs.com/forge/contributing.html). To report or research a bug with any part of this module, please go to -[http://tickets.puppetlabs.com/browse/PUP](http://tickets.puppetlabs.com/browse/PUP). +[http://tickets.puppetlabs.com/browse/MODULES](http://tickets.puppetlabs.com/browse/MODULES). ## Contributors -- cgit v1.2.3 From f947fce65e967fc95d71feb44b9e2a53c2b93a03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Mo=CC=88ding?= Date: Fri, 14 Oct 2016 16:45:13 +0200 Subject: Fix incorrect environment variable name in README The README references the environment variable `STDLIB_LOG_DEPRECATION` while the code uses `STDLIB_LOG_DEPRECATIONS` (note the trailing S). --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index c0b3155..b41039d 100644 --- a/README.markdown +++ b/README.markdown @@ -358,7 +358,7 @@ deprecation(key, message) The Puppet settings '[disable_warnings](https://docs.puppet.com/puppet/latest/reference/configuration.html#disablewarnings)', '[max_deprecations](https://docs.puppet.com/puppet/latest/reference/configuration.html#maxdeprecations)', and '[strict](https://docs.puppet.com/puppet/latest/reference/configuration.html#strict)' affect this function. Set 'strict' to `error` to fail immediately with the deprecation message, `off` to output emit no messages at all, or `warning` (default) to log all warnings. -Additionally you can set the environment variable `STDLIB_LOG_DEPRECATION` to decide whether or not to log deprecation warnings: if this environment variable is set to `true`, the functions log a warning, if it is set to `false`, no warnings are logged. If no value is set at all, Puppet 4 will emit warnings, while Puppet 3 will not. Using this setting is especially useful for automated tests to avoid flooding your logs before you are ready to migrate. +Additionally you can set the environment variable `STDLIB_LOG_DEPRECATIONS` to decide whether or not to log deprecation warnings: if this environment variable is set to `true`, the functions log a warning, if it is set to `false`, no warnings are logged. If no value is set at all, Puppet 4 will emit warnings, while Puppet 3 will not. Using this setting is especially useful for automated tests to avoid flooding your logs before you are ready to migrate. *Type*: String, String. -- cgit v1.2.3 From 4f61f3cc7f3f6051536c2ef1e88e39848773b133 Mon Sep 17 00:00:00 2001 From: jbondpdx Date: Mon, 14 Nov 2016 15:12:20 -0800 Subject: MODULES-4008: clarify deprecation language --- README.markdown | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 55 insertions(+), 7 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index cc29af9..821deb0 100644 --- a/README.markdown +++ b/README.markdown @@ -712,46 +712,68 @@ See the [`assert_type()`](https://docs.puppetlabs.com/references/latest/function #### `is_absolute_path` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the given path is absolute. *Type*: rvalue. #### `is_array` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable passed to this function is an array. *Type*: rvalue. #### `is_bool` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue. #### `is_domain_name` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the string passed to this function is a syntactically correct domain name. *Type*: rvalue. #### `is_float` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable passed to this function is a float. *Type*: rvalue. #### `is_function_available` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Accepts a string as an argument and determines whether the Puppet runtime has access to a function by that name. It returns 'true' if the function exists, 'false' if not. *Type*: rvalue. #### `is_hash` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable passed to this function is a hash. *Type*: rvalue. #### `is_integer` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable returned to this string is an integer. *Type*: rvalue. #### `is_ip_address` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue. #### `is_ipv6_address` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the string passed to this function is a valid IPv6 address. *Type*: rvalue. #### `is_ipv4_address` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the string passed to this function is a valid IPv4 address. *Type*: rvalue. #### `is_mac_address` @@ -760,10 +782,14 @@ Returns 'true' if the string passed to this function is a valid MAC address. *Ty #### `is_numeric` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable passed to this function is a number. *Type*: rvalue. #### `is_string` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Returns 'true' if the variable passed to this function is a string. *Type*: rvalue. #### `join` @@ -1228,6 +1254,8 @@ validate_absolute_path($undefined) #### `validate_array` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that all passed values are array data structures. Aborts catalog compilation if any value fails this check. The following values pass: @@ -1276,6 +1304,8 @@ validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers #### `validate_bool` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that all passed values are either true or false. Aborts catalog compilation if any value fails this check. The following values will pass: @@ -1316,6 +1346,8 @@ validate_cmd($haproxycontent, '/usr/sbin/haproxy -f % -c', 'Haproxy failed to va #### `validate_hash` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that all passed values are hash data structures. Aborts catalog compilation if any value fails this check. The following values will pass: @@ -1338,6 +1370,8 @@ Validates that all passed values are hash data structures. Aborts catalog compil #### `validate_integer` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that the first argument is an integer (or an array of integers). Aborts catalog compilation if any of the checks fail. The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. @@ -1396,6 +1430,8 @@ Validates that the first argument is an integer (or an array of integers). Abort #### `validate_ip_address` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that the argument is an IP address, regardless of it is an IPv4 or an IPv6 address. It also validates IP address with netmask. The argument must be given as a string. @@ -1444,24 +1480,28 @@ validate_legacy("Optional[String]", "validate_re", "Value to be validated", ["." This function supports updating modules from Puppet 3 style argument validation (using the stdlib `validate_*` functions) to Puppet 4 data types, without breaking functionality for those depending on Puppet 3 style validation. -> Note: This function relies on internal APIs from Puppet 4.4.0 (PE 2016.1) onwards, and doesn't work on earlier versions. +> Note: This function is compatible only with Puppet 4.4.0 (PE 2016.1) and later. ##### For module users -If you are running Puppet 4 and receiving deprecation warnings about `validate_*` functions, the `validate_legacy` function can help you find and resolve the deprecated code. +If you are running Puppet 4, the `validate_legacy` function can help you find and resolve deprecated Puppet 3 `validate_*` functions. These functions are deprecated as of stdlib version 4.13 and will be removed in a future version of stdlib. -In Puppet 3, the `validate_*` functions were the only way to easily check the types of class and defined type arguments. Some of the functions provided additional helpers like [validate_numeric](#validate_numeric), which unintentionally allowed not only numbers, but also arrays of numbers. Puppet 4 allows much better defined type checking using [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html), without such unintentional effects. The `validate_legacy` function makes these differences visible and makes it easier to move to the clearer Puppet 4 syntax. +Puppet 4 allows improved defined type checking using [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html). Data types avoid some of the problems with Puppet 3's `validate_*` functions, which could sometimes be inconsistent. For example, [validate_numeric](#validate_numeric) unintentionally allowed not only numbers, but also arrays of numbers or strings that looked like numbers. -Depending on the current state of development of the modules you use and the data you feed those modules, you'll encounter different messages: +If you run Puppet 4 and use modules with deprecated `validate_*` functions, you might encounter deprecation messages. The `validate_legacy` function makes these differences visible and makes it easier to move to the clearer Puppet 4 syntax. + +The deprecation messages you get can vary, depending on the modules and data that you use. These deprecation messages appear by default only in Puppet 4: * `Notice: Accepting previously invalid value for target type ''`: This message is informational only. You're using values that are allowed by the new type, but would have been invalid by the old validation function. * `Warning: This method is deprecated, please use the stdlib validate_legacy function`: The module has not yet upgraded to `validate_legacy`. Use the [deprecation](#deprecation) options to silence warnings for now, or submit a fix with the module's developer. See the information [for module developers](#for-module-developers) below for how to fix the issue. -* `Warning: validate_legacy() expected value, got _`: Your code passes a value that was accepted by the Puppet 3 style validation, but will not be accepted by the next version of the module. Most often, you can fix this by removing quotes from numbers or booleans. +* `Warning: validate_legacy() expected value, got _`: Your code passes a value that was accepted by the Puppet 3-style validation, but will not be accepted by the next version of the module. Most often, you can fix this by removing quotes from numbers or booleans. * `Error: Evaluation Error: Error while evaluating a Resource Statement, Evaluation Error: Error while evaluating a Function Call, validate_legacy() expected value, got `: Your code passes a value that is not acceptable to either the new or the old style validation. ##### For module developers -Many `validate_*` functions have surprising holes in their validation. For example, [validate_numeric](#validate_numeric) allows not only numbers, but also arrays of numbers or strings that look like numbers, without giving you any control over the specifics. In contrast, Puppet 4 [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html) allows you to choose between `Numeric`, `Array[Numeric]`, or `Optional[Numeric]`. The `validate_legacy` function helps you move from Puppet 3 style validation to Puppet 4 validation without breaking functionality your module's users depend on. +The `validate_legacy` function helps you move from Puppet 3 style validation to Puppet 4 validation without breaking functionality your module's users depend on. + +Moving to Puppet 4 type validation allows much better defined type checking using [data types](https://docs.puppet.com/puppet/latest/reference/lang_data.html). Many of Puppet 3's `validate_*` functions have surprising holes in their validation. For example, [validate_numeric](#validate_numeric) allows not only numbers, but also arrays of numbers or strings that look like numbers, without giving you any control over the specifics. For each parameter of your classes and defined types, choose a new Puppet 4 data type to use. In most cases, the new data type allows a different set of values than the original `validate_*` function. The situation then looks like this: @@ -1504,6 +1544,8 @@ Always note such changes in your CHANGELOG and README. #### `validate_numeric` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that the first argument is a numeric value (or an array or string of numeric values). Aborts catalog compilation if any of the checks fail. The second argument is optional and passes a maximum. (All elements of) the first argument has to be less or equal to this max. @@ -1520,6 +1562,8 @@ Validates that the first argument is a numeric value (or an array or string of n #### `validate_re` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the 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 aborts with a parse error. @@ -1554,6 +1598,8 @@ test, and the second argument should be a stringified regular expression (withou #### `validate_slength` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if the second argument is not convertable to a number. Optionally, a minimum string length can be given as the third argument. The following values pass: @@ -1576,6 +1622,8 @@ Validates that the first argument is a string (or an array of strings), and is l #### `validate_string` +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** + Validates that all passed values are string data structures. Aborts catalog compilation if any value fails this check. The following values pass: @@ -1646,7 +1694,7 @@ Takes one element from first array given and merges corresponding elements from As of Puppet Enterprise 3.7, the stdlib module is no longer included in PE. PE users should install the most recent release of stdlib for compatibility with Puppet modules. -###Version Compatibility +### Version Compatibility Versions | Puppet 2.6 | Puppet 2.7 | Puppet 3.x | Puppet 4.x | :---------------|:-----:|:---:|:---:|:----: -- cgit v1.2.3 From 88ed19d149ccfe5e94daf714c2ec98205bb35932 Mon Sep 17 00:00:00 2001 From: Ian Norton Date: Mon, 21 Nov 2016 09:17:01 +0000 Subject: Fixing broken link to #validate_legacy docs --- README.markdown | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 821deb0..3e937b1 100644 --- a/README.markdown +++ b/README.markdown @@ -712,67 +712,67 @@ See the [`assert_type()`](https://docs.puppetlabs.com/references/latest/function #### `is_absolute_path` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the given path is absolute. *Type*: rvalue. #### `is_array` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable passed to this function is an array. *Type*: rvalue. #### `is_bool` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue. #### `is_domain_name` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the string passed to this function is a syntactically correct domain name. *Type*: rvalue. #### `is_float` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable passed to this function is a float. *Type*: rvalue. #### `is_function_available` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Accepts a string as an argument and determines whether the Puppet runtime has access to a function by that name. It returns 'true' if the function exists, 'false' if not. *Type*: rvalue. #### `is_hash` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable passed to this function is a hash. *Type*: rvalue. #### `is_integer` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable returned to this string is an integer. *Type*: rvalue. #### `is_ip_address` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue. #### `is_ipv6_address` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the string passed to this function is a valid IPv6 address. *Type*: rvalue. #### `is_ipv4_address` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the string passed to this function is a valid IPv4 address. *Type*: rvalue. @@ -782,13 +782,13 @@ Returns 'true' if the string passed to this function is a valid MAC address. *Ty #### `is_numeric` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable passed to this function is a number. *Type*: rvalue. #### `is_string` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Returns 'true' if the variable passed to this function is a string. *Type*: rvalue. @@ -1254,7 +1254,7 @@ validate_absolute_path($undefined) #### `validate_array` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that all passed values are array data structures. Aborts catalog compilation if any value fails this check. @@ -1304,7 +1304,7 @@ validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers #### `validate_bool` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that all passed values are either true or false. Aborts catalog compilation if any value fails this check. @@ -1346,7 +1346,7 @@ validate_cmd($haproxycontent, '/usr/sbin/haproxy -f % -c', 'Haproxy failed to va #### `validate_hash` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that all passed values are hash data structures. Aborts catalog compilation if any value fails this check. @@ -1370,7 +1370,7 @@ Validates that all passed values are hash data structures. Aborts catalog compil #### `validate_integer` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that the first argument is an integer (or an array of integers). Aborts catalog compilation if any of the checks fail. @@ -1430,7 +1430,7 @@ Validates that the first argument is an integer (or an array of integers). Abort #### `validate_ip_address` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that the argument is an IP address, regardless of it is an IPv4 or an IPv6 address. It also validates IP address with netmask. The argument must be given as a string. @@ -1544,7 +1544,7 @@ Always note such changes in your CHANGELOG and README. #### `validate_numeric` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that the first argument is a numeric value (or an array or string of numeric values). Aborts catalog compilation if any of the checks fail. @@ -1562,7 +1562,7 @@ Validates that the first argument is a numeric value (or an array or string of n #### `validate_re` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Performs simple validation of a string against one or more regular expressions. The first argument of this function should be the 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 aborts with a parse error. @@ -1598,7 +1598,7 @@ test, and the second argument should be a stringified regular expression (withou #### `validate_slength` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that the first argument is a string (or an array of strings), and is less than or equal to the length of the second argument. It fails if the first argument is not a string or array of strings, or if the second argument is not convertable to a number. Optionally, a minimum string length can be given as the third argument. @@ -1622,7 +1622,7 @@ Validates that the first argument is a string (or an array of strings), and is l #### `validate_string` -**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validatelegacy).** +**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).** Validates that all passed values are string data structures. Aborts catalog compilation if any value fails this check. -- cgit v1.2.3 From d3bbd3cbf89cb23bce4e55c3828e17c05c4cfd70 Mon Sep 17 00:00:00 2001 From: Nick Walker Date: Thu, 1 Dec 2016 05:54:08 -0800 Subject: Indicate that the type function is preferred (#695) Prior to this commit, users coming to the type_of function would not realize that the type function in puppet does the same thing and is preferred over type_of. After this commit, we have a comment indicating the above. --- README.markdown | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 3e937b1..a6b7bda 100644 --- a/README.markdown +++ b/README.markdown @@ -1190,6 +1190,8 @@ Returns a string description of the type when passed a value. Type can be a stri #### `type_of` +This function is provided for backwards compatibility but is generally not preferred over the built-in [type() function](https://docs.puppet.com/puppet/latest/reference/function.html#type) provided by Puppet. + Returns the literal type when passed a value. Requires the new parser. Useful for comparison of types with `<=` such as in `if type_of($some_value) <= Array[String] { ... }` (which is equivalent to `if $some_value =~ Array[String] { ... }`) *Type*: rvalue. #### `union` -- cgit v1.2.3 From 1cd0209aec84b0135adbe6b5fc2769f0053c26f3 Mon Sep 17 00:00:00 2001 From: Hunter Haugen Date: Wed, 17 Aug 2016 10:27:54 -0700 Subject: Add pry() function from hunner-pry --- README.markdown | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index a6b7bda..3039a2a 100644 --- a/README.markdown +++ b/README.markdown @@ -935,6 +935,20 @@ For example: *Type*: rvalue. +#### `pry` + +This function invokes a pry debugging session in the current scope object. This is useful for debugging manifest code at specific points during a compilation. Should only be used when running `puppet apply` or running a puppet master in the foreground. This requires the `pry` gem to be installed in puppet's rubygems. + +*Examples:* +```puppet +pry() +``` +Once in a pry session, some interesting commands: + +* Run `catalog` to see the contents currently compiling catalog +* Run `cd catalog` and `ls` to see catalog methods and instance variables +* Run `@resource_table` to see the current catalog resource table + #### `assert_private` Sets the current class or definition as private. Calling the class or definition from outside the current module will fail. -- cgit v1.2.3 From 0e684d82ea1ad0f5c85b8aa0147ffec39aac8ddd Mon Sep 17 00:00:00 2001 From: Peter Souter Date: Wed, 7 Dec 2016 19:25:03 +0000 Subject: (MODULES-4188) Add FQDN UUID generation function * Generates UUID based on a given FQDN string and the DNS namespace (6ba7b810-9dad-11d1-80b4-00c04fd430c8) --- README.markdown | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index a6b7bda..627e73a 100644 --- a/README.markdown +++ b/README.markdown @@ -578,6 +578,15 @@ fqdn_rotate([1, 2, 3], 'custom seed') *Type*: rvalue. +#### `fqdn_uuid` + +Returns a rfc4122 valid version 5 UUID based on an FQDN string under the DNS namespace + + * fqdn_uuid('puppetlabs.com') returns '9c70320f-6815-5fc5-ab0f-debe68bf764c' + * fqdn_uuid('google.com') returns '64ee70a4-8cc1-5d25-abf2-dea6c79a09c8' + +*Type*: rvalue. + #### `get_module_path` Returns the absolute path of the specified module for the current environment. -- cgit v1.2.3 From 3451bd9fdecceab9bce99570a69369737589b9e8 Mon Sep 17 00:00:00 2001 From: Michael Watters Date: Mon, 19 Dec 2016 12:23:36 -0500 Subject: Change - Update str2bool documentation Updated documentation for this function to be consistent with the function itself. --- README.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 5aea25f..a4c30b5 100644 --- a/README.markdown +++ b/README.markdown @@ -1079,7 +1079,7 @@ Returns a new string where runs of the same character that occur in this set are #### `str2bool` -Converts certain strings to a boolean. This attempts to convert strings that contain the values '1', 't', 'y', or 'yes' to true. Strings that contain values '0', 'f', 'n', or 'no', or that are an empty string or undefined are converted to false. Any other value causes an error. *Type*: rvalue. +Converts certain strings to a boolean. This attempts to convert strings that contain the values '1', 'true', 't', 'y', or 'yes' to true. Strings that contain values '0', 'false', 'f', 'n', or 'no', or that are an empty string or undefined are converted to false. Any other value causes an error. These checks are case insensitive. *Type*: rvalue. #### `str2saltedsha512` -- cgit v1.2.3