puppet-retrospec 0.12.2 → 1.0.0

data/vendor/gems/puppet-4.5.2/lib/puppet/parser/functions/hiera_array.rb

@@ -0,0 +1,78 @@
+require 'hiera_puppet'
+
+module Puppet::Parser::Functions
+  newfunction(
+    :hiera_array,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<-DOC
+Finds all matches of a key throughout the hierarchy and returns them as a single flattened
+array of unique values. If any of the matched values are arrays, they're flattened and
+included in the results. This is called an
+[array merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#array-merge).
+
+The `hiera_array` 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.
+
+**Example**: Using `hiera_array`
+
+~~~ yaml
+# Assuming hiera.yaml
+# :hierarchy:
+#   - web01.example.com
+#   - common
+
+# Assuming common.yaml:
+# users:
+#   - 'cdouglas = regular'
+#   - 'efranklin = regular'
+
+# Assuming web01.example.com.yaml:
+# users: 'abarry = admin'
+~~~
+
+~~~ puppet
+$allusers = hiera_array('users', undef)
+
+# $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+~~~
+
+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_array` with a lambda
+
+~~~ puppet
+# Assuming the same Hiera data as the previous example:
+
+$allusers = hiera_array('users') | $key | { "Key \'${key}\' not found" }
+
+# $allusers contains ["cdouglas = regular", "efranklin = regular", "abarry = admin"].
+# If hiera_array couldn't match its key, it would return the lambda result,
+# "Key 'users' not found".
+~~~
+
+`hiera_array` expects that all values returned will be strings or arrays. If any matched
+value is a hash, Puppet raises a type mismatch error.
+
+See
+[the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+for more information about Hiera lookup functions.
+
+- Since 4.0.0
+DOC
+) do |*args|
+    function_fail(["hiera_array() has been converted to 4x API"])
+  end
+end
+

data/vendor/gems/puppet-4.5.2/lib/puppet/parser/functions/hiera_hash.rb

@@ -0,0 +1,88 @@
+require 'hiera_puppet'
+
+module Puppet::Parser::Functions
+  newfunction(
+    :hiera_hash,
+    :type => :rvalue,
+    :arity => -2,
+    :doc => <<-DOC
+Finds all matches of a key throughout the hierarchy and returns them in a merged hash.
+If any of the matched hashes share keys, the final hash uses the value from the
+highest priority match. This is called a
+[hash merge lookup](https://docs.puppetlabs.com/hiera/latest/lookup_types.html#hash-merge).
+
+The merge strategy is determined by Hiera's
+[`:merge_behavior`](https://docs.puppetlabs.com/hiera/latest/configuring.html#mergebehavior)
+setting.
+
+The `hiera_hash` 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.
+
+**Example**: Using `hiera_hash`
+
+~~~ yaml
+# Assuming hiera.yaml
+# :hierarchy:
+#   - web01.example.com
+#   - common
+
+# Assuming common.yaml:
+# users:
+#   regular:
+#     'cdouglas': 'Carrie Douglas'
+
+# Assuming web01.example.com.yaml:
+# users:
+#   administrators:
+#     'aberry': 'Amy Berry'
+~~~
+
+~~~ puppet
+# Assuming we are not web01.example.com:
+
+$allusers = hiera_hash('users', undef)
+
+# $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+#                     administrators => {"aberry" => "Amy Berry"}}
+~~~
+
+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_hash` with a lambda
+
+~~~ puppet
+# Assuming the same Hiera data as the previous example:
+
+$allusers = hiera_hash('users') | $key | { "Key \'${key}\' not found" }
+
+# $allusers contains {regular => {"cdouglas" => "Carrie Douglas"},
+#                     administrators => {"aberry" => "Amy Berry"}}
+# If hiera_hash couldn't match its key, it would return the lambda result,
+# "Key 'users' not found".
+~~~
+
+`hiera_hash` expects that all values returned will be hashes. If any of the values
+found in the data sources are strings or arrays, Puppet raises a type mismatch error.
+
+See
+[the documentation](https://docs.puppetlabs.com/hiera/latest/puppet.html#hiera-lookup-functions)
+for more information about Hiera lookup functions.
+
+- Since 4.0.0
+DOC
+  ) do |*args|
+    function_fail(["hiera_hash() has been converted to 4x API"])
+  end
+end
+

data/vendor/gems/puppet-4.5.2/lib/puppet/parser/functions/hiera_include.rb

@@ -0,0 +1,88 @@
+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".
+~~~
+
+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|
+    function_fail(["hiera_include() has been converted to 4x API"])
+  end
+end
+

data/vendor/gems/puppet-4.5.2/lib/puppet/parser/functions/include.rb

@@ -0,0 +1,37 @@
+# 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
+") do |vals|
+
+  # Unify call patterns (if called with nested arrays), make names absolute if
+  # wanted and evaluate the classes
+  compiler.evaluate_classes(
+  transform_and_assert_classnames(
+      vals.is_a?(Array) ? vals.flatten : [vals]),
+      self, false)
+end

data/vendor/gems/puppet-4.5.2/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|
+
+  function_fail(["inline_epp() is only available when parser/evaluator future is in effect"])
+end

data/vendor/gems/puppet-4.5.2/lib/puppet/parser/functions/inline_template.rb

@@ -0,0 +1,21 @@
+Puppet::Parser::Functions::newfunction(:inline_template, :type => :rvalue, :arity => -2, :doc =>
+  "Evaluate a template string and return its value.  See
+  [the templating docs](https://docs.puppetlabs.com/puppet/latest/reference/lang_template.html) for
+  more information. Note that if multiple template strings are specified, their
+  output is all concatenated and returned as the output of the function.") do |vals|
+
+  require 'erb'
+
+    vals.collect do |string|
+      # Use a wrapper, so the template can't get access to the full
+      # Scope object.
+
+      wrapper = Puppet::Parser::TemplateWrapper.new(self)
+      begin
+        wrapper.result(string)
+      rescue => detail
+        raise Puppet::ParseError,
+          "Failed to parse inline template: #{detail}", detail.backtrace
+      end
+    end.join("")
+end

data/vendor/gems/puppet-4.5.2/lib/puppet/parser/functions/lookup.rb

@@ -0,0 +1,130 @@
+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
+  function_fail(["lookup() has been converted to 4x API"])
+end