bolt 0.0.1 → 0.5.0

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

@@ -0,0 +1,200 @@
+# Runs a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# recursively and repeatedly using values from a data structure, then returns the unchanged data structure, or if
+# a lambda is not given, returns an `Iterator` for the tree.
+#
+# This function takes one mandatory argument, one optional, and an optional block in this order:
+#
+# 1. An `Array`, `Hash`, `Iterator`, or `Object` that the function will iterate over.
+# 2. An optional hash with the options:
+#    * `include_containers` => `Optional[Boolean]` # default true - if containers should be given to the lambda
+#    * `include_values` => `Optional[Boolean]` # default true - if non containers should be given to the lambda
+#    * `include_root` => `Optional[Boolean]` # default true - if the root container should be given to the lambda
+#    * `container_type` => `Optional[Type[Variant[Array, Hash, Object]]]` # a type that determines what a container is - can only
+#       be set to a type that matches the default `Variant[Array, Hash, Object]`.
+#    * `order` => `Enum[depth_first, breadth_first]` # default ´depth_first`, the order in which elements are visited
+#    * `include_refs` => Optional[Boolean] # default `false`, if attributes in objects marked as bing of `reference` kind
+#       should be included.
+# 3. An optional lambda, which the function calls for each element in the first argument. It must
+#    accept one or two arguments; either `$path`, and `$value`, or just `$value`.
+#
+# @example Using the `tree_each` function
+#
+# `$data.tree_each |$path, $value| { <PUPPET CODE BLOCK> }`
+# `$data.tree_each |$value| { <PUPPET CODE BLOCK> }`
+#
+# or
+#
+# `tree_each($data) |$path, $value| { <PUPPET CODE BLOCK> }`
+# `tree_each($data) |$value| { <PUPPET CODE BLOCK> }`
+#
+# The parameter `$path` is always given as an `Array` containing the path that when applied to
+# the tree as `$data.dig(*$path) yields the `$value`.
+# The `$value` is the value at that path.
+#
+# For `Array` values, the path will contain `Integer` entries with the array index,
+# and for `Hash` values, the path will contain the hash key, which may be `Any` value.
+# For `Object` containers, the entry is the name of the attribute (a `String`).
+#
+# The tree is walked in either depth-first order, or in breadth-first order under the control of the
+# `order` option, yielding each `Array`, `Hash`, `Object`, and each entry/attribute.
+# The default is `depth_first` which means that children are processed before siblings.
+# An order of `breadth_first` means that siblings are processed before children.
+#
+# @example depth- or breadth-first order
+#
+# ~~~ puppet
+# [1, [2, 3], 4]
+# ~~~
+# 
+# Results in:
+# 
+# If containers are skipped:
+#
+# * `depth_first` order `1`, `2`, `3`, `4` 
+# * `breadth_first` order `1`, `4`,`2`, `3` 
+#
+# If containers and root, are included:
+#
+# * `depth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `2`, `3`, `4` 
+# * `breadth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `4`, `2`, `3` 
+#
+# Typical use of the `tree_each` function include:
+# * a more efficient way to iterate over a tree than first using `flatten` on an array
+#   as that requires a new (potentially very large) array to be created
+# * when a tree needs to be transformed and 'pretty printed' in a template
+# * avoiding having to write a special recursive function when tree contains hashes (flatten does
+#   not work on hashes)
+#
+# @example A flattened iteration over a tree excluding Collections
+#
+# ~~~ puppet
+# $data = [1, 2, [3, [4, 5]]]
+# $data.tree_each({include_containers => false}) |$v| { notice "$v" }
+# ~~~
+#
+# This would call the lambda 5 times with with the following values in sequence: `1`, `2`, `3`, `4`, `5`
+#
+# @example A flattened iteration over a tree (including containers by default)
+#
+# ~~~ puppet
+# $data = [1, 2, [3, [4, 5]]]
+# $data.tree_each |$v| { notice "$v" }
+# ~~~
+#
+# This would call the lambda 7 times with the following values in sequence:
+# `1`, `2`, `[3, [4, 5]]`, `3`, `[4, 5]`, `4`, `5`
+#
+# @example A flattened iteration over a tree (including only non root containers)
+#
+# ~~~ puppet
+# $data = [1, 2, [3, [4, 5]]]
+# $data.tree_each({include_values => false, include_root => false}) |$v| { notice "$v" }
+# ~~~
+#
+# This would call the lambda 2 times with the following values in sequence:
+# `[3, [4, 5]]`, `[4, 5]`
+
+# Any Puppet Type system data type can be used to filter what is
+# considered to be a container, but it must be a narrower type than one of
+# the default Array, Hash, Object types - for example it is not possible to make a
+# `String` be a container type.
+#
+# @example Only `Array` as container type
+#
+# ~~~ puppet
+# $data = [1, {a => 'hello', b => [100, 200]}, [3, [4, 5]]]
+# $data.tree_each({container_type => Array, include_containers => false} |$v| { notice "$v" }
+# ~~~
+# 
+# Would call the lambda 5 times with `1`, `{a => 'hello', b => [100, 200]}`, `3`, `4`, `5`
+#
+# **Chaining** When calling `tree_each` without a lambda the function produces an `Iterator`
+# that can be chained into another iteration. Thus it is easy to use one of:
+# 
+# * `reverse_each` - get "leaves before root" 
+# * `filter` - prune the tree
+# * `map` - transform each element
+# * `reduce` - produce something else
+#
+# Note than when chaining, the value passed on is a `Tuple` with `[path, value]`.
+#
+# @example pruning a tree
+# 
+# ~~~ puppet
+# # A tree of some complexity (here very simple for readability)
+# $tree = [
+#  { name => 'user1', status => 'inactive', id => '10'},
+#  { name => 'user2', status => 'active', id => '20'}
+# ]
+# notice $tree.tree_each.filter |$v| {
+#  $value = $v[1]
+#  $value =~ Hash and $value[status] == active
+# }
+# ~~~
+#
+# Would notice `[[[1], {name => user2, status => active, id => 20}]]`, which can then be processed
+# further as each filtered result appears as a `Tuple` with `[path, value]`.
+#
+#
+# For general examples that demonstrates iteration see the Puppet
+# [iteration](https://docs.puppetlabs.com/puppet/latest/reference/lang_iteration.html)
+# documentation.
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:tree_each) do
+
+  local_types do
+    type "OptionsType  = Struct[{\
+      container_type => Optional[Type],\
+      include_root   => Optional[Boolean],
+      include_containers => Optional[Boolean],\
+      include_values => Optional[Boolean],\
+      order => Optional[Enum[depth_first, breadth_first]],\
+      include_refs   => Optional[Boolean]\
+    }]"
+  end
+
+  dispatch :tree_Enumerable2 do
+    param 'Variant[Iterator, Array, Hash, Object]', :tree
+    optional_param 'OptionsType', :options
+    block_param 'Callable[2,2]', :block
+  end
+
+  dispatch :tree_Enumerable1 do
+    param 'Variant[Iterator, Array, Hash, Object]', :tree
+    optional_param 'OptionsType', :options
+    block_param 'Callable[1,1]', :block
+  end
+
+  dispatch :tree_Iterable do
+    param 'Variant[Iterator, Array, Hash, Object]', :tree
+    optional_param 'OptionsType', :options
+  end
+
+  def tree_Enumerable1(enum, options = {}, &block)
+    iterator(enum, options).each {|_, v| yield(v) }
+    enum
+  end
+
+  def tree_Enumerable2(enum, options = {}, &block)
+    iterator(enum, options).each {|path, v| yield(path, v) }
+    enum
+  end
+
+  def tree_Iterable(enum, options = {}, &block)
+    Puppet::Pops::Types::Iterable.on(iterator(enum, options))
+  end
+
+  def iterator(enum, options)
+    if depth_first?(options)
+      Puppet::Pops::Types::Iterable::DepthFirstTreeIterator.new(enum, options)
+    else
+      Puppet::Pops::Types::Iterable::BreadthFirstTreeIterator.new(enum, options)
+    end
+  end
+
+  def depth_first?(options)
+    (order = options['order']).nil? ? true : order == 'depth_first'
+  end
+end

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

@@ -0,0 +1,31 @@
+# (Documentation in 3.x stub)
+# @since 4.4.0
+#
+Puppet::Functions.create_function(:type) do
+  dispatch :type_detailed do
+    param 'Any', :value
+    optional_param 'Enum[detailed]', :inference_method
+  end
+
+  dispatch :type_parameterized do
+    param 'Any', :value
+    param 'Enum[reduced]', :inference_method
+  end
+
+  dispatch :type_generalized do
+    param 'Any', :value
+    param 'Enum[generalized]', :inference_method
+  end
+
+  def type_detailed(value, _ = nil)
+    Puppet::Pops::Types::TypeCalculator.infer_set(value)
+  end
+
+  def type_parameterized(value, _)
+    Puppet::Pops::Types::TypeCalculator.infer(value)
+  end
+
+  def type_generalized(value, _)
+    Puppet::Pops::Types::TypeCalculator.infer(value).generalize
+  end
+end

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

@@ -0,0 +1,132 @@
+# The `unique` function returns a unique set of values from an `Iterable` argument.
+#
+# * If the argument is a `String`, the unique set of characters are returned as a new `String`.
+# * If the argument is a `Hash`, the resulting hash associates a set of keys with a set of unique values.
+# * For all other types of `Iterable` (`Array`, `Iterator`) the result is an `Array` with
+#   a unique set of entries.
+# * Comparison of all `String` values are case sensitive.
+# * An optional code block can be given - if present it is given each candidate value and its return is used instead of the given value. This
+#   enables transformation of the value before comparison. The result of the lambda is only used for comparison.
+# * The optional code block when used with a hash is given each value (not the keys).
+#
+# @example Using unique with a String
+#
+# ~~~puppet
+# # will produce 'abc'
+# "abcaabb".unique
+# ~~~
+#
+# @example Using unique with an Array
+#
+# ~~~puppet
+# # will produce ['a', 'b', 'c']
+# ['a', 'b', 'c', 'a', 'a', 'b'].unique
+# ~~~
+#
+# @example Using unique with a Hash
+#
+# ~~~puppet
+# # will produce { ['a', 'b'] => [10], ['c'] => [20]}
+# {'a' => 10, 'b' => 10, 'c' => 20}.unique
+#
+# # will produce { 'a' => 10, 'c' => 20 } (use first key with first value)
+# Hash.new({'a' => 10, 'b' => 10, 'c' => 20}.unique.map |$k, $v| { [ $k[0] , $v[0]] })
+#
+# # will produce { 'b' => 10, 'c' => 20 } (use last key with first value)
+# Hash.new({'a' => 10, 'b' => 10, 'c' => 20}.unique.map |$k, $v| { [ $k[-1] , $v[0]] })
+# ~~~
+#
+# @example Using unique with an Iterable
+#
+# ~~~
+# # will produce [3, 2, 1]
+# [1,2,2,3,3].reverse_each.unique
+# ~~~
+#
+# @example Using unique with a lambda
+#
+# ~~~puppet
+# # will produce [['sam', 'smith'], ['sue', 'smith']]
+# [['sam', 'smith'], ['sam', 'brown'], ['sue', 'smith']].unique |$x| { $x[0] }
+#
+# # will produce [['sam', 'smith'], ['sam', 'brown']]
+# [['sam', 'smith'], ['sam', 'brown'], ['sue', 'smith']].unique |$x| { $x[1] }
+#
+# # will produce ['aBc', 'bbb'] (using a lambda to make comparison using downcased (%d) strings)
+# ['aBc', 'AbC', 'bbb'].unique |$x| { String($x,'%d') }
+#
+# # will produce {[a] => [10], [b, c, d, e] => [11, 12, 100]}
+# {a => 10, b => 11, c => 12, d => 100, e => 11}.unique |$v| { if $v > 10 { big } else { $v } } 
+# ~~~
+#
+# Note that for `Hash` the result is slightly different than for the other data types. For those the result contains the
+# *first-found* unique value, but for `Hash` it contains associations from a set of keys to the set of values clustered by the
+# equality lambda (or the default value equality if no lambda was given). This makes the `unique` function more versatile for hashes
+# in general, while requiring that the simple computation of "hash's unique set of values" is performed as `$hsh.map |$k, $v| { $v }.unique`.
+# (A unique set of hash keys is in general meaningless (since they are unique by definition) - although if processed with a different
+# lambda for equality that would be different. First map the hash to an array of its keys if such a unique computation is wanted). 
+# If the more advanced clustering is wanted for one of the other data types, simply transform it into a `Hash` as shown in the
+# following example.
+#
+# @example turning a string or array into a hash with index keys
+#
+# ~~puppet
+# # Array ['a', 'b', 'c'] to Hash with index results in
+# # {0 => 'a', 1 => 'b', 2 => 'c'}
+# Hash(['a', 'b', 'c'].map |$i, $v| { [$i, $v]})
+#
+# # String "abc" to Hash with index results in
+# # {0 => 'a', 1 => 'b', 2 => 'c'}
+# Hash(Array("abc").map |$i,$v| { [$i, $v]})
+# "abc".to(Array).map |$i,$v| { [$i, $v]}.to(Hash)
+# ~~~
+#
+# @since Puppet 5.0.0
+#
+Puppet::Functions.create_function(:unique) do
+  dispatch :unique_string do
+    param 'String', :string
+    optional_block_param 'Callable[String]', :block
+  end
+
+  dispatch :unique_hash do
+    param 'Hash', :hash
+    optional_block_param 'Callable[Any]', :block
+  end
+
+  dispatch :unique_array do
+    param 'Array', :array
+    optional_block_param 'Callable[Any]', :block
+  end
+
+  dispatch :unique_iterable do
+    param 'Iterable', :iterable
+    optional_block_param 'Callable[Any]', :block
+  end
+
+  def unique_string(string, &block)
+    string.split('').uniq(&block).join('')
+  end
+
+  def unique_hash(hash, &block)
+    block = lambda {|v| v } unless block_given?
+    result = Hash.new {|h, k| h[k] = {:keys =>[], :values =>[]} }
+    hash.each_pair do |k,v|
+      rc = result[ block.call(v) ]
+      rc[:keys] << k
+      rc[:values] << v
+    end
+    # reduce the set of possibly duplicated value entries
+    inverted = {}
+    result.each_pair {|k,v| inverted[v[:keys]] = v[:values].uniq }
+    inverted
+  end
+
+  def unique_array(array,&block)
+    array.uniq(&block)
+  end
+
+  def unique_iterable(iterable, &block)
+    Puppet::Pops::Types::Iterable.on(iterable).uniq(&block)
+  end
+end

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

@@ -0,0 +1,40 @@
+# Unwraps a Sensitive value and returns the wrapped object.
+#
+# ~~~puppet
+# $plaintext = 'hunter2'
+# $pw = Sensitive.new($plaintext)
+# notice("Wrapped object is $pw") #=> Prints "Wrapped object is Sensitive [value redacted]"
+# $unwrapped = $pw.unwrap
+# notice("Unwrapped object is $unwrapped") #=> Prints "Unwrapped object is hunter2"
+# ~~~
+#
+# You can optionally pass a block to unwrap in order to limit the scope where the
+# unwrapped value is visible.
+#
+# ~~~puppet
+# $pw = Sensitive.new('hunter2')
+# notice("Wrapped object is $pw") #=> Prints "Wrapped object is Sensitive [value redacted]"
+# $pw.unwrap |$unwrapped| {
+#   $conf = inline_template("password: ${unwrapped}\n")
+#   Sensitive.new($conf)
+# } #=> Returns a new Sensitive object containing an interpolated config file
+# # $unwrapped is now out of scope
+# ~~~
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:unwrap) do
+  dispatch :unwrap do
+    param 'Sensitive', :arg
+    optional_block_param
+  end
+
+  def unwrap(arg)
+    unwrapped = arg.unwrap
+    if block_given?
+      yield(unwrapped)
+    else
+      unwrapped
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+require 'puppet/util/package'
+
+# Compares two version numbers.
+#
+# Prototype:
+#
+#     \$result = versioncmp(a, b)
+#
+# Where a and b are arbitrary version strings.
+#
+# This function returns:
+#
+# * `1` if version a is greater than version b
+# * `0` if the versions are equal
+# * `-1` if version a is less than version b
+#
+# @example
+#
+#     if versioncmp('2.6-1', '2.4.5') > 0 {
+#         notice('2.6-1 is > than 2.4.5')
+#     }
+#
+# This function uses the same version comparison algorithm used by Puppet's
+# `package` type.
+#
+Puppet::Functions.create_function(:versioncmp) do
+
+  dispatch :versioncmp do
+    param 'String', :a
+    param 'String', :b
+  end
+
+  def versioncmp(a, b)
+    Puppet::Util::Package.versioncmp(a, b)
+  end
+end

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

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