puppet 5.5.22 → 6.0.0

data/lib/puppet/functions/abs.rb

@@ -0,0 +1,61 @@
+# Returns the absolute value of a Numeric value, for example -34.56 becomes
+# 34.56. Takes a single `Integer` or `Float` value as an argument.
+#
+# *Deprecated behavior*
+#
+# For backwards compatibility reasons this function also works when given a
+# number in `String` format such that it first attempts to covert it to either a `Float` or
+# an `Integer` and then taking the absolute value of the result. Only strings representing
+# a number in decimal format is supported - an error is raised if
+# value is not decimal (using base 10). Leading 0 chars in the string
+# are ignored. A floating point value in string form can use some forms of
+# scientific notation but not all.
+#
+# Callers should convert strings to `Numeric` before calling
+# this function to have full control over the conversion.
+#
+# @example Converting to Numeric before calling
+# ```puppet
+# abs(Numeric($str_val))
+# ```
+# 
+# It is worth noting that `Numeric` can convert to absolute value
+# directly as in the following examples:
+#
+# @example Absolute value and String to Numeric
+# ```puppet
+# Numeric($strval, true)     # Converts to absolute Integer or Float
+# Integer($strval, 10, true) # Converts to absolute Integer using base 10 (decimal)
+# Integer($strval, 16, true) # Converts to absolute Integer using base 16 (hex)
+# Float($strval, true)       # Converts to absolute Float
+# ```puppet
+#
+Puppet::Functions.create_function(:abs) do
+  dispatch :on_numeric do
+    param 'Numeric', :val
+  end
+
+  dispatch :on_string do
+    param 'String', :val
+  end
+
+  def on_numeric(x)
+    x.abs
+  end
+
+  def on_string(x)
+    Puppet.warn_once('deprecations', 'abs_function_numeric_coerce_string',
+      _("The abs() function's auto conversion of String to Numeric is deprecated - change to convert input before calling"))
+
+    # These patterns for conversion are backwards compatible with the stdlib
+    # version of this function.
+    #
+    if x =~ %r{^-?(?:\d+)(?:\.\d+){1}$}
+      x.to_f.abs
+    elsif x =~ %r{^-?\d+$}
+      x.to_i.abs
+    else
+      raise(ArgumentError, 'abs(): Requires float or integer to work with - was given non decimal string')
+    end
+  end
+end

data/lib/puppet/functions/call.rb

@@ -6,6 +6,10 @@
 # 2. Any number of arguments to be passed to the called function.
 # 3. An optional lambda, if the function being called supports it.
 #
+# This function can also be used to resolve a `Deferred` given as
+# the only argument to the function (does not accept arguments nor
+# a block).
+#
 # @example Using the `call` function
 #
 # ```puppet
@@ -26,6 +30,29 @@
 # The `call` function can be used to call either Ruby functions or Puppet language
 # functions.
 #
+# When used with `Deferred` values, the deferred value can either describe
+# a function call, or a dig into a variable.
+#
+# @example Resolving a deferred function call
+#
+# ```puppet
+# $d = Deferred('join', [[1,2,3], ':']) # A future call to join that joins the arguments 1,2,3 with ':'
+# notice($d.call())
+# ```
+#
+# Would notice the string "1:2:3".
+#
+# @example Resolving a deferred variable value with optional dig into its structure
+#
+# ```puppet
+# $d = Deferred('$facts', ['processors', 'count'])
+# notice($d.call())
+# ```
+#
+# Would notice the value of `$facts['processors']['count']` at the time when the `call` is made.
+#
+# * Deferred values supported since Puppet 5.6.0
+#
 # @since 5.0.0
 #
 Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
@@ -36,8 +63,17 @@ Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
     optional_block_param
   end
 
+  dispatch :call_deferred do
+    scope_param
+    param 'Deferred', :deferred
+  end
+
   def call_impl_block(scope, function_name, *args, &block)
-    # The call function must be able to call functions loaded by any loader visible from the calling scope.
-    Puppet::Pops::Parser::EvaluatingParser.new.evaluator.external_call_function(function_name, args, scope, &block)
+    call_function_with_scope(scope, function_name, *args, &block)
+  end
+
+  def call_deferred(scope, deferred)
+    Puppet::Pops::Evaluator::DeferredResolver.resolve(deferred, scope.compiler)
   end
+
 end

data/lib/puppet/functions/camelcase.rb

@@ -0,0 +1,62 @@
+# Creates a Camel Case version of a String
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion replaces all combinations of *_<char>* with an upcased version of the
+#   character following the _.  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").
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is capitalized 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.
+# * The result will not contain any underscore characters.
+#
+# 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 Camelcase a String
+# ```puppet
+# 'hello_friend'.camelcase()
+# camelcase('hello_friend')
+# ```
+# Would both result in `"HelloFriend"`
+#
+# @example Camelcase of strings in an Array
+# ```puppet
+# ['abc_def', 'bcd_xyz'].capitalize()
+# capitalize(['abc_def', 'bcd_xyz'])
+# ```
+# Would both result in `['AbcDef', 'BcdXyz']`
+#
+Puppet::Functions.create_function(:camelcase) 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.split('_').map {|x| x.capitalize }.join('')
+  end
+
+  def on_iterable(a)
+    a.map {|x| do_camelcase(x) }
+  end
+
+  def do_camelcase(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? on_string(x) : x
+  end
+end

data/lib/puppet/functions/capitalize.rb

@@ -0,0 +1,61 @@
+# Capitalizes the first character of a String, or the first character of every String in an Iterable value (such as an Array).
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String`, a string with its first character in upper 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 capitalized to "Ss").
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is capitalized 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.
+#
+# 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 Capitalizing a String
+# ```puppet
+# 'hello'.capitalize()
+# upcase('hello')
+# ```
+# Would both result in "Hello"
+#
+# @example Capitalizing strings in an Array
+# ```puppet
+# ['abc', 'bcd'].capitalize()
+# capitalize(['abc', 'bcd'])
+# ```
+# Would both result in ['Abc', 'Bcd']
+#
+Puppet::Functions.create_function(:capitalize) 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.capitalize
+  end
+
+  def on_iterable(a)
+    a.map {|x| do_capitalize(x) }
+  end
+
+  def do_capitalize(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.capitalize : x
+  end
+end

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