From a1510a1e71cafd7c6d20d407e77b1e1fc165475d Mon Sep 17 00:00:00 2001 From: Raphaël Pinson Date: Mon, 4 Mar 2013 23:37:57 +0100 Subject: Add missing documentation for validate_augeas and validate_cmd to README.markdown --- README.markdown | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index c58d31f..f1ac6b3 100644 --- a/README.markdown +++ b/README.markdown @@ -777,6 +777,38 @@ The following values will fail, causing compilation to abort: +- *Type*: statement + +validate_augeas +-------------- +Perform validation of a string using an Augeas lens +The first argument of this function should be a string to +test, and the second argument should be the name of the Augeas lens to use. +If Augeas fails to parse the string with the lens, the compilation will +abort with a parse error. + +A third argument can be specified, listing 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, if you want to make sure your passwd content never contains +a user `foo`, you could write: + + validate_augeas($passwdcontent, 'Passwd.lns', ['$file/foo']) + +Or if you wanted to ensure that no users used the '/bin/barsh' shell, +you could use: + + validate_augeas($passwdcontent, 'Passwd.lns', ['$file/*[shell="/bin/barsh"]'] + +If a fourth argument is specified, this will be the error message raised and +seen by the user. + +A helpful error message can be returned like this: + + validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas') + + - *Type*: statement validate_bool @@ -799,6 +831,29 @@ The following values will fail, causing compilation to abort: +- *Type*: statement + + +validate_cmd +------------- +Perform validation of a string with an external command. +The first argument of this function should be a string to +test, and the second argument should be a path to a test command +taking a file as last argument. 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. + +A helpful error message can be returned like this: + +Example: + + validate_cmd($sudoerscontent, '/usr/sbin/visudo -c -f', 'Visudo failed to validate sudoers content') + + + - *Type*: statement validate_hash -- cgit v1.2.3 From 05273419e1c8b34115ede15b1d8a8739f6a0db00 Mon Sep 17 00:00:00 2001 From: Kristof Willaert Date: Tue, 19 Mar 2013 10:00:57 +0100 Subject: Add floor function implementation and unit tests --- README.markdown | 14 +++++++++ lib/puppet/parser/functions/floor.rb | 20 +++++++++++++ spec/unit/puppet/parser/functions/floor_spec.rb | 39 +++++++++++++++++++++++++ 3 files changed, 73 insertions(+) create mode 100644 lib/puppet/parser/functions/floor.rb create mode 100644 spec/unit/puppet/parser/functions/floor_spec.rb (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index f1ac6b3..121b784 100644 --- a/README.markdown +++ b/README.markdown @@ -196,6 +196,20 @@ as a result. Would return: ['a','b','c'] +- *Type*: rvalue + +floor +----- +Returns the largest integer less or equal to the argument. +Takes a single numeric value as an argument. + +*Examples:* + + floor('3.8') + +Would return: '3' + + - *Type*: rvalue fqdn_rotate diff --git a/lib/puppet/parser/functions/floor.rb b/lib/puppet/parser/functions/floor.rb new file mode 100644 index 0000000..a401923 --- /dev/null +++ b/lib/puppet/parser/functions/floor.rb @@ -0,0 +1,20 @@ +module Puppet::Parser::Functions + newfunction(:floor, :type => :rvalue, :doc => <<-EOS + Returns the largest integer less or equal to the argument. + Takes a single numeric value as an argument. + EOS + ) do |arguments| + + raise(Puppet::ParseError, "floor(): Wrong number of arguments " + + "given (#{arguments.size} for 1)") if arguments.size != 1 + + arg = arguments[0] + + raise(Puppet::ParseError, "floor(): Wrong argument type " + + "given (#{arg.class} for Numeric)") if arg.is_a?(Numeric) == false + + arg.floor + end +end + +# vim: set ts=2 sw=2 et : diff --git a/spec/unit/puppet/parser/functions/floor_spec.rb b/spec/unit/puppet/parser/functions/floor_spec.rb new file mode 100644 index 0000000..dbc8c77 --- /dev/null +++ b/spec/unit/puppet/parser/functions/floor_spec.rb @@ -0,0 +1,39 @@ +#! /usr/bin/env ruby -S rspec + +require 'spec_helper' + +describe "the floor function" do + let(:scope) { PuppetlabsSpec::PuppetInternals.scope } + + it "should exist" do + Puppet::Parser::Functions.function("floor").should == "function_floor" + end + + it "should raise a ParseError if there is less than 1 argument" do + lambda { scope.function_floor([]) }.should( raise_error(Puppet::ParseError, /Wrong number of arguments/)) + end + + it "should should raise a ParseError if input isn't numeric (eg. String)" do + lambda { scope.function_floor(["foo"]) }.should( raise_error(Puppet::ParseError, /Wrong argument type/)) + end + + it "should should raise a ParseError if input isn't numeric (eg. Boolean)" do + lambda { scope.function_floor([true]) }.should( raise_error(Puppet::ParseError, /Wrong argument type/)) + end + + it "should return an integer when a numeric type is passed" do + result = scope.function_floor([12.4]) + result.is_a?(Integer).should(eq(true)) + end + + it "should return the input when an integer is passed" do + result = scope.function_floor([7]) + result.should(eq(7)) + end + + it "should return the largest integer less than or equal to the input" do + result = scope.function_floor([3.8]) + result.should(eq(3)) + end +end + -- cgit v1.2.3 From 88a93ac6cdf38045e1cf29325a70e5e4143016b3 Mon Sep 17 00:00:00 2001 From: Richard Soderberg Date: Tue, 26 Mar 2013 15:45:40 -0700 Subject: add suffix function to accompany the prefix function --- README.markdown | 13 +++++++ lib/puppet/parser/functions/suffix.rb | 45 ++++++++++++++++++++++++ spec/unit/puppet/parser/functions/suffix_spec.rb | 19 ++++++++++ 3 files changed, 77 insertions(+) create mode 100644 lib/puppet/parser/functions/suffix.rb create mode 100644 spec/unit/puppet/parser/functions/suffix_spec.rb (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 121b784..2f93db4 100644 --- a/README.markdown +++ b/README.markdown @@ -659,6 +659,19 @@ every string inside an array. Would result in: "aaa" +- *Type*: rvalue + +suffix +------ +This function applies a suffix to all elements in an array. + +*Examples:* + + suffix(['a','b','c'], 'p') + +Will return: ['ap','bp','cp'] + + - *Type*: rvalue swapcase diff --git a/lib/puppet/parser/functions/suffix.rb b/lib/puppet/parser/functions/suffix.rb new file mode 100644 index 0000000..5018280 --- /dev/null +++ b/lib/puppet/parser/functions/suffix.rb @@ -0,0 +1,45 @@ +# +# suffix.rb +# + +module Puppet::Parser::Functions + newfunction(:suffix, :type => :rvalue, :doc => <<-EOS +This function applies a suffix to all elements in an array. + +*Examples:* + + suffix(['a','b','c'], 'p') + +Will return: ['ap','bp','cp'] + EOS + ) do |arguments| + + # Technically we support two arguments but only first is mandatory ... + raise(Puppet::ParseError, "suffix(): Wrong number of arguments " + + "given (#{arguments.size} for 1)") if arguments.size < 1 + + array = arguments[0] + + unless array.is_a?(Array) + raise(Puppet::ParseError, 'suffix(): Requires array to work with') + end + + suffix = arguments[1] if arguments[1] + + if suffix + unless suffix.is_a?(String) + raise(Puppet::ParseError, 'suffix(): Requires string to work with') + end + end + + # Turn everything into string same as join would do ... + result = array.collect do |i| + i = i.to_s + suffix ? i + suffix : i + end + + return result + end +end + +# vim: set ts=2 sw=2 et : diff --git a/spec/unit/puppet/parser/functions/suffix_spec.rb b/spec/unit/puppet/parser/functions/suffix_spec.rb new file mode 100644 index 0000000..c28f719 --- /dev/null +++ b/spec/unit/puppet/parser/functions/suffix_spec.rb @@ -0,0 +1,19 @@ +#! /usr/bin/env ruby -S rspec +require 'spec_helper' + +describe "the suffix function" do + let(:scope) { PuppetlabsSpec::PuppetInternals.scope } + + it "should exist" do + Puppet::Parser::Functions.function("suffix").should == "function_suffix" + end + + it "should raise a ParseError if there is less than 1 arguments" do + lambda { scope.function_suffix([]) }.should( raise_error(Puppet::ParseError)) + end + + it "should return a suffixed array" do + result = scope.function_suffix([['a','b','c'], 'p']) + result.should(eq(['ap','bp','cp'])) + end +end -- cgit v1.2.3 From a83318d3ee41683118a55a2b15769c97efbcf6d9 Mon Sep 17 00:00:00 2001 From: Richard Soderberg Date: Tue, 26 Mar 2013 15:49:09 -0700 Subject: prefix: fix doc typo Examles -> Examples --- README.markdown | 2 +- lib/puppet/parser/functions/prefix.rb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 2f93db4..336d0ab 100644 --- a/README.markdown +++ b/README.markdown @@ -479,7 +479,7 @@ prefix ------ This function applies a prefix to all elements in an array. -*Examles:* +*Examples:* prefix(['a','b','c'], 'p') diff --git a/lib/puppet/parser/functions/prefix.rb b/lib/puppet/parser/functions/prefix.rb index 4593976..243cf18 100644 --- a/lib/puppet/parser/functions/prefix.rb +++ b/lib/puppet/parser/functions/prefix.rb @@ -6,7 +6,7 @@ module Puppet::Parser::Functions newfunction(:prefix, :type => :rvalue, :doc => <<-EOS This function applies a prefix to all elements in an array. -*Examles:* +*Examples:* prefix(['a','b','c'], 'p') -- cgit v1.2.3 From 25b670e6f6c52e84e28bbe4810f949b467a9b2d8 Mon Sep 17 00:00:00 2001 From: Jeff McCune Date: Thu, 11 Apr 2013 13:44:05 -0700 Subject: Update Modulefile, README, CHANGELOG for stdlib-4.0.0 --- CHANGELOG | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- Modulefile | 4 +-- README.markdown | 12 +++++++-- 3 files changed, 87 insertions(+), 6 deletions(-) (limited to 'README.markdown') diff --git a/CHANGELOG b/CHANGELOG index 313b83c..b704f52 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,78 @@ -2012-11-28 - Peter Meier - 3.2.0 - * Add reject() function (a79b2cd) +2013-04-11 - Jeff McCune - 4.0.0 + * stdlib 4.0 drops support with Puppet 2.7 + * stdlib 4.0 preserves support with Puppet 3 + +2013-04-11 - Jeff McCune - 4.0.0 + * Add ability to use puppet from git via bundler (9c5805f) + +2013-04-10 - Jeff McCune - 4.0.0 + * (maint) Make stdlib usable as a Ruby GEM (e81a45e) + +2013-04-10 - Erik Dalén - 4.0.0 + * Add a count function (f28550e) + +2013-03-31 - Amos Shapira - 4.0.0 + * (#19998) Implement any2array (7a2fb80) + +2013-03-29 - Steve Huff - 4.0.0 + * (19864) num2bool match fix (8d217f0) + +2013-03-20 - Erik Dalén - 4.0.0 + * Allow comparisons of Numeric and number as String (ff5dd5d) + +2013-03-26 - Richard Soderberg - 4.0.0 + * add suffix function to accompany the prefix function (88a93ac) + +2013-03-19 - Kristof Willaert - 4.0.0 + * Add floor function implementation and unit tests (0527341) + +2012-04-03 - Eric Shamow - 4.0.0 + * (#13610) Add is_function_available to stdlib (961dcab) + +2012-12-17 - Justin Lambert - 4.0.0 + * str2bool should return a boolean if called with a boolean (5d5a4d4) + +2012-10-23 - Uwe Stuehler - 4.0.0 + * Fix number of arguments check in flatten() (e80207b) + +2013-03-11 - Jeff McCune - 4.0.0 + * Add contributing document (96e19d0) + +2013-03-04 - Raphaël Pinson - 4.0.0 + * Add missing documentation for validate_augeas and validate_cmd to README.markdown (a1510a1) + +2013-02-14 - Joshua Hoblitt - 4.0.0 + * (#19272) Add has_element() function (95cf3fe) + +2013-02-07 - Raphaël Pinson - 4.0.0 + * validate_cmd(): Use Puppet::Util::Execution.execute when available (69248df) + +2012-12-06 - Raphaël Pinson - 4.0.0 + * Add validate_augeas function (3a97c23) + +2012-12-06 - Raphaël Pinson - 4.0.0 + * Add validate_cmd function (6902cc5) + +2013-01-14 - David Schmitt - 4.0.0 + * Add geppetto project definition (b3fc0a3) + +2013-01-02 - Jaka Hudoklin - 4.0.0 + * Add getparam function to get defined resource parameters (20e0e07) + +2013-01-05 - Jeff McCune - 4.0.0 + * (maint) Add Travis CI Support (d082046) + +2012-12-04 - Jeff McCune - 4.0.0 + * Clarify that stdlib 3 supports Puppet 3 (3a6085f) + +2012-11-30 - Erik Dalén - 4.0.0 + * maint: style guideline fixes (7742e5f) + +2012-11-09 - James Fryman - 4.0.0 + * puppet-lint cleanup (88acc52) + +2012-11-06 - Joe Julian - 4.0.0 + * Add function, uriescape, to URI.escape strings. Redmine #17459 (fd52b8d) 2012-09-18 - Chad Metcalf - 3.2.0 * Add an ensure_packages function. (8a8c09e) diff --git a/Modulefile b/Modulefile index 34564fa..72a0b1b 100644 --- a/Modulefile +++ b/Modulefile @@ -1,6 +1,6 @@ name 'puppetlabs-stdlib' -version '3.2.0' -source 'git://github.com/puppetlabs/puppetlabs-stdlib' +version '4.0.0' +source 'git://github.com/puppetlabs/puppetlabs-stdlib.git' author 'puppetlabs' license 'Apache 2.0' summary 'Puppet Module Standard Library' diff --git a/README.markdown b/README.markdown index 336d0ab..9a1cdc0 100644 --- a/README.markdown +++ b/README.markdown @@ -28,9 +28,11 @@ older versions of Puppet Enterprise that Puppet Labs still supports will have bugfix maintenance branches periodically "merged up" into master. The current list of integration branches are: - * v2.1.x (v2.1.1 released in PE 1.2, 1.2.1, 1.2.3, 1.2.4) + * v2.1.x (v2.1.1 released in PE 1) * v2.2.x (Never released as part of PE, only to the Forge) - * v2.3.x (Released in PE 2.5.x) + * v2.3.x (Released in PE 2) + * v3.0.x (Never released as part of PE, only to the Forge) + * v4.0.x (Drops support for Puppet 2.7) * master (mainline development branch) The first Puppet Enterprise version including the stdlib module is Puppet @@ -50,6 +52,12 @@ All stdlib releases in the 2.0 major version support Puppet 2.6 and Puppet 2.7. The 3.0 major release of stdlib drops support for Puppet 2.6. Stdlib 3.x supports Puppet 2 and Puppet 3. +## stdlib 4.x ## + +The 4.0 major release of stdlib drops support for Puppet 2.7. Stdlib 4.x +supports Puppet 3. Notably, ruby 1.8.5 is no longer supported though ruby +1.8.7, 1.9.3, and 2.0.0 are fully supported. + # Functions # abs -- cgit v1.2.3 From ddfafc4a856d32185ef2318cf58341852bf58b29 Mon Sep 17 00:00:00 2001 From: Jeff McCune Date: Thu, 11 Apr 2013 14:04:31 -0700 Subject: Update function documentation for 4.0.0 Without this patch the function documentation is out of sync with the functions contained in the standard library. This commit updates the functions. I generated the list using this sequence: cd ~/src/puppet git checkout 3.1.1 bundle exec puppet doc -r function > /tmp/puppet_functions.txt cd ~/src/stdlib bundle exec puppet doc -r function > /tmp/stdlib_functions.txt diff -U2 puppet_functions.txt stdlib_functions.txt | grep '^+' | perl -ple 's/^\+//' > functions.txt I then replaced the README function documentation with the contents of functions.txt which contains only the functions contained in stdlib. --- README.markdown | 326 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 271 insertions(+), 55 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 9a1cdc0..15a5516 100644 --- a/README.markdown +++ b/README.markdown @@ -62,8 +62,17 @@ supports Puppet 3. Notably, ruby 1.8.5 is no longer supported though ruby abs --- -Returns the absolute value of a number, for example -34.56 becomes 34.56. Takes -a single integer and float value as an argument. +Returns the absolute value of a number, for example -34.56 becomes +34.56. Takes a single integer and float value as an argument. + + +- *Type*: rvalue + +any2array +--------- +This converts any object to an array containing that object. Empty argument +lists are converted to an empty array. Arrays are left untouched. Hashes are +converted to arrays of alternating keys and values. - *Type*: rvalue @@ -88,9 +97,9 @@ Requires either a single string or an array as an input. chomp ----- -Removes the record separator from the end of a string or an array of strings, -for example `hello\n` becomes `hello`. Requires a single string or array as an -input. +Removes the record separator from the end of a string or an array of +strings, for example `hello\n` becomes `hello`. +Requires a single string or array as an input. - *Type*: rvalue @@ -107,8 +116,25 @@ Requires a string or array of strings as input. - *Type*: rvalue concat +------ +Appends the contents of array 2 onto array 1. + +*Example:* + + concat(['1','2','3'],['4','5','6']) + +Would result in: + + ['1','2','3','4','5','6'] + + +- *Type*: rvalue + +count ----- -Appends the contents of the second array onto the first array. +Takes an array as first argument and an optional second argument. +Count the number of elements in array that matches second argument. +If called with only an array it counts the number of elements that are not nil/undef. - *Type*: rvalue @@ -133,13 +159,19 @@ to the catalog, and false otherwise. delete ------ -Deletes a selected element from an array. +Deletes all instances of a given element from an array, substring from a +string, or key from a hash. *Examples:* - delete(['a','b','c'], 'b') + delete(['a','b','c','b'], 'b') + Would return: ['a','c'] -Would return: ['a','c'] + delete({'a'=>1,'b'=>2,'c'=>3}, 'b') + Would return: {'a'=>1,'c'=>3} + + delete('abracadabra', 'bra') + Would return: 'acada' - *Type*: rvalue @@ -171,6 +203,13 @@ Returns true if the variable is empty. - *Type*: rvalue +ensure_packages +--------------- +Takes a list of packages and only installs them if they don't already exist. + + +- *Type*: statement + ensure_resource --------------- Takes a resource type, title, and a list of attributes that describe a @@ -211,12 +250,6 @@ floor Returns the largest integer less or equal to the argument. Takes a single numeric value as an argument. -*Examples:* - - floor('3.8') - -Would return: '3' - - *Type*: rvalue @@ -240,11 +273,10 @@ Example: getparam -------- +Takes a resource reference and name of the parameter and +returns value of resource's parameter. -Takes a resource reference and name of the parameter and returns -value of resource's parameter. - -For example: +*Examples:* define example_resource($param) { } @@ -255,6 +287,9 @@ For example: getparam(Example_resource["example_resource_instance"], "param") +Would return: param_value + + - *Type*: rvalue getvar @@ -289,6 +324,44 @@ Would return: ['aaa','aaaddd'] +- *Type*: rvalue + +has_interface_with +------------------ +Returns boolean based on kind and value: +* macaddress +* netmask +* ipaddress +* network + +has_interface_with("macaddress", "x:x:x:x:x:x") +has_interface_with("ipaddress", "127.0.0.1") => true +etc. + +If no "kind" is given, then the presence of the interface is checked: +has_interface_with("lo") => true + + +- *Type*: rvalue + +has_ip_address +-------------- +Returns true if the client has the requested IP address on some interface. + +This function iterates through the 'interfaces' fact and checks the +'ipaddress_IFACE' facts, performing a simple string comparison. + + +- *Type*: rvalue + +has_ip_network +-------------- +Returns true if the client has an IP address within the requested network. + +This function iterates through the 'interfaces' fact and checks the +'network_IFACE' facts, performing a simple string comparision. + + - *Type*: rvalue has_key @@ -325,57 +398,39 @@ Would return: {'a'=>1,'b'=>2,'c'=>3} is_array -------- Returns true if the variable passed to this function is an array. - - - *Type*: rvalue - is_domain_name -------------- Returns true if the string passed to this function is a syntactically correct domain name. - - - *Type*: rvalue - is_float --------- Returns true if the variable passed to this function is a float. - - - *Type*: rvalue - +is_function_available +--------------------- +This function accepts a string as an argument, determines whether the +Puppet runtime has access to a function by that name. It returns a +true if the function exists, false if not. +- *Type*: rvalue is_hash ------- Returns true if the variable passed to this function is a hash. - - -- *Type*: rvalue - is_integer ---------- Returns true if the variable returned to this string is an integer. - - - *Type*: rvalue - is_ip_address ------------- Returns true if the string passed to this function is a valid IP address. - - - *Type*: rvalue - is_mac_address -------------- Returns true if the string passed to this function is a valid mac address. - - - *Type*: rvalue - is_numeric ---------- Returns true if the variable passed to this function is a number. - - *Type*: rvalue is_string @@ -396,6 +451,21 @@ This function joins an array into a string using a seperator. Would result in: "a,b,c" +- *Type*: rvalue + +join_keys_to_values +------------------- +This function joins each key of a hash to that key's corresponding value with a +separator. Keys and values are cast to strings. The return value is an array in +which each element is one joined key/value pair. + +*Examples:* + + join_keys_to_values({'a'=>1,'b'=>2}, " is ") + +Would result in: ["a is 1","b is 2"] + + - *Type*: rvalue keys @@ -422,6 +492,20 @@ lstrip Strips leading spaces to the left of a string. +- *Type*: rvalue + +max +--- +Returns the highest value of all arguments. +Requires at least one argument. + + +- *Type*: rvalue + +md5 +--- +Returns a MD5 hash value from a provided string. + - *Type*: rvalue member @@ -459,10 +543,25 @@ When there is a duplicate key, the key in the rightmost hash will "win." - *Type*: rvalue +min +--- +Returns the lowest value of all arguments. +Requires at least one argument. + + +- *Type*: rvalue + +notice +------ +Log a message on the server at level notice. + +- *Type*: statement + num2bool -------- -This function converts a number into a true boolean. Zero becomes false. Numbers -higher then 0 become true. +This function converts a number or a string representation of a number into a +true boolean. Zero or anything non-numeric becomes false. Numbers higher then 0 +become true. - *Type*: rvalue @@ -481,6 +580,25 @@ This function accepts YAML as a string and converts it into the correct Puppet structure. +- *Type*: rvalue + +pick +---- +This function is similar to a coalesce function in SQL in that it will return +the first value in a list of values that is not undefined or an empty string +(two things in Puppet that will return a boolean false value). Typically, +this function is used to check for a value in the Puppet Dashboard/Enterprise +Console, and failover to a default value like the following: + + $real_jenkins_version = pick($::jenkins_version, '1.449') + +The value of $real_jenkins_version will first look for a top-scope variable +called 'jenkins_version' (note that parameters set in the Puppet Dashboard/ +Enterprise Console are brought into Puppet as top-scope variables), and, +failing that, will use a default value of 1.449. + + + - *Type*: rvalue prefix @@ -523,6 +641,94 @@ Will return: ["host01", "host02", ..., "host09", "host10"] - *Type*: rvalue +realize +------- +Make a virtual object real. This is useful +when you want to know the name of the virtual object and don't want to +bother with a full collection. It is slightly faster than a collection, +and, of course, is a bit shorter. You must pass the object using a +reference; e.g.: `realize User[luke]`. + +- *Type*: statement + +regsubst +-------- +Perform regexp replacement on a string or array of strings. + +* *Parameters* (in order): + * _target_ The string or array of strings to operate on. If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array. + * _regexp_ The regular expression matching the target string. If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself. + * _replacement_ Replacement string. Can contain backreferences to what was matched using \0 (whole match), \1 (first set of parentheses), and so on. + * _flags_ Optional. String of single letter flags for how the regexp is interpreted: + - *E* Extended regexps + - *I* Ignore case in regexps + - *M* Multiline regexps + - *G* Global replacement; all occurrences of the regexp in each target string will be replaced. Without this, only the first occurrence will be replaced. + * _encoding_ Optional. How to handle multibyte characters. A single-character string with the following values: + - *N* None + - *E* EUC + - *S* SJIS + - *U* UTF-8 + +* *Examples* + +Get the third octet from the node's IP address: + + $i3 = regsubst($ipaddress,'^(\d+)\.(\d+)\.(\d+)\.(\d+)$','\3') + +Put angle brackets around each octet in the node's IP address: + + $x = regsubst($ipaddress, '([0-9]+)', '<\1>', 'G') + + +- *Type*: rvalue + +reject +------ +This function searches through an array and rejects all elements that match +the provided regular expression. + +*Examples:* + + reject(['aaa','bbb','ccc','aaaddd'], 'aaa') + +Would return: + + ['bbb','ccc'] + + +- *Type*: rvalue + +require +------- +Evaluate one or more classes, adding the required class as a dependency. + +The relationship metaparameters work well for specifying relationships +between individual resources, but they can be clumsy for specifying +relationships between classes. This function is a superset of the +'include' function, adding a class relationship so that the requiring +class depends on the required class. + +Warning: using require in place of include can lead to unwanted dependency cycles. + +For instance the following manifest, with 'require' instead of 'include' would produce a nasty dependence cycle, because notify imposes a before between File[/foo] and Service[foo]: + + class myservice { + service { foo: ensure => running } + } + + class otherstuff { + include myservice + file { '/foo': notify => Service[foo] } + } + +Note that this function only works with clients 0.25 and later, and it will +fail if used with earlier clients. + + + +- *Type*: statement + reverse ------- Reverses the order of a string or array. @@ -537,6 +743,7 @@ Strips leading spaces to the right of the string. - *Type*: rvalue +search shuffle ------- Randomizes the order of a string or array elements. @@ -560,8 +767,7 @@ Sorts strings and arrays lexically. squeeze ------- -Returns a new string where runs of the same character that occur in this set -are replaced by a single character. +Returns a new string where runs of the same character that occur in this set are replaced by a single character. - *Type*: rvalue @@ -577,10 +783,10 @@ like: 0, f, n, false, no to 'false'. str2saltedsha512 ---------------- -This converts a string to a salted-SHA512 password hash (which is used for OS X -versions >= 10.7). Given any simple string, you will get a hex version of a -salted-SHA512 password hash that can be inserted into your Puppet manifests as -a valid password attribute. +This converts a string to a salted-SHA512 password hash (which is used for +OS X versions >= 10.7). Given any simple string, you will get a hex version +of a salted-SHA512 password hash that can be inserted into your Puppet +manifests as a valid password attribute. - *Type*: rvalue @@ -763,7 +969,15 @@ Converts a string or an array of strings to uppercase. Will return: - ABCD + ASDF + + +- *Type*: rvalue + +uriescape +--------- +Urlencodes a string or array of strings. +Requires either a single string or an array as an input. - *Type*: rvalue @@ -815,7 +1029,7 @@ The following values will fail, causing compilation to abort: - *Type*: statement validate_augeas --------------- +--------------- Perform validation of a string using an Augeas lens The first argument of this function should be a string to test, and the second argument should be the name of the Augeas lens to use. @@ -844,6 +1058,7 @@ A helpful error message can be returned like this: validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas') + - *Type*: statement validate_bool @@ -868,9 +1083,8 @@ The following values will fail, causing compilation to abort: - *Type*: statement - validate_cmd -------------- +------------ Perform validation of a string with an external command. The first argument of this function should be a string to test, and the second argument should be a path to a test command @@ -1045,3 +1259,5 @@ Would result in: - *Type*: rvalue + +*This page autogenerated on 2013-04-11 13:54:25 -0700* -- cgit v1.2.3 From ab3e30c0251d28745bcf3820e06fd2ce948c08aa Mon Sep 17 00:00:00 2001 From: Jeff McCune Date: Thu, 11 Apr 2013 14:29:56 -0700 Subject: Fix README function documentation Without this patch some core puppet functions leaked into the documentation for the functions contained in stdlib. This patch removes them and cleans up some of the formatting. --- README.markdown | 132 +++++++++----------------------------------------------- 1 file changed, 21 insertions(+), 111 deletions(-) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index 15a5516..fb6e585 100644 --- a/README.markdown +++ b/README.markdown @@ -398,35 +398,53 @@ Would return: {'a'=>1,'b'=>2,'c'=>3} is_array -------- Returns true if the variable passed to this function is an array. + - *Type*: rvalue + is_domain_name -------------- Returns true if the string passed to this function is a syntactically correct domain name. + - *Type*: rvalue + is_float +-------- Returns true if the variable passed to this function is a float. + - *Type*: rvalue + is_function_available --------------------- This function accepts a string as an argument, determines whether the Puppet runtime has access to a function by that name. It returns a true if the function exists, false if not. + - *Type*: rvalue + is_hash ------- Returns true if the variable passed to this function is a hash. + +- *Type*: rvalue + is_integer ---------- Returns true if the variable returned to this string is an integer. + - *Type*: rvalue + is_ip_address ------------- Returns true if the string passed to this function is a valid IP address. + - *Type*: rvalue + is_mac_address -------------- Returns true if the string passed to this function is a valid mac address. + - *Type*: rvalue + is_numeric ---------- Returns true if the variable passed to this function is a number. @@ -437,7 +455,6 @@ is_string --------- Returns true if the variable passed to this function is a string. - - *Type*: rvalue join @@ -450,7 +467,6 @@ This function joins an array into a string using a seperator. Would result in: "a,b,c" - - *Type*: rvalue join_keys_to_values @@ -465,14 +481,12 @@ which each element is one joined key/value pair. Would result in: ["a is 1","b is 2"] - - *Type*: rvalue keys ---- Returns the keys of a hash as an array. - - *Type*: rvalue loadyaml @@ -491,7 +505,6 @@ lstrip ------ Strips leading spaces to the left of a string. - - *Type*: rvalue max @@ -499,13 +512,6 @@ max Returns the highest value of all arguments. Requires at least one argument. - -- *Type*: rvalue - -md5 ---- -Returns a MD5 hash value from a provided string. - - *Type*: rvalue member @@ -522,7 +528,6 @@ Would return: true Would return: false - - *Type*: rvalue merge @@ -539,8 +544,6 @@ For example: When there is a duplicate key, the key in the rightmost hash will "win." - - - *Type*: rvalue min @@ -548,22 +551,14 @@ min Returns the lowest value of all arguments. Requires at least one argument. - - *Type*: rvalue -notice ------- -Log a message on the server at level notice. - -- *Type*: statement - num2bool -------- This function converts a number or a string representation of a number into a true boolean. Zero or anything non-numeric becomes false. Numbers higher then 0 become true. - - *Type*: rvalue parsejson @@ -571,7 +566,6 @@ parsejson This function accepts JSON as a string and converts into the correct Puppet structure. - - *Type*: rvalue parseyaml @@ -579,7 +573,6 @@ parseyaml This function accepts YAML as a string and converts it into the correct Puppet structure. - - *Type*: rvalue pick @@ -590,15 +583,13 @@ the first value in a list of values that is not undefined or an empty string this function is used to check for a value in the Puppet Dashboard/Enterprise Console, and failover to a default value like the following: - $real_jenkins_version = pick($::jenkins_version, '1.449') + $real_jenkins_version = pick($::jenkins_version, '1.449') The value of $real_jenkins_version will first look for a top-scope variable called 'jenkins_version' (note that parameters set in the Puppet Dashboard/ Enterprise Console are brought into Puppet as top-scope variables), and, failing that, will use a default value of 1.449. - - - *Type*: rvalue prefix @@ -611,7 +602,6 @@ This function applies a prefix to all elements in an array. Will return: ['pa','pb','pc'] - - *Type*: rvalue range @@ -638,49 +628,6 @@ Will return: ["a","b","c"] Will return: ["host01", "host02", ..., "host09", "host10"] - -- *Type*: rvalue - -realize -------- -Make a virtual object real. This is useful -when you want to know the name of the virtual object and don't want to -bother with a full collection. It is slightly faster than a collection, -and, of course, is a bit shorter. You must pass the object using a -reference; e.g.: `realize User[luke]`. - -- *Type*: statement - -regsubst --------- -Perform regexp replacement on a string or array of strings. - -* *Parameters* (in order): - * _target_ The string or array of strings to operate on. If an array, the replacement will be performed on each of the elements in the array, and the return value will be an array. - * _regexp_ The regular expression matching the target string. If you want it anchored at the start and or end of the string, you must do that with ^ and $ yourself. - * _replacement_ Replacement string. Can contain backreferences to what was matched using \0 (whole match), \1 (first set of parentheses), and so on. - * _flags_ Optional. String of single letter flags for how the regexp is interpreted: - - *E* Extended regexps - - *I* Ignore case in regexps - - *M* Multiline regexps - - *G* Global replacement; all occurrences of the regexp in each target string will be replaced. Without this, only the first occurrence will be replaced. - * _encoding_ Optional. How to handle multibyte characters. A single-character string with the following values: - - *N* None - - *E* EUC - - *S* SJIS - - *U* UTF-8 - -* *Examples* - -Get the third octet from the node's IP address: - - $i3 = regsubst($ipaddress,'^(\d+)\.(\d+)\.(\d+)\.(\d+)$','\3') - -Put angle brackets around each octet in the node's IP address: - - $x = regsubst($ipaddress, '([0-9]+)', '<\1>', 'G') - - - *Type*: rvalue reject @@ -699,76 +646,40 @@ Would return: - *Type*: rvalue -require -------- -Evaluate one or more classes, adding the required class as a dependency. - -The relationship metaparameters work well for specifying relationships -between individual resources, but they can be clumsy for specifying -relationships between classes. This function is a superset of the -'include' function, adding a class relationship so that the requiring -class depends on the required class. - -Warning: using require in place of include can lead to unwanted dependency cycles. - -For instance the following manifest, with 'require' instead of 'include' would produce a nasty dependence cycle, because notify imposes a before between File[/foo] and Service[foo]: - - class myservice { - service { foo: ensure => running } - } - - class otherstuff { - include myservice - file { '/foo': notify => Service[foo] } - } - -Note that this function only works with clients 0.25 and later, and it will -fail if used with earlier clients. - - - -- *Type*: statement - reverse ------- Reverses the order of a string or array. - - *Type*: rvalue rstrip ------ Strips leading spaces to the right of the string. - - *Type*: rvalue -search shuffle ------- Randomizes the order of a string or array elements. - - *Type*: rvalue size ---- Returns the number of elements in a string or array. - - *Type*: rvalue sort ---- Sorts strings and arrays lexically. - - *Type*: rvalue squeeze ------- -Returns a new string where runs of the same character that occur in this set are replaced by a single character. - +Returns a new string where runs of the same character that occur in this set +are replaced by a single character. - *Type*: rvalue @@ -1194,7 +1105,6 @@ The following values will fail, causing compilation to abort: validate_string($undefined) - - *Type*: statement values -- cgit v1.2.3 From 5a2d4c4a68f75a180804768e9504e1f4e3c9f9ae Mon Sep 17 00:00:00 2001 From: Garrett Honeycutt Date: Fri, 12 Apr 2013 13:04:15 +0200 Subject: adds compatibility matrix --- README.markdown | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.markdown') diff --git a/README.markdown b/README.markdown index fb6e585..0efaf16 100644 --- a/README.markdown +++ b/README.markdown @@ -40,6 +40,12 @@ Enterprise 1.2. # Compatibility # +Puppet Versions | < 2.6 | 2.6 | 2.7 | 3.x | +:---------------|:-----:|:---:|:---:|:----: +**stdlib 2.x** | no | **yes** | **yes** | no +**stdlib 3.x** | no | no | **yes** | **yes** +**stdlib 4.x** | no | no | no | **yes** + The stdlib module does not work with Puppet versions released prior to Puppet 2.6.0. -- cgit v1.2.3