#stdlib

####Table of Contents

1. [Overview](#overview)

2. [Module Description - What the module does and why it is useful](#module-description)

3. [Setup - The basics of getting started with stdlib](#setup)

4. [Usage - Configuration options and additional functionality](#usage)

5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)

5. [Limitations - OS compatibility, etc.](#limitations)

6. [Development - Guide for contributing to the module](#development)

##Overview

Adds a standard library of resources for Puppet modules.

##Module Description

This module provides a standard library of resources for the development of Puppet modules. Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet:

 * Stages

 * Facts

 * Functions

 * Defined resource types

 * Types

 * Providers

> *Note:* As of version 3.7, Puppet Enterprise no longer includes the stdlib module. If you're running Puppet Enterprise, you should install the most recent release of stdlib for compatibility with Puppet modules.

##Setup

Installing the stdlib module adds the functions, facts, and resources of this standard library to Puppet.

##Usage

After you've installed stdlib, all of its functions, facts, and resources are available for module use or development.

If you want to use a standardized set of run stages for Puppet, `include stdlib` in your manifest.

* `stdlib`: Most of stdlib's features are automatically loaded by Puppet. To use standardized run stages in Puppet, declare this class in your manifest with `include stdlib`.

  When declared, stdlib declares all other classes in the module. The only other class currently included in the module is `stdlib::stages`.

The `stdlib::stages` class declares various run stages for deploying infrastructure, language runtimes, and application layers. The high level stages are (in order):

  * setup

  * main

  * runtime

  * setup_infra

  * deploy_infra

  * setup_app

  * deploy_app

  * deploy

  Sample usage:

  ~~~

  node default {

    include stdlib

    class { java: stage => 'runtime' }

  }

  ~~~

## Reference

### Classes

#### Public Classes

  The stdlib class has no parameters.

#### Private Classes

* `stdlib::stages`: Manages a standard set of run stages for Puppet. It is managed by the stdlib class and should not be declared independently.

### Types

#### `file_line`

 Ensures that a given line, including whitespace at the beginning and end, is contained within a file. If the line is not contained in the given file, Puppet will add the line. Multiple resources can be declared to manage multiple lines in the same file. You can also use `match` to replace existing lines.

  ~~~

  file_line { 'sudo_rule':

    path => '/etc/sudoers',

    line => '%sudo ALL=(ALL) ALL',

  }

  file_line { 'sudo_rule_nopw':

    path => '/etc/sudoers',

    line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',

  }

  ~~~

##### Parameters

All parameters are optional, unless otherwise noted.

* `after`: Specifies the line after which Puppet will add any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined.

* `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'.

* `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined.

* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. Valid options: String containing a regex. Default: Undefined.

* `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined.

* `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined.

* `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file.

* `replace`: Defines whether the resource will overwrite an existing line that matches the `match` parameter. If set to false and a line is found matching the `match` param, the line will not be placed in the file. Valid options: true, false, yes, no. Default: true

### Functions

#### `abs`

Returns the absolute value of a number; for example, '-34.56' becomes '34.56'. Takes a single integer and float value as an argument. *Type*: rvalue.

#### `any2array`

Converts any object to an array containing that object. Empty argument lists are converted to an empty array. Arrays are left untouched. Hashes are converted to arrays of alternating keys and values. *Type*: rvalue.

#### `base64`

Converts a string to and from base64 encoding. Requires an action ('encode', 'decode') and either a plain or base64-encoded string. *Type*: rvalue.

#### `basename`

Returns the `basename` of a path (optionally stripping an extension). For example:

  * ('/path/to/a/file.ext') returns 'file.ext'

  * ('relative/path/file.ext') returns 'file.ext'

  * ('/path/to/a/file.ext', '.ext') returns 'file'

*Type*: rvalue.

#### `bool2num`

Converts a boolean to a number. Converts values:

  * 'false', 'f', '0', 'n', and 'no' to 0.

  * 'true', 't', '1', 'y', and 'yes' to 1.

  Requires a single boolean or string as an input. *Type*: rvalue.

#### `capitalize`

Capitalizes the first letter of a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue.

#### `ceiling`

Returns the smallest integer greater than or equal to the argument. Takes a single numeric value as an argument. *Type*: rvalue.

#### `chomp`

Removes the record separator from the end of a string or an array of strings; for example, 'hello\n' becomes 'hello'. Requires a single string or array as an input. *Type*: rvalue.

#### `chop`

Returns a new string with the last character removed. If the string ends with '\r\n', both characters are removed. Applying `chop` to an empty string returns an empty string. If you want to merely remove record separators, then you should use the `chomp` function. Requires a string or an array of strings as input. *Type*: rvalue.

#### `concat`

Appends the contents of multiple arrays onto the first array given. For example:

  * `concat(['1','2','3'],'4')` returns ['1','2','3','4'].

  * `concat(['1','2','3'],'4',['5','6','7'])` returns ['1','2','3','4','5','6','7'].

  *Type*: rvalue.

#### `convert_base`

Converts a given integer or base 10 string representing an integer to a specified base, as a string. For example:

  * `convert_base(5, 2)` results in: '101'

  * `convert_base('254', '16')` results in: 'fe'

#### `count`

If called with only an array, it counts the number of elements that are **not** nil/undef. If called with a second argument, counts the number of elements in an array that matches the second argument. *Type*: rvalue.

#### `defined_with_params`

Takes a resource reference and an optional hash of attributes. Returns 'true' if a resource with the specified attributes has already been added to the catalog. Returns 'false' otherwise.

  ~~~

  user { 'dan':

    ensure => present,

  }

  if ! defined_with_params(User[dan], {'ensure' => 'present' }) {

    user { 'dan': ensure => present, }

  }

  ~~~

*Type*: rvalue.

#### `delete`

Deletes all instances of a given element from an array, substring from a string, or key from a hash. For example, `delete(['a','b','c','b'], 'b')` returns ['a','c']; `delete('abracadabra', 'bra')` returns 'acada'. `delete({'a' => 1,'b' => 2,'c' => 3},['b','c'])` returns {'a'=> 1}. *Type*: rvalue.

#### `delete_at`

Deletes a determined indexed value from an array. For example, `delete_at(['a','b','c'], 1)` returns ['a','c']. *Type*: rvalue.

#### `delete_values`

Deletes all instances of a given value from a hash. For example, `delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B')` returns {'a'=>'A','c'=>'C','B'=>'D'} *Type*: rvalue.

#### `delete_undef_values`

Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue.

#### `difference`

Returns the difference between two arrays. The returned array is a copy of the original array, removing any items that also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. *Type*: rvalue.

#### `dirname`

Returns the `dirname` of a path. For example, `dirname('/path/to/a/file.ext')` returns '/path/to/a'. *Type*: rvalue.

#### `dos2unix`

Returns the Unix version of the given string. Very useful when using a File resource with a cross-platform template. *Type*: rvalue.

~~~

file{$config_file:

  ensure  => file,

  content => dos2unix(template('my_module/settings.conf.erb')),

}

~~~

See also [unix2dos](#unix2dos).

#### `downcase`

Converts the case of a string or of all strings in an array to lowercase. *Type*: rvalue.

#### `empty`

Returns 'true' if the variable is empty. *Type*: rvalue.

#### `ensure_packages`

Takes a list of packages and only installs them if they don't already exist. It optionally takes a hash as a second parameter to be passed as the third argument to the `ensure_resource()` function. *Type*: statement.

#### `ensure_resource`

Takes a resource type, title, and a hash of attributes that describe the resource(s).

~~~

user { 'dan':

  ensure => present,

}

~~~

This example only creates the resource if it does not already exist:

  `ensure_resource('user', 'dan', {'ensure' => 'present' })`

If the resource already exists, but does not match the specified parameters, this function attempts to recreate the resource, leading to a duplicate resource definition error.

An array of resources can also be passed in, and each will be created with the type and parameters specified if it doesn't already exist.

  `ensure_resource('user', ['dan','alex'], {'ensure' => 'present'})`

*Type*: statement.

#### `flatten`

Flattens deeply nested arrays and returns a single flat array as a result. For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c']. *Type*: rvalue.

#### `floor`

Takes a single numeric value as an argument, and returns the largest integer less than or equal to the argument. *Type*: rvalue.

#### `fqdn_rand_string`

Generates a random alphanumeric string using an optionally-specified character set (default is alphanumeric), combining the `$fqdn` fact and an optional seed for repeatable randomness.

*Usage:*

~~~

fqdn_rand_string(LENGTH, [CHARSET], [SEED])

~~~

*Examples:*

~~~

fqdn_rand_string(10)

fqdn_rand_string(10, 'ABCDEF!@#$%^')

fqdn_rand_string(10, '', 'custom seed')

~~~

*Type*: rvalue.

#### `fqdn_rotate`

Rotates an array or string a random number of times, combining the `$fqdn` fact and an optional seed for repeatable randomness.

*Usage:*

~~~

fqdn_rotate(VALUE, [SEED])

~~~

*Examples:*

~~~

fqdn_rotate(['a', 'b', 'c', 'd'])

fqdn_rotate('abcd')

fqdn_rotate([1, 2, 3], 'custom seed')

~~~

*Type*: rvalue.

#### `get_module_path`

Returns the absolute path of the specified module for the current environment.

  `$module_path = get_module_path('stdlib')`

*Type*: rvalue.

#### `getparam`

Takes a resource reference and the name of the parameter, and returns the value of the resource's parameter.

For example, the following returns 'param_value':

  ~~~

  define example_resource($param) {

  }

  example_resource { "example_resource_instance":

    param => "param_value"

  }

  getparam(Example_resource["example_resource_instance"], "param")

  ~~~

*Type*: rvalue.

#### `getvar`

Looks up a variable in a remote namespace.

For example:

  ~~~

  $foo = getvar('site::data::foo')

  # Equivalent to $foo = $site::data::foo

  ~~~

This is useful if the namespace itself is stored in a string:

  ~~~

  $datalocation = 'site::data'

  $bar = getvar("${datalocation}::bar")

  # Equivalent to $bar = $site::data::bar

  ~~~

*Type*: rvalue.

#### `grep`

Searches through an array and returns any elements that match the provided regular expression. For example, `grep(['aaa','bbb','ccc','aaaddd'], 'aaa')` returns ['aaa','aaaddd']. *Type*: rvalue.

#### `has_interface_with`

Returns a boolean based on kind and value:

  * macaddress

  * netmask

  * ipaddress

  * network

*Examples:*

  ~~~

  has_interface_with("macaddress", "x:x:x:x:x:x")

  has_interface_with("ipaddress", "127.0.0.1")    => true

  ~~~

If no kind is given, then the presence of the interface is checked:

  ~~~

  has_interface_with("lo")                        => true

  ~~~

*Type*: rvalue.

#### `has_ip_address`

Returns 'true' if the client has the requested IP address on some interface. This function iterates through the `interfaces` fact and checks the `ipaddress_IFACE` facts, performing a simple string comparison. *Type*: rvalue.

#### `has_ip_network`

Returns 'true' if the client has an IP address within the requested network. This function iterates through the `interfaces` fact and checks the `network_IFACE` facts, performing a simple string comparision. *Type*: rvalue.

#### `has_key`

Determines if a hash has a certain key value.

*Example*:

  ~~~

  $my_hash = {'key_one' => 'value_one'}

  if has_key($my_hash, 'key_two') {

    notice('we will not reach here')

  }

  if has_key($my_hash, 'key_one') {

    notice('this will be printed')

  }

  ~~~

*Type*: rvalue.

#### `hash`

Converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns {'a'=>1,'b'=>2,'c'=>3}. *Type*: rvalue.

#### `intersection`

Returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. *Type*: rvalue.

#### `is_array`

Returns 'true' if the variable passed to this function is an array. *Type*: rvalue.

#### `is_bool`

Returns 'true' if the variable passed to this function is a boolean. *Type*: rvalue.

#### `is_domain_name`

Returns 'true' if the string passed to this function is a syntactically correct domain name. *Type*: rvalue.

#### `is_float`

Returns 'true' if the variable passed to this function is a float. *Type*: rvalue.

#### `is_function_available`

Accepts a string as an argument and determines whether the Puppet runtime has access to a function by that name. It returns 'true' if the function exists, 'false' if not. *Type*: rvalue.

#### `is_hash`

Returns 'true' if the variable passed to this function is a hash. *Type*: rvalue.

#### `is_integer`

Returns 'true' if the variable returned to this string is an integer. *Type*: rvalue.

#### `is_ip_address`

Returns 'true' if the string passed to this function is a valid IP address. *Type*: rvalue.

#### `is_mac_address`

Returns 'true' if the string passed to this function is a valid MAC address. *Type*: rvalue.

#### `is_numeric`

Returns 'true' if the variable passed to this function is a number. *Type*: rvalue.

#### `is_string`

Returns 'true' if the variable passed to this function is a string. *Type*: rvalue.

#### `join`

Joins an array into a string using a separator. For example, `join(['a','b','c'], ",")` results in: "a,b,c". *Type*: rvalue.

#### `join_keys_to_values`

Joins each key of a hash to that key's corresponding value with a separator. Keys and values are cast to strings. The return value is an array in which each element is one joined key/value pair. For example, `join_keys_to_values({'a'=>1,'b'=>2}, " is ")` results in ["a is 1","b is 2"]. *Type*: rvalue.

#### `keys`

Returns the keys of a hash as an array. *Type*: rvalue.

#### `loadyaml`

Loads a YAML file containing an array, string, or hash, and returns the data in the corresponding native data type. For example:

  ~~~

  $myhash = loadyaml('/etc/puppet/data/myhash.yaml')

  ~~~

*Type*: rvalue.

#### `load_module_metadata`

Loads the metadata.json of a target module. Can be used to determine module version and authorship for dynamic support of modules.

  ~~~

  $metadata = load_module_metadata('archive')

  notify { $metadata['author']: }

  ~~~

*Type*: rvalue.

#### `lstrip`

Strips spaces to the left of a string. *Type*: rvalue.

#### `max`

Returns the highest value of all arguments. Requires at least one argument. *Type*: rvalue.

#### `member`

This function determines if a variable is a member of an array. The variable can be either a string, array, or fixnum. For example, `member(['a','b'], 'b')` and `member(['a','b','c'], ['b','c'])` return 'true', while `member(['a','b'], 'c')` and `member(['a','b','c'], ['c','d'])` return 'false'. *Note*: This function does not support nested arrays. If the first argument contains nested arrays, it will not recurse through them.

*Type*: rvalue.

#### `merge`

Merges two or more hashes together and returns the resulting hash.

*Example*:

  ~~~

  $hash1 = {'one' => 1, 'two' => 2}

  $hash2 = {'two' => 'dos', 'three' => 'tres'}

  $merged_hash = merge($hash1, $hash2)

  # The resulting hash is equivalent to: