puppet 5.5.22 → 6.0.0

data/lib/puppet/functions/convert_to.rb

@@ -23,11 +23,12 @@ Puppet::Functions.create_function(:convert_to) do
   dispatch :convert_to do
     param 'Any', :value
     param 'Type', :type
+    optional_repeated_param 'Any', :args
     optional_block_param 'Callable[1,1]', :block
   end
 
-  def convert_to(value, type, &block)
-    result = call_function('new', type, value)
+  def convert_to(value, type, *args, &block)
+    result = call_function('new', type, value, *args)
     block_given? ? yield(result) : result
   end
 end

data/lib/puppet/functions/dig.rb

@@ -38,9 +38,29 @@ Puppet::Functions.create_function(:dig) do
     args.reduce(data) do | d, k |
       return nil if d.nil? || k.nil?
       if !(d.is_a?(Array) || d.is_a?(Hash))
-        raise ArgumentError, _("The given data does not contain a Collection at %{walked_path}, got '%{klass}'") % { walked_path: walked_path, klass: d.class }
+        t = Puppet::Pops::Types::TypeCalculator.infer(d)
+        msg = _("The given data does not contain a Collection at %{walked_path}, got '%{type}'") % { walked_path: walked_path, type: t }
+        error_data = Puppet::DataTypes::Error.new(
+            msg,
+            'SLICE_ERROR',
+            {'walked_path' => walked_path, 'value_type' => t},
+            'EXPECTED_COLLECTION'
+        )
+        raise Puppet::ErrorWithData.new(error_data, msg)
       end
+
       walked_path << k
+      if d.is_a?(Array) && !k.is_a?(Integer)
+        t = Puppet::Pops::Types::TypeCalculator.infer(k)
+        msg = _("The given data requires an Integer index at %{walked_path}, got '%{type}'") % { walked_path: walked_path, type: t }
+        error_data = Puppet::DataTypes::Error.new(
+            msg,
+            'SLICE_ERROR',
+            {'walked_path' => walked_path, 'index_type' => t},
+            'EXPECTED_INTEGER_INDEX'
+        )
+        raise Puppet::ErrorWithData.new(error_data, msg)
+      end
       d[k]
     end
   end

data/lib/puppet/functions/downcase.rb

@@ -0,0 +1,89 @@
+# Converts a String, Array or Hash (recursively) into lower case.
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String`, its lower case version is returned. This is done using Ruby system locale which handles some, but not all
+#   special international up-casing rules (for example German double-s ß is upcased to "SS", whereas upper case double-s
+#   is downcased to ß).
+# * For `Array` and `Hash` the conversion to lower case is recursive and each key and value must be convertible by
+#   this function.
+# * When a `Hash` is converted, some keys could result in the same key - in those cases, the
+#   latest key-value wins. For example if keys "aBC", and "abC" where both present, after downcase there would only be one
+#   key "abc".
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# Please note: This function relies directly on Ruby's String implementation and as such may not be entirely UTF8 compatible.
+# To ensure best compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085.
+#
+# @example Converting a String to lower case
+# ```puppet
+# 'HELLO'.downcase()
+# downcase('HEllO')
+# ```
+# Would both result in "hello"
+#
+# @example Converting an Array to lower case
+# ```puppet
+# ['A', 'B'].downcase()
+# downcase(['A', 'B'])
+# ```
+# Would both result in ['a', 'b']
+#
+# @example Converting a Hash to lower case
+# ```puppet
+# {'A' => 'HEllO', 'B' => 'GOODBYE'}.downcase()
+# ```
+# Would result in `{'a' => 'hello', 'b' => 'goodbye'}`
+#
+# @example Converting a recursive structure
+# ```puppet
+# ['A', 'B', ['C', ['D']], {'X' => 'Y'}].downcase
+# ```
+# Would result in `['a', 'b', ['c', ['d']], {'x' => 'y'}]`
+#
+Puppet::Functions.create_function(:downcase) do
+  local_types do
+    type 'StringData = Variant[String, Numeric, Array[StringData], Hash[StringData, StringData]]'
+  end
+
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_array do
+    param 'Array[StringData]', :arg
+  end
+
+  dispatch :on_hash do
+    param 'Hash[StringData, StringData]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.downcase
+  end
+
+  def on_array(a)
+    a.map {|x| do_downcase(x) }
+  end
+
+  def on_hash(h)
+    result = {}
+    h.each_pair {|k,v| result[do_downcase(k)] = do_downcase(v) }
+    result
+  end
+
+  def do_downcase(x)
+    x.is_a?(String) ? x.downcase : call_function('downcase', x)
+  end
+end

data/lib/puppet/functions/epp.rb

@@ -6,12 +6,12 @@
 # The first argument to this function should be a `<MODULE NAME>/<TEMPLATE FILE>`
 # reference, which loads `<TEMPLATE FILE>` from `<MODULE NAME>`'s `templates`
 # directory. In most cases, the last argument is optional; if used, it should be a
-# [hash](https://puppet.com/docs/puppet/latest/lang_data_hash.html) that contains parameters to
+# [hash](/puppet/latest/reference/lang_data_hash.html) that contains parameters to
 # pass to the template.
 #
-# - See the [template](https://puppet.com/docs/puppet/latest/lang_template.html)
-# documentation for general template usage information.
-# - See the [EPP syntax](https://puppet.com/docs/puppet/latest/lang_template_epp.html)
+# - 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 call the apache module's `templates/vhost/_docroot.epp`

data/lib/puppet/functions/eyaml_lookup_key.rb

@@ -46,7 +46,7 @@ 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
@@ -55,10 +55,9 @@ Puppet::Functions.create_function(:eyaml_lookup_key) do
           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](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:
 #
@@ -67,6 +67,7 @@
 # ```
 #
 # @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
@@ -122,7 +123,7 @@ Puppet::Functions.create_function(:filter) do
     enum = Puppet::Pops::Types::Iterable.asserted_iterable(self, enumerable)
     if enum.hash_style?
       result = {}
-      enum.each { |k, v| result[k] = v if yield(k, v) == true }
+      enum.each { |k, v| result[k] = v if yield(k, v) }
       result
     else
       result = []
@@ -130,7 +131,7 @@ Puppet::Functions.create_function(:filter) do
         index = 0
         loop do
           it = enum.next
-          if yield(index, it) == true
+          if yield(index, it)
             result << it
           end
           index += 1

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

data/lib/puppet/functions/getvar.rb

@@ -0,0 +1,87 @@
+# Digs into a variable with dot notation to get a value from a structure.
+#
+# **To get the value from a variable** (that may or may not exist), call the function with
+# one or two arguments:
+#
+# * The **first** argument must be a string, and must start with a variable name without leading `$`,
+#   for example `get('facts')`. The variable name can be followed
+#   by a _dot notation navigation string_ to dig out a value in the array or hash value
+#   of the variable.
+# * The **optional second** 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 Getting the value of a variable
+# ```puppet
+# getvar('facts') # results in the value of $facts
+# ```
+#
+# @example Navigating into a variable
+# ```puppet
+# getvar('facts.os.family') # results in the value of $facts['os']['family']
+# ```
+#
+# @example Using a default value
+# ```puppet
+# $x = [1,2,[{'name' =>'waldo'}]]
+# getvar('x.2.1.name', 'not waldo')
+# # results in 'not waldo'
+# ```
+#
+# For further examples and how to perform error handling, see the `get()` function
+# which this function delegates to after having resolved the variable value.
+#
+# @since 6.0.0 - the ability to dig into the variable's value with dot notation.
+#
+Puppet::Functions.create_function(:getvar, Puppet::Functions::InternalFunction) do
+  dispatch :get_from_navigation do
+    scope_param
+     param 'Pattern[/\A(?:::)?(?:[a-z]\w*::)*[a-z_]\w*(?:\.|\Z)/]', :get_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable[1,1]', :block
+  end
+
+  argument_mismatch :invalid_variable_error do
+    param 'String', :get_string
+    optional_param 'Any', :default_value
+    optional_block_param 'Callable', :block
+  end
+
+  def invalid_variable_error(navigation, default_value=nil, &block)
+    _("The given string does not start with a valid variable name")
+  end
+
+  # Gets a result from a navigation string starting with $var
+  #
+  def get_from_navigation(scope, navigation, default_value = nil, &block)
+    # asserted to start with a valid variable name - dig out the variable
+    matches = navigation.match(/^((::)?(\w+::)*\w+)(.*)\z/)
+    navigation = matches[4]
+    if navigation[0] == '.'
+      navigation = navigation[1..-1]
+    else
+      unless navigation.empty?
+        raise ArgumentError, _("First character after var name in get string must be a '.' - got %{char}") % {char: navigation[0]}
+      end
+    end
+    get_from_var_name(scope, matches[1], navigation, default_value, &block)
+  end
+
+  # Gets a result from a $var name and a navigation string
+  #
+  def get_from_var_name(scope, var_string, navigation, default_value = nil, &block)
+    catch(:undefined_variable) do
+      return call_function_with_scope(scope,'get', scope.lookupvar(var_string), navigation, default_value, &block)
+    end
+    default_value
+  end
+end