puppet 5.0.0 → 6.0.0

data/lib/puppet/functions/ceiling.rb

@@ -0,0 +1,37 @@
+# Returns the smallest `Integer` greater 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(:ceiling) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  dispatch :on_string do
+    param 'String', :val
+  end
+
+  def on_numeric(x)
+    x.ceil
+  end
+
+  def on_string(x)
+    Puppet.warn_once('deprecations', 'ceiling_function_numeric_coerce_string',
+      _("The ceiling() function's auto conversion of String to Float is deprecated - change to convert input before calling"))
+
+    begin
+      Float(x).ceil
+    rescue TypeError, ArgumentError => _e
+      # TRANSLATORS: 'ceiling' is a name and should not be translated
+      raise(ArgumentError, _('ceiling(): cannot convert given value to a floating point value.'))
+    end
+  end
+
+end

data/lib/puppet/functions/chomp.rb

@@ -0,0 +1,57 @@
+# Returns a new string with the record separator character(s) removed.
+# The record separator is the line ending characters `\r` and `\n`.
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes `\r\n`, `\n` or `\r` from the end of a string.
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is processed and the conversion is not recursive.
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# @example Removing line endings
+# ```puppet
+# "hello\r\n".chomp()
+# chomp("hello\r\n")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing line endings in an array
+# ```puppet
+# ["hello\r\n", "hi\r\n"].chomp()
+# chomp(["hello\r\n", "hi\r\n"])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:chomp) do
+
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_iterable do
+    param 'Iterable[Variant[String, Numeric]]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.chomp
+  end
+
+  def on_iterable(a)
+    a.map {|x| do_chomp(x) }
+  end
+
+  def do_chomp(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.chomp : x
+  end
+end

data/lib/puppet/functions/chop.rb

@@ -0,0 +1,67 @@
+# Returns a new string with the last character removed.
+# If the string ends with `\r\n`, both characters are removed. Applying chop to an empty
+# string returns an empty string. If you wish to merely remove record
+# separators then you should use the `chomp` function.
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes the last character, or if it ends with \r\n` it removes both. If String is empty
+#   an empty string is returned.
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is processed and the conversion is not recursive.
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# @example Removing line endings
+# ```puppet
+# "hello\r\n".chop()
+# chop("hello\r\n")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing last char
+# ```puppet
+# "hello".chop()
+# chop("hello")
+# ```
+# Would both result in `"hell"`
+#
+# @example Removing last char in an array
+# ```puppet
+# ["hello\r\n", "hi\r\n"].chop()
+# chop(["hello\r\n", "hi\r\n"])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:chop) do
+
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_iterable do
+    param 'Iterable[Variant[String, Numeric]]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.chop
+  end
+
+  def on_iterable(a)
+    a.map {|x| do_chop(x) }
+  end
+
+  def do_chop(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.chop : x
+  end
+end

data/lib/puppet/functions/compare.rb

@@ -0,0 +1,125 @@
+# Compares two values and returns -1, 0 or 1 if first value is smaller, equal or larger than the second value.
+# The compare function accepts arguments of the data types `String`, `Numeric`, `Timespan`, `Timestamp`, and `Semver`,
+# such that:
+#
+# * two of the same data type can be compared
+# * `Timespan` and `Timestamp` can be compared with each other and with `Numeric`
+#
+# When comparing two `String` values the comparison can be made to consider case by passing a third (optional)
+# boolean `false` value - the default is `true` which ignores case as the comparison operators
+# in the Puppet Language.
+#
+Puppet::Functions.create_function(:compare) do
+  local_types do
+    type 'TimeComparable = Variant[Numeric, Timespan, Timestamp]'
+    type 'Comparable = Variant[String, Semver, TimeComparable]'
+  end
+
+  dispatch :on_numeric do
+    param 'Numeric', :a
+    param 'Numeric', :b
+  end
+
+  dispatch :on_string do
+    param 'String', :a
+    param 'String', :b
+    optional_param 'Boolean', :ignore_case
+  end
+
+  dispatch :on_version do
+    param 'Semver', :a
+    param 'Semver', :b
+  end
+
+  dispatch :on_time_num_first do
+    param 'Numeric', :a
+    param 'Variant[Timespan, Timestamp]', :b
+  end
+
+  dispatch :on_timestamp do
+    param 'Timestamp', :a
+    param 'Variant[Timestamp, Numeric]', :b
+  end
+
+  dispatch :on_timespan do
+    param 'Timespan', :a
+    param 'Variant[Timespan, Numeric]', :b
+  end
+
+  argument_mismatch :on_error do
+    param 'Comparable', :a
+    param 'Comparable', :b
+    repeated_param 'Any', :ignore_case
+  end
+
+  argument_mismatch :on_not_comparable do
+    param 'Any', :a
+    param 'Any', :b
+    repeated_param 'Any', :ignore_case
+  end
+
+  def on_numeric(a, b)
+    a <=> b
+  end
+
+  def on_string(a, b, ignore_case = true)
+    if ignore_case
+      a.casecmp(b)
+    else
+      a <=> b
+    end
+  end
+
+  def on_version(a, b)
+    a <=> b
+  end
+
+  def on_time_num_first(a, b)
+    # Time data types can compare against Numeric but not the other way around
+    # the comparison is therefore done in reverse and the answer is inverted.
+    -(b <=> a)
+  end
+
+  def on_timespan(a, b)
+    a <=> b
+  end
+
+  def on_timestamp(a, b)
+    a <=> b
+  end
+
+  def on_not_comparable(a, b, *ignore_case)
+    # TRANSLATORS 'compare' is a name
+    _("compare(): Non comparable type. Only values of the types Numeric, String, Semver, Timestamp and Timestamp can be compared. Got %{type_a} and %{type_b}") % {
+      type_a: type_label(a), type_b: type_label(b)
+    }
+  end
+
+  def on_error(a, b, *ignore_case)
+    if !ignore_case.empty?
+      unless a.is_a?(String) && b.is_a?(String)
+        # TRANSLATORS 'compare' is a name
+        return _("compare(): The third argument (ignore case) can only be used when comparing strings")
+      end
+      unless ignore_case.size == 1
+        # TRANSLATORS 'compare' is a name
+        return _("compare(): Accepts at most 3 arguments, got %{actual_number}") % {actual_number: 2 + ignore_case.size}
+      end
+      unless ignore_case[0].is_a?(Boolean)
+        # TRANSLATORS 'compare' is a name
+        return _("compare(): The third argument (ignore case) must be a Boolean. Got %{type}") % { type: type_label(ignore_case[0]) }
+      end
+    end
+
+    if a.class != b.class
+      # TRANSLATORS 'compare' is a name
+      return _("compare(): Can only compare values of the same type (or for Timestamp/Timespan also against Numeric). Got %{type_a} and %{type_b}") % {
+        type_a: type_label(a), type_b: type_label(b)
+      }
+    end
+  end
+
+  def type_label(x)
+    Puppet::Pops::Model::ModelLabelProvider.new.label(x)
+  end
+end

data/lib/puppet/functions/contain.rb

@@ -1,6 +1,22 @@
-# Called within a class definition, establishes a containment
-# relationship with another class
-# For documentation, see the 3.x stub
+# Makes one or more classes be contained inside the current class.
+# If any of these classes are undeclared, they will be declared as if
+# there were declared with the `include` function.
+# Accepts a class name, an array of class names, or a comma-separated
+# list of class names.
+#
+# A contained class will not be applied before the containing class is
+# begun, and will be finished before the containing class is finished.
+#
+# You must use the class's full name;
+# relative names are not allowed. In addition to names in string form,
+# you may also directly use `Class` and `Resource` `Type`-values that are produced by
+# evaluating resource and relationship expressions.
+#
+# The function returns an array of references to the classes that were contained thus
+# allowing the function call to `contain` to directly continue.
+#
+# - Since 4.0.0 support for `Class` and `Resource` `Type`-values, absolute names
+# - Since 4.7.0 a value of type `Array[Type[Class[n]]]` is returned with all the contained classes
 #
 Puppet::Functions.create_function(:contain, Puppet::Functions::InternalFunction) do
   dispatch :contain do
@@ -13,6 +29,12 @@ Puppet::Functions.create_function(:contain, Puppet::Functions::InternalFunction)
   end
 
   def contain(scope, *classes)
+    if Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+        {:operation => 'contain'})
+    end
+
     # Make call patterns uniform and protected against nested arrays, also make
     # names absolute if so desired.
     classes = scope.transform_and_assert_classnames(classes.flatten)

data/lib/puppet/functions/convert_to.rb

@@ -0,0 +1,34 @@
+# The `convert_to(value, type)` is a convenience function that does the same as `new(type, value)`.
+# The difference in the argument ordering allows it to be used in chained style for
+# improved readability "left to right".
+#
+# When the function is given a lambda, it is called with the converted value, and the function
+# returns what the lambda returns, otherwise the converted value.
+#
+# @example 'convert_to' instead of 'new'
+#
+# ```puppet
+#   # The harder to read variant:
+#   # Using new operator - that is "calling the type" with operator ()
+#   Hash(Array("abc").map |$i,$v| { [$i, $v] })
+#
+#   # The easier to read variant:
+#   # using 'convert_to'
+#   "abc".convert_to(Array).map |$i,$v| { [$i, $v] }.convert_to(Hash)
+# ```
+#
+# @since 5.4.0
+#
+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, *args, &block)
+    result = call_function('new', type, value, *args)
+    block_given? ? yield(result) : result
+  end
+end

data/lib/puppet/functions/crit.rb

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

data/lib/puppet/functions/debug.rb

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

data/lib/puppet/functions/defined.rb

@@ -4,15 +4,17 @@
 # being declared or assigned).
 #
 # This function takes at least one string argument, which can be a class name, type name,
-# resource reference, or variable reference of the form `'$name'`.
+# resource reference, or variable reference of the form `'$name'`. (Note that the `$` sign
+# is included in the string which must be in single quotes to prevent the `$` character
+# to be interpreted as interpolation.
 #
 # The `defined` function checks both native and defined types, including types
 # provided by modules. Types and classes are matched by their names. The function matches
 # resource declarations by using resource references.
 #
-# **Examples**: Different types of `defined` function matches
+# @example Different types of `defined` function matches
 #
-# ~~~ puppet
+# ```puppet
 # # Matching resource types
 # defined("file")
 # defined("customtype")
@@ -21,19 +23,19 @@
 # defined("foo")
 # defined("foo::bar")
 #
-# # Matching variables
+# # Matching variables (note the single quotes)
 # defined('$name')
 #
 # # Matching declared resources
 # defined(File['/tmp/file'])
-# ~~~
+# ```
 #
 # Puppet depends on the configuration's evaluation order when checking whether a resource
 # is declared.
 #
 # @example Importance of evaluation order when using `defined`
 #
-# ~~~ puppet
+# ```puppet
 # # Assign values to $is_defined_before and $is_defined_after using identical `defined`
 # # functions.
 #
@@ -46,7 +48,7 @@
 # $is_defined_after = defined(File['/tmp/file'])
 #
 # # $is_defined_before returns false, but $is_defined_after returns true.
-# ~~~
+# ```
 #
 # This order requirement only refers to evaluation order. The order of resources in the
 # configuration graph (e.g. with `before` or `require`) does not affect the `defined`
@@ -64,7 +66,7 @@
 #
 # @example Matching multiple resources and resources by different types with `defined`
 #
-# ~~~ puppet
+# ```puppet
 # file { "/tmp/file1":
 #   ensure => file,
 # }
@@ -90,7 +92,7 @@
 # defined(Resource['exec','/tmp/file2'])
 # defined(File['/tmp/file3'])
 # defined('$tmp_file2')
-# ~~~
+# ```
 #
 # @since 2.7.0
 # @since 3.6.0 variable reference and future parser types
@@ -105,7 +107,6 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
   end
 
   def is_defined(scope, *vals)
-    env = scope.environment
     vals.any? do |val|
       case val
       when String
@@ -120,7 +121,6 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
             Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_main_class(scope)
           else
             # Find a resource type, definition or class definition
-            krt = scope.environment.known_resource_types
             Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_resource_type_or_class(scope, val)
           end
         end
@@ -133,24 +133,23 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
         type = Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_resource_type(scope, val.type_name)
         val.title.nil? ? type : scope.compiler.findresource(type, val.title)
 
-      when Puppet::Pops::Types::PHostClassType
+      when Puppet::Pops::Types::PClassType
         raise  ArgumentError, _('The given class type is a reference to all classes') if val.class_name.nil?
         scope.compiler.findresource(:class, val.class_name)
 
-      when Puppet::Pops::Types::PType
+      when Puppet::Pops::Types::PTypeType
         case val.type
         when Puppet::Pops::Types::PResourceType
           # It is most reasonable to take Type[File] and Type[File[foo]] to mean the same as if not wrapped in a Type
           # Since the difference between File and File[foo] already captures the distinction of type vs instance.
           is_defined(scope, val.type)
 
-        when Puppet::Pops::Types::PHostClassType
+        when Puppet::Pops::Types::PClassType
           # Interpreted as asking if a class (and nothing else) is defined without having to be included in the catalog
           # (this is the same as asking for just the class' name, but with the added certainty that it cannot be a defined type.
           #
           raise  ArgumentError, _('The given class type is a reference to all classes') if val.type.class_name.nil?
           Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_hostclass(scope, val.type.class_name)
-          #scope.environment.known_resource_types.find_hostclass(val.type.class_name)
         end
       else
         raise ArgumentError, _("Invalid argument of type '%{value_class}' to 'defined'") % { value_class: val.class }

data/lib/puppet/functions/dig.rb

@@ -1,5 +1,29 @@
-# Digs into a data structure.
-# (Documented in 3.x stub)
+# Returns a value for a sequence of given keys/indexes into a structure, such as
+# an array or hash.
+#
+# This function is used to "dig into" a complex data structure by
+# using a sequence of keys / indexes to access a value from which
+# the next key/index is accessed recursively.
+#
+# The first encountered `undef` value or key stops the "dig" and `undef` is returned.
+#
+# An error is raised if an attempt is made to "dig" into
+# something other than an `undef` (which immediately returns `undef`), an `Array` or a `Hash`.
+#
+# @example Using `dig`
+#
+# ```puppet
+# $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
+# notice $data.dig('a', 'b', 1, 'x')
+# ```
+#
+# Would notice the value 100.
+#
+# This is roughly equivalent to `$data['a']['b'][1]['x']`. However, a standard
+# index will return an error and cause catalog compilation failure if any parent
+# of the final key (`'x'`) is `undef`. The `dig` function will return `undef`,
+# rather than failing catalog compilation. This allows you to check if data
+# exists in a structure without mandating that it always exists.
 #
 # @since 4.5.0
 #
@@ -14,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