diff --git a/REFERENCE.md b/REFERENCE.md index cd501ff18..57d3eca9a 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -39,7 +39,7 @@ the stdlib class, and should not be declared independently. specified base, as a string. * [`count`](#count): Counts the number of elements in array. * [`deep_merge`](#deep_merge): Recursively merges two or more hashes together and returns the resulting hash. -* [`defined_with_params`](#defined_with_params) +* [`defined_with_params`](#defined_with_params): Takes a resource reference and an optional hash of attributes. * [`delete`](#delete): Deletes all instances of a given element from an array, substring from a string, or key from a hash. * [`delete_at`](#delete_at): Deletes a determined indexed value from an array. @@ -52,26 +52,31 @@ from an array or key from a hash. * [`difference`](#difference): This function returns the difference between two arrays. * [`dig`](#dig): **DEPRECATED** Retrieves a value within multiple layers of hashes and arrays via an array of keys containing a path. -* [`dig44`](#dig44) +* [`dig44`](#dig44): **DEPRECATED**: Looks up into a complex structure of arrays and hashes and returns a value +or the default value if nothing was found. * [`dirname`](#dirname): Returns the dirname of a path. * [`dos2unix`](#dos2unix): Returns the Unix version of the given string. * [`downcase`](#downcase): **Deprecated:** Converts the case of a string or all strings in an array to lower case. * [`empty`](#empty): **Deprecated:** Returns true if the variable is empty. * [`enclose_ipv6`](#enclose_ipv6): Takes an array of ip addresses and encloses the ipv6 addresses with square brackets. * [`ensure_packages`](#ensure_packages): Takes a list of packages and only installs them if they don't already exist. -* [`ensure_resource`](#ensure_resource) -* [`ensure_resources`](#ensure_resources) +* [`ensure_resource`](#ensure_resource): Takes a resource type, title, and a list of attributes that describe a +resource. +* [`ensure_resources`](#ensure_resources): Takes a resource type, title (only hash), and a list of attributes that describe a +resource. * [`fact`](#fact): Digs into the facts hash using dot-notation * [`flatten`](#flatten): This function flattens any deeply nested arrays and returns a single flat array as a result. * [`floor`](#floor): Returns the largest integer less or equal to the argument. -* [`fqdn_rand_string`](#fqdn_rand_string) -* [`fqdn_rotate`](#fqdn_rotate): fqdn_rotate.rb +* [`fqdn_rand_string`](#fqdn_rand_string): Generates a random alphanumeric string. Combining the `$fqdn` fact and an +optional seed for repeatable randomness. +* [`fqdn_rotate`](#fqdn_rotate): Rotates an array or string a random number of times, combining the `$fqdn` fact +and an optional seed for repeatable randomness. * [`fqdn_uuid`](#fqdn_uuid): Returns a [RFC 4122](https://tools.ietf.org/html/rfc4122) valid version 5 UUID based on an FQDN string under the DNS namespace * [`get_module_path`](#get_module_path): Returns the absolute path of the specified module for the current environment. -* [`getparam`](#getparam) +* [`getparam`](#getparam): Returns the value of a resource's parameter. * [`getvar`](#getvar): Lookup a variable in a given namespace. * [`glob`](#glob): Uses same patterns as Dir#glob. * [`grep`](#grep): This function searches through an array and returns any elements that match @@ -136,7 +141,7 @@ Puppet structure Puppet structure. * [`parseyaml`](#parseyaml): This function accepts YAML as a string and converts it into the correct Puppet structure. -* [`pick`](#pick): This function is similar to a coalesce function in SQL in that it will return +* [`pick`](#pick): This function will return the first value in a list of values that is not undefined or an empty string. * [`pick_default`](#pick_default): This function will return the first value in a list of values that is not undefined or an empty string. * [`powershell_escape`](#powershell_escape): Escapes a string so that it can be safely used in a PowerShell command line. @@ -144,7 +149,8 @@ the first value in a list of values that is not undefined or an empty string. * [`private`](#private): **Deprecated:** Sets the current class or definition as private. Calling the class or definition from outside the current module will fail. * [`pry`](#pry): This function invokes a pry debugging session in the current scope object. -* [`pw_hash`](#pw_hash): Please note: This function is an implementation of a Ruby class and as such may not be entirely UTF8 compatible. To ensure compatibility ple +* [`pw_hash`](#pw_hash): Hashes a password using the crypt function. Provides a hash usable +on most POSIX systems. * [`range`](#range): When given range in the form of (start, stop) it will extrapolate a range as an array. * [`regexpescape`](#regexpescape): Regexp escape a string or array of strings. @@ -154,7 +160,7 @@ the provided regular expression. * [`reverse`](#reverse): Reverses the order of a string or array. * [`round`](#round): Rounds a number to the nearest integer * [`rstrip`](#rstrip): Strips leading spaces to the right of the string. -* [`seeded_rand`](#seeded_rand): seeded_rand.rb +* [`seeded_rand`](#seeded_rand): Generates a random whole number greater than or equal to 0 and less than MAX, using the value of SEED for repeatable randomness. * [`seeded_rand_string`](#seeded_rand_string): Generates a consistent random string of specific length based on provided seed. * [`shell_escape`](#shell_escape): Escapes a string so that it can be safely used in a Bourne shell command line. * [`shell_join`](#shell_join): Builds a command line string from the given array of strings. Each array item is escaped for Bourne shell. All items are then joined together @@ -171,16 +177,6 @@ last Period). * [`stdlib::ip_in_range`](#stdlibip_in_range): Returns true if the ipaddress is within the given CIDRs * [`stdlib::start_with`](#stdlibstart_with): Returns true if str starts with one of the prefixes given. Each of the prefixes should be a String. * [`stdlib::str2resource`](#stdlibstr2resource): This converts a string to a puppet resource. - -This attempts to convert a string like 'File[/foo]' into the -puppet resource `File['/foo']` as detected by the catalog. - -Things like 'File[/foo, /bar]' are not supported as a -title might contain things like ',' or ' '. There is -no clear value seperator to use. - -This function can depend on the parse order of your -manifests/modules as it inspects the catalog thus far. * [`stdlib::xml_encode`](#stdlibxml_encode): Encode strings for XML files * [`str2bool`](#str2bool): This converts a string to a boolean. * [`str2saltedpbkdf2`](#str2saltedpbkdf2): Convert a string into a salted SHA512 PBKDF2 password hash like requred for OS X / macOS 10.8+ @@ -193,13 +189,13 @@ in a hash. * [`swapcase`](#swapcase): This function will swap the existing case of a string. * [`time`](#time): This function will return the current time since epoch as an integer. * [`to_bytes`](#to_bytes): Converts the argument into bytes, for example 4 kB becomes 4096. -* [`to_json`](#to_json): } +* [`to_json`](#to_json): Convert a data structure and output to JSON * [`to_json_pretty`](#to_json_pretty): Convert data structure and output to pretty JSON * [`to_python`](#to_python): Convert an object into a String containing its Python representation * [`to_ruby`](#to_ruby): Convert an object into a String containing its Ruby representation * [`to_toml`](#to_toml): Convert a data structure and output to TOML. -* [`to_yaml`](#to_yaml): } -* [`try_get_value`](#try_get_value) +* [`to_yaml`](#to_yaml): Convert a data structure and output it as YAML +* [`try_get_value`](#try_get_value): **DEPRECATED:** this function is deprecated, please use dig() instead. * [`type`](#type): **DEPRECATED:** This function will cease to function on Puppet 4; * [`type3x`](#type3x): **DEPRECATED:** This function will be removed when Puppet 3 support is dropped; please migrate to the new parser's typing system. * [`type_of`](#type_of): Returns the type of the passed value. @@ -248,13 +244,10 @@ expressions. expressions. * [`validate_slength`](#validate_slength): Validate that a passed string has length less/equal with the passed value * [`validate_slength`](#validate_slength): Validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument. -An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings, -and if arg 2 and arg 3 are not convertable to a number. * [`validate_string`](#validate_string): Validate that all passed values are string data structures. * [`validate_string`](#validate_string): Validate that all passed values are string data structures * [`validate_x509_rsa_key_pair`](#validate_x509_rsa_key_pair): Validates a PEM-formatted X.509 certificate and RSA private key using -OpenSSL. Verifies that the certficate's signature was created from the -supplied key. +OpenSSL. * [`values`](#values): When given a hash this function will return the values of that hash. * [`values_at`](#values_at): Finds value inside an array based on location. * [`zip`](#zip): Takes one element from first array and merges corresponding elements from second array. @@ -264,60 +257,60 @@ supplied key. * [`Stdlib::Absolutepath`](#stdlibabsolutepath): A strict absolutepath type * [`Stdlib::Base32`](#stdlibbase32): Type to match base32 String * [`Stdlib::Base64`](#stdlibbase64): Type to match base64 String -* [`Stdlib::Compat::Absolute_path`](#stdlibcompatabsolute_path): Emulate the is_absolute_path and validate_absolute_path functions The first pattern is originally from is_absolute_path, which had it from 2 +* [`Stdlib::Compat::Absolute_path`](#stdlibcompatabsolute_path): Emulate the is_absolute_path and validate_absolute_path functions * [`Stdlib::Compat::Array`](#stdlibcompatarray): Emulate the is_array and validate_array functions * [`Stdlib::Compat::Bool`](#stdlibcompatbool): Emulate the is_bool and validate_bool functions -* [`Stdlib::Compat::Float`](#stdlibcompatfloat): Emulate the is_float function The regex is what's currently used in is_float To keep your development moving forward, you can also add a depr +* [`Stdlib::Compat::Float`](#stdlibcompatfloat): Emulate the is_float function * [`Stdlib::Compat::Hash`](#stdlibcompathash): Emulate the is_hash and validate_hash functions -* [`Stdlib::Compat::Integer`](#stdlibcompatinteger): Emulate the is_integer and validate_integer functions The regex is what's currently used in is_integer validate_numeric also allows range che -* [`Stdlib::Compat::Ip_address`](#stdlibcompatip_address) +* [`Stdlib::Compat::Integer`](#stdlibcompatinteger): Emulate the is_integer and validate_integer functions +* [`Stdlib::Compat::Ip_address`](#stdlibcompatip_address): Validate an IP address * [`Stdlib::Compat::Ipv4`](#stdlibcompatipv4): Emulate the validate_ipv4_address and is_ipv4_address functions -* [`Stdlib::Compat::Ipv6`](#stdlibcompatipv6) -* [`Stdlib::Compat::Numeric`](#stdlibcompatnumeric): Emulate the is_numeric and validate_numeric functions The regex is what's currently used in is_numeric validate_numeric also allows range che +* [`Stdlib::Compat::Ipv6`](#stdlibcompatipv6): Validate an IPv6 address +* [`Stdlib::Compat::Numeric`](#stdlibcompatnumeric): Emulate the is_numeric and validate_numeric functions * [`Stdlib::Compat::String`](#stdlibcompatstring): Emulate the is_string and validate_string functions -* [`Stdlib::Datasize`](#stdlibdatasize) -* [`Stdlib::Email`](#stdlibemail): https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address lint:ignore:140chars -* [`Stdlib::Ensure::File`](#stdlibensurefile) -* [`Stdlib::Ensure::File::Directory`](#stdlibensurefiledirectory) -* [`Stdlib::Ensure::File::File`](#stdlibensurefilefile) -* [`Stdlib::Ensure::File::Link`](#stdlibensurefilelink) -* [`Stdlib::Ensure::Service`](#stdlibensureservice) -* [`Stdlib::Filemode`](#stdlibfilemode): See `man chmod.1` for the regular expression for symbolic mode lint:ignore:140chars +* [`Stdlib::Datasize`](#stdlibdatasize): Validate the size of data +* [`Stdlib::Email`](#stdlibemail): Validate an e-mail address +* [`Stdlib::Ensure::File`](#stdlibensurefile): Validate the value of the ensure parameter for a file +* [`Stdlib::Ensure::File::Directory`](#stdlibensurefiledirectory): Validate the ensure parameter of a "directory" file resource +* [`Stdlib::Ensure::File::File`](#stdlibensurefilefile): Validate the ensure parameter of a "file" file resource +* [`Stdlib::Ensure::File::Link`](#stdlibensurefilelink): Validate the ensure parameter of a "link" file resource +* [`Stdlib::Ensure::Service`](#stdlibensureservice): Validate the value of the ensure parameter of a service resource +* [`Stdlib::Filemode`](#stdlibfilemode): Validate a file mode * [`Stdlib::Filesource`](#stdlibfilesource): Validate the source parameter on file types -* [`Stdlib::Fqdn`](#stdlibfqdn) -* [`Stdlib::HTTPSUrl`](#stdlibhttpsurl) -* [`Stdlib::HTTPUrl`](#stdlibhttpurl) -* [`Stdlib::Host`](#stdlibhost) -* [`Stdlib::HttpStatus`](#stdlibhttpstatus) -* [`Stdlib::IP::Address`](#stdlibipaddress) -* [`Stdlib::IP::Address::Nosubnet`](#stdlibipaddressnosubnet) -* [`Stdlib::IP::Address::V4`](#stdlibipaddressv4) +* [`Stdlib::Fqdn`](#stdlibfqdn): Validate a Fully Qualified Domain Name +* [`Stdlib::HTTPSUrl`](#stdlibhttpsurl): Validate a HTTPS URL +* [`Stdlib::HTTPUrl`](#stdlibhttpurl): Validate a HTTP(S) URL +* [`Stdlib::Host`](#stdlibhost): Validate a host (FQDN or IP address) +* [`Stdlib::HttpStatus`](#stdlibhttpstatus): Validate a HTTP status code +* [`Stdlib::IP::Address`](#stdlibipaddress): Validate an IP address +* [`Stdlib::IP::Address::Nosubnet`](#stdlibipaddressnosubnet): Validate an IP address without subnet +* [`Stdlib::IP::Address::V4`](#stdlibipaddressv4): Validate an IPv4 address * [`Stdlib::IP::Address::V4::CIDR`](#stdlibipaddressv4cidr): lint:ignore:140chars * [`Stdlib::IP::Address::V4::Nosubnet`](#stdlibipaddressv4nosubnet): lint:ignore:140chars -* [`Stdlib::IP::Address::V6`](#stdlibipaddressv6) +* [`Stdlib::IP::Address::V6`](#stdlibipaddressv6): Validate an IPv6 address * [`Stdlib::IP::Address::V6::Alternative`](#stdlibipaddressv6alternative): lint:ignore:140chars * [`Stdlib::IP::Address::V6::CIDR`](#stdlibipaddressv6cidr): lint:ignore:140chars -* [`Stdlib::IP::Address::V6::Compressed`](#stdlibipaddressv6compressed) -* [`Stdlib::IP::Address::V6::Full`](#stdlibipaddressv6full) -* [`Stdlib::IP::Address::V6::Nosubnet`](#stdlibipaddressv6nosubnet) +* [`Stdlib::IP::Address::V6::Compressed`](#stdlibipaddressv6compressed): Validate a compressed IPv6 address +* [`Stdlib::IP::Address::V6::Full`](#stdlibipaddressv6full): Validate a full IPv6 address +* [`Stdlib::IP::Address::V6::Nosubnet`](#stdlibipaddressv6nosubnet): Validate an IPv6 address without subnet * [`Stdlib::IP::Address::V6::Nosubnet::Alternative`](#stdlibipaddressv6nosubnetalternative): lint:ignore:140chars -* [`Stdlib::IP::Address::V6::Nosubnet::Compressed`](#stdlibipaddressv6nosubnetcompressed) -* [`Stdlib::IP::Address::V6::Nosubnet::Full`](#stdlibipaddressv6nosubnetfull) +* [`Stdlib::IP::Address::V6::Nosubnet::Compressed`](#stdlibipaddressv6nosubnetcompressed): Validate compressed IPv6 address without subnet +* [`Stdlib::IP::Address::V6::Nosubnet::Full`](#stdlibipaddressv6nosubnetfull): Validate full IPv6 address without subnet * [`Stdlib::MAC`](#stdlibmac): A type for a MAC address -* [`Stdlib::ObjectStore`](#stdlibobjectstore) -* [`Stdlib::ObjectStore::GSUri`](#stdlibobjectstoregsuri) -* [`Stdlib::ObjectStore::S3Uri`](#stdlibobjectstores3uri) -* [`Stdlib::Port`](#stdlibport) -* [`Stdlib::Port::Dynamic`](#stdlibportdynamic) -* [`Stdlib::Port::Ephemeral`](#stdlibportephemeral) -* [`Stdlib::Port::Privileged`](#stdlibportprivileged) -* [`Stdlib::Port::Registered`](#stdlibportregistered) -* [`Stdlib::Port::Unprivileged`](#stdlibportunprivileged) -* [`Stdlib::Port::User`](#stdlibportuser) -* [`Stdlib::Syslogfacility`](#stdlibsyslogfacility) -* [`Stdlib::Unixpath`](#stdlibunixpath): this regex rejects any path component that does not start with "/" or is NUL -* [`Stdlib::Windowspath`](#stdlibwindowspath) -* [`Stdlib::Yes_no`](#stdlibyes_no) +* [`Stdlib::ObjectStore`](#stdlibobjectstore): Validate an ObjectStore +* [`Stdlib::ObjectStore::GSUri`](#stdlibobjectstoregsuri): Validate a Google Cloud object store URI +* [`Stdlib::ObjectStore::S3Uri`](#stdlibobjectstores3uri): Validate an Amazon Web Services S3 object store URI +* [`Stdlib::Port`](#stdlibport): Validate a port number +* [`Stdlib::Port::Dynamic`](#stdlibportdynamic): Validate a dynamic port number +* [`Stdlib::Port::Ephemeral`](#stdlibportephemeral): Validate an ephemeral port number +* [`Stdlib::Port::Privileged`](#stdlibportprivileged): Validate a priviliged port number +* [`Stdlib::Port::Registered`](#stdlibportregistered): Validate a registered port number +* [`Stdlib::Port::Unprivileged`](#stdlibportunprivileged): Validate an unprivileged port number +* [`Stdlib::Port::User`](#stdlibportuser): Validate a port number usable by a user +* [`Stdlib::Syslogfacility`](#stdlibsyslogfacility): Validate a syslog facility +* [`Stdlib::Unixpath`](#stdlibunixpath): Validate a UNIX path +* [`Stdlib::Windowspath`](#stdlibwindowspath): Validate a Windows path +* [`Stdlib::Yes_no`](#stdlibyes_no): Validate a yes / no value ## Classes @@ -340,15 +333,6 @@ There is limited support for `before`, `require`, `notify`, and `subscribe`. However, the target resources must be defined before this module is run. -stdlib::manage::create_resources: - file: - '/etc/motd.d/hello': - content: I say Hi - notify: 'Service[sshd]' - package: - example: - ensure: installed - #### Examples ##### @@ -370,6 +354,19 @@ class { 'stdlib::manage': } ``` +##### + +```puppet +stdlib::manage::create_resources: + file: + '/etc/motd.d/hello': + content: I say Hi + notify: 'Service[sshd]' + package: + example: + ensure: installed +``` + #### Parameters The following parameters are available in the `stdlib::manage` class: @@ -1339,13 +1336,35 @@ When there is a duplicate key that is not a hash, the key in the rightmost hash Type: Ruby 3.x API -The defined_with_params function. +Returns `true` if a resource with the specified attributes has already been added +to the catalog, and `false` otherwise. + + ``` + user { 'dan': + ensure => present, + } + + if ! defined_with_params(User[dan], {'ensure' => 'present' }) { + user { 'dan': ensure => present, } + } + ``` #### `defined_with_params()` -The defined_with_params function. +Returns `true` if a resource with the specified attributes has already been added +to the catalog, and `false` otherwise. + + ``` + user { 'dan': + ensure => present, + } + + if ! defined_with_params(User[dan], {'ensure' => 'present' }) { + user { 'dan': ensure => present, } + } + ``` -Returns: `Any` +Returns: `Boolean` returns `true` or `false` ### `delete` @@ -1810,13 +1829,69 @@ the value at the end of the path. Type: Ruby 3.x API -The dig44 function. +Key can contain slashes to describe path components. The function will go down +the structure and try to extract the required value. + +``` +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = dig44($data, ['a', 'b', 2]) +# $value = 'b3' + +# with all possible options +$value = dig44($data, ['a', 'b', 2], 'not_found') +# $value = 'b3' + +# using the default value +$value = dig44($data, ['a', 'b', 'c', 'd'], 'not_found') +# $value = 'not_found' +``` + +> **Note:* **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. #### `dig44()` -The dig44 function. +Key can contain slashes to describe path components. The function will go down +the structure and try to extract the required value. -Returns: `Any` +``` +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = dig44($data, ['a', 'b', 2]) +# $value = 'b3' + +# with all possible options +$value = dig44($data, ['a', 'b', 2], 'not_found') +# $value = 'b3' + +# using the default value +$value = dig44($data, ['a', 'b', 'c', 'd'], 'not_found') +# $value = 'not_found' +``` + +> **Note:* **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. + +Returns: `String` 'not_found' will be returned if nothing is found ### `dirname` @@ -1907,25 +1982,123 @@ Returns: `Any` install the passed packages Type: Ruby 3.x API -The ensure_resource function. +user { 'dan': + ensure => present, +} + +#### Examples + +##### Example usage + +```puppet + +Creates the resource if it does not already exist: + + ensure_resource('user', 'dan', {'ensure' => 'present' }) + +If the resource already exists but does not match the specified parameters, +this function will attempt to recreate the resource leading to a duplicate +resource definition error. + +An array of resources can also be passed in and each will be created with +the type and parameters specified if it doesn't already exist. + + ensure_resource('user', ['dan','alex'], {'ensure' => 'present'}) +``` #### `ensure_resource()` -The ensure_resource function. +user { 'dan': + ensure => present, +} + +Returns: `Any` created or recreated the passed resource with the passed type and attributes + +##### Examples -Returns: `Any` +###### Example usage + +```puppet + +Creates the resource if it does not already exist: + + ensure_resource('user', 'dan', {'ensure' => 'present' }) + +If the resource already exists but does not match the specified parameters, +this function will attempt to recreate the resource leading to a duplicate +resource definition error. + +An array of resources can also be passed in and each will be created with +the type and parameters specified if it doesn't already exist. + + ensure_resource('user', ['dan','alex'], {'ensure' => 'present'}) +``` ### `ensure_resources` Type: Ruby 3.x API -The ensure_resources function. +An hash of resources should be passed in and each will be created with + the type and parameters specified if it doesn't already exist. + + ensure_resources('user', {'dan' => { gid => 'mygroup', uid => '600' }, 'alex' => { gid => 'mygroup' }}, {'ensure' => 'present'}) + + From Hiera Backend: + + userlist: + dan: + gid: 'mygroup' + uid: '600' + alex: + gid: 'mygroup' + + Call: + ensure_resources('user', hiera_hash('userlist'), {'ensure' => 'present'}) + +#### Examples + +##### Example usage + +```puppet + +user { 'dan': + gid => 'mygroup', + ensure => present, +} +``` #### `ensure_resources()` -The ensure_resources function. +An hash of resources should be passed in and each will be created with + the type and parameters specified if it doesn't already exist. + + ensure_resources('user', {'dan' => { gid => 'mygroup', uid => '600' }, 'alex' => { gid => 'mygroup' }}, {'ensure' => 'present'}) + + From Hiera Backend: + + userlist: + dan: + gid: 'mygroup' + uid: '600' + alex: + gid: 'mygroup' + + Call: + ensure_resources('user', hiera_hash('userlist'), {'ensure' => 'present'}) + +Returns: `Any` created resources with the passed type and attributes -Returns: `Any` +##### Examples + +###### Example usage + +```puppet + +user { 'dan': + gid => 'mygroup', + ensure => present, +} +``` ### `fact` @@ -2043,25 +2216,76 @@ Returns: `Any` the largest integer less or equal to the argument. Type: Ruby 3.x API -The fqdn_rand_string function. +Optionally, you can specify a character set for the function (defaults to alphanumeric). + +Arguments +* An integer, specifying the length of the resulting string. +* Optionally, a string specifying the character set. +* Optionally, a string specifying the seed for repeatable randomness. + +#### Examples + +##### Example Usage: + +```puppet +fqdn_rand_string(10) +fqdn_rand_string(10, 'ABCDEF!@$%^') +fqdn_rand_string(10, '', 'custom seed') +``` #### `fqdn_rand_string()` -The fqdn_rand_string function. +Optionally, you can specify a character set for the function (defaults to alphanumeric). + +Arguments +* An integer, specifying the length of the resulting string. +* Optionally, a string specifying the character set. +* Optionally, a string specifying the seed for repeatable randomness. + +Returns: `String` + +##### Examples + +###### Example Usage: -Returns: `Any` +```puppet +fqdn_rand_string(10) +fqdn_rand_string(10, 'ABCDEF!@$%^') +fqdn_rand_string(10, '', 'custom seed') +``` ### `fqdn_rotate` Type: Ruby 3.x API -fqdn_rotate.rb +Rotates an array or string a random number of times, combining the `$fqdn` fact +and an optional seed for repeatable randomness. + +#### Examples + +##### Example Usage: + +```puppet +fqdn_rotate(['a', 'b', 'c', 'd']) +fqdn_rotate('abcd') +fqdn_rotate([1, 2, 3], 'custom seed') +``` #### `fqdn_rotate()` -fqdn_rotate.rb +The fqdn_rotate function. -Returns: `Any` +Returns: `Any` rotated array or string + +##### Examples + +###### Example Usage: + +```puppet +fqdn_rotate(['a', 'b', 'c', 'd']) +fqdn_rotate('abcd') +fqdn_rotate([1, 2, 3], 'custom seed') +``` ### `fqdn_uuid` @@ -2135,13 +2359,83 @@ $module_path = get_module_path('stdlib') Type: Ruby 3.x API -The getparam function. +Takes a resource reference and name of the parameter and +returns value of resource's parameter. Note that user defined +resource types are evaluated lazily. + +Would notice: 'the value we are getting in this example' + +> **Note** that since Puppet 4.0.0 it is possible to get a parameter value by using its data type +and the [ ] operator. The example below is equivalent to a call to getparam(): + ```Example_resource['example_resource_instance']['param']`` + +#### Examples + +##### Example Usage: + +```puppet + +# define a resource type with a parameter +define example_resource($param) { +} + +# declare an instance of that type +example_resource { "example_resource_instance": + param => "'the value we are getting in this example''" +} + +# 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': } +``` #### `getparam()` -The getparam function. +Takes a resource reference and name of the parameter and +returns value of resource's parameter. Note that user defined +resource types are evaluated lazily. + +Would notice: 'the value we are getting in this example' -Returns: `Any` +> **Note** that since Puppet 4.0.0 it is possible to get a parameter value by using its data type +and the [ ] operator. The example below is equivalent to a call to getparam(): + ```Example_resource['example_resource_instance']['param']`` + +Returns: `Any` value of a resource's parameter. + +##### Examples + +###### Example Usage: + +```puppet + +# define a resource type with a parameter +define example_resource($param) { +} + +# declare an instance of that type +example_resource { "example_resource_instance": + param => "'the value we are getting in this example''" +} + +# 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': } +``` ### `getvar` @@ -3570,7 +3864,7 @@ $data = parsehocon("{any valid hocon: string}") The parsehocon function. -Returns: `Any` +Returns: `Data` ##### Examples @@ -3628,6 +3922,8 @@ Returns: `Any` converted YAML into Puppet structure Type: Ruby 3.x API +This function is similar to a coalesce function in SQL. + 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: @@ -3641,6 +3937,8 @@ Dashboard/Enterprise Console, and failover to a default value like the following #### `pick()` +This function is similar to a coalesce function in SQL. + 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: @@ -3799,15 +4097,55 @@ Returns: `Any` debugging information Type: Ruby 3.x API -Please note: This function is an implementation of a Ruby class and as such may not be entirely UTF8 compatible. - To ensure compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085. +The first argument to this function is the password to hash. If it is +undef or an empty string, this function returns undef. + +The second argument to this function is which hash algorithm to use. It +will be converted into the appropriate crypt(3) hash specifier. Valid +hash types are: + +|Hash type|Prefix|Note | +|---------|------|---------------------| +|MD5 |1 | | +|SHA-256 |5 | | +|SHA-512 |6 |Recommended | +|bcrypt |2b | | +|bcrypt-a |2a |bug compatible | +|bcrypt-x |2x |bug compatible | +|bcrypt-y |2y |historic alias for 2b| + +The third argument to this function is the salt to use. + +> *Note:*: this uses the Puppet Server's implementation of crypt(3). If your + environment contains several different operating systems, ensure that they + are compatible before using this function. #### `pw_hash()` -Please note: This function is an implementation of a Ruby class and as such may not be entirely UTF8 compatible. - To ensure compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085. +The first argument to this function is the password to hash. If it is +undef or an empty string, this function returns undef. + +The second argument to this function is which hash algorithm to use. It +will be converted into the appropriate crypt(3) hash specifier. Valid +hash types are: + +|Hash type|Prefix|Note | +|---------|------|---------------------| +|MD5 |1 | | +|SHA-256 |5 | | +|SHA-512 |6 |Recommended | +|bcrypt |2b | | +|bcrypt-a |2a |bug compatible | +|bcrypt-x |2x |bug compatible | +|bcrypt-y |2y |historic alias for 2b| + +The third argument to this function is the salt to use. -Returns: `Any` +> *Note:*: this uses the Puppet Server's implementation of crypt(3). If your + environment contains several different operating systems, ensure that they + are compatible before using this function. + +Returns: `String` Provides a crypt hash usable on most POSIX systems. ### `range` @@ -3950,24 +4288,34 @@ Returns: `Any` reversed string or array Type: Ruby 3.x API -```round(2.9)``` returns ```3``` - -```round(2.4)``` returns ```2``` - > *Note:* from Puppet 6.0.0, the compatible function with the same name in Puppet core will be used instead of this function. -#### `round()` +#### Examples -```round(2.9)``` returns ```3``` +##### Example usage -```round(2.4)``` returns ```2``` +```puppet +round(2.9) #=> 3 +round(2.4) #=> 2 +``` + +#### `round()` > *Note:* from Puppet 6.0.0, the compatible function with the same name in Puppet core will be used instead of this function. Returns: `Any` the rounded value as integer +##### Examples + +###### Example usage + +```puppet +round(2.9) #=> 3 +round(2.4) #=> 2 +``` + ### `rstrip` Type: Ruby 3.x API @@ -3986,13 +4334,35 @@ Returns: `Any` the string with leading spaces removed Type: Ruby 3.x API -seeded_rand.rb +Generates a random whole number greater than or equal to 0 and less +than MAX, using the value of SEED for repeatable randomness. If SEED +starts with "$fqdn:", this is behaves the same as `fqdn_rand`. + +#### Examples + +##### **Usage:** + +```puppet +seeded_rand(MAX, SEED). +MAX must be a positive integer; SEED is any string. +``` #### `seeded_rand()` -seeded_rand.rb +Generates a random whole number greater than or equal to 0 and less +than MAX, using the value of SEED for repeatable randomness. If SEED +starts with "$fqdn:", this is behaves the same as `fqdn_rand`. -Returns: `Any` +Returns: `Any` random number greater than or equal to 0 and less than MAX + +##### Examples + +###### **Usage:** + +```puppet +seeded_rand(MAX, SEED). +MAX must be a positive integer; SEED is any string. +``` ### `seeded_rand_string` @@ -4421,8 +4791,6 @@ The prefixes to check. Type: Ruby 4.x API -This converts a string to a puppet resource. - This attempts to convert a string like 'File[/foo]' into the puppet resource `File['/foo']` as detected by the catalog. @@ -4443,7 +4811,15 @@ stdlib::str2resource('File[/foo]') => File[/foo] #### `stdlib::str2resource(String $res_string)` -The stdlib::str2resource function. +This attempts to convert a string like 'File[/foo]' into the +puppet resource `File['/foo']` as detected by the catalog. + +Things like 'File[/foo, /bar]' are not supported as a +title might contain things like ',' or ' '. There is +no clear value seperator to use. + +This function can depend on the parse order of your +manifests/modules as it inspects the catalog thus far. Returns: `Any` Puppet::Resource @@ -4788,14 +5164,36 @@ Returns: `Any` converted value into bytes Type: Ruby 4.x API +Convert a data structure and output to JSON + +#### Examples + +##### Output JSON to a file + +```puppet +file { '/tmp/my.json': + ensure => file, + content => to_json($myhash), } +``` #### `to_json(Any $data)` -} +Convert a data structure and output to JSON Returns: `String` Converted data to JSON +##### Examples + +###### Output JSON to a file + +```puppet +file { '/tmp/my.json': + ensure => file, + content => to_json($myhash), +} +``` + ##### `data` Data type: `Any` @@ -4940,7 +5338,7 @@ file { '/opt/acme/etc/settings.py': The to_python function. -Returns: `Any` +Returns: `String` The String representation of the object ##### Examples @@ -4962,7 +5360,7 @@ file { '/opt/acme/etc/settings.py': Data type: `Any` - +The object to be converted ### `to_ruby` @@ -4990,7 +5388,7 @@ file { '/opt/acme/etc/settings.rb': The to_ruby function. -Returns: `Any` +Returns: `String` The String representation of the object ##### Examples @@ -5012,7 +5410,7 @@ file { '/opt/acme/etc/settings.rb': Data type: `Any` - +The object to be converted ### `to_toml` @@ -5058,14 +5456,54 @@ Data structure which needs to be converted into TOML Type: Ruby 4.x API +Convert a data structure and output it as YAML + +#### Examples + +##### Output YAML to a file + +```puppet +file { '/tmp/my.yaml': + ensure => file, + content => to_yaml($myhash), } +``` -#### `to_yaml(Any $data, Optional[Hash] $options)` +##### Use options to control the output format +```puppet +file { '/tmp/my.yaml': + ensure => file, + content => to_yaml($myhash, {indentation => 4}) } +``` + +#### `to_yaml(Any $data, Optional[Hash] $options)` + +Convert a data structure and output it as YAML Returns: `String` The YAML document +##### Examples + +###### Output YAML to a file + +```puppet +file { '/tmp/my.yaml': + ensure => file, + content => to_yaml($myhash), +} +``` + +###### Use options to control the output format + +```puppet +file { '/tmp/my.yaml': + ensure => file, + content => to_yaml($myhash, {indentation => 4}) +} +``` + ##### `data` Data type: `Any` @@ -5082,13 +5520,68 @@ A hash of options that will be passed to Ruby's Psych library. Note, this could Type: Ruby 3.x API -The try_get_value function. +Key can contain slashes to describe path components. The function will go down +the structure and try to extract the required value. +`` +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = try_get_value($data, 'a/b/2', 'not_found', '/') +=> $value = 'b3' +``` +``` +a -> first hash key +b -> second hash key +2 -> array index starting with 0 + +not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil. +/ -> (optional) path delimiter. Defaults to '/'. +``` + +In addition to the required "key" argument, "try_get_value" accepts default +argument. It will be returned if no value was found or a path component is +missing. And the fourth argument can set a variable path separator. #### `try_get_value()` -The try_get_value function. +Key can contain slashes to describe path components. The function will go down +the structure and try to extract the required value. +`` +$data = { + 'a' => { + 'b' => [ + 'b1', + 'b2', + 'b3', + ] + } +} + +$value = try_get_value($data, 'a/b/2', 'not_found', '/') +=> $value = 'b3' +``` +``` +a -> first hash key +b -> second hash key +2 -> array index starting with 0 + +not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil. +/ -> (optional) path delimiter. Defaults to '/'. +``` + +In addition to the required "key" argument, "try_get_value" accepts default +argument. It will be returned if no value was found or a path component is +missing. And the fourth argument can set a variable path separator. -Returns: `Any` +Returns: `Any` Looks up into a complex structure of arrays and hashes and returns a value +or the default value if nothing was found. ### `type` @@ -6504,7 +6997,6 @@ Any additional values that are to be passed to the method Type: Ruby 3.x API -Validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument. An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings, and if arg 2 and arg 3 are not convertable to a number. @@ -6528,7 +7020,8 @@ The following valueis will not: #### `validate_slength()` -The validate_slength function. +An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings, +and if arg 2 and arg 3 are not convertable to a number. Returns: `Any` validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument. Fail compilation if any of the checks fail. @@ -6638,10 +7131,16 @@ The following values will fail, causing compilation to abort: Type: Ruby 3.x API +Verifies that the certficate's signature was created from the +supplied key. + ```validate_x509_rsa_key_pair($cert, $key)``` #### `validate_x509_rsa_key_pair()` +Verifies that the certficate's signature was created from the +supplied key. + ```validate_x509_rsa_key_pair($cert, $key)``` Returns: `Any` Fail compilation if any value fails this check. @@ -6826,8 +7325,6 @@ Pattern[/\A[a-zA-Z0-9\/\+]+={,2}\z/] ### `Stdlib::Compat::Absolute_path` -Emulate the is_absolute_path and validate_absolute_path functions - The first pattern is originally from is_absolute_path, which had it from 2.7.x's lib/puppet/util.rb Puppet::Util.absolute_path? slash = '[\\\\/]' name = '[^\\\\/]+' @@ -6861,7 +7358,6 @@ Boolean ### `Stdlib::Compat::Float` -Emulate the is_float function The regex is what's currently used in is_float To keep your development moving forward, you can also add a deprecation warning using the Integer type: @@ -6898,7 +7394,6 @@ Hash[Any, Any] ### `Stdlib::Compat::Integer` -Emulate the is_integer and validate_integer functions The regex is what's currently used in is_integer validate_numeric also allows range checking, which cannot be mapped to the string parsing inside the function. For full backwards compatibility, you will need to keep the validate_numeric call around to catch everything. @@ -6929,7 +7424,7 @@ Variant[Integer, Pattern[/^-?(?:(?:[1-9]\d*)|0)$/], Array[Variant[Integer, Patte ### `Stdlib::Compat::Ip_address` -The Stdlib::Compat::Ip_address data type. +Validate an IP address Alias of @@ -6949,7 +7444,7 @@ Pattern[/^((([0-9](?!\d)|[1-9][0-9](?!\d)|1[0-9]{2}(?!\d)|2[0-4][0-9](?!\d)|25[0 ### `Stdlib::Compat::Ipv6` -The Stdlib::Compat::Ipv6 data type. +Validate an IPv6 address Alias of @@ -6959,7 +7454,6 @@ Pattern[/\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6 ### `Stdlib::Compat::Numeric` -Emulate the is_numeric and validate_numeric functions The regex is what's currently used in is_numeric validate_numeric also allows range checking, which cannot be mapped to the string parsing inside the function. For full backwards compatibility, you will need to keep the validate_numeric call around to catch everything. @@ -7000,7 +7494,7 @@ Optional[String] ### `Stdlib::Datasize` -The Stdlib::Datasize data type. +Validate the size of data Alias of @@ -7021,7 +7515,7 @@ Pattern[/\A[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a- ### `Stdlib::Ensure::File` -The Stdlib::Ensure::File data type. +Validate the value of the ensure parameter for a file Alias of @@ -7031,7 +7525,7 @@ Enum['present', 'file', 'directory', 'link', 'absent'] ### `Stdlib::Ensure::File::Directory` -The Stdlib::Ensure::File::Directory data type. +Validate the ensure parameter of a "directory" file resource Alias of @@ -7041,7 +7535,7 @@ Enum['directory', 'absent'] ### `Stdlib::Ensure::File::File` -The Stdlib::Ensure::File::File data type. +Validate the ensure parameter of a "file" file resource Alias of @@ -7051,7 +7545,7 @@ Enum['file', 'absent'] ### `Stdlib::Ensure::File::Link` -The Stdlib::Ensure::File::Link data type. +Validate the ensure parameter of a "link" file resource Alias of @@ -7061,7 +7555,7 @@ Enum['link', 'absent'] ### `Stdlib::Ensure::Service` -The Stdlib::Ensure::Service data type. +Validate the value of the ensure parameter of a service resource Alias of @@ -7095,7 +7589,7 @@ Variant[Stdlib::Absolutepath, Stdlib::HTTPUrl, Pattern[ ### `Stdlib::Fqdn` -The Stdlib::Fqdn data type. +Validate a Fully Qualified Domain Name Alias of @@ -7105,7 +7599,7 @@ Pattern[/\A(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[ ### `Stdlib::HTTPSUrl` -The Stdlib::HTTPSUrl data type. +Validate a HTTPS URL Alias of @@ -7115,7 +7609,7 @@ Pattern[/(?i:\Ahttps:\/\/.*\z)/] ### `Stdlib::HTTPUrl` -The Stdlib::HTTPUrl data type. +Validate a HTTP(S) URL Alias of @@ -7125,7 +7619,7 @@ Pattern[/(?i:\Ahttps?:\/\/.*\z)/] ### `Stdlib::Host` -The Stdlib::Host data type. +Validate a host (FQDN or IP address) Alias of @@ -7135,7 +7629,7 @@ Variant[Stdlib::Fqdn, Stdlib::Compat::Ip_address] ### `Stdlib::HttpStatus` -The Stdlib::HttpStatus data type. +Validate a HTTP status code Alias of @@ -7145,7 +7639,7 @@ Integer[100, 599] ### `Stdlib::IP::Address` -The Stdlib::IP::Address data type. +Validate an IP address Alias of @@ -7155,7 +7649,7 @@ Variant[Stdlib::IP::Address::V4, Stdlib::IP::Address::V6] ### `Stdlib::IP::Address::Nosubnet` -The Stdlib::IP::Address::Nosubnet data type. +Validate an IP address without subnet Alias of @@ -7165,7 +7659,7 @@ Variant[Stdlib::IP::Address::V4::Nosubnet, Stdlib::IP::Address::V6::Nosubnet] ### `Stdlib::IP::Address::V4` -The Stdlib::IP::Address::V4 data type. +Validate an IPv4 address Alias of @@ -7195,7 +7689,7 @@ Pattern[/\A([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\.([0-9]|[1-9][0-9]| ### `Stdlib::IP::Address::V6` -The Stdlib::IP::Address::V6 data type. +Validate an IPv6 address Alias of @@ -7225,7 +7719,7 @@ Pattern[/\A((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6} ### `Stdlib::IP::Address::V6::Compressed` -The Stdlib::IP::Address::V6::Compressed data type. +Validate a compressed IPv6 address Alias of @@ -7235,7 +7729,7 @@ Pattern[/\A:(:|(:[[:xdigit:]]{1,4}){1,7})(\/(1([01][0-9]|2[0-8])|[1-9][0-9]|[0-9 ### `Stdlib::IP::Address::V6::Full` -The Stdlib::IP::Address::V6::Full data type. +Validate a full IPv6 address Alias of @@ -7245,7 +7739,7 @@ Pattern[/\A[[:xdigit:]]{1,4}(:[[:xdigit:]]{1,4}){7}(\/(1([01][0-9]|2[0-8])|[1-9] ### `Stdlib::IP::Address::V6::Nosubnet` -The Stdlib::IP::Address::V6::Nosubnet data type. +Validate an IPv6 address without subnet Alias of @@ -7265,7 +7759,7 @@ Pattern[/\A([[:xdigit:]]{1,4}:){6}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5 ### `Stdlib::IP::Address::V6::Nosubnet::Compressed` -The Stdlib::IP::Address::V6::Nosubnet::Compressed data type. +Validate compressed IPv6 address without subnet Alias of @@ -7275,7 +7769,7 @@ Pattern[/\A:(:|(:[[:xdigit:]]{1,4}){1,7})\z/, /\A([[:xdigit:]]{1,4}:){1}(:|(:[[: ### `Stdlib::IP::Address::V6::Nosubnet::Full` -The Stdlib::IP::Address::V6::Nosubnet::Full data type. +Validate full IPv6 address without subnet Alias of @@ -7295,7 +7789,7 @@ Pattern[/\A([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})\z/, /\A([0-9A-Fa-f]{2}[:-]){1 ### `Stdlib::ObjectStore` -The Stdlib::ObjectStore data type. +Validate an ObjectStore Alias of @@ -7305,7 +7799,7 @@ Variant[Stdlib::ObjectStore::GSUri, Stdlib::ObjectStore::S3Uri] ### `Stdlib::ObjectStore::GSUri` -The Stdlib::ObjectStore::GSUri data type. +Validate a Google Cloud object store URI Alias of @@ -7315,7 +7809,7 @@ Pattern[/\Ags:\/\/.*\z/] ### `Stdlib::ObjectStore::S3Uri` -The Stdlib::ObjectStore::S3Uri data type. +Validate an Amazon Web Services S3 object store URI Alias of @@ -7325,7 +7819,7 @@ Pattern[/\As3:\/\/.*\z/] ### `Stdlib::Port` -The Stdlib::Port data type. +Validate a port number Alias of @@ -7335,7 +7829,7 @@ Integer[0, 65535] ### `Stdlib::Port::Dynamic` -The Stdlib::Port::Dynamic data type. +Validate a dynamic port number Alias of @@ -7345,7 +7839,7 @@ Integer[49152, 65535] ### `Stdlib::Port::Ephemeral` -The Stdlib::Port::Ephemeral data type. +Validate an ephemeral port number Alias of @@ -7355,7 +7849,7 @@ Stdlib::Port::Dynamic ### `Stdlib::Port::Privileged` -The Stdlib::Port::Privileged data type. +Validate a priviliged port number Alias of @@ -7365,7 +7859,7 @@ Integer[1, 1023] ### `Stdlib::Port::Registered` -The Stdlib::Port::Registered data type. +Validate a registered port number Alias of @@ -7375,7 +7869,7 @@ Stdlib::Port::User ### `Stdlib::Port::Unprivileged` -The Stdlib::Port::Unprivileged data type. +Validate an unprivileged port number Alias of @@ -7385,7 +7879,7 @@ Integer[1024, 65535] ### `Stdlib::Port::User` -The Stdlib::Port::User data type. +Validate a port number usable by a user Alias of @@ -7395,7 +7889,7 @@ Integer[1024, 49151] ### `Stdlib::Syslogfacility` -The Stdlib::Syslogfacility data type. +Validate a syslog facility Alias of @@ -7415,7 +7909,7 @@ Pattern[/\A\/([^\n\/\0]+\/*)*\z/] ### `Stdlib::Windowspath` -The Stdlib::Windowspath data type. +Validate a Windows path Alias of @@ -7425,7 +7919,7 @@ Pattern[/\A(([a-zA-Z]:[\\\/])|([\\\/][\\\/][^\\\/]+[\\\/][^\\\/]+)|([\\\/][\\\/] ### `Stdlib::Yes_no` -The Stdlib::Yes_no data type. +Validate a yes / no value Alias of diff --git a/functions/ensure.pp b/functions/ensure.pp index 8f7ea63a7..b4ea17b2c 100644 --- a/functions/ensure.pp +++ b/functions/ensure.pp @@ -1,4 +1,6 @@ # @summary function to cast ensure parameter to resource specific value +# +# @return [String] function stdlib::ensure( Variant[Boolean, Enum['present', 'absent']] $ensure, Enum['directory', 'link', 'mounted', 'service', 'file', 'package'] $resource, diff --git a/lib/puppet/functions/parsehocon.rb b/lib/puppet/functions/parsehocon.rb index 6b7ae62c8..be490ba24 100644 --- a/lib/puppet/functions/parsehocon.rb +++ b/lib/puppet/functions/parsehocon.rb @@ -4,15 +4,13 @@ # This function accepts HOCON as a string and converts it into the correct # Puppet structure # -# @return -# Data -# # @example How to parse hocon # $data = parsehocon("{any valid hocon: string}") # Puppet::Functions.create_function(:parsehocon) do # @param hocon_string A valid HOCON string # @param default An optional default to return if parsing hocon_string fails + # @return [Data] dispatch :parsehocon do param 'String', :hocon_string optional_param 'Any', :default diff --git a/lib/puppet/functions/stdlib/str2resource.rb b/lib/puppet/functions/stdlib/str2resource.rb index 7290b176a..67188abd7 100644 --- a/lib/puppet/functions/stdlib/str2resource.rb +++ b/lib/puppet/functions/stdlib/str2resource.rb @@ -3,15 +3,15 @@ # @summary # This converts a string to a puppet resource. # -# This attempts to convert a string like 'File[/foo]' into the -# puppet resource `File['/foo']` as detected by the catalog. +# This attempts to convert a string like 'File[/foo]' into the +# puppet resource `File['/foo']` as detected by the catalog. # -# Things like 'File[/foo, /bar]' are not supported as a -# title might contain things like ',' or ' '. There is -# no clear value seperator to use. +# Things like 'File[/foo, /bar]' are not supported as a +# title might contain things like ',' or ' '. There is +# no clear value seperator to use. # -# This function can depend on the parse order of your -# manifests/modules as it inspects the catalog thus far. +# This function can depend on the parse order of your +# manifests/modules as it inspects the catalog thus far. Puppet::Functions.create_function(:'stdlib::str2resource') do # @param res_string The string to lookup as a resource # @example diff --git a/lib/puppet/functions/to_json.rb b/lib/puppet/functions/to_json.rb index 5f3be4464..337860568 100644 --- a/lib/puppet/functions/to_json.rb +++ b/lib/puppet/functions/to_json.rb @@ -3,16 +3,16 @@ require 'json' # @summary # Convert a data structure and output to JSON -# -# @example Output JSON to a file -# file { '/tmp/my.json': -# ensure => file, -# content => to_json($myhash), -# } -# Puppet::Functions.create_function(:to_json) do # @param data # Data structure which needs to be converted into JSON + # + # @example Output JSON to a file + # file { '/tmp/my.json': + # ensure => file, + # content => to_json($myhash), + # } + # # @return [String] Converted data to JSON dispatch :to_json do param 'Any', :data diff --git a/lib/puppet/functions/to_python.rb b/lib/puppet/functions/to_python.rb index 9e9a38769..a6ba9a08e 100644 --- a/lib/puppet/functions/to_python.rb +++ b/lib/puppet/functions/to_python.rb @@ -15,15 +15,15 @@ # } Puppet::Functions.create_function(:to_python) do - dispatch :to_python do - param 'Any', :object - end - # @param object # The object to be converted # # @return [String] # The String representation of the object + dispatch :to_python do + param 'Any', :object + end + def to_python(object) serialized = Puppet::Pops::Serialization::ToDataConverter.convert(object, rich_data: true) serialized_to_python(serialized) diff --git a/lib/puppet/functions/to_ruby.rb b/lib/puppet/functions/to_ruby.rb index 8e89c9be6..d387c819a 100644 --- a/lib/puppet/functions/to_ruby.rb +++ b/lib/puppet/functions/to_ruby.rb @@ -15,15 +15,15 @@ # } Puppet::Functions.create_function(:to_ruby) do - dispatch :to_ruby do - param 'Any', :object - end - # @param object # The object to be converted # # @return [String] # The String representation of the object + dispatch :to_ruby do + param 'Any', :object + end + def to_ruby(object) serialized = Puppet::Pops::Serialization::ToDataConverter.convert(object, rich_data: true) serialized_to_ruby(serialized) diff --git a/lib/puppet/functions/to_yaml.rb b/lib/puppet/functions/to_yaml.rb index e7cc9bc5f..6792b4aab 100644 --- a/lib/puppet/functions/to_yaml.rb +++ b/lib/puppet/functions/to_yaml.rb @@ -3,23 +3,23 @@ require 'yaml' # @summary # Convert a data structure and output it as YAML -# -# @example Output YAML to a file -# file { '/tmp/my.yaml': -# ensure => file, -# content => to_yaml($myhash), -# } -# @example Use options to control the output format -# file { '/tmp/my.yaml': -# ensure => file, -# content => to_yaml($myhash, {indentation => 4}) -# } Puppet::Functions.create_function(:to_yaml) do # @param data # The data you want to convert to YAML # @param options # A hash of options that will be passed to Ruby's Psych library. Note, this could change between Puppet versions, but at time of writing these are `line_width`, `indentation`, and `canonical`. # + # @example Output YAML to a file + # file { '/tmp/my.yaml': + # ensure => file, + # content => to_yaml($myhash), + # } + # @example Use options to control the output format + # file { '/tmp/my.yaml': + # ensure => file, + # content => to_yaml($myhash, {indentation => 4}) + # } + # # @return [String] The YAML document dispatch :to_yaml do param 'Any', :data diff --git a/lib/puppet/parser/functions/defined_with_params.rb b/lib/puppet/parser/functions/defined_with_params.rb index 74fc67a6e..8cfd9a123 100644 --- a/lib/puppet/parser/functions/defined_with_params.rb +++ b/lib/puppet/parser/functions/defined_with_params.rb @@ -3,9 +3,7 @@ # Test whether a given class or definition is defined require 'puppet/parser/functions' -Puppet::Parser::Functions.newfunction(:defined_with_params, - type: :rvalue, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:defined_with_params, type: :rvalue, doc: <<-DOC @summary Takes a resource reference and an optional hash of attributes. @@ -25,7 +23,7 @@ @return [Boolean] returns `true` or `false` DOC - ) do |vals| +) do |vals| reference, params = vals raise(ArgumentError, 'Must specify a reference') unless reference if !params || params == '' diff --git a/lib/puppet/parser/functions/dig44.rb b/lib/puppet/parser/functions/dig44.rb index 7b58c226f..c9e6b69de 100644 --- a/lib/puppet/parser/functions/dig44.rb +++ b/lib/puppet/parser/functions/dig44.rb @@ -4,11 +4,7 @@ # dig44.rb # module Puppet::Parser::Functions - newfunction( - :dig44, - type: :rvalue, - arity: -2, - doc: <<-DOC, + newfunction(:dig44, type: :rvalue, arity: -2, doc: <<-DOC @summary **DEPRECATED**: Looks up into a complex structure of arrays and hashes and returns a value or the default value if nothing was found. diff --git a/lib/puppet/parser/functions/ensure_resource.rb b/lib/puppet/parser/functions/ensure_resource.rb index e606360c8..46b2c4637 100644 --- a/lib/puppet/parser/functions/ensure_resource.rb +++ b/lib/puppet/parser/functions/ensure_resource.rb @@ -3,9 +3,7 @@ # Test whether a given class or definition is defined require 'puppet/parser/functions' -Puppet::Parser::Functions.newfunction(:ensure_resource, - type: :statement, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:ensure_resource, type: :statement, doc: <<-DOC @summary Takes a resource type, title, and a list of attributes that describe a resource. @@ -33,7 +31,7 @@ ensure_resource('user', ['dan','alex'], {'ensure' => 'present'}) DOC - ) do |vals| +) do |vals| type, title, params = vals raise(ArgumentError, 'Must specify a type') unless type raise(ArgumentError, 'Must specify a title') unless title diff --git a/lib/puppet/parser/functions/ensure_resources.rb b/lib/puppet/parser/functions/ensure_resources.rb index ed82b2338..d6a890667 100644 --- a/lib/puppet/parser/functions/ensure_resources.rb +++ b/lib/puppet/parser/functions/ensure_resources.rb @@ -2,9 +2,7 @@ require 'puppet/parser/functions' -Puppet::Parser::Functions.newfunction(:ensure_resources, - type: :statement, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:ensure_resources, type: :statement, doc: <<-DOC @summary Takes a resource type, title (only hash), and a list of attributes that describe a resource. @@ -36,7 +34,7 @@ Call: ensure_resources('user', hiera_hash('userlist'), {'ensure' => 'present'}) DOC - ) do |vals| +) do |vals| type, title, params = vals raise(ArgumentError, 'Must specify a type') unless type raise(ArgumentError, 'Must specify a title') unless title diff --git a/lib/puppet/parser/functions/fqdn_rand_string.rb b/lib/puppet/parser/functions/fqdn_rand_string.rb index e9636c24f..20248ae1a 100644 --- a/lib/puppet/parser/functions/fqdn_rand_string.rb +++ b/lib/puppet/parser/functions/fqdn_rand_string.rb @@ -1,10 +1,6 @@ # frozen_string_literal: true -Puppet::Parser::Functions.newfunction( - :fqdn_rand_string, - arity: -2, - type: :rvalue, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:fqdn_rand_string, arity: -2, type: :rvalue, doc: <<-DOC @summary Generates a random alphanumeric string. Combining the `$fqdn` fact and an optional seed for repeatable randomness. diff --git a/lib/puppet/parser/functions/fqdn_rotate.rb b/lib/puppet/parser/functions/fqdn_rotate.rb index 603c57ca6..d9773a3a9 100644 --- a/lib/puppet/parser/functions/fqdn_rotate.rb +++ b/lib/puppet/parser/functions/fqdn_rotate.rb @@ -3,10 +3,7 @@ # # fqdn_rotate.rb # -Puppet::Parser::Functions.newfunction( - :fqdn_rotate, - type: :rvalue, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:fqdn_rotate, type: :rvalue, doc: <<-DOC @summary Rotates an array or string a random number of times, combining the `$fqdn` fact and an optional seed for repeatable randomness. diff --git a/lib/puppet/parser/functions/getparam.rb b/lib/puppet/parser/functions/getparam.rb index 18b7b51e1..c0ae572f3 100644 --- a/lib/puppet/parser/functions/getparam.rb +++ b/lib/puppet/parser/functions/getparam.rb @@ -3,9 +3,7 @@ # Test whether a given class or definition is defined require 'puppet/parser/functions' -Puppet::Parser::Functions.newfunction(:getparam, - type: :rvalue, - doc: <<-'DOC', +Puppet::Parser::Functions.newfunction(:getparam, type: :rvalue, doc: <<-'DOC' @summary Returns the value of a resource's parameter. @@ -45,7 +43,7 @@ ```Example_resource['example_resource_instance']['param']`` DOC - ) do |vals| +) do |vals| reference, param = vals raise(ArgumentError, 'Must specify a reference') unless reference raise(ArgumentError, 'Must specify name of a parameter') unless param&.instance_of?(String) diff --git a/lib/puppet/parser/functions/pick.rb b/lib/puppet/parser/functions/pick.rb index 34450c5fa..fc4ebb635 100644 --- a/lib/puppet/parser/functions/pick.rb +++ b/lib/puppet/parser/functions/pick.rb @@ -6,9 +6,11 @@ module Puppet::Parser::Functions newfunction(:pick, type: :rvalue, doc: <<-EOS @summary - This function is similar to a coalesce function in SQL in that it will return + This function will return the first value in a list of values that is not undefined or an empty string. + This function is similar to a coalesce function in SQL. + @return the first value in a list of values that is not undefined or an empty string. diff --git a/lib/puppet/parser/functions/pw_hash.rb b/lib/puppet/parser/functions/pw_hash.rb index acc7394a8..67346efeb 100644 --- a/lib/puppet/parser/functions/pw_hash.rb +++ b/lib/puppet/parser/functions/pw_hash.rb @@ -3,11 +3,7 @@ # Please note: This function is an implementation of a Ruby class and as such may not be entirely UTF8 compatible. # To ensure compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085. # -Puppet::Parser::Functions.newfunction( - :pw_hash, - type: :rvalue, - arity: 3, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:pw_hash, type: :rvalue, arity: 3, doc: <<-DOC @summary Hashes a password using the crypt function. Provides a hash usable on most POSIX systems. diff --git a/lib/puppet/parser/functions/round.rb b/lib/puppet/parser/functions/round.rb index bb1013ad9..a528e0cdb 100644 --- a/lib/puppet/parser/functions/round.rb +++ b/lib/puppet/parser/functions/round.rb @@ -11,11 +11,9 @@ module Puppet::Parser::Functions @return the rounded value as integer - @example - - ```round(2.9)``` returns ```3``` - - ```round(2.4)``` returns ```2``` + @example Example usage + round(2.9) #=> 3 + round(2.4) #=> 2 > *Note:* from Puppet 6.0.0, the compatible function with the same name in Puppet core will be used instead of this function. diff --git a/lib/puppet/parser/functions/seeded_rand.rb b/lib/puppet/parser/functions/seeded_rand.rb index eb495e812..f9919f8d1 100644 --- a/lib/puppet/parser/functions/seeded_rand.rb +++ b/lib/puppet/parser/functions/seeded_rand.rb @@ -3,11 +3,7 @@ # # seeded_rand.rb # -Puppet::Parser::Functions.newfunction( - :seeded_rand, - arity: 2, - type: :rvalue, - doc: <<-DOC, +Puppet::Parser::Functions.newfunction(:seeded_rand, arity: 2, type: :rvalue, doc: <<-DOC @summary Generates a random whole number greater than or equal to 0 and less than MAX, using the value of SEED for repeatable randomness. diff --git a/lib/puppet/parser/functions/try_get_value.rb b/lib/puppet/parser/functions/try_get_value.rb index 8df953089..00fdf5b46 100644 --- a/lib/puppet/parser/functions/try_get_value.rb +++ b/lib/puppet/parser/functions/try_get_value.rb @@ -4,11 +4,7 @@ # try_get_value.rb # module Puppet::Parser::Functions - newfunction( - :try_get_value, - type: :rvalue, - arity: -2, - doc: <<-DOC, + newfunction(:try_get_value, type: :rvalue, arity: -2, doc: <<-DOC @summary **DEPRECATED:** this function is deprecated, please use dig() instead. diff --git a/lib/puppet/parser/functions/validate_slength.rb b/lib/puppet/parser/functions/validate_slength.rb index c7d5bb6c3..f6a31a25a 100644 --- a/lib/puppet/parser/functions/validate_slength.rb +++ b/lib/puppet/parser/functions/validate_slength.rb @@ -7,8 +7,9 @@ module Puppet::Parser::Functions newfunction(:validate_slength, doc: <<-DOC @summary Validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument. - An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings, - and if arg 2 and arg 3 are not convertable to a number. + + An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings, + and if arg 2 and arg 3 are not convertable to a number. @return validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument. Fail compilation if any of the checks fail. diff --git a/lib/puppet/parser/functions/validate_x509_rsa_key_pair.rb b/lib/puppet/parser/functions/validate_x509_rsa_key_pair.rb index a62ba3753..ee52a11bb 100644 --- a/lib/puppet/parser/functions/validate_x509_rsa_key_pair.rb +++ b/lib/puppet/parser/functions/validate_x509_rsa_key_pair.rb @@ -7,8 +7,10 @@ module Puppet::Parser::Functions newfunction(:validate_x509_rsa_key_pair, doc: <<-DOC @summary Validates a PEM-formatted X.509 certificate and RSA private key using - OpenSSL. Verifies that the certficate's signature was created from the - supplied key. + OpenSSL. + + Verifies that the certficate's signature was created from the + supplied key. @return Fail compilation if any value fails this check. diff --git a/manifests/manage.pp b/manifests/manage.pp index 36c2d6574..b6765afcb 100644 --- a/manifests/manage.pp +++ b/manifests/manage.pp @@ -30,14 +30,14 @@ # } # # @example -# stdlib::manage::create_resources: -# file: -# '/etc/motd.d/hello': -# content: I say Hi -# notify: 'Service[sshd]' -# package: -# example: -# ensure: installed +# stdlib::manage::create_resources: +# file: +# '/etc/motd.d/hello': +# content: I say Hi +# notify: 'Service[sshd]' +# package: +# example: +# ensure: installed class stdlib::manage ( Hash[String, Hash] $create_resources = {} ) { diff --git a/types/absolutepath.pp b/types/absolutepath.pp index 70ec9164b..906bd6960 100644 --- a/types/absolutepath.pp +++ b/types/absolutepath.pp @@ -1,2 +1,2 @@ -# A strict absolutepath type +# @summary A strict absolutepath type type Stdlib::Absolutepath = Variant[Stdlib::Windowspath, Stdlib::Unixpath] diff --git a/types/base32.pp b/types/base32.pp index 89939b168..9c8574d82 100644 --- a/types/base32.pp +++ b/types/base32.pp @@ -1,2 +1,2 @@ -# Type to match base32 String +# @summary Type to match base32 String type Stdlib::Base32 = Pattern[/\A[a-z2-7]+={,6}\z/, /\A[A-Z2-7]+={,6}\z/] diff --git a/types/base64.pp b/types/base64.pp index 9f44ab690..3fc198f6c 100644 --- a/types/base64.pp +++ b/types/base64.pp @@ -1,2 +1,2 @@ -# Type to match base64 String +# @summary Type to match base64 String type Stdlib::Base64 = Pattern[/\A[a-zA-Z0-9\/\+]+={,2}\z/] diff --git a/types/compat/absolute_path.pp b/types/compat/absolute_path.pp index 60f9c861f..28e03ab89 100644 --- a/types/compat/absolute_path.pp +++ b/types/compat/absolute_path.pp @@ -1,4 +1,4 @@ -# Emulate the is_absolute_path and validate_absolute_path functions +# @summary Emulate the is_absolute_path and validate_absolute_path functions # # The first pattern is originally from is_absolute_path, which had it from 2.7.x's lib/puppet/util.rb Puppet::Util.absolute_path? # slash = '[\\\\/]' diff --git a/types/compat/array.pp b/types/compat/array.pp index ba65dc4d2..12ddbab7e 100644 --- a/types/compat/array.pp +++ b/types/compat/array.pp @@ -1,2 +1,2 @@ -# Emulate the is_array and validate_array functions +# @summary Emulate the is_array and validate_array functions type Stdlib::Compat::Array = Array[Any] diff --git a/types/compat/bool.pp b/types/compat/bool.pp index 5d8e27e5c..1918bf8b0 100644 --- a/types/compat/bool.pp +++ b/types/compat/bool.pp @@ -1,2 +1,2 @@ -# Emulate the is_bool and validate_bool functions +# @summary Emulate the is_bool and validate_bool functions type Stdlib::Compat::Bool = Boolean diff --git a/types/compat/float.pp b/types/compat/float.pp index 7f98bd272..84b261754 100644 --- a/types/compat/float.pp +++ b/types/compat/float.pp @@ -1,4 +1,4 @@ -# Emulate the is_float function +# @summary Emulate the is_float function # The regex is what's currently used in is_float # To keep your development moving forward, you can also add a deprecation warning using the Integer type: # diff --git a/types/compat/hash.pp b/types/compat/hash.pp index e84a10bb4..14dc6fd1d 100644 --- a/types/compat/hash.pp +++ b/types/compat/hash.pp @@ -1,2 +1,2 @@ -# Emulate the is_hash and validate_hash functions +# @summary Emulate the is_hash and validate_hash functions type Stdlib::Compat::Hash = Hash[Any, Any] diff --git a/types/compat/integer.pp b/types/compat/integer.pp index 047344d55..811daacba 100644 --- a/types/compat/integer.pp +++ b/types/compat/integer.pp @@ -1,4 +1,4 @@ -# Emulate the is_integer and validate_integer functions +# @summary Emulate the is_integer and validate_integer functions # The regex is what's currently used in is_integer # validate_numeric also allows range checking, which cannot be mapped to the string parsing inside the function. # For full backwards compatibility, you will need to keep the validate_numeric call around to catch everything. diff --git a/types/compat/ip_address.pp b/types/compat/ip_address.pp index bf4c4b4f2..b877020cc 100644 --- a/types/compat/ip_address.pp +++ b/types/compat/ip_address.pp @@ -1 +1,2 @@ +# @summary Validate an IP address type Stdlib::Compat::Ip_address = Variant[Stdlib::Compat::Ipv4, Stdlib::Compat::Ipv6] diff --git a/types/compat/ipv4.pp b/types/compat/ipv4.pp index 87a4dc991..bcd2c00bb 100644 --- a/types/compat/ipv4.pp +++ b/types/compat/ipv4.pp @@ -1,2 +1,2 @@ -# Emulate the validate_ipv4_address and is_ipv4_address functions +# @summary Emulate the validate_ipv4_address and is_ipv4_address functions type Stdlib::Compat::Ipv4 = Pattern[/^((([0-9](?!\d)|[1-9][0-9](?!\d)|1[0-9]{2}(?!\d)|2[0-4][0-9](?!\d)|25[0-5](?!\d))[.]){3}([0-9](?!\d)|[1-9][0-9](?!\d)|1[0-9]{2}(?!\d)|2[0-4][0-9](?!\d)|25[0-5](?!\d)))(\/((([0-9](?!\d)|[1-9][0-9](?!\d)|1[0-9]{2}(?!\d)|2[0-4][0-9](?!\d)|25[0-5](?!\d))[.]){3}([0-9](?!\d)|[1-9][0-9](?!\d)|1[0-9]{2}(?!\d)|2[0-4][0-9](?!\d)|25[0-5](?!\d))|[0-9]+))?$/] # lint:ignore:140chars diff --git a/types/compat/ipv6.pp b/types/compat/ipv6.pp index 0a9677e91..0c6f4228e 100644 --- a/types/compat/ipv6.pp +++ b/types/compat/ipv6.pp @@ -1 +1,2 @@ +# @summary Validate an IPv6 address type Stdlib::Compat::Ipv6 = Pattern[/\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$/] # lint:ignore:140chars diff --git a/types/compat/numeric.pp b/types/compat/numeric.pp index 3cf9c0d09..d509d7ab6 100644 --- a/types/compat/numeric.pp +++ b/types/compat/numeric.pp @@ -1,4 +1,4 @@ -# Emulate the is_numeric and validate_numeric functions +# @summary Emulate the is_numeric and validate_numeric functions # The regex is what's currently used in is_numeric # validate_numeric also allows range checking, which cannot be mapped to the string parsing inside the function. # For full backwards compatibility, you will need to keep the validate_numeric call around to catch everything. diff --git a/types/compat/re.pp b/types/compat/re.pp index e4b5f30f6..81db38cef 100644 --- a/types/compat/re.pp +++ b/types/compat/re.pp @@ -1,3 +1,3 @@ -# Emulate the validate_re function +# @summary Emulate the validate_re function # validate_re(value, re) translates to Pattern[re], which is not directly mappable as a type alias, but can be specified as Pattern[re]. # Therefore this needs to be translated directly. diff --git a/types/compat/string.pp b/types/compat/string.pp index b06255de9..ce08bafb4 100644 --- a/types/compat/string.pp +++ b/types/compat/string.pp @@ -1,2 +1,2 @@ -# Emulate the is_string and validate_string functions +# @summary Emulate the is_string and validate_string functions type Stdlib::Compat::String = Optional[String] diff --git a/types/datasize.pp b/types/datasize.pp index fb389a9fa..6892c0171 100644 --- a/types/datasize.pp +++ b/types/datasize.pp @@ -1 +1,2 @@ +# @summary Validate the size of data type Stdlib::Datasize = Pattern[/^\d+(?i:[kmgt]b?|b)$/] diff --git a/types/email.pp b/types/email.pp index 1fd841a45..6103edb64 100644 --- a/types/email.pp +++ b/types/email.pp @@ -1,3 +1,4 @@ +# @summary Validate an e-mail address # https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address # lint:ignore:140chars type Stdlib::Email = Pattern[/\A[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/] diff --git a/types/ensure/file.pp b/types/ensure/file.pp index 540fe549f..6d5928715 100644 --- a/types/ensure/file.pp +++ b/types/ensure/file.pp @@ -1 +1,2 @@ +# @summary Validate the value of the ensure parameter for a file type Stdlib::Ensure::File = Enum['present', 'file', 'directory', 'link', 'absent'] diff --git a/types/ensure/file/directory.pp b/types/ensure/file/directory.pp index 576505187..1c4d2686d 100644 --- a/types/ensure/file/directory.pp +++ b/types/ensure/file/directory.pp @@ -1 +1,2 @@ +# Validate the ensure parameter of a "directory" file resource type Stdlib::Ensure::File::Directory = Enum['directory', 'absent'] diff --git a/types/ensure/file/file.pp b/types/ensure/file/file.pp index 22cd639d4..d35deafe5 100644 --- a/types/ensure/file/file.pp +++ b/types/ensure/file/file.pp @@ -1 +1,2 @@ +# Validate the ensure parameter of a "file" file resource type Stdlib::Ensure::File::File = Enum['file', 'absent'] diff --git a/types/ensure/file/link.pp b/types/ensure/file/link.pp index 20620b868..bc1276dbe 100644 --- a/types/ensure/file/link.pp +++ b/types/ensure/file/link.pp @@ -1 +1,2 @@ +# Validate the ensure parameter of a "link" file resource type Stdlib::Ensure::File::Link = Enum['link', 'absent'] diff --git a/types/ensure/service.pp b/types/ensure/service.pp index fba66acc9..af9c513a3 100644 --- a/types/ensure/service.pp +++ b/types/ensure/service.pp @@ -1 +1,2 @@ +# @summary Validate the value of the ensure parameter of a service resource type Stdlib::Ensure::Service = Enum['stopped', 'running'] diff --git a/types/filemode.pp b/types/filemode.pp index 0cbd4942c..2974a05f2 100644 --- a/types/filemode.pp +++ b/types/filemode.pp @@ -1,3 +1,4 @@ +# @summary Validate a file mode # See `man chmod.1` for the regular expression for symbolic mode # lint:ignore:140chars type Stdlib::Filemode = Pattern[/\A(([0-7]{1,4})|(([ugoa]*([-+=]([rwxXst]*|[ugo]))+|[-+=][0-7]+)(,([ugoa]*([-+=]([rwxXst]*|[ugo]))+|[-+=][0-7]+))*))\z/] diff --git a/types/filesource.pp b/types/filesource.pp index 9e75cd583..9c12d9ed2 100644 --- a/types/filesource.pp +++ b/types/filesource.pp @@ -1,4 +1,4 @@ -# Validate the source parameter on file types +# @summary Validate the source parameter on file types type Stdlib::Filesource = Variant[ Stdlib::Absolutepath, Stdlib::HTTPUrl, diff --git a/types/fqdn.pp b/types/fqdn.pp index 4349a05ca..c2fbe09ae 100644 --- a/types/fqdn.pp +++ b/types/fqdn.pp @@ -1 +1,2 @@ +# @summary Validate a Fully Qualified Domain Name type Stdlib::Fqdn = Pattern[/\A(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])\z/] diff --git a/types/host.pp b/types/host.pp index 8f6919e70..21772f1fc 100644 --- a/types/host.pp +++ b/types/host.pp @@ -1 +1,2 @@ +# @summary Validate a host (FQDN or IP address) type Stdlib::Host = Variant[Stdlib::Fqdn, Stdlib::Compat::Ip_address] diff --git a/types/httpstatus.pp b/types/httpstatus.pp index 146587be8..4199d8acf 100644 --- a/types/httpstatus.pp +++ b/types/httpstatus.pp @@ -1 +1,2 @@ +# @summary Validate a HTTP status code type Stdlib::HttpStatus = Integer[100, 599] diff --git a/types/httpsurl.pp b/types/httpsurl.pp index 706570829..1c878c3ba 100644 --- a/types/httpsurl.pp +++ b/types/httpsurl.pp @@ -1 +1,2 @@ +# @summary Validate a HTTPS URL type Stdlib::HTTPSUrl = Pattern[/(?i:\Ahttps:\/\/.*\z)/] diff --git a/types/httpurl.pp b/types/httpurl.pp index 60b4adab2..2cf0bd970 100644 --- a/types/httpurl.pp +++ b/types/httpurl.pp @@ -1 +1,2 @@ +# @summary Validate a HTTP(S) URL type Stdlib::HTTPUrl = Pattern[/(?i:\Ahttps?:\/\/.*\z)/] diff --git a/types/ip/address.pp b/types/ip/address.pp index 4c5c05ca8..b73d3a1f5 100644 --- a/types/ip/address.pp +++ b/types/ip/address.pp @@ -1,3 +1,4 @@ +# @summary Validate an IP address type Stdlib::IP::Address = Variant[ Stdlib::IP::Address::V4, Stdlib::IP::Address::V6, diff --git a/types/ip/address/nosubnet.pp b/types/ip/address/nosubnet.pp index 4b7d16dc3..2f24b5ed3 100644 --- a/types/ip/address/nosubnet.pp +++ b/types/ip/address/nosubnet.pp @@ -1,3 +1,4 @@ +# Validate an IP address without subnet type Stdlib::IP::Address::Nosubnet = Variant[ Stdlib::IP::Address::V4::Nosubnet, Stdlib::IP::Address::V6::Nosubnet, diff --git a/types/ip/address/v4.pp b/types/ip/address/v4.pp index 5670dfed6..33f8f6fce 100644 --- a/types/ip/address/v4.pp +++ b/types/ip/address/v4.pp @@ -1,3 +1,4 @@ +# Validate an IPv4 address type Stdlib::IP::Address::V4 = Variant[ Stdlib::IP::Address::V4::CIDR, Stdlib::IP::Address::V4::Nosubnet, diff --git a/types/ip/address/v6.pp b/types/ip/address/v6.pp index 96c100f12..e8ca7eb31 100644 --- a/types/ip/address/v6.pp +++ b/types/ip/address/v6.pp @@ -1,3 +1,4 @@ +# Validate an IPv6 address type Stdlib::IP::Address::V6 = Variant[ Stdlib::IP::Address::V6::Full, Stdlib::IP::Address::V6::Compressed, diff --git a/types/ip/address/v6/compressed.pp b/types/ip/address/v6/compressed.pp index a7558642d..44f08df63 100644 --- a/types/ip/address/v6/compressed.pp +++ b/types/ip/address/v6/compressed.pp @@ -1,3 +1,4 @@ +# Validate a compressed IPv6 address type Stdlib::IP::Address::V6::Compressed = Pattern[ /\A:(:|(:[[:xdigit:]]{1,4}){1,7})(\/(1([01][0-9]|2[0-8])|[1-9][0-9]|[0-9]))?\z/, /\A([[:xdigit:]]{1,4}:){1}(:|(:[[:xdigit:]]{1,4}){1,6})(\/(1([01][0-9]|2[0-8])|[1-9][0-9]|[0-9]))?\z/, diff --git a/types/ip/address/v6/full.pp b/types/ip/address/v6/full.pp index a86276956..f0c23212a 100644 --- a/types/ip/address/v6/full.pp +++ b/types/ip/address/v6/full.pp @@ -1 +1,2 @@ +# Validate a full IPv6 address type Stdlib::IP::Address::V6::Full = Pattern[/\A[[:xdigit:]]{1,4}(:[[:xdigit:]]{1,4}){7}(\/(1([01][0-9]|2[0-8])|[1-9][0-9]|[0-9]))?\z/] diff --git a/types/ip/address/v6/nosubnet.pp b/types/ip/address/v6/nosubnet.pp index 94b8c50f5..f2345c1b4 100644 --- a/types/ip/address/v6/nosubnet.pp +++ b/types/ip/address/v6/nosubnet.pp @@ -1,3 +1,4 @@ +# Validate an IPv6 address without subnet type Stdlib::IP::Address::V6::Nosubnet = Variant[ Stdlib::IP::Address::V6::Nosubnet::Full, Stdlib::IP::Address::V6::Nosubnet::Compressed, diff --git a/types/ip/address/v6/nosubnet/compressed.pp b/types/ip/address/v6/nosubnet/compressed.pp index c06a2746e..01b1f96b0 100644 --- a/types/ip/address/v6/nosubnet/compressed.pp +++ b/types/ip/address/v6/nosubnet/compressed.pp @@ -1,3 +1,4 @@ +# Validate compressed IPv6 address without subnet type Stdlib::IP::Address::V6::Nosubnet::Compressed = Pattern[ /\A:(:|(:[[:xdigit:]]{1,4}){1,7})\z/, /\A([[:xdigit:]]{1,4}:){1}(:|(:[[:xdigit:]]{1,4}){1,6})\z/, diff --git a/types/ip/address/v6/nosubnet/full.pp b/types/ip/address/v6/nosubnet/full.pp index 22ba1bed3..4bfedcdaf 100644 --- a/types/ip/address/v6/nosubnet/full.pp +++ b/types/ip/address/v6/nosubnet/full.pp @@ -1 +1,2 @@ +# Validate full IPv6 address without subnet type Stdlib::IP::Address::V6::Nosubnet::Full = Pattern[/\A[[:xdigit:]]{1,4}(:[[:xdigit:]]{1,4}){7}\z/] diff --git a/types/mac.pp b/types/mac.pp index 3c2947a70..283c861c9 100644 --- a/types/mac.pp +++ b/types/mac.pp @@ -1,4 +1,4 @@ -# A type for a MAC address +# @summary A type for a MAC address type Stdlib::MAC = Pattern[ /\A([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})\z/, /\A([0-9A-Fa-f]{2}[:-]){19}([0-9A-Fa-f]{2})\z/, diff --git a/types/objectstore.pp b/types/objectstore.pp index a89fb6a45..69c344b08 100644 --- a/types/objectstore.pp +++ b/types/objectstore.pp @@ -1,3 +1,4 @@ +# @summary Validate an ObjectStore type Stdlib::ObjectStore = Variant[ Stdlib::ObjectStore::GSUri, Stdlib::ObjectStore::S3Uri, diff --git a/types/objectstore/gsuri.pp b/types/objectstore/gsuri.pp index 2d05effda..28f4f3b52 100644 --- a/types/objectstore/gsuri.pp +++ b/types/objectstore/gsuri.pp @@ -1 +1,2 @@ +# @summary Validate a Google Cloud object store URI type Stdlib::ObjectStore::GSUri = Pattern[/\Ags:\/\/.*\z/] diff --git a/types/objectstore/s3uri.pp b/types/objectstore/s3uri.pp index 2abd19b3f..eb03b3040 100644 --- a/types/objectstore/s3uri.pp +++ b/types/objectstore/s3uri.pp @@ -1 +1,2 @@ +# @summary Validate an Amazon Web Services S3 object store URI type Stdlib::ObjectStore::S3Uri = Pattern[/\As3:\/\/.*\z/] diff --git a/types/port.pp b/types/port.pp index edeef151e..eef4590a0 100644 --- a/types/port.pp +++ b/types/port.pp @@ -1 +1,2 @@ +# @summary Validate a port number type Stdlib::Port = Integer[0, 65535] diff --git a/types/port/dynamic.pp b/types/port/dynamic.pp index 5e67a868d..743261f0f 100644 --- a/types/port/dynamic.pp +++ b/types/port/dynamic.pp @@ -1 +1,2 @@ +# @summary Validate a dynamic port number type Stdlib::Port::Dynamic = Integer[49152, 65535] diff --git a/types/port/ephemeral.pp b/types/port/ephemeral.pp index a0dd633ce..2d3ed84c2 100644 --- a/types/port/ephemeral.pp +++ b/types/port/ephemeral.pp @@ -1 +1,2 @@ +# @summary Validate an ephemeral port number type Stdlib::Port::Ephemeral = Stdlib::Port::Dynamic diff --git a/types/port/privileged.pp b/types/port/privileged.pp index 3fbb7852c..c00784c6a 100644 --- a/types/port/privileged.pp +++ b/types/port/privileged.pp @@ -1 +1,2 @@ +# @summary Validate a priviliged port number type Stdlib::Port::Privileged = Integer[1, 1023] diff --git a/types/port/registered.pp b/types/port/registered.pp index cbbf80744..17ce92117 100644 --- a/types/port/registered.pp +++ b/types/port/registered.pp @@ -1 +1,2 @@ +# @summary Validate a registered port number type Stdlib::Port::Registered = Stdlib::Port::User diff --git a/types/port/unprivileged.pp b/types/port/unprivileged.pp index ebd29db6e..01b7433ad 100644 --- a/types/port/unprivileged.pp +++ b/types/port/unprivileged.pp @@ -1 +1,2 @@ +# @summary Validate an unprivileged port number type Stdlib::Port::Unprivileged = Integer[1024, 65535] diff --git a/types/port/user.pp b/types/port/user.pp index 01b82cb46..1cc626ad5 100644 --- a/types/port/user.pp +++ b/types/port/user.pp @@ -1 +1,2 @@ +# @summary Validate a port number usable by a user type Stdlib::Port::User = Integer[1024, 49151] diff --git a/types/syslogfacility.pp b/types/syslogfacility.pp index 020c3e007..733ba7601 100644 --- a/types/syslogfacility.pp +++ b/types/syslogfacility.pp @@ -1,3 +1,4 @@ +# @summary Validate a syslog facility type Stdlib::Syslogfacility = Enum[ 'kern', 'user', diff --git a/types/unixpath.pp b/types/unixpath.pp index 71330c3bf..e610a107c 100644 --- a/types/unixpath.pp +++ b/types/unixpath.pp @@ -1,2 +1,3 @@ +# @summary Validate a UNIX path # this regex rejects any path component that does not start with "/" or is NUL type Stdlib::Unixpath = Pattern[/\A\/([^\n\/\0]+\/*)*\z/] diff --git a/types/windowspath.pp b/types/windowspath.pp index a79d3cd61..6943cf614 100644 --- a/types/windowspath.pp +++ b/types/windowspath.pp @@ -1 +1,2 @@ +# @summary Validate a Windows path type Stdlib::Windowspath = Pattern[/\A(([a-zA-Z]:[\\\/])|([\\\/][\\\/][^\\\/]+[\\\/][^\\\/]+)|([\\\/][\\\/]\?[\\\/][^\\\/]+)).*\z/] diff --git a/types/yes_no.pp b/types/yes_no.pp index d87f4eebf..2545cbc26 100644 --- a/types/yes_no.pp +++ b/types/yes_no.pp @@ -1 +1,2 @@ +# @summary Validate a yes / no value type Stdlib::Yes_no = Pattern[/\A(?i:(yes|no))\z/]