puppet 5.4.0-x86-mingw32 → 5.5.0-x86-mingw32

data/lib/puppet/functions/then.rb

@@ -1,5 +1,68 @@
-# (Documented in 3.x stub)
-# @since 4.5.0
+# Calls a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# with the given argument unless the argument is `undef`.
+# Returns `undef` if the argument is `undef`, and otherwise the result of giving the
+# argument to the lambda.
+#
+# This is useful to process a sequence of operations where an intermediate
+# result may be `undef` (which makes the entire sequence `undef`).
+# The `then` function is especially useful with the function `dig` which
+# performs in a similar way "digging out" a value in a complex structure.
+#
+# @example Using `dig` and `then`
+#
+# ```puppet
+# $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
+# notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
+# ```
+#
+# Would notice the value 200
+#
+# Contrast this with:
+#
+# ```puppet
+# $data = {a => { b => [{x => 10, y => 20}, {not_x => 100, why => 200}]}}
+# notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
+# ```
+#
+# Which would notice `undef` since the last lookup of 'x' results in `undef` which
+# is returned (without calling the lambda given to the `then` function).
+#
+# As a result there is no need for conditional logic or a temporary (non local)
+# variable as the result is now either the wanted value (`x`) multiplied
+# by 2 or `undef`.
+#
+# Calls to `then` can be chained. In the next example, a structure is using an offset based on
+# using 1 as the index to the first element (instead of 0 which is used in the language).
+# We are not sure if user input actually contains an index at all, or if it is
+# outside the range of available names.args.
+#
+# @example Chaining calls to the `then` function
+#
+# ```puppet
+# # Names to choose from
+# $names = ['Ringo', 'Paul', 'George', 'John']
+#
+# # Structure where 'beatle 2' is wanted (but where the number refers
+# # to 'Paul' because input comes from a source using 1 for the first
+# # element).
+#
+# $data = ['singer', { beatle => 2 }]
+# $picked = assert_type(String,
+#   # the data we are interested in is the second in the array,
+#   # a hash, where we want the value of the key 'beatle'
+#   $data.dig(1, 'beatle')
+#     # and we want the index in $names before the given index
+#     .then |$x| { $names[$x-1] }
+#     # so we can construct a string with that beatle's name
+#     .then |$x| { "Picked Beatle '${x}'" }
+# )
+# notice $picked
+# ```
+#
+# Would notice "Picked Beatle 'Paul'", and would raise an error if the result
+# was not a String.
+#
+# * Since 4.5.0
 #
 Puppet::Functions.create_function(:then) do
   dispatch :then do

data/lib/puppet/functions/tree_each.rb

@@ -42,12 +42,12 @@
 #
 # @example depth- or breadth-first order
 #
-# ~~~ puppet
+# ```puppet
 # [1, [2, 3], 4]
-# ~~~
-# 
+# ```
+#
 # Results in:
-# 
+#
 # If containers are skipped:
 #
 # * `depth_first` order `1`, `2`, `3`, `4` 
@@ -67,33 +67,33 @@
 #
 # @example A flattened iteration over a tree excluding Collections
 #
-# ~~~ puppet
+# ```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
+# ```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
+# ```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
@@ -101,16 +101,16 @@
 #
 # @example Only `Array` as container type
 #
-# ~~~ puppet
+# ```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
@@ -118,9 +118,9 @@
 #
 # Note than when chaining, the value passed on is a `Tuple` with `[path, value]`.
 #
-# @example pruning a tree
-# 
-# ~~~ puppet
+# @example Pruning a tree
+#
+# ```puppet
 # # A tree of some complexity (here very simple for readability)
 # $tree = [
 #  { name => 'user1', status => 'inactive', id => '10'},
@@ -130,7 +130,7 @@
 #  $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]`.

data/lib/puppet/functions/type.rb

@@ -1,4 +1,45 @@
-# (Documentation in 3.x stub)
+# Returns the data type of a given value with a given degree of generality.
+#
+# ```puppet
+# type InferenceFidelity = Enum[generalized, reduced, detailed]
+#
+# function type(Any $value, InferenceFidelity $fidelity = 'detailed') # returns Type
+# ```
+#
+# @example Using `type`
+#
+# ``` puppet
+# notice type(42) =~ Type[Integer]
+# ```
+#
+# Would notice `true`.
+#
+# By default, the best possible inference is made where all details are retained.
+# This is good when the type is used for further type calculations but is overwhelmingly
+# rich in information if it is used in a error message.
+#
+# The optional argument `$fidelity` may be given as (from lowest to highest fidelity):
+#
+# * `generalized` - reduces to common type and drops size constraints
+# * `reduced` - reduces to common type in collections
+# * `detailed` - (default) all details about inferred types is retained
+#
+# @example Using `type()` with different inference fidelity:
+#
+# ``` puppet
+# notice type([3.14, 42], 'generalized')
+# notice type([3.14, 42], 'reduced'')
+# notice type([3.14, 42], 'detailed')
+# notice type([3.14, 42])
+# ```
+#
+# Would notice the four values:
+#
+# 1. 'Array[Numeric]'
+# 2. 'Array[Numeric, 2, 2]'
+# 3. 'Tuple[Float[3.14], Integer[42,42]]]'
+# 4. 'Tuple[Float[3.14], Integer[42,42]]]'
+#
 # @since 4.4.0
 #
 Puppet::Functions.create_function(:type) do

data/lib/puppet/functions/unique.rb

@@ -1,4 +1,4 @@
-# The `unique` function returns a unique set of values from an `Iterable` argument.
+# Produces 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.
@@ -11,21 +11,21 @@
 #
 # @example Using unique with a String
 #
-# ~~~puppet
+# ```puppet
 # # will produce 'abc'
 # "abcaabb".unique
-# ~~~
+# ```
 #
 # @example Using unique with an Array
 #
-# ~~~puppet
+# ```puppet
 # # will produce ['a', 'b', 'c']
 # ['a', 'b', 'c', 'a', 'a', 'b'].unique
-# ~~~
+# ```
 #
 # @example Using unique with a Hash
 #
-# ~~~puppet
+# ```puppet
 # # will produce { ['a', 'b'] => [10], ['c'] => [20]}
 # {'a' => 10, 'b' => 10, 'c' => 20}.unique
 #
@@ -34,18 +34,18 @@
 #
 # # 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
+# ```puppet
 # # will produce [['sam', 'smith'], ['sue', 'smith']]
 # [['sam', 'smith'], ['sam', 'brown'], ['sue', 'smith']].unique |$x| { $x[0] }
 #
@@ -57,7 +57,7 @@
 #
 # # 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
@@ -70,7 +70,7 @@
 #
 # @example turning a string or array into a hash with index keys
 #
-# ~~~puppet
+# ```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]})
@@ -79,7 +79,7 @@
 # # {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
 #

data/lib/puppet/functions/unwrap.rb

@@ -1,17 +1,21 @@
 # Unwraps a Sensitive value and returns the wrapped object.
 #
-# ~~~puppet
+# @example Usage of unwrap
+#
+# ```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
+# @example Unwrapping with a block of code
+#
+# ```puppet
 # $pw = Sensitive.new('hunter2')
 # notice("Wrapped object is $pw") #=> Prints "Wrapped object is Sensitive [value redacted]"
 # $pw.unwrap |$unwrapped| {
@@ -19,7 +23,7 @@
 #   Sensitive.new($conf)
 # } #=> Returns a new Sensitive object containing an interpolated config file
 # # $unwrapped is now out of scope
-# ~~~
+# ```
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/values.rb

@@ -0,0 +1,25 @@
+# Returns the values of a hash as an Array
+#
+# @example Using `values`
+#
+# ```puppet
+# $hsh = {"apples" => 3, "oranges" => 4 }
+# $hsh.values()
+# values($hsh)
+# # both results in the array [3, 4]
+# ```
+#
+# * 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 values is the same as the order in the hash (typically the order in which they were added).
+#
+Puppet::Functions.create_function(:values) do
+  dispatch :values do
+    param 'Hash', :hsh
+  end
+
+  def values(hsh)
+    hsh.values
+  end
+end

data/lib/puppet/functions/versioncmp.rb

@@ -14,7 +14,7 @@ require 'puppet/util/package'
 # * `0` if the versions are equal
 # * `-1` if version a is less than version b
 #
-# @example
+# @example Using versioncmp
 #
 #     if versioncmp('2.6-1', '2.4.5') > 0 {
 #         notice('2.6-1 is > than 2.4.5')

data/lib/puppet/functions/warning.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level notice.
+# Logs 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]

data/lib/puppet/functions/with.rb

@@ -1,12 +1,14 @@
-# Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
-# with the given arguments and return the result. Since a lambda's scope is
+# Calls a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# with the given arguments and returns the result.
+#
+# Since a lambda's scope is
 # [local](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html#lambda-scope)
 # to the lambda, you can use the `with` function to create private blocks of code within a
 # class using variables whose values cannot be accessed outside of the lambda.
 #
 # @example Using `with`
 #
-# ~~~ puppet
+# ```puppet
 # # Concatenate three strings into a single string formatted as a list.
 # $fruit = with("apples", "oranges", "bananas") |$x, $y, $z| { 
 #   "${x}, ${y}, and ${z}" 
@@ -14,7 +16,7 @@
 # $check_var = $x
 # # $fruit contains "apples, oranges, and bananas"
 # # $check_var is undefined, as the value of $x is local to the lambda.
-# ~~~
+# ```
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/yaml_data.rb

@@ -25,7 +25,9 @@ Puppet::Functions.create_function(:yaml_data) do
         if data.is_a?(Hash)
           Puppet::Pops::Lookup::HieraConfig.symkeys_to_string(data)
         else
-          Puppet.warning(_("%{path}: file does not contain a valid yaml hash" % { path: path }))
+          msg = _("%{path}: file does not contain a valid yaml hash" % { path: path })
+          raise Puppet::DataBinding::LookupError, msg if Puppet[:strict] == :error && data != false
+          Puppet.warning(msg)
           {}
         end
       rescue YAML::SyntaxError => ex

data/lib/puppet/indirector/certificate_status/file.rb

@@ -70,7 +70,7 @@ class Puppet::Indirector::CertificateStatus::File < Puppet::Indirector::Code
       klass.indirection.search(request.key, request.options)
     end.flatten.collect do |result|
       result.name
-    end.uniq.collect &Puppet::SSL::Host.method(:new)
+    end.uniq.collect(&Puppet::SSL::Host.method(:new))
   end
 
   def find(request)

data/lib/puppet/indirector/facts/facter.rb

@@ -38,8 +38,6 @@ class Puppet::Node::Facts::Facter < Puppet::Indirector::Code
     result
   end
 
-  private
-
   def self.setup_search_paths(request)
     # Add any per-module fact directories to facter's search path
     dirs = request.environment.modulepath.collect do |dir|
@@ -64,7 +62,7 @@ class Puppet::Node::Facts::Facter < Puppet::Indirector::Code
       true
     end
 
-    Facter.search *dirs
+    Facter.search(*dirs)
   end
 
   def self.setup_external_search_paths(request)

data/lib/puppet/indirector/facts/rest.rb

@@ -0,0 +1,21 @@
+require 'puppet/node/facts'
+require 'puppet/indirector/rest'
+
+class Puppet::Node::Facts::Rest < Puppet::Indirector::REST
+  desc "Find and save facts about nodes over HTTP via REST."
+
+  def save(request)
+    raise ArgumentError, _("PUT does not accept options") unless request.options.empty?
+
+    response = do_request(request) do |req|
+      http_put(req, IndirectedRoutes.request_to_uri(req), req.instance.render, headers.merge({ "Content-Type" => req.instance.mime }))
+    end
+
+    if is_http_200?(response)
+      content_type, body = parse_response(response)
+      deserialize_save(content_type, body)
+    else
+      raise convert_to_http_error(response)
+    end
+  end
+end