puppet 5.0.0 → 6.0.0

data/lib/puppet/functions/each.rb

@@ -1,4 +1,4 @@
-# Runs a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# Runs a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
 # repeatedly using each value in a data structure, then returns the values unchanged.
 #
 # This function takes two mandatory arguments, in this order:
@@ -20,7 +20,7 @@
 #
 # @example Using the `each` function with an array and a one-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the array $data, run a lambda that creates a resource for each item.
 # $data = ["routers", "servers", "workstations"]
 # $data.each |$item| {
@@ -30,14 +30,14 @@
 # }
 # # Puppet creates one resource for each of the three items in $data. Each resource is
 # # named after the item's value and uses the item's value in a parameter.
-# ~~~
+# ```
 #
 # 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]` and returns the original hash.
 #
 # @example Using the `each` function with a hash and a one-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the hash $data, run a lambda using each item as a key-value array that creates a
 # # resource for each item.
 # $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
@@ -48,7 +48,7 @@
 # }
 # # Puppet creates one resource for each of the three items in $data, each named after the
 # # item's key and containing a parameter using the item's value.
-# ~~~
+# ```
 #
 # 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
@@ -56,7 +56,7 @@
 #
 # @example Using the `each` function with an array and a two-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the array $data, run a lambda using each item's index and value that creates a
 # # resource for each item.
 # $data = ["routers", "servers", "workstations"]
@@ -67,14 +67,14 @@
 # }
 # # Puppet creates one resource for each of the three items in $data, each named after the
 # # item's value and containing a parameter using the item's index.
-# ~~~
+# ```
 #
 # 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 `each` function with a hash and a two-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the hash $data, run a lambda using each item's key and value to create a resource
 # # for each item.
 # $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
@@ -85,11 +85,11 @@
 # }
 # # Puppet creates one resource for each of the three items in $data, each named after the
 # # item's key and containing a parameter using the item's value.
-# ~~~
+# ```
 #
 # For an example that demonstrates how to create multiple `file` resources using `each`,
 # see the Puppet
-# [iteration](https://docs.puppetlabs.com/puppet/latest/reference/lang_iteration.html)
+# [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
 # documentation.
 #
 # @since 4.0.0
@@ -117,8 +117,11 @@ Puppet::Functions.create_function(:each) do
 
   def foreach_Hash_1(hash)
     enumerator = hash.each_pair
-    hash.size.times do
-      yield(enumerator.next)
+    begin
+      hash.size.times do
+        yield(enumerator.next)
+      end
+    rescue StopIteration
     end
     # produces the receiver
     hash
@@ -126,8 +129,11 @@ Puppet::Functions.create_function(:each) do
 
   def foreach_Hash_2(hash)
     enumerator = hash.each_pair
-    hash.size.times do
-      yield(*enumerator.next)
+    begin
+      hash.size.times do
+        yield(*enumerator.next)
+      end
+    rescue StopIteration
     end
     # produces the receiver
     hash
@@ -145,13 +151,17 @@ Puppet::Functions.create_function(:each) do
 
   def foreach_Enumerable_2(enumerable)
     enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
-    index = 0
-    begin
-      loop do
-        yield(index, enum.next)
-        index += 1
+    if enum.hash_style?
+      enum.each { |entry| yield(*entry) }
+    else
+      begin
+        index = 0
+        loop do
+          yield(index, enum.next)
+          index += 1
+        end
+      rescue StopIteration
       end
-    rescue StopIteration
     end
     # produces the receiver
     enumerable

data/lib/puppet/functions/emerg.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level emerg.
+# Logs a message on the server at level `emerg`.
 Puppet::Functions.create_function(:emerg, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/empty.rb

@@ -0,0 +1,77 @@
+# Returns `true` if the given argument is an empty collection of values.
+#
+# This function can answer if one of the following is empty:
+# * `Array`, `Hash` - having zero entries
+# * `String`, `Binary` - having zero length
+#
+# For backwards compatibility with the stdlib function with the same name the
+# following data types are also accepted by the function instead of raising an error.
+# Using these is deprecated and will raise a warning:
+#
+# * `Numeric` - `false` is returned for all `Numeric` values.
+# * `Undef` - `true` is returned for all `Undef` values.
+#
+# @example Using `empty`
+#
+# ```puppet
+# notice([].empty)
+# notice(empty([]))
+# # would both notice 'true'
+# ```
+#
+# @since Puppet 5.5.0 - support for Binary
+#
+Puppet::Functions.create_function(:empty) do
+  dispatch :collection_empty do
+    param 'Collection', :coll
+  end
+
+  dispatch :string_empty do
+    param 'String', :str
+  end
+
+  dispatch :numeric_empty do
+    param 'Numeric', :num
+  end
+
+  dispatch :binary_empty do
+    param 'Binary', :bin
+  end
+
+  dispatch :undef_empty do
+    param 'Undef', :x
+  end
+
+  def collection_empty(coll)
+    coll.empty?
+  end
+
+  def string_empty(str)
+    str.empty?
+  end
+
+  # For compatibility reasons - return false rather than error on floats and integers
+  # (Yes, it is strange)
+  #
+  def numeric_empty(num)
+    deprecation_warning_for('Numeric')
+    false
+  end
+
+  def binary_empty(bin)
+    bin.length == 0
+  end
+
+  # For compatibility reasons - return true rather than error on undef
+  # (Yes, it is strange, but undef was passed as empty string in 3.x API)
+  #
+  def undef_empty(x)
+    true
+  end
+
+  def deprecation_warning_for(arg_type)
+    file, line = Puppet::Pops::PuppetStack.top_of_stack
+    msg = _("Calling function empty() with %{arg_type} value is deprecated.") % { arg_type: arg_type }
+    Puppet.warn_once('deprecations', "empty-from-#{file}-#{line}", msg, file, line)
+  end
+end

data/lib/puppet/functions/epp.rb

@@ -21,6 +21,9 @@
 # `epp('apache/vhost/_docroot.epp', { 'docroot' => '/var/www/html',
 # 'virtual_docroot' => '/var/www/example' })`
 #
+# This function can also accept an absolute path, which can load a template file
+# from anywhere on disk.
+#
 # 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.

data/lib/puppet/functions/err.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level err.
+# Logs a message on the server at level `err`.
 Puppet::Functions.create_function(:err, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/eyaml_lookup_key.rb

@@ -1,5 +1,5 @@
 # The `eyaml_lookup_key` is a hiera 5 `lookup_key` data provider function.
-# See [the configuration guide documentation](https://docs.puppet.com/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-hiera-eyaml) for
+# See [the configuration guide documentation](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html#configuring-a-hierarchy-level-hiera-eyaml) for
 # how to use this function.
 #
 # @since 5.0.0
@@ -26,8 +26,10 @@ Puppet::Functions.create_function(:eyaml_lookup_key) do
     # Can't do this with an argument_mismatch dispatcher since there is no way to declare a struct that at least
     # contains some keys but may contain other arbitrary keys.
     unless options.include?('path')
+      #TRANSLATORS 'eyaml_lookup_key':, 'path', 'paths' 'glob', 'globs', 'mapped_paths', and lookup_key should not be translated
       raise ArgumentError,
-        "'eyaml_lookup_key': one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml when using this lookup_key function"
+        _("'eyaml_lookup_key': one of 'path', 'paths' 'glob', 'globs' or 'mapped_paths' must be declared in hiera.yaml"\
+              " when using this lookup_key function")
     end
 
     # nil key is used to indicate that the cache contains the raw content of the eyaml file
@@ -44,17 +46,18 @@ Puppet::Functions.create_function(:eyaml_lookup_key) do
     path = options['path']
     context.cached_file_data(path) do |content|
       begin
-        data = YAML.load(content, path)
+        data = Puppet::Util::Yaml.safe_load(content, [Symbol], path)
         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")
+          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
-        # Psych errors includes the absolute path to the file, so no need to add that
-        # to the message
-        raise Puppet::DataBinding::LookupError, "Unable to parse #{ex.message}"
+      rescue Puppet::Util::Yaml::YamlLoadError => ex
+        # YamlLoadErrors include the absolute path to the file, so no need to add that
+        raise Puppet::DataBinding::LookupError, _("Unable to parse %{message}") % { message: ex.message }
       end
     end
   end

data/lib/puppet/functions/filter.rb

@@ -1,6 +1,6 @@
-# Applies a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
 # to every value in a data structure and returns an array or hash containing any elements
-# for which the lambda evaluates to `true`.
+# for which the lambda evaluates to a truthy value (not `false` or `undef`).
 #
 # This function takes two mandatory arguments, in this order:
 #
@@ -21,19 +21,19 @@
 #
 # @example Using the `filter` function with an array and a one-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the array $data, return an array containing the values that end with "berry"
 # $data = ["orange", "blueberry", "raspberry"]
 # $filtered_data = $data.filter |$items| { $items =~ /berry$/ }
 # # $filtered_data = [blueberry, raspberry]
-# ~~~
+# ```
 #
 # 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]` and returns a hash containing the results.
 #
 # @example Using the `filter` function with a hash and a one-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the hash $data, return a hash containing all values of keys that end with "berry"
 # $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
 # $filtered_data = $data.filter |$items| { $items[0] =~ /berry$/ }
@@ -45,28 +45,29 @@
 #
 # @example Using the `filter` function with an array and a two-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the array $data, return an array of all keys that both end with "berry" and have
 # # an even-numbered index
 # $data = ["orange", "blueberry", "raspberry"]
 # $filtered_data = $data.filter |$indexes, $values| { $indexes % 2 == 0 and $values =~ /berry$/ }
 # # $filtered_data = [raspberry]
-# ~~~
+# ```
 #
 # 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 `filter` function with a hash and a two-parameter lambda
 #
-# ~~~ puppet
-# # For the hash $data, return a hash of all keys that both end with "berry" and have 
+# ```puppet
+# # For the hash $data, return a hash of all keys that both end with "berry" and have
 # # values less than or equal to 1
 # $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
 # $filtered_data = $data.filter |$keys, $values| { $keys =~ /berry$/ and $values <= 1 }
 # # $filtered_data = {blueberry => 1}
-# ~~~
+# ```
 #
 # @since 4.0.0
+# @since 6.0.0 does not filter if truthy value is returned from block
 #
 Puppet::Functions.create_function(:filter) do
   dispatch :filter_Hash_2 do
@@ -90,14 +91,14 @@ Puppet::Functions.create_function(:filter) do
   end
 
   def filter_Hash_1(hash)
-    result = hash.select {|x, y| yield([x, y]) == true }
+    result = hash.select {|x, y| yield([x, y]) }
     # Ruby 1.8.7 returns Array
     result = Hash[result] unless result.is_a? Hash
     result
   end
 
   def filter_Hash_2(hash)
-    result = hash.select {|x, y| yield(x, y) == true }
+    result = hash.select {|x, y| yield(x, y) }
     # Ruby 1.8.7 returns Array
     result = Hash[result] unless result.is_a? Hash
     result
@@ -109,7 +110,7 @@ Puppet::Functions.create_function(:filter) do
     begin
       loop do
         it = enum.next
-        if yield(it) == true
+        if yield(it)
           result << it
         end
       end
@@ -119,19 +120,25 @@ Puppet::Functions.create_function(:filter) do
   end
 
   def filter_Enumerable_2(enumerable)
-    result = []
-    index = 0
     enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
-    begin
-      loop do
-        it = enum.next
-        if yield(index, it) == true
-          result << it
+    if enum.hash_style?
+      result = {}
+      enum.each { |k, v| result[k] = v if yield(k, v) }
+      result
+    else
+      result = []
+      begin
+        index = 0
+        loop do
+          it = enum.next
+          if yield(index, it)
+            result << it
+          end
+          index += 1
         end
-        index += 1
+      rescue StopIteration
       end
-    rescue StopIteration
+      result
     end
-    result
   end
 end

data/lib/puppet/functions/find_file.rb

@@ -1,5 +1,19 @@
 # Finds an existing file from a module and returns its path.
-# (Documented in 3.x stub)
+#
+# The argument to this function should be a String as a `<MODULE NAME>/<FILE>`
+# reference, which will search for `<FILE>` relative to a module's `files`
+# directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
+# file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+#
+# This function can also accept:
+# 
+# * An absolute String path, which will check for the existence of a file from anywhere on disk.
+# * Multiple String arguments, which will return the path of the **first** file
+#   found, skipping non existing files.
+# * An array of string paths, which will return the path of the **first** file
+#   found from the given paths in the array, skipping non existing files.
+#
+# The function returns `undef` if none of the given paths were found
 #
 # @since 4.8.0
 #
@@ -19,7 +33,6 @@ Puppet::Functions.create_function(:find_file, Puppet::Functions::InternalFunctio
   end
 
   def find_file(scope, *args)
-    path = nil
     args.each do |file|
       found = Puppet::Parser::Files.find_file(file, scope.compiler.environment)
       if found && Puppet::FileSystem.exist?(found)

data/lib/puppet/functions/flatten.rb

@@ -0,0 +1,64 @@
+# Returns a flat Array produced from its possibly deeply nested given arguments.
+#
+# One or more arguments of any data type can be given to this function.
+# The result is always a flat array representation where any nested arrays are recursively flattened.
+#
+# @example Typical use of `flatten()`
+#
+# ```puppet
+# flatten(['a', ['b', ['c']]])
+# # Would return: ['a','b','c']
+# ```
+#
+# To flatten other kinds of iterables (for example hashes, or intermediate results like from a `reverse_each`)
+# first convert the result to an array using `Array($x)`, or `$x.convert_to(Array)`. See the `new` function
+# for details and options when performing a conversion.
+#
+# @example Flattening a Hash
+#
+# ```puppet
+# $hsh = { a => 1, b => 2}
+#
+# # -- without conversion
+# $hsh.flatten()
+# # Would return [{a => 1, b => 2}]
+#
+# # -- with conversion
+# $hsh.convert_to(Array).flatten()
+# # Would return [a,1,b,2]
+#
+# flatten(Array($hsh))
+# # Would also return [a,1,b,2]
+# ```
+#
+# @example Flattening and concatenating at the same time
+#
+# ```puppet
+# $a1 = [1, [2, 3]]
+# $a2 = [[4,[5,6]]
+# $x = 7
+# flatten($a1, $a2, $x)
+# # would return [1,2,3,4,5,6,7]
+# ```
+#
+# @example Transforming to Array if not already an Array
+#
+# ```puppet
+# flatten(42)
+# # Would return [42]
+#
+# flatten([42])
+# # Would also return [42]
+# ```
+#
+# @since 5.5.0 support for flattening and concatenating at the same time
+#
+Puppet::Functions.create_function(:flatten) do
+  dispatch :flatten_args do
+    repeated_param 'Any', :args
+  end
+
+  def flatten_args(*args)
+    args.flatten()
+  end
+end

data/lib/puppet/functions/floor.rb

@@ -0,0 +1,37 @@
+# Returns the largest `Integer` less or equal to the argument.
+# Takes a single numeric value as an argument.
+#
+# This function is backwards compatible with the same function in stdlib
+# and accepts a `Numeric` value. A `String` that can be converted
+# to a floating point number can also be used in this version - but this
+# is deprecated.
+#
+# In general convert string input to `Numeric` before calling this function
+# to have full control over how the conversion is done.
+#
+Puppet::Functions.create_function(:floor) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  dispatch :on_string do
+    param 'String', :val
+  end
+
+  def on_numeric(x)
+    x.floor
+  end
+
+  def on_string(x)
+    Puppet.warn_once('deprecations', 'floor_function_numeric_coerce_string',
+      _("The floor() function's auto conversion of String to Float is deprecated - change to convert input before calling"))
+
+    begin
+      Float(x).floor
+    rescue TypeError, ArgumentError => _e
+      # TRANSLATORS: 'floor' is a name and should not be translated
+      raise(ArgumentError, _('floor(): cannot convert given value to a floating point value.'))
+    end
+  end
+
+end

data/lib/puppet/functions/get.rb

@@ -0,0 +1,150 @@
+# Digs into a value with dot notation to get a value from within a structure.
+#
+# **To dig into a given value**, call the function with (at least) two arguments:
+#
+# * The **first** argument must be an Array, or Hash. Value can also be `undef`
+#   (which also makes the result `undef` unless a _default value_ is given).
+# * The **second** argument must be a _dot notation navigation string_.
+# * The **optional third** argument can be any type of value and it is used
+#   as the _default value_ if the function would otherwise return `undef`.
+# * An **optional lambda** for error handling taking one `Error` argument.
+#
+# **Dot notation navigation string** -
+# The dot string consists of period `.` separated segments where each
+# segment is either the index into an array or the value of a hash key.
+# If a wanted key contains a period it must be quoted to avoid it being
+# taken as a segment separator. Quoting can be done with either
+# single quotes `'` or double quotes `"`. If a segment is
+# a decimal number it is converted to an Integer index. This conversion
+# can be prevented by quoting the value.
+#
+# @example Navigating into a value
+# ```puppet
+# #get($facts, 'os.family')
+# $facts.get('os.family')
+# ```
+# Would both result in the value of $facts['os']['family']
+#
+# @example Getting the value from an expression
+# ```puppet
+# get([1,2,[{'name' =>'waldo'}]], '2.0.name')
+# ```
+# Would result in 'waldo'
+#
+# @example Using a default value
+# ```puppet
+# get([1,2,[{'name' =>'waldo'}]], '2.1.name', 'not waldo')
+#
+# ```
+# Would result in 'not waldo'
+#
+# @example Quoting a key with period
+# ```puppet
+# $x = [1, 2, { 'readme.md' => "This is a readme."}]
+# $x.get('2."readme.md"')
+# ```
+#
+# @example Quoting a numeric string
+# ```puppet
+# $x = [1, 2, { '10' => "ten"}]
+# $x.get('2."0"')
+# ```
+#
+# **Error Handling** - There are two types of common errors that can
+# be handled by giving the function a code block to execute.
+# (A third kind or error; when the navigation string has syntax errors
+# (for example an empty segment or unbalanced quotes) will always raise
+# an error).
+#
+# The given block will be given an instance of the `Error` data type,
+# and it has methods to extract `msg`, `issue_code`, `kind`, and
+# `details`.
+#
+# The `msg` will be a preformatted message describing the error.
+# This is the error message that would have surfaced if there was
+# no block to handle the error.
+#
+# The `kind` is the string `'SLICE_ERROR'` for both kinds of errors,
+# and the `issue_code` is either the string `'EXPECTED_INTEGER_INDEX'`
+# for an attempt to index into an array with a String,
+# or `'EXPECTED_COLLECTION'` for an attempt to index into something that
+# is not a Collection.
+#
+# The `details` is a Hash that for both issue codes contain the
+# entry `'walked_path'` which is an Array with each key in the
+# progression of the dig up to the place where the error occurred.
+#
+# For an `EXPECTED_INTEGER_INDEX`-issue the detail `'index_type'` is
+# set to the data type of the index value and for an
+# `'EXPECTED_COLLECTION'`-issue the detail `'value_type'` is set
+# to the type of the value.
+#
+# The logic in the error handling block can inspect the details,
+# and either call `fail()` with a custom error message or produce
+# the wanted value.
+#
+# If the block produces `undef` it will not be replaced with a
+# given default value.
+#
+# @example Ensure `undef` result on error
+# ```puppet
+# $x = 'blue'
+# $x.get('0.color', 'green') |$error| { undef } # result is undef
+#
+# $y = ['blue']
+# $y.get('color', 'green') |$error| { undef } # result is undef
+# ```
+#
+# @example Accessing information in the Error
+# ```puppet
+# $x = [1, 2, ['blue']]
+# $x.get('2.color') |$error| {
+#   notice("Walked path is ${error.details['walked_path']}")
+# }
+# ```
+# Would notice `Walked path is [2, color]`
+#
+# Also see:
+# * `getvar()` that takes the first segment to be the name of a variable
+#   and then delegates to this function.
+# * `dig()` function which is similar but uses an
+#   array of navigation values instead of a dot notation string.
+#
+# @since 6.0.0
+#
+Puppet::Functions.create_function(:get, Puppet::Functions::InternalFunction) do
+  dispatch :get_from_value do
+    param 'Any', :value
+    param 'String', :dotted_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable[1,1]', :block
+  end
+
+  # Gets a result from given value and a navigation string
+  #
+  def get_from_value(value, navigation, default_value = nil, &block)
+    return default_value if value.nil?
+    return value if navigation.empty?
+
+    # Note: split_key always processes the initial segment as a string even if it could be an integer.
+    # This since it is designed for lookup keys. For a numeric first segment
+    # like '0.1' the wanted result is [0,1], not ["0", 1]. The workaround here is to
+    # prefix the navigation with "x." thus giving split_key a first segment that is a string.
+    # The fake segment is then dropped.
+    segments = split_key("x." + navigation) {|err| _("Syntax error in dotted-navigation string")}
+    segments.shift
+
+    begin
+      result = call_function('dig', value, *segments)
+      return result.nil? ? default_value : result
+    rescue Puppet::ErrorWithData => e
+      if block_given?
+        yield(e.error_data)
+      else
+        raise e
+      end
+    end
+  end
+  # reuse the split_key parser used also by lookup
+  include Puppet::Pops::Lookup::SubLookup
+end