bolt 0.20.0 → 0.20.2

data/vendored/puppet/lib/puppet/functions/info.rb

@@ -0,0 +1,14 @@
+# Logs a message on the server at level `info`.
+Puppet::Functions.create_function(:info, Puppet::Functions::InternalFunction) do
+  # @param values The values to log.
+  # @return [Undef]
+  dispatch :info do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def info(scope, *values)
+    Puppet::Util::Log.log_func(scope, :info, values)
+  end
+end

data/vendored/puppet/lib/puppet/functions/inline_epp.rb

@@ -0,0 +1,59 @@
+# 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 4.0.0
+#
+Puppet::Functions.create_function(:inline_epp, Puppet::Functions::InternalFunction) do
+
+  dispatch :inline_epp do
+    scope_param()
+    param 'String', :template
+    optional_param 'Hash[Pattern[/^\w+$/], Any]', :parameters
+  end
+
+  def inline_epp(scope, template, parameters = nil)
+    Puppet::Pops::Evaluator::EppEvaluator.inline_epp(scope, template, parameters)
+  end
+end

data/vendored/puppet/lib/puppet/functions/join.rb

@@ -0,0 +1,56 @@
+# Joins the values of an Array into a string with elements separated by a delimiter.
+#
+# Supports up to two arguments
+# * **values** - first argument is required and must be an an `Array`
+# * **delimiter** - second arguments is the delimiter between elements, must be a `String` if given, and defaults to an empty string.
+#
+# @example Typical use of `join`
+#
+# ```puppet
+# join(['a','b','c'], ",")
+# # Would result in: "a,b,c"
+# ```
+#
+# Note that array is flattened before elements are joined, but flattening does not extend to arrays nested in hashes or other objects.
+#
+# @example Arrays nested in hashes are not joined
+#
+# ```puppet
+# $a = [1,2, undef, 'hello', [x,y,z], {a => 2, b => [3, 4]}]
+# notice join($a, ', ')
+#
+# # would result in noticing:
+# # 1, 2, , hello, x, y, z, {"a"=>2, "b"=>[3, 4]}
+# ```
+#
+# For joining iterators and other containers of elements a conversion must first be made to
+# an `Array`. The reason for this is that there are many options how such a conversion should
+# be made.
+#
+# @example Joining the result of a reverse_each converted to an array
+# 
+# ```puppet
+# [1,2,3].reverse_each.convert_to(Array).join(', ')
+# # would result in: "3, 2, 1"
+# ```
+# @example Joining a hash
+#
+# ```puppet
+# {a => 1, b => 2}.convert_to(Array).join(', ')
+# # would result in "a, 1, b, 2"
+# ```
+#
+# For more detailed control over the formatting (including indentations and line breaks, delimiters around arrays
+# and hash entries, between key/values in hash entries, and individual formatting of values in the array)
+# see the `new` function for `String` and its formatting options for `Array` and `Hash`.
+#
+Puppet::Functions.create_function(:join) do
+  dispatch :join do
+    param 'Array', :arg
+    optional_param 'String', :delimiter
+  end
+
+  def join(arg, delimiter = '', puppet_formatting = false)
+      arg.join(delimiter)
+  end
+end

data/vendored/puppet/lib/puppet/functions/json_data.rb

@@ -0,0 +1,33 @@
+# The `json_data` is a hiera 5 `data_hash` data provider function.
+# See [the configuration guide documentation](https://docs.puppet.com/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-built-in-backends) for
+# how to use this function.
+#
+# @since 4.8.0
+#
+Puppet::Functions.create_function(:json_data) do
+  dispatch :json_data do
+    param 'Struct[{path=>String[1]}]', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  argument_mismatch :missing_path do
+    param 'Hash', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  def json_data(options, context)
+    path = options['path']
+    context.cached_file_data(path) do |content|
+      begin
+        JSON.parse(content)
+      rescue JSON::ParserError => ex
+        # Filename not included in message, so we add it here.
+        raise Puppet::DataBinding::LookupError, "Unable to parse (%{path}): %{message}" % { path: path, message: ex.message }
+      end
+    end
+  end
+
+  def missing_path(options, context)
+    "one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this data_hash function"
+  end
+end

data/vendored/puppet/lib/puppet/functions/keys.rb

@@ -0,0 +1,25 @@
+# Returns the keys of a hash as an Array
+#
+# @example Using `keys`
+#
+# ```puppet
+# $hsh = {"apples" => 3, "oranges" => 4 }
+# $hsh.keys()
+# keys($hsh)
+# # both results in the array ["apples", "oranges"]
+# ```
+#
+# * Note that a hash in the puppet language accepts any data value (including `undef`) unless
+#   it is constrained with a `Hash` data type that narrows the allowed data types.
+# * For an empty hash, an empty array is returned.
+# * The order of the keys is the same as the order in the hash (typically the order in which they were added).
+#
+Puppet::Functions.create_function(:keys) do
+  dispatch :keys do
+    param 'Hash', :hsh
+  end
+
+  def keys(hsh)
+    hsh.keys
+  end
+end

data/vendored/puppet/lib/puppet/functions/length.rb

@@ -0,0 +1,44 @@
+# Returns the length of an Array, Hash, String, or Binary value.
+#
+# The returned value is a positive integer indicating the number
+# of elements in the container; counting (possibly multibyte) characters for a `String`,
+# bytes in a `Binary`, number of elements in an `Array`, and number of
+# key-value associations in a Hash.
+#
+# @example Using `length`
+#
+# ```puppet
+# "roses".length()        # 5
+# length("violets")       # 7
+# [10, 20].length         # 2
+# {a => 1, b => 3}.length # 2
+# ```
+#
+# @since 5.5.0 - also supporting Binary
+#
+Puppet::Functions.create_function(:length) do
+  dispatch :collection_length do
+    param 'Collection', :arg
+  end
+
+  dispatch :string_length do
+    param 'String', :arg
+  end
+
+  dispatch :binary_length do
+    param 'Binary', :arg
+  end
+
+  def collection_length(col)
+    col.size
+  end
+
+  def string_length(s)
+    s.length
+  end
+
+  def binary_length(bin)
+    bin.length
+  end
+
+end

data/vendored/puppet/lib/puppet/functions/lest.rb

@@ -0,0 +1,55 @@
+# Calls a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# without arguments if the value given to `lest` 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
+#
+Puppet::Functions.create_function(:lest) do
+  dispatch :lest do
+    param 'Any', :arg
+    block_param 'Callable[0,0]', :block
+  end
+
+  def lest(arg)
+    if arg.nil?
+      yield()
+    else
+      arg
+    end
+  end
+end

data/vendored/puppet/lib/puppet/functions/lookup.rb

@@ -0,0 +1,223 @@
+# 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'}`, `{'strategy' => 'unique'}`,
+# or `{'strategy' => '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. If a value is exactly equal
+#     to the prefix, it will knockout the entire element. 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`.
+#
+# @example Look up a key and return the first value found
+#
+#     lookup('ntp::service_name')
+#
+# @example 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
+#
+# @example 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' => '--',
+#               },
+#     })
+#
+# @since 4.0.0
+Puppet::Functions.create_function(:lookup, Puppet::Functions::InternalFunction) do
+
+  local_types do
+    type 'NameType         = Variant[String, Array[String]]'
+    type 'ValueType        = Type'
+    type 'DefaultValueType = Any'
+    type 'MergeType        = Variant[String[1], Hash[String, Scalar]]'
+    type 'BlockType        = Callable[NameType]'
+    type "OptionsWithName  = Struct[{\
+      name                => NameType,\
+      value_type          => Optional[ValueType],\
+      default_value       => Optional[DefaultValueType],\
+      override            => Optional[Hash[String,Any]],\
+      default_values_hash => Optional[Hash[String,Any]],\
+      merge               => Optional[MergeType]\
+    }]"
+    type "OptionsWithoutName = Struct[{\
+      value_type          => Optional[ValueType],\
+      default_value       => Optional[DefaultValueType],\
+      override            => Optional[Hash[String,Any]],\
+      default_values_hash => Optional[Hash[String,Any]],\
+      merge               => Optional[MergeType]\
+    }]"
+
+  end
+
+  dispatch :lookup_1 do
+    scope_param
+    param           'NameType',       :name
+    optional_param  'ValueType',      :value_type
+    optional_param  'MergeType',      :merge
+  end
+
+  dispatch :lookup_2 do
+    scope_param
+    param 'NameType',                 :name
+    param 'Optional[ValueType]',      :value_type
+    param 'Optional[MergeType]',      :merge
+    param 'DefaultValueType',         :default_value
+  end
+
+  dispatch :lookup_3 do
+    scope_param
+    param                'NameType',   :name
+    optional_param       'ValueType',  :value_type
+    optional_param       'MergeType',  :merge
+    required_block_param 'BlockType',  :block
+  end
+
+  # Lookup without name. Name then becomes a required entry in the options hash
+  dispatch :lookup_4 do
+    scope_param
+    param                'OptionsWithName', :options_hash
+    optional_block_param 'BlockType',       :block
+  end
+
+  # Lookup using name and options hash.
+  dispatch :lookup_5 do
+    scope_param
+    param                'Variant[String,Array[String]]', :name
+    param                'OptionsWithoutName',            :options_hash
+    optional_block_param 'BlockType',                     :block
+  end
+
+  def lookup_1(scope, name, value_type=nil, merge=nil)
+    do_lookup(scope, name, value_type, nil, false, {}, {}, merge)
+  end
+
+  def lookup_2(scope, name, value_type, merge, default_value)
+    do_lookup(scope, name, value_type, default_value, true, {}, {}, merge)
+  end
+
+  def lookup_3(scope, name, value_type=nil, merge=nil, &block)
+    do_lookup(scope, name, value_type, nil, false, {}, {}, merge, &block)
+  end
+
+  def lookup_4(scope, options_hash, &block)
+    do_lookup(scope, options_hash['name'], *hash_args(options_hash), &block)
+  end
+
+  def lookup_5(scope, name, options_hash, &block)
+    do_lookup(scope, name, *hash_args(options_hash), &block)
+  end
+
+  def do_lookup(scope, name, value_type, default_value, has_default, override, default_values_hash, merge, &block)
+    Puppet::Pops::Lookup.lookup(name, value_type, default_value, has_default, merge, Puppet::Pops::Lookup::Invocation.new(scope, override, default_values_hash), &block)
+  end
+
+  def hash_args(options_hash)
+    [
+        options_hash['value_type'],
+        options_hash['default_value'],
+        options_hash.include?('default_value'),
+        options_hash['override'] || {},
+        options_hash['default_values_hash'] || {},
+        options_hash['merge']
+    ]
+  end
+end