1. [Development - Guide for contributing to the module](#development)
1. [Contributors](#contributors)
-
+<a id="module-description"></a>
## Module Description
This module provides a standard library of resources for Puppet modules. Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet:
> *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.
+<a id="setup"></a>
## Setup
-[Install](https://docs.puppet.com/puppet/latest/modules_installing.html) the stdlib module to add the functions, facts, and resources of this standard library to Puppet.
+[Install](https://puppet.com/docs/puppet/latest/modules_installing.html) the stdlib module to add the functions, facts, and resources of this standard library to Puppet.
-If you are authoring a module that depends on stdlib, be sure to [specify dependencies](https://docs.puppet.com/puppet/latest/modules_metadata.html#specifying-dependencies) in your metadata.json.
+If you are authoring a module that depends on stdlib, be sure to [specify dependencies](https://puppet.com/docs/puppet/latest/modules_metadata.html#specifying-dependencies-in-modules) in your metadata.json.
+<a id="usage"></a>
## Usage
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`.
}
```
+<a id="reference"></a>
## Reference
* [Public classes](#public-classes)
* [Facts](#facts)
* [Functions](#functions)
+<a id="classes"></a>
### Classes
+<a id="public-classes"></a>
#### Public classes
The `stdlib` class has no parameters.
+<a id="private-classes"></a>
#### Private classes
* `stdlib::stages`: Manages a standard set of run stages for Puppet.
+<a id="defined-types"></a>
### Defined types
#### `file_line`
Match Example:
- file_line { 'bashrc_proxy':
- ensure => present,
- path => '/etc/bashrc',
- line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
- match => '^export\ HTTP_PROXY\=',
- append_on_no_match => false,
- }
+```puppet
+file_line { 'bashrc_proxy':
+ ensure => present,
+ path => '/etc/bashrc',
+ line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+ match => '^export\ HTTP_PROXY\=',
+ append_on_no_match => false,
+}
+```
-In this code example, `match` looks for a line beginning with export followed by HTTP_PROXY and replaces it with the value in line. If a match is not found, then no changes are made to the file.
+In this code example, `match` looks for a line beginning with export followed by 'HTTP_PROXY' and replaces it with the value in line. If a match is not found, then no changes are made to the file.
-Match Example with `ensure => absent`:
+Examples of `ensure => absent`:
+
+This type has two behaviors when `ensure => absent` is set.
+
+The first is to set `match => ...` and `match_for_absence => true`. Match looks for a line beginning with 'export', followed by 'HTTP_PROXY', and then deletes it. If multiple lines match, an error is raised unless the `multiple => true` parameter is set.
+
+The `line => ...` parameter in this example would be accepted but ignored.
+
+For example:
```puppet
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 the example above, `match` looks for a line beginning with 'export' followed by 'HTTP_PROXY' and deletes it. If multiple lines match, an error is raised, unless the `multiple => true` parameter is set.
+The second way of using `ensure => absent` is to specify a `line => ...` and no match. When ensuring lines are absent, the default behavior is to remove all lines matching. This behavior can't be disabled.
+
+For example:
+
+```puppet
+file_line { 'bashrc_proxy':
+ ensure => absent,
+ path => '/etc/bashrc',
+ line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+}
+```
+
Encoding example:
Default: 'UTF-8'.
-##### `ensure`: Specifies whether the resource is present.
+##### `ensure`
+
+Specifies whether the resource is present.
Values: 'present', 'absent'.
##### `match`
-Specifies a regular expression to compare 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.
+Specifies a regular expression to compare against existing lines in the file; if a match is found, it is replaced rather than adding a new line.
Values: String containing a regex.
##### `multiple`
-Specifies whether `match` and `after` can change multiple lines. If set to `false`, an exception is raised if more than one line matches.
+Specifies whether `match` and `after` can change multiple lines. If set to `false`, allows file_line to replace only one line and raises an error if more than one will be replaced. If set to `true`, allows file_line to replace one or more lines.
Values: `true`, `false`.
##### `replace`
-Specifies whether the resource overwrites an existing line that matches the `match` parameter. If set to `false` and a line is found matching the `match` parameter, the line is not placed in the file.
+Specifies whether the resource overwrites an existing line that matches the `match` parameter when `line` does not otherwise exist.
+
+If set to `false` and a line is found matching the `match` parameter, the line is not placed in the file.
Boolean.
Default value: `true`.
+##### `replace_all_matches_not_matching_line`
+
+Replaces all lines matched by `match` parameter, even if `line` already exists in the file.
+
+Default value: `false`.
+
+<a id="data-types"></a>
### Data types
#### `Stdlib::Absolutepath`
../relative_path
```
+#### `Stdlib::Ensure::Service`
+
+Matches acceptable ensure values for service resources.
+
+Acceptable input examples:
+
+```shell
+stopped
+running
+```
+
+Unacceptable input example:
+
+```shell
+true
+false
+```
+
#### `Stdlib::Httpsurl`
-Matches HTTPS URLs.
+Matches HTTPS URLs. It is a case insensitive match.
Acceptable input example:
```shell
https://hello.com
+
+HTTPS://HELLO.COM
```
Unacceptable input example:
#### `Stdlib::Httpurl`
-Matches both HTTPS and HTTP URLs.
+Matches both HTTPS and HTTP URLs. It is a case insensitive match.
Acceptable input example:
https://hello.com
http://hello.com
+
+HTTP://HELLO.COM
```
Unacceptable input example:
#### `Stdlib::Unixpath`
-Matches paths on Unix operating systems.
+Matches absolute paths on Unix operating systems.
Acceptable input example:
```shell
C:/whatever
+
+some/path
+
+../some/other/path
+```
+
+#### `Stdlib::Filemode`
+
+Matches octal file modes consisting of one to four numbers and symbolic file modes.
+
+Acceptable input examples:
+
+```shell
+0644
+```
+
+```shell
+1777
+```
+
+```shell
+a=Xr,g=w
+```
+
+Unacceptable input examples:
+
+```shell
+x=r,a=wx
+```
+
+```shell
+0999
```
#### `Stdlib::Windowspath`
\\\\host\\windows
```
-Unacceptable input example:
+Valid values: A windows filepath.
+
+#### `Stdlib::Filesource`
+
+Matches paths valid values for the source parameter of the Puppet file type.
+
+Acceptable input example:
```shell
-/usr2/username/bin:/usr/local/bin:/usr/bin:.
+http://example.com
+
+https://example.com
+
+file:///hello/bla
+```
+
+Valid values: A filepath.
+
+#### `Stdlib::Fqdn`
+
+Matches paths on fully qualified domain name.
+
+Acceptable input example:
+
+```shell
+localhost
+
+example.com
+
+www.example.com
```
+Valid values: Domain name of a server.
+
+#### `Stdlib::Host`
+
+Matches a valid host which could be a valid ipv4, ipv6 or fqdn.
+
+Acceptable input example:
+
+```shell
+localhost
+
+www.example.com
+
+192.0.2.1
+```
+
+Valid values: An IP address or domain name.
+
+#### `Stdlib::Port`
+
+Matches a valid TCP/UDP Port number.
+
+Acceptable input examples:
+
+```shell
+80
+
+443
+
+65000
+```
+
+Valid values: An Integer.
+
+#### `Stdlib::Port::Privileged`
+
+Matches a valid TCP/UDP Privileged port i.e. < 1024.
+
+Acceptable input examples:
+
+```shell
+80
+
+443
+
+1023
+```
+
+Valid values: A number less than 1024.
+
+#### `Stdlib::Port::Unprivileged`
+
+Matches a valid TCP/UDP Privileged port i.e. >= 1024.
+
+Acceptable input examples:
+
+```shell
+1024
+
+1337
+
+65000
+
+```
+
+Valid values: A number more than or equal to 1024.
+
+#### `Stdlib::Base32`
+
+Matches paths a valid base32 string.
+
+Acceptable input example:
+
+```shell
+ASDASDDASD3453453
+
+asdasddasd3453453=
+
+ASDASDDASD3453453==
+```
+
+Valid values: A base32 string.
+
+#### `Stdlib::Base64`
+
+Matches paths a valid base64 string.
+
+Acceptable input example:
+
+```shell
+asdasdASDSADA342386832/746+=
+
+asdasdASDSADA34238683274/6+
+
+asdasdASDSADA3423868327/46+==
+```
+
+Valid values: A base64 string.
+
+#### `Stdlib::Ipv4`
+
+This type is no longer available. To make use of this functionality, use [Stdlib::IP::Address::V4](https://github.com/puppetlabs/puppetlabs-stdlib#stdlibipaddressv4).
+
+#### `Stdlib::Ipv6`
+
+This type is no longer available. To make use of this functionality, use [Stdlib::IP::Address::V6](https://github.com/puppetlabs/puppetlabs-stdlib#stdlibipaddressv6).
+
+#### `Stdlib::Ip_address`
+
+This type is no longer available. To make use of this functionality, use [Stdlib::IP::Address](https://github.com/puppetlabs/puppetlabs-stdlib#stdlibipaddress)
+
+#### `Stdlib::IP::Address`
+
+Matches any IP address, including both IPv4 and IPv6 addresses. It will match them either with or without an address prefix as used in CIDR format IPv4 addresses.
+
+Examples:
+
+```
+'127.0.0.1' =~ Stdlib::IP::Address # true
+'10.1.240.4/24' =~ Stdlib::IP::Address # true
+'52.10.10.141' =~ Stdlib::IP::Address # true
+'192.168.1' =~ Stdlib::IP::Address # false
+'FEDC:BA98:7654:3210:FEDC:BA98:7654:3210' =~ Stdlib::IP::Address # true
+'FF01:0:0:0:0:0:0:101' =~ Stdlib::IP::Address # true
+```
+
+#### `Stdlib::IP::Address::V4`
+
+Match any string consisting of an IPv4 address in the quad-dotted decimal format, with or without a CIDR prefix. It will not match any abbreviated form (for example, 192.168.1) because these are poorly documented and inconsistently supported.
+
+Examples:
+
+```
+'127.0.0.1' =~ Stdlib::IP::Address::V4 # true
+'10.1.240.4/24' =~ Stdlib::IP::Address::V4 # true
+'192.168.1' =~ Stdlib::IP::Address::V4 # false
+'FEDC:BA98:7654:3210:FEDC:BA98:7654:3210' =~ Stdlib::IP::Address::V4 # false
+'12AB::CD30:192.168.0.1' =~ Stdlib::IP::Address::V4 # false
+```
+
+Valid values: An IPv4 address.
+
+#### `Stdlib::IP::Address::V6`
+
+Match any string consistenting of an IPv6 address in any of the documented formats in RFC 2373, with or without an address prefix.
+
+Examples:
+
+```
+'127.0.0.1' =~ Stdlib::IP::Address::V6 # false
+'10.1.240.4/24' =~ Stdlib::IP::Address::V6 # false
+'FEDC:BA98:7654:3210:FEDC:BA98:7654:3210' =~ Stdlib::IP::Address::V6 # true
+'FF01:0:0:0:0:0:0:101' =~ Stdlib::IP::Address::V6 # true
+'FF01::101' =~ Stdlib::IP::Address::V6 # true
+```
+
+Valid values: An IPv6 address.
+
+#### `Stdlib::IP::Address::Nosubnet`
+
+Match the same things as the `Stdlib::IP::Address` alias, except it will not match an address that includes an address prefix (for example, it will match '192.168.0.6' but not '192.168.0.6/24').
+
+Valid values: An IP address with no subnet.
+
+#### `Stdlib::IP::Address::V4::CIDR`
+
+Match an IPv4 address in the CIDR format. It will only match if the address contains an address prefix (for example, it will match '192.168.0.6/24'
+but not '192.168.0.6').
+
+Valid values: An IPv4 address with a CIDR provided eg: '192.186.8.101/105'. This will match anything inclusive of '192.186.8.101' to '192.168.8.105'.
+
+#### `Stdlib::IP::Address::V4::Nosubnet`
+
+Match an IPv4 address only if the address does not contain an address prefix (for example, it will match '192.168.0.6' but not '192.168.0.6/24').
+
+Valid values: An IPv4 address with no subnet.
+
+#### `Stdlib::IP::Address::V6::Full`
+
+Match an IPv6 address formatted in the "preferred form" as documented in section 2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt), with or without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
+
+#### `Stdlib::IP::Address::V6::Alternate`
+
+Match an IPv6 address formatted in the "alternative form" allowing for representing the last two 16-bit pieces of the address with a quad-dotted decimal, as documented in section 2.2.1 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will match addresses with or without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
+
+#### `Stdlib::IP::Address::V6::Compressed`
+
+Match an IPv6 address which may contain `::` used to compress zeros as documented in section 2.2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will match addresses with or without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
+#### `Stdlib::IP::Address::V6::Nosubnet`
+
+Alias to allow `Stdlib::IP::Address::V6::Nosubnet::Full`, `Stdlib::IP::Address::V6::Nosubnet::Alternate` and `Stdlib::IP::Address::V6::Nosubnet::Compressed`.
+
+#### `Stdlib::IP::Address::V6::Nosubnet::Full`
+
+Match an IPv6 address formatted in the "preferred form" as documented in section 2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will not match addresses with address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
+
+#### `Stdlib::IP::Address::V6::Nosubnet::Alternate`
+
+Match an IPv6 address formatted in the "alternative form" allowing for representing the last two 16-bit pieces of the address with a quad-dotted decimal, as documented in section 2.2.1 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will only match addresses without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
+
+#### `Stdlib::IP::Address::V6::Nosubnet::Compressed`
+
+Match an IPv6 address which may contain `::` used to compress zeros as documented in section 2.2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will only match addresses without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
+
+#### `Stdlib::IP::Address::V6::CIDR`
+
+Match an IPv6 address in the CIDR format. It will only match if the address contains an address prefix (for example, it will match 'FF01:0:0:0:0:0:0:101/32', 'FF01::101/60', '::/0',
+but not 'FF01:0:0:0:0:0:0:101', 'FF01::101', '::').
+
+<a id="facts"></a>
### Facts
#### `package_provider`
Returns the default provider Puppet uses to manage services on this system
+<a id="functions"></a>
### Functions
#### `abs`
+**Deprecated:** This function has been replaced with a built-in [`abs`](https://puppet.com/docs/puppet/latest/function.html#abs) function as of Puppet 6.0.0.
+
Returns the absolute value of a number. For example, '-34.56' becomes '34.56'.
Argument: A single argument of either an integer or float value.
Converts any object to an array containing that object. Converts empty argument lists are to empty arrays. Hashes are converted to arrays of alternating keys and values. Arrays are not touched.
+Since Puppet 5.0.0, you can create new values of almost any datatype using the type system — you can use the built-in [`Array.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-array-and-tuple) function to create a new array:
+
+ $hsh = {'key' => 42, 'another-key' => 100}
+ notice(Array($hsh))
+
+Would notice `[['key', 42], ['another-key', 100]]`
+
+The array data type also has a special mode to "create an array if not already an array":
+
+ notice(Array({'key' => 42, 'another-key' => 100}, true))
+
+Would notice `[{'key' => 42, 'another-key' => 100}]`, as the `true` flag prevents the hash from being transformed into an array.
+
*Type*: rvalue.
#### `any2bool`
* An undef value returns `false`.
* Anything else returns `true`.
+See the built-in [`Boolean.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-boolean)
+
*Type*: rvalue.
#### `assert_private`
For backward compatibility, `method` is set as `default` if not specified.
-*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+> **Note**: This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+
+Since Puppet 4.8.0, the `Binary` data type can be used to produce base 64 encoded strings.
+
+See the built-in [`String.new`](https://puppet.com/docs/puppet/latest/function.html#binary-value-to-string) and [`Binary.new`](https://puppet.com/docs/puppet/latest/function.html#creating-a-binary) functions.
+
+See the built-in [`binary_file`](https://puppet.com/docs/puppet/latest/function.html#binary_file) function for reading a file with binary (non UTF-8) content.
+
+ # encode a string as if it was binary
+ $encodestring = String(Binary('thestring', '%s'))
+ # decode a Binary assuming it is an UTF-8 String
+ $decodestring = String(Binary("dGhlc3RyaW5n"), "%s")
**Examples:**
Returns the `basename` of a path. An optional argument strips the 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'
+```puppet
+basename('/path/to/a/file.ext') => 'file.ext'
+basename('relative/path/file.ext') => 'file.ext'
+basename('/path/to/a/file.ext', '.ext') => 'file'
+```
*Type*: rvalue.
* `false`, 'f', '0', 'n', and 'no' to 0.
* `true`, 't', '1', 'y', and 'yes' to 1.
- Argument: a single Boolean or string as an input.
+Argument: a single Boolean or string as an input.
+
+Since Puppet 5.0.0, you can create values for almost any data type using the type system — you can use the built-in [`Numeric.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-numeric), [`Integer.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-integer), and [`Float.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-float)
+functions to convert to numeric values:
- *Type*: rvalue.
+ notice(Integer(false)) # Notices 0
+ notice(Float(true)) # Notices 1.0
+
+*Type*: rvalue.
#### `bool2str`
Arguments: Boolean.
+Since Puppet 5.0.0, you can create new values for almost any
+data type using the type system — you can use the built-in
+[`String.new`](https://puppet.com/docs/puppet/latest/function.html#boolean-to-string)
+function to convert to String, with many different format options:
+
+ notice(String(false)) # Notices 'false'
+ notice(String(true)) # Notices 'true'
+ notice(String(false, '%y')) # Notices 'yes'
+ notice(String(true, '%y')) # Notices 'no'
+
*Type*: rvalue.
#### `camelcase`
+**Deprecated:** This function has been replaced with a built-in [`camelcase`](https://puppet.com/docs/puppet/latest/function.html#camelcase) function as of Puppet 6.0.0.
+
Converts the case of a string or all strings in an array to CamelCase (mixed case).
Arguments: Either an array or string. Returns the same type of argument as it received, but in CamelCase form.
#### `capitalize`
+**Deprecated:** This function has been replaced with a built-in [`capitalize`](https://puppet.com/docs/puppet/latest/function.html#capitalize) function as of Puppet 6.0.0.
+
Capitalizes the first character of a string or array of strings and lowercases the remaining characters of each string.
Arguments: either a single string or an array as an input. *Type*: rvalue.
#### `ceiling`
+**Deprecated:** This function has been replaced with a built-in [`ceiling`](https://puppet.com/docs/puppet/latest/function.html#ceiling) function as of Puppet 6.0.0.
+
Returns the smallest integer greater than or equal to the argument.
Arguments: A single numeric value.
#### `chomp`
+**Deprecated:** This function has been replaced with a built-in [`chomp`](https://puppet.com/docs/puppet/latest/function.html#chomp) function as of Puppet 6.0.0.
+
Removes the record separator from the end of a string or an array of strings; for example, 'hello\n' becomes 'hello'.
Arguments: a single string or array.
#### `chop`
+**Deprecated:** This function has been replaced with a built-in [`chop`](https://puppet.com/docs/puppet/latest/function.html#chop) function as of Puppet 6.0.0.
+
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. To only remove record separators, use the `chomp` function.
Arguments: A string or an array of strings as input.
Arguments: strings, arrays, or numerics.
+Since Puppet 6.0.0, you can use built-in functions to get the same result:
+
+ [$minval, $maxval, $value_to_clamp].sort[1]
+
*Type*: rvalue.
#### `concat`
* `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'].
+Since Puppet 4.0, you can use the `+` operator for concatenation of arrays and merge of hashes, and the `<<` operator for appending:
+
+ ['1','2','3'] + ['4','5','6'] + ['7','8','9'] # returns ['1','2','3','4','5','6','7','8','9']
+ [1, 2, 3] << 4 # returns [1, 2, 3, 4]
+ [1, 2, 3] << [4, 5] # returns [1, 2, 3, [4, 5]]
+
*Type*: rvalue.
#### `convert_base`
* `convert_base(5, 2)` results in: '101'
* `convert_base('254', '16')` results in: 'fe'
+Since Puppet 4.5.0, you can do this with the built-in [`String.new`](https://puppet.com/docs/puppet/latest/function.html#integer-to-string) function, with various formatting options:
+
+ $binary_repr = String(5, '%b') # results in "101"
+ $hex_repr = String(254, '%x') # results in "fe"
+ $hex_repr = String(254, '%#x') # results in "0xfe"
+
#### `count`
-If called with only an array, counts the number of elements that are **not** nil or `undef`. If called with a second argument, counts the number of elements in an array that matches the second argument.
+Takes an array as the first argument and an optional second argument.
+It counts the number of elements in an array that is equal to the second argument.
+If called with only an array, it counts the number of elements that are not nil/undef/empty-string.
+
+> **Note**: Equality is tested with a Ruby method. It is subject to what Ruby considers
+to be equal. For strings, equality is case sensitive.
+
+In Puppet core, counting is done using a combination of the built-in functions
+[`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) (since Puppet 4.0.0) and
+[`length`](https://puppet.com/docs/puppet/latest/function.html#length) (since Puppet 5.5.0, before that in stdlib).
+
+This example shows counting values that are not `undef`:
+
+ notice([42, "hello", undef].filter |$x| { $x =~ NotUndef }.length)
+
+Would notice 2.
*Type*: rvalue.
* `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}.
* `delete(['ab', 'b'], 'b')` returns ['ab'].
+Since Puppet 4.0.0, the minus (`-`) operator deletes values from arrays and deletes keys from a hash:
+
+ ['a', 'b', 'c', 'b'] - 'b'
+ # would return ['a', 'c']
+
+ {'a'=>1,'b'=>2,'c'=>3} - ['b','c'])
+ # would return {'a' => '1'}
+
+You can perform a global delete from a string with the built-in
+[`regsubst`](https://puppet.com/docs/puppet/latest/function.html#regsubst) function.
+
+ 'abracadabra'.regsubst(/bra/, '', 'G')
+ # would return 'acada'
+
+In general, the built-in
+[`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) function
+can filter out entries from arrays and hashes based on a combination of keys and values.
+
*Type*: rvalue.
#### `delete_at`
For example: `delete_at(['a','b','c'], 1)` returns ['a','c'].
+Since Puppet 4, this can be done with the built-in
+[`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) function:
+
+ ['a', 'b', 'c'].filter |$pos, $val | { $pos != 1 } # returns ['a', 'c']
+ ['a', 'b', 'c', 'd'].filter |$pos, $val | { $pos % 2 != 0 } # returns ['b', 'd']
+
+Or, if you want to delete from the beginning or the end of the array — or from both ends at the same time — use the slice operator `[ ]`:
+
+ $array[0, -1] # the same as all the values
+ $array[2, -1] # all but the first 2 elements
+ $array[0, -3] # all but the last 2 elements
+ $array[1, -2] # all but the first and last element
+
*Type*: rvalue.
#### `delete_regex`
*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
-
-For example
+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'].
+Since Puppet 4.0.0, do the equivalent with the built-in
+[`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) function:
+
+ ["aaa", "aba", "aca"].filter |$val| { $val !~ /b/ }
+ # Would return: ['aaa', 'aca']
+
*Type*: rvalue.
#### `delete_values`
* `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'}
+Since Puppet 4.0.0, do the equivalent with the built-in
+[`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) function:
+
+ $array.filter |$val| { $val != 'B' }
+ $hash.filter |$key, $val| { $val != 'B' }
+
*Type*: rvalue.
#### `delete_undef_values`
* `$hash = delete_undef_values({a=>'A', b=>'', c=>`undef`, d => false})` returns {a => 'A', b => '', d => false}.
+Since Puppet 4.0.0, do the equivalent with the built-in
+[`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) function:
+
+ $array.filter |$val| { $val =~ NotUndef }
+ $hash.filter |$key, $val| { $val =~ NotUndef }
+
*Type*: rvalue.
#### `deprecation`
Other settings in Puppet affect the stdlib `deprecation` function:
-* [`disable_warnings`](https://docs.puppet.com/puppet/latest/reference/configuration.html#disablewarnings)
-* [`max_deprecations`](https://docs.puppet.com/puppet/latest/reference/configuration.html#maxdeprecations)
-* [`strict`](https://docs.puppet.com/puppet/latest/reference/configuration.html#strict):
+* [`disable_warnings`](https://puppet.com/docs/puppet/latest/configuration.html#disablewarnings)
+* [`max_deprecations`](https://puppet.com/docs/puppet/latest/configuration.html#maxdeprecations)
+* [`strict`](https://puppet.com/docs/puppet/latest/configuration.html#strict):
* `error`: Fails immediately with the deprecation message
* `off`: Output emits no messages.
* `difference(["a","b","c"],["b","c","d"])` returns ["a"].
+Since Puppet 4, the minus (`-`) operator in the Puppet language does the same:
+
+ ['a', 'b', 'c'] - ['b', 'c', 'd']
+ # would return ['a']
+
*Type*: rvalue.
#### `dig`
-> DEPRECATED: This function has been replaced with a built-in [`dig`](https://docs.puppet.com/puppet/latest/function.html#dig) function as of Puppet 4.5.0. Use [`dig44()`](#dig44) for backwards compatibility or use the new version.
+**Deprecated:** This function has been replaced with a built-in [`dig`](https://puppet.com/docs/puppet/latest/function.html#dig) function as of Puppet 4.5.0. Use [`dig44()`](#dig44) for backwards compatibility or use the new version.
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.
#### `downcase`
+**Deprecated:** This function has been replaced with a built-in [`downcase`](https://puppet.com/docs/puppet/latest/function.html#downcase) function as of Puppet 6.0.0.
+
Converts the case of a string or of all strings in an array to lowercase.
*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
#### `empty`
+**Deprecated:** This function has been replaced with a built-in [`empty`](https://puppet.com/docs/puppet/latest/function.html#empty) function as of Puppet 5.5.0.
+
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_resources('user', hiera_hash('userlist'), {'ensure' => 'present'})
```
+#### `stdlib::extname`
+
+Returns the Extension (the Portion of Filename in Path starting from the last Period).
+
+Example usage:
+
+```puppet
+stdlib::extname('test.rb') => '.rb'
+stdlib::extname('a/b/d/test.rb') => '.rb'
+stdlib::extname('test') => ''
+stdlib::extname('.profile') => ''
+```
+
+*Type*: rvalue.
+
#### `fact`
Return the value of a given fact. Supports the use of dot-notation for referring to structured facts. If a fact requested does not exist, returns Undef.
#### `flatten`
+**Deprecated:** This function has been replaced with a built-in [`flatten`](https://puppet.com/docs/puppet/latest/function.html#flatten) function as of Puppet 5.5.0.
+
Flattens deeply nested arrays and returns a single flat array as a result.
For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c'].
#### `floor`
+**Deprecated:** This function has been replaced with a built-in [`floor`](https://puppet.com/docs/puppet/latest/function.html#floor) function as of Puppet 6.0.0.
+
Returns the largest integer less than or equal to the argument.
Arguments: A single numeric value.
$module_path = get_module_path('stdlib')
```
+Since Puppet 5.4.0, the built-in [`module_directory`](https://puppet.com/docs/puppet/latest/function.html#module_directory) function does the same thing and will return the path to the first module found, if given multiple values or an array.
+
*Type*: rvalue.
#### `getparam`
-
Returns the value of a resource's parameter.
Arguments: A resource reference and the name of the parameter.
-For example, the following returns 'param_value':
+> Note: User defined resource types are evaluated lazily.
+
+*Examples:*
```puppet
+# define a resource type with a parameter
define example_resource($param) {
}
+# declare an instance of that type
example_resource { "example_resource_instance":
- param => "param_value"
+ param => "'the value we are getting in this example''"
}
-getparam(Example_resource["example_resource_instance"], "param")
+# Because of order of evaluation, a second definition is needed
+# that will be evaluated after the first resource has been declared
+#
+define example_get_param {
+ # This will notice the value of the parameter
+ notice(getparam(Example_resource["example_resource_instance"], "param"))
+}
+
+# Declare an instance of the second resource type - this will call notice
+example_get_param { 'show_notify': }
```
-*Type*: rvalue.
+Would notice: 'the value we are getting in this example'
+
+Since Puppet 4.0.0, you can get a parameter value by using its data type
+and the [ ] operator. The example below is equivalent to a call to getparam():
+
+```puppet
+Example_resource['example_resource_instance']['param']
+```
#### `getvar`
+**Deprecated:** This function has been replaced with a built-in [`getvar`](https://puppet.com/docs/puppet/latest/function.html#getvar)
+function as of Puppet 6.0.0. The new version also supports digging into a structured value.
Looks up a variable in a remote namespace.
For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd'].
+Since Puppet 4.0.0, the built-in [`filter`](https://puppet.com/docs/puppet/latest/function.html#filter) function does the "same" — as any logic can be used to filter, as opposed to just regular expressions:
+
+ ['aaa', 'bbb', 'ccc', 'aaaddd']. filter |$x| { $x =~ 'aaa' }
+
*Type*: rvalue.
#### `has_interface_with`
*Type*: rvalue.
#### `has_key`
+**Deprecated:** This function has been replaced with the built-in operator `in`.
Determines if a hash has a certain key value.
}
```
+Since Puppet 4.0.0, this can be achieved in the Puppet language with the following equivalent expression:
+
+ $my_hash = {'key_one' => 'value_one'}
+ if 'key_one' in $my_hash {
+ notice('this will be printed')
+ }
+
*Type*: rvalue.
#### `hash`
+**Deprecated:** This function has been replaced with the built-in ability to create a new value of almost any
+data type - see the built-in [`Hash.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-hash-and-struct) function
+in Puppet.
+
Converts an array into a hash.
-For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}.
+For example (deprecated), `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}.
+
+For example (built-in), `Hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}.
*Type*: rvalue.
}
```
-* See the [the Puppet type system](https://docs.puppetlabs.com/latest/type.html#about-resource-types) for more information about types.
-* See the [`assert_type()`](https://docs.puppetlabs.com/latest/function.html#asserttype) function for flexible ways to assert the type of a value.
+* See the [the Puppet type system](https://puppet.com/docs/puppet/latest/lang_data.html) for more information about types.
+* See the [`assert_type()`](https://puppet.com/docs/puppet/latest/function.html#asserttype) function for flexible ways to assert the type of a value.
#### `is_absolute_path`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Returns `true` if the given path is absolute.
#### `is_array`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_bool`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_domain_name`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_float`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_function_available`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_hash`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_integer`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_ip_address`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_ipv6_address`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_ipv4_address`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_numeric`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `is_string`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `join`
+**Deprecated:** This function has been replaced with a built-in [`join`](https://puppet.com/docs/puppet/latest/function.html#join) function as of Puppet 5.5.0.
+
Joins an array into a string using a separator. For example, `join(['a','b','c'], ",")` results in: "a,b,c".
*Type*: rvalue.
For example, `join_keys_to_values({'a'=>1,'b'=>[2,3]}, " is ")` results in ["a is 1","b is 2","b is 3"].
+Since Puppet 5.0.0, there is more control over the formatting (including indentations and line breaks, delimiters around arrays and hash entries, between key/values in hash entries, and individual
+formatting of values in the array) - see the
+built-in [`String.new`](https://docs.puppet.com/puppet/latest/function.html#conversion-to-string) function and its formatting options for `Array` and `Hash`.
+
*Type*: rvalue.
#### `keys`
+**Deprecated:** This function has been replaced with a built-in [`keys`](https://puppet.com/docs/puppet/latest/function.html#keys) function as of Puppet 5.5.0.
+
Returns the keys of a hash as an array.
*Type*: rvalue.
#### `length`
+**Deprecated:** This function has been replaced with a built-in [`length`](https://puppet.com/docs/puppet/latest/function.html#length) function as of Puppet 5.5.0.
+
Returns the length of a given string, array or hash. Replaces the deprecated `size()` function.
*Type*: rvalue.
For example:
+The first parameter can be an absolute file path, or a URL.
+
```puppet
$myhash = loadjson('/etc/puppet/data/myhash.json')
```
notify { $metadata['author']: }
```
-When a module's metadata file is absent, the catalog compilation fails. To avoid this failure:
+When a module's metadata file is absent, the catalog compilation fails. To avoid this failure, do the following:
```
$metadata = load_module_metadata('mysql', true)
#### `lstrip`
+**Deprecated:** This function has been replaced with a built-in [`lstrip`](https://puppet.com/docs/puppet/latest/function.html#lstrip) function as of Puppet 6.0.0.
+
Strips spaces to the left of a string.
*Type*: rvalue.
#### `max`
+**Deprecated:** This function has been replaced with a built-in [`max`](https://puppet.com/docs/puppet/latest/function.html#max) function as of Puppet 6.0.0.
+
Returns the highest value of all arguments. Requires at least one argument.
Arguments: A numeric or a string representing a number.
*Note*: This function does not support nested arrays. If the first argument contains nested arrays, it will not recurse through them.
+Since Puppet 4.0.0, you can perform the same in the Puppet language. For single values,
+use the operator `in`:
+
+ 'a' in ['a', 'b'] # true
+
+And for arrays, use the operator `-` to compute a diff:
+
+ ['d', 'b'] - ['a', 'b', 'c'] == [] # false because 'd' is not subtracted
+ ['a', 'b'] - ['a', 'b', 'c'] == [] # true because both 'a' and 'b' are subtracted
+
+Also note that since Puppet 5.2.0, the general form to test the content of an array or hash is to use the built-in [`any`](https://puppet.com/docs/puppet/latest/function.html#any) and [`all`](https://puppet.com/docs/puppet/latest/function.html#all) functions.
+
*Type*: rvalue.
#### `merge`
When there is a duplicate key, the key in the rightmost hash takes precedence.
+Since Puppet 4.0.0, you can use the + operator to achieve the same merge.
+
+ $merged_hash = $hash1 + $hash2
+
*Type*: rvalue.
#### `min`
+**Deprecated:** This function has been replaced with a built-in [`min`](https://puppet.com/docs/puppet/latest/function.html#min) function as of Puppet 6.0.0.
+
Returns the lowest value of all arguments. Requires at least one argument.
Arguments: A numeric or a string representing a number.
#### `num2bool`
-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`.
+Converts a number, or a string representation of a number, into a true Boolean.
+Zero or anything non-numeric becomes `false`.
+Numbers greater than zero become `true`.
+
+Since Puppet 5.0.0, the same can be achieved with the Puppet type system.
+See the [`Boolean.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-boolean)
+function in Puppet for the many available type conversions.
+
+ Boolean(0) # false
+ Boolean(1) # true
*Type*: rvalue.
+#### `os_version_gte`
+
+Checks to see if the OS version is at least a certain version. Note that only the major version is taken into account.
+
+Example usage:
+```
+ if os_version_gte('Debian', '9') { }
+ if os_version_gte('Ubuntu', '18.04') { }
+```
+
+Returns:
+ - Boolean(0) # When OS is below the given version.
+ - Boolean(1) # When OS is equal to or greater than the given version.
+
#### `parsejson`
Converts a string of JSON into the correct Puppet structure (as a hash, array, string, integer, or a combination of such).
* `prefix(['a','b','c'], 'p')` returns ['pa','pb','pc'].
* `prefix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'pa'=>'b','pb'=>'c','pc'=>'d'}.
+Since Puppet 4.0.0, modify values in array by using the built-in [`map`](https://docs.puppet.com/puppet/latest/function.html#map) function.
+This example does the same as the first example above:
+
+ ['a', 'b', 'c'].map |$x| { "p${x}" }
+
*Type*: rvalue.
#### `pry`
* `range("0", "9", "2")` returns ["0","2","4","6","8"].
+> Note: The Puppet language supports `Integer` and `Float` ranges by using the type system. They are suitable for iterating a given number of times.
+
+See the built-in [`step`](https://docs.puppet.com/puppet/latest/function.html#step) function in Puppet for skipping values.
+
+ Integer[0, 9].each |$x| { notice($x) } # notices 0, 1, 2, ... 9
+
*Type*: rvalue.
#### `regexpescape`
For example, `reject(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['bbb','ccc'].
+Since Puppet 4.0.0, the same is true with the built-in [`filter`](https://docs.puppet.com/puppet/latest/function.html#filter) function in Puppet.
+The equivalent of the stdlib `reject` function:
+
+ ['aaa','bbb','ccc','aaaddd'].filter |$x| { $x !~ /aaa/ }
+
*Type*: rvalue.
#### `reverse`
Reverses the order of a string or array.
+> *Note*: The same can be done with the built-in [`reverse_each`](https://docs.puppet.com/puppet/latest/function.html#reverse_each) function in Puppet.
+
+
#### `round`
- Rounds a number to the nearest integer
+**Deprecated:** This function has been replaced with a built-in [`round`](https://puppet.com/docs/puppet/latest/function.html#round) function as of Puppet 6.0.0.
+
+Rounds a number to the nearest integer.
*Type*: rvalue.
#### `rstrip`
+**Deprecated:** This function has been replaced with a built-in [`rstrip`](https://puppet.com/docs/puppet/latest/function.html#rstrip) function as of Puppet 6.0.0.
+
Strips spaces to the right of the string.
*Type*: rvalue.
*Type*: rvalue.
+#### `seeded_rand_string`
+
+Generates a consistent (based on seed value) random string. Useful for generating matching passwords for different hosts.
+
#### `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 either double or single quotes. This function behaves the same as Ruby's `Shellwords.shellescape()` function; see the [Ruby documentation](http://ruby-doc.org/stdlib-2.3.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shellescape).
#### `size`
+**Deprecated:** This function has been replaced with a built-in [`size`](https://puppet.com/docs/puppet/latest/function.html#size) function as of Puppet 6.0.0 (`size` is now an alias for `length`).
+
Returns the number of elements in a string, an array or a hash. This function will be deprecated in a future release. For Puppet 4, use the `length` function.
*Type*: rvalue.
+#### `sprintf_hash`
+
+**Deprecated:** The same functionality can be achieved with the built-in [`sprintf`](https://docs.puppet.com/puppet/latest/function.html#sprintf) function as of Puppet 4.10.10 and 5.3.4. This function will be removed in a future release.
+
+Performs printf-style formatting with named references of text.
+
+The first parameter is a format string describing how to format the rest of the parameters in the hash. See Ruby documentation for [`Kernel::sprintf`](https://ruby-doc.org/core-2.4.2/Kernel.html#method-i-sprintf) for details about this function.
+
+For example:
+
+```puppet
+$output = sprintf_hash('String: %<foo>s / number converted to binary: %<number>b',
+ { 'foo' => 'a string', 'number' => 5 })
+# $output = 'String: a string / number converted to binary: 101'
+```
+
+*Type*: rvalue
+
#### `sort`
+**Deprecated:** This function has been replaced with a built-in [`sort`](https://puppet.com/docs/puppet/latest/function.html#sort) function as of Puppet 6.0.0.
+
Sorts strings and arrays lexically.
*Type*: rvalue.
-*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+> *Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
#### `squeeze`
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.
+Since Puppet 5.0.0, the same can be achieved with the Puppet type system.
+See the [`Boolean.new`](https://puppet.com/docs/puppet/latest/function.html#conversion-to-boolean)
+function in Puppet for the many available type conversions.
+
+ Boolean('false'), Boolean('n'), Boolean('no') # all false
+ Boolean('true'), Boolean('y'), Boolean('yes') # all true
+
*Type*: rvalue.
#### `str2saltedsha512`
*Type*: rvalue.
-*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+> *Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
#### `strftime`
+**Deprecated:** This function has been replaced with a built-in [`strftime`](https://puppet.com/docs/puppet/latest/function.html#strftime) function as of Puppet 4.8.0.
+
Returns formatted time.
For example, `strftime("%s")` returns the time since Unix epoch, and `strftime("%Y-%m-%d")` returns the date.
*Type*: rvalue.
-*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+> *Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
*Format:*
* `%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 (for example +0900)
* `%Z`: Time zone name
* `%%`: Literal '%' character
#### `strip`
+**Deprecated:** This function has been replaced with a built-in [`strip`](https://puppet.com/docs/puppet/latest/function.html#strip) function as of Puppet 6.0.0.
+
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(['a','b','c'], 'p')` returns ['ap','bp','cp'].
* `suffix({'a'=>'b','b'=>'c','c'=>'d'}, 'p')` returns {'ap'=>'b','bp'=>'c','cp'=>'d'}.
+Note that since Puppet 4.0.0, you can modify values in an array using the built-in [`map`](https://docs.puppet.com/puppet/latest/function.html#map) function. This example does the same as the first example above:
+
+ ['a', 'b', 'c'].map |$x| { "${x}p" }
+
*Type*: rvalue.
#### `swapcase`
*Type*: rvalue.
-*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+> *Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
#### `time`
For example, `time()` returns something like '1311972653'.
+Since Puppet 4.8.0, the Puppet language has the data types `Timestamp` (a point in time) and `Timespan` (a duration). The following example is equivalent to calling `time()` without any arguments:
+
+ Timestamp()
+
*Type*: rvalue.
#### `to_bytes`
*Type*: rvalue.
+#### `to_json`
+
+Converts input into a JSON String.
+
+For example, `{ "key" => "value" }` becomes `{"key":"value"}`.
+
+*Type*: rvalue.
+
+#### `to_json_pretty`
+
+Converts input into a pretty JSON String.
+
+For example, `{ "key" => "value" }` becomes `{\n \"key\": \"value\"\n}`.
+
+*Type*: rvalue.
+
+#### `to_yaml`
+
+Converts input into a YAML String.
+
+For example, `{ "key" => "value" }` becomes `"---\nkey: value\n"`.
+
+*Type*: rvalue.
+
#### `try_get_value`
-**DEPRECATED:** replaced by `dig()`.
+**Deprecated:** Replaced by `dig()`.
Retrieves a value within multiple layers of hashes and arrays.
#### `type3x`
-**Deprecated**. This function will be removed in a future release.
+**Deprecated:** This function will be removed in a future release.
Returns a string description of the type of a given value. The type can be a string, array, hash, float, integer, or Boolean. For Puppet 4, use the new type system instead.
#### `type_of`
-This function is provided for backwards compatibility, but the built-in [type() function](https://docs.puppet.com/puppet/latest/reference/function.html#type) provided by Puppet is preferred.
+This function is provided for backwards compatibility, but the built-in [type() function](https://puppet.com/docs/puppet/latest/function.html#type) provided by Puppet is preferred.
Returns the literal type of a given value. Requires Puppet 4. 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] { ... }`).
#### `upcase`
+**Deprecated:** This function has been replaced with a built-in [`upcase`](https://puppet.com/docs/puppet/latest/function.html#upcase) function as of Puppet 6.0.0.
+
Converts an object, array, or hash of objects to uppercase. Objects to be converted must respond to upcase.
For example, `upcase('abcd')` returns 'ABCD'.
*Type*: rvalue.
-*Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
+> *Note:* This function is an implementation of a Ruby class and might not be UTF8 compatible. To ensure compatibility, use this function with Ruby 2.4.0 or greater.
#### `validate_absolute_path`
#### `validate_array`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Validates that all passed values are array data structures. Terminates catalog compilation if any value fails this check.
#### `validate_bool`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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`.
Terminates catalog compilation if any value fails this check.
#### `validate_domain_name`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Validate that all values passed are syntactically correct domain names. Aborts catalog compilation if any value fails this check.
#### `validate_hash`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Validates that all passed values are hash data structures. Terminates catalog compilation if any value fails this check.
#### `validate_integer`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Validates an integer or an array of integers. Terminates catalog compilation if any of the checks fail.
#### `validate_ip_address`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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 whether it is an IPv4 or an IPv6 address. It also validates IP address with netmask.
Example:
```puppet
-validate_legacy("Optional[String]", "validate_re", "Value to be validated", ["."])
+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.
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.
-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 were sometimes inconsistent. For example, [validate_numeric](#validate_numeric) unintentionally allowed not only numbers, but also arrays of numbers or strings that looked like numbers.
+Puppet 4 allows improved defined type checking using [data types](https://puppet.com/docs/puppet/latest/lang_data.html). Data types avoid some of the problems with Puppet 3's `validate_*` functions, which were sometimes inconsistent. For example, [validate_numeric](#validate_numeric) unintentionally allowed not only numbers, but also arrays of numbers or strings that looked like numbers.
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 `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.
+Moving to Puppet 4 type validation allows much better defined type checking using [data types](https://puppet.com/docs/puppet/latest/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:
#### `validate_numeric`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Validates a numeric value, or an array or string of numeric values. Terminates catalog compilation if any of the checks fail.
#### `validate_re`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
#### `validate_slength`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**Deprecated:** Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).
Validates that a string (or an array of strings) is less than or equal to a specified length
#### `validate_string`
-**Deprecated. Will be removed in a future version of stdlib. See [`validate_legacy`](#validate_legacy).**
+**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.
validate_string([ 'some', 'array' ])
```
-*Note:* validate_string(`undef`) will not fail in this version of the functions API.
+> *Note:* validate_string(`undef`) will not fail in this version of the functions API.
Instead, use:
#### `values`
+**Deprecated:** This function has been replaced with a built-in [`values`](https://puppet.com/docs/puppet/latest/function.html#values) function as of Puppet 5.5.0.
+
Returns the values of a given hash.
For example, given `$hash = {'a'=1, 'b'=2, 'c'=3} values($hash)` returns [1,2,3].
* `values_at(['a','b','c'], ["0-1"])` returns ['a','b'].
* `values_at(['a','b','c','d','e'], [0, "2-3"])` returns ['a','c','d'].
+Since Puppet 4.0.0, you can slice an array with index and count directly in the language.
+A negative value is taken to be "from the end" of the array, for example:
+
+```puppet
+['a', 'b', 'c', 'd'][1, 2] # results in ['b', 'c']
+['a', 'b', 'c', 'd'][2, -1] # results in ['c', 'd']
+['a', 'b', 'c', 'd'][1, -2] # results in ['b', 'c']
+```
+
*Type*: rvalue.
#### `zip`
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.
+<a id="limitations"></a>
## 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.
-### Version Compatibility
-
-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).
+For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-stdlib/blob/master/metadata.json)
+<a id="development"></a>
## 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 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.puppet.com/forge/contributing.html).
To report or research a bug with any part of this module, please go to
[http://tickets.puppetlabs.com/browse/MODULES](http://tickets.puppetlabs.com/browse/MODULES).
+<a id="contributors"></a>
## 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).
projects / mirror / dsa-puppet.git / blobdiff