puppet-retrospec 1.5.0 → 1.6.0

data/vendor/pup410/lib/puppet/parser/functions/hiera_include.rb

@@ -0,0 +1,102 @@
+require 'hiera_puppet'
+
+module Puppet::Parser::Functions
+  newfunction(
+    :hiera_include,
+    :arity => -2,
+    :doc => <<-DOC
+Assigns classes to a node using an
+[array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge)
+that retrieves the value for a user-specified key from Hiera's data.
+
+The `hiera_include` function requires:
+
+- A string key name to use for classes.
+- A call to this function (i.e. `hiera_include('classes')`) in your environment's
+`sites.pp` manifest, outside of any node definitions and below any top-scope variables
+that Hiera uses in lookups.
+- `classes` keys in the appropriate Hiera data sources, with an array for each
+`classes` key and each value of the array containing the name of a class.
+
+The function takes up to three arguments, in this order:
+
+1. A string key that Hiera searches for in the hierarchy. **Required**.
+2. An optional default value to return if Hiera doesn't find anything matching the key.
+    * If this argument isn't provided and this function results in a lookup failure, Puppet
+    fails with a compilation error.
+3. The optional name of an arbitrary
+[hierarchy level](https://docs.puppetlabs.com/hiera/latest/hierarchy.html) to insert at the
+top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+    * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+    searching the rest of the hierarchy.
+
+The function uses an
+[array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge)
+to retrieve the `classes` array, so every node gets every class from the hierarchy.
+
+**Example**: Using `hiera_include`
+
+~~~ yaml
+# Assuming hiera.yaml
+# :hierarchy:
+#   - web01.example.com
+#   - common
+
+# Assuming web01.example.com.yaml:
+# classes:
+#   - apache::mod::php
+
+# Assuming common.yaml:
+# classes:
+#   - apache
+~~~
+
+~~~ puppet
+# In site.pp, outside of any node definitions and below any top-scope variables:
+hiera_include('classes', undef)
+
+# Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+~~~
+
+You can optionally generate the default value with a
+[lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
+takes one parameter.
+
+**Example**: Using `hiera_include` with a lambda
+
+~~~ puppet
+# Assuming the same Hiera data as the previous example:
+
+# In site.pp, outside of any node definitions and below any top-scope variables:
+hiera_include('classes') | $key | {"Key \'${key}\' not found" }
+
+# Puppet assigns the apache and apache::mod::php classes to the web01.example.com node.
+# If hiera_include couldn't match its key, it would return the lambda result,
+# "Key 'classes' not found".
+~~~
+
+`hiera_include` is deprecated in favor of using a combination of `include`and `lookup` and will be
+removed in 6.0.0. See  https://docs.puppet.com/puppet/#{Puppet.minor_version}/reference/deprecated_language.html.
+Replace the calls as follows:
+
+| from  | to |
+| ----  | ---|
+| hiera_include($key) | include(lookup($key, { 'merge' => 'unique' })) |
+| hiera_include($key, $default) | include(lookup($key, { 'default_value' => $default, 'merge' => 'unique' })) |
+| hiera_include($key, $default, $level) | override level not supported |
+
+Note that calls using the 'override level' option are not directly supported by 'lookup' and the produced
+result must be post processed to get exactly the same result, for example using simple hash/array `+` or
+with calls to stdlib's `deep_merge` function depending on kind of hiera call and setting of merge in hiera.yaml.
+
+See [the documentation](http://links.puppetlabs.com/hierainclude) for more information
+and a more detailed example of how `hiera_include` uses array merge lookups to classify
+nodes.
+
+- Since 4.0.0
+DOC
+  ) do |*args|
+    Error.is4x('hiera_include')
+  end
+end
+

data/vendor/pup410/lib/puppet/parser/functions/include.rb

@@ -0,0 +1,33 @@
+# Include the specified classes
+Puppet::Parser::Functions::newfunction(:include, :arity => -2, :doc =>
+"Declares one or more classes, causing the resources in them to be
+evaluated and added to the catalog. Accepts a class name, an array of class
+names, or a comma-separated list of class names.
+
+The `include` function can be used multiple times on the same class and will
+only declare a given class once. If a class declared with `include` has any
+parameters, Puppet will automatically look up values for them in Hiera, using
+`<class name>::<parameter name>` as the lookup key.
+
+Contrast this behavior with resource-like class declarations
+(`class {'name': parameter => 'value',}`), which must be used in only one place
+per class and can directly set parameters. You should avoid using both `include`
+and resource-like declarations with the same class.
+
+The `include` function does not cause classes to be contained in the class
+where they are declared. For that, see the `contain` function. It also
+does not create a dependency relationship between the declared class and the
+surrounding class; for that, see the `require` function.
+
+You must use the class's full name;
+relative names are not allowed. In addition to names in string form,
+you may also directly use Class and Resource Type values that are produced by
+the future parser's resource and relationship expressions.
+
+- Since < 3.0.0
+- Since 4.0.0 support for class and resource type values, absolute names
+- Since 4.7.0 returns an Array[Type[Class]] of all included classes 
+") do |classes|
+  Puppet.warn_once(:deprecation, '3xfunction#include', "Calling function_include via the Scope class is deprecated. Use Scope#call_function instead")
+  call_function('include', classes)
+end

data/vendor/pup410/lib/puppet/parser/functions/inline_epp.rb

@@ -0,0 +1,51 @@
+Puppet::Parser::Functions::newfunction(:inline_epp, :type => :rvalue, :arity => -2, :doc =>
+"Evaluates an Embedded Puppet (EPP) template string and returns the rendered
+text result as a String.
+
+`inline_epp('<EPP TEMPLATE STRING>', <PARAMETER HASH>)`
+
+The first argument to this function should be a string containing an EPP
+template. In most cases, the last argument is optional; if used, it should be a
+[hash](/puppet/latest/reference/lang_data_hash.html) that contains parameters to
+pass to the template.
+
+- See the [template](/puppet/latest/reference/lang_template.html) documentation
+for general template usage information.
+- See the [EPP syntax](/puppet/latest/reference/lang_template_epp.html)
+documentation for examples of EPP.
+
+For example, to evaluate an inline EPP template and pass it the `docroot` and
+`virtual_docroot` parameters, call the `inline_epp` function like this:
+
+`inline_epp('docroot: <%= $docroot %> Virtual docroot: <%= $virtual_docroot %>',
+{ 'docroot' => '/var/www/html', 'virtual_docroot' => '/var/www/example' })`
+
+Puppet produces a syntax error if you pass more parameters than are declared in
+the template's parameter tag. When passing parameters to a template that
+contains a parameter tag, use the same names as the tag's declared parameters.
+
+Parameters are required only if they are declared in the called template's
+parameter tag without default values. Puppet produces an error if the
+`inline_epp` function fails to pass any required parameter.
+
+An inline EPP template should be written as a single-quoted string or
+[heredoc](/puppet/latest/reference/lang_data_string.html#heredocs).
+A double-quoted string is subject to expression interpolation before the string
+is parsed as an EPP template.
+
+For example, to evaluate an inline EPP template using a heredoc, call the
+`inline_epp` function like this:
+
+~~~ puppet
+# Outputs 'Hello given argument planet!'
+inline_epp(@(END), { x => 'given argument' })
+<%- | $x, $y = planet | -%>
+Hello <%= $x %> <%= $y %>!
+END
+~~~
+
+- Since 3.5
+- Requires [future parser](/puppet/3.8/reference/experiments_future.html) in Puppet 3.5 to 3.8") do |arguments|
+
+  Puppet::Parser::Functions::Error.is4x('inline_epp')
+end

data/vendor/pup410/lib/puppet/parser/functions/lest.rb

@@ -0,0 +1,49 @@
+Puppet::Parser::Functions::newfunction(
+  :lest,
+  :type => :rvalue,
+  :arity => -2,
+  :doc => <<-DOC
+Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+(which should accept no arguments) if the argument given to the function is `undef`.
+Returns the result of calling the lambda if the argument is `undef`, otherwise the
+given argument.
+
+The `lest` function is useful in a chain of `then` calls, or in general
+as a guard against `undef` values. The function can be used to call `fail`, or to
+return a default value.
+
+These two expressions are equivalent:
+
+```puppet
+if $x == undef { do_things() }
+lest($x) || { do_things() }
+```
+
+**Example:** Using the `lest` function
+
+```puppet
+$data = {a => [ b, c ] }
+notice $data.dig(a, b, c)
+ .then |$x| { $x * 2 }
+ .lest || { fail("no value for $data[a][b][c]" }
+```
+
+Would fail the operation because $data[a][b][c] results in `undef`
+(there is no `b` key in `a`).
+
+In contrast - this example:
+
+```puppet
+$data = {a => { b => { c => 10 } } }
+notice $data.dig(a, b, c)
+ .then |$x| { $x * 2 }
+ .lest || { fail("no value for $data[a][b][c]" }
+```
+
+Would notice the value `20`
+
+* Since 4.5.0
+DOC
+) do |args|
+  Puppet::Parser::Functions::Error.is4x('lest')
+end

data/vendor/pup410/lib/puppet/parser/functions/lookup.rb

@@ -0,0 +1,132 @@
+module Puppet::Parser::Functions
+  newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<-'ENDHEREDOC') do |args|
+Uses the Puppet lookup system to retrieve a value for a given key. By default,
+this returns the first value found (and fails compilation if no values are
+available), but you can configure it to merge multiple values into one, fail
+gracefully, and more.
+
+When looking up a key, Puppet will search up to three tiers of data, in the
+following order:
+
+1. Hiera.
+2. The current environment's data provider.
+3. The indicated module's data provider, if the key is of the form
+   `<MODULE NAME>::<SOMETHING>`.
+
+#### Arguments
+
+You must provide the name of a key to look up, and can optionally provide other
+arguments. You can combine these arguments in the following ways:
+
+* `lookup( <NAME>, [<VALUE TYPE>], [<MERGE BEHAVIOR>], [<DEFAULT VALUE>] )`
+* `lookup( [<NAME>], <OPTIONS HASH> )`
+* `lookup( as above ) |$key| { # lambda returns a default value }`
+
+Arguments in `[square brackets]` are optional.
+
+The arguments accepted by `lookup` are as follows:
+
+1. `<NAME>` (string or array) --- The name of the key to look up.
+    * This can also be an array of keys. If Puppet doesn't find anything for the
+    first key, it will try again with the subsequent ones, only resorting to a
+    default value if none of them succeed.
+2. `<VALUE TYPE>` (data type) --- A
+[data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_type.html)
+that must match the retrieved value; if not, the lookup (and catalog
+compilation) will fail. Defaults to `Data` (accepts any normal value).
+3. `<MERGE BEHAVIOR>` (string or hash; see **"Merge Behaviors"** below) ---
+Whether (and how) to combine multiple values. If present, this overrides any
+merge behavior specified in the data sources. Defaults to no value; Puppet will
+use merge behavior from the data sources if present, and will otherwise do a
+first-found lookup.
+4. `<DEFAULT VALUE>` (any normal value) --- If present, `lookup` returns this
+when it can't find a normal value. Default values are never merged with found
+values. Like a normal value, the default must match the value type. Defaults to
+no value; if Puppet can't find a normal value, the lookup (and compilation) will
+fail.
+5. `<OPTIONS HASH>` (hash) --- Alternate way to set the arguments above, plus
+some less-common extra options. If you pass an options hash, you can't combine
+it with any regular arguments (except `<NAME>`). An options hash can have the
+following keys:
+    * `'name'` --- Same as `<NAME>` (argument 1). You can pass this as an
+    argument or in the hash, but not both.
+    * `'value_type'` --- Same as `<VALUE TYPE>` (argument 2).
+    * `'merge'` --- Same as `<MERGE BEHAVIOR>` (argument 3).
+    * `'default_value'` --- Same as `<DEFAULT VALUE>` (argument 4).
+    * `'default_values_hash'` (hash) --- A hash of lookup keys and default
+    values. If Puppet can't find a normal value, it will check this hash for the
+    requested key before giving up. You can combine this with `default_value` or
+    a lambda, which will be used if the key isn't present in this hash. Defaults
+    to an empty hash.
+    * `'override'` (hash) --- A hash of lookup keys and override values. Puppet
+    will check for the requested key in the overrides hash _first;_ if found, it
+    returns that value as the _final_ value, ignoring merge behavior. Defaults
+    to an empty hash.
+
+Finally, `lookup` can take a lambda, which must accept a single parameter.
+This is yet another way to set a default value for the lookup; if no results are
+found, Puppet will pass the requested key to the lambda and use its result as
+the default value.
+
+#### Merge Behaviors
+
+Puppet lookup uses a hierarchy of data sources, and a given key might have
+values in multiple sources. By default, Puppet returns the first value it finds,
+but it can also continue searching and merge all the values together.
+
+> **Note:** Data sources can use the special `lookup_options` metadata key to
+request a specific merge behavior for a key. The `lookup` function will use that
+requested behavior unless you explicitly specify one.
+
+The valid merge behaviors are:
+
+* `'first'` --- Returns the first value found, with no merging. Puppet lookup's
+default behavior.
+* `'unique'` (called "array merge" in classic Hiera) --- Combines any number of
+arrays and scalar values to return a merged, flattened array with all duplicate
+values removed. The lookup will fail if any hash values are found.
+* `'hash'` --- Combines the keys and values of any number of hashes to return a
+merged hash. If the same key exists in multiple source hashes, Puppet will use
+the value from the highest-priority data source; it won't recursively merge the
+values.
+* `'deep'` --- Combines the keys and values of any number of hashes to return a
+merged hash. If the same key exists in multiple source hashes, Puppet will
+recursively merge hash or array values (with duplicate values removed from
+arrays). For conflicting scalar values, the highest-priority value will win.
+* `{'strategy' => 'first|unique|hash'}` --- Same as the string versions of these
+merge behaviors.
+* `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
+but can adjust the merge with additional options. The available options are:
+    * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a
+    value should be _removed_ from the final result. Defaults to `undef`, which
+    disables this feature.
+    * `'sort_merged_arrays'` (boolean) --- Whether to sort all arrays that are
+    merged together. Defaults to `false`.
+    * `'merge_hash_arrays'` (boolean) --- Whether to merge hashes within arrays.
+    Defaults to `false`.
+
+#### Examples
+
+Look up a key and return the first value found:
+
+    lookup('ntp::service_name')
+
+Do a unique merge lookup of class names, then add all of those classes to the
+catalog (like `hiera_include`):
+
+    lookup('classes', Array[String], 'unique').include
+
+Do a deep hash merge lookup of user data, but let higher priority sources
+remove values by prefixing them with `--`:
+
+    lookup( { 'name'  => 'users',
+              'merge' => {
+                'strategy'        => 'deep',
+                'knockout_prefix' => '--',
+              },
+    })
+
+ENDHEREDOC
+  Error.is4x('lookup')
+end
+end

data/vendor/pup410/lib/puppet/parser/functions/map.rb

@@ -0,0 +1,76 @@
+Puppet::Parser::Functions::newfunction(
+  :map,
+  :type => :rvalue,
+  :arity => -3,
+  :doc => <<-DOC
+Applies a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+to every value in a data structure and returns an array containing the results.
+
+This function takes two mandatory arguments, in this order:
+
+1. An array or hash the function will iterate over.
+2. A lambda, which the function calls for each element in the first argument. It can
+request one or two parameters.
+
+**Example**: Using the `map` function
+
+`$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
+
+or
+
+`$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
+
+When the first argument (`$data` in the above example) is an array, Puppet passes each
+value in turn to the lambda.
+
+**Example**: Using the `map` function with an array and a one-parameter lambda
+
+~~~ puppet
+# For the array $data, return an array containing each value multiplied by 10
+$data = [1,2,3]
+$transformed_data = $data.map |$items| { $items * 10 }
+# $transformed_data contains [10,20,30]
+~~~
+
+When the first argument is a hash, Puppet passes each key and value pair to the lambda
+as an array in the form `[key, value]`.
+
+**Example**: Using the `map` function with a hash and a one-parameter lambda
+
+~~~ puppet
+# For the hash $data, return an array containing the keys
+$data = {'a'=>1,'b'=>2,'c'=>3}
+$transformed_data = $data.map |$items| { $items[0] }
+# $transformed_data contains ['a','b','c']
+~~~
+
+When the first argument is an array and the lambda has two parameters, Puppet passes the
+array's indexes (enumerated from 0) in the first parameter and its values in the second
+parameter.
+
+**Example**: Using the `map` function with an array and a two-parameter lambda
+
+~~~ puppet
+# For the array $data, return an array containing the indexes
+$data = [1,2,3]
+$transformed_data = $data.map |$index,$value| { $index }
+# $transformed_data contains [0,1,2]
+~~~
+
+When the first argument is a hash, Puppet passes its keys to the first parameter and its
+values to the second parameter.
+
+**Example**: Using the `map` function with a hash and a two-parameter lambda
+
+~~~ puppet
+# For the hash $data, return an array containing each value
+$data = {'a'=>1,'b'=>2,'c'=>3}
+$transformed_data = $data.map |$key,$value| { $value }
+# $transformed_data contains [1,2,3]
+~~~
+
+- Since 4.0.0
+DOC
+) do |args|
+  Puppet::Parser::Functions::Error.is4x('map')
+end