Ignore Puppet's strict setting when calling function without namespace

Previously, when a user had the Puppet setting `strict` set to `error`
(which is the default in Puppet 8), a call to one of stdlib's functions
via the deprecated non-namespaced function would cause a hard failure
instead of just logging a warning and calling the real namespaced
function.

In this change, an optional third parameter is added to the
`deprecation` function.  The default behaviour remains the same, but
when the third parameter is set to `false`, the `strict` setting is
ignored.  Finally, all of our shims have been updated to call
`deprecation` with this parameter set to `false`.

This change will make it much easier for users to migrate to stdlib 9
(and to upgrade modules that now depend on stdlib 9)

Fixes #1373

Author: alexjfisher

Rakefile

@@ -115,7 +115,7 @@ task :regenerate_unamespaced_shims do
           repeated_param 'Any', :args
         end
         def deprecation_gen(*args)
-          call_function('deprecation', '#{function_name}', 'This function is deprecated, please use stdlib::#{function_name} instead.')
+          call_function('deprecation', '#{function_name}', 'This function is deprecated, please use stdlib::#{function_name} instead.', false)
           call_function('stdlib::#{function_name}', *args)
         end
       end

lib/puppet/functions/batch_escape.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'batch_escape', 'This function is deprecated, please use stdlib::batch_escape instead.')
+    call_function('deprecation', 'batch_escape', 'This function is deprecated, please use stdlib::batch_escape instead.', false)
     call_function('stdlib::batch_escape', *args)
   end
 end

lib/puppet/functions/deprecation.rb

@@ -1,38 +1,38 @@
 # frozen_string_literal: true
 
-#   Function to print deprecation warnings, Logs a warning once for a given key.
-#
-# The uniqueness key - can appear once.
-# The msg is the message text including any positional information that is formatted by the
-# user/caller of the method.
-# It is affected by the puppet setting 'strict', which can be set to :error
-# (outputs as an error message), :off (no message / error is displayed) and :warning
-# (default, outputs a warning)  *Type*: String, String.
-#
+# @summary Function to print deprecation warnings, Logs a warning once for a given key.
 Puppet::Functions.create_function(:deprecation) do
   # @param key
-  # @param  message
-  # @return deprecated warnings
+  #   The uniqueness key.  This function logs once for any given key.
+  # @param message
+  #   Is the message text including any positional information that is formatted by the user/caller of the function.
+  # @param use_strict_setting
+  #   When `true`, (the default), the function is affected by the puppet setting 'strict', which can be set to :error
+  #   (outputs as an error message), :off (no message / error is displayed) and :warning
+  #   (default, outputs a warning).
   dispatch :deprecation do
     param 'String', :key
     param 'String', :message
+    optional_param 'Boolean', :use_strict_setting
   end
 
-  def deprecation(key, message)
+  def deprecation(key, message, use_strict_setting = true) # rubocop:disable Style/OptionalBooleanParameter
     if defined? Puppet::Pops::PuppetStack.stacktrace
       stacktrace = Puppet::Pops::PuppetStack.stacktrace
       file = stacktrace[0]
       line = stacktrace[1]
       message = "#{message} at #{file}:#{line}"
     end
-    # depending on configuration setting of strict
-    case Puppet.settings[:strict]
-    when :off
-      # do nothing
-    when :error
-      raise("deprecation. #{key}. #{message}")
-    else
-      Puppet.deprecation_warning(message, key) unless ENV['STDLIB_LOG_DEPRECATIONS'] == 'false'
-    end
+
+    # Do nothing if using strict setting and strict is set to `off`
+    return if use_strict_setting && Puppet.settings[:strict] == :off
+
+    # Fail hard if using strict setting and strict is set to `error`
+    raise("deprecation. #{key}. #{message}") if use_strict_setting && Puppet.settings[:strict] == :error
+
+    # Otherwise raise a soft warning
+    # (unless the STDLIB_LOG_DEPRECATIONS has been set to `false`.  This is mainly for use in rspec-puppet testing to supress noise in logs)
+    Puppet.deprecation_warning(message, key) unless ENV['STDLIB_LOG_DEPRECATIONS'] == 'false'
+    nil
   end
 end

lib/puppet/functions/ensure_packages.rb

@@ -7,7 +7,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(scope, *args)
-    call_function('deprecation', 'ensure_packages', 'This function is deprecated, please use stdlib::ensure_packages instead.')
+    call_function('deprecation', 'ensure_packages', 'This function is deprecated, please use stdlib::ensure_packages instead.', false)
     scope.call_function('stdlib::ensure_packages', args)
   end
 end

lib/puppet/functions/fqdn_rand_string.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'fqdn_rand_string', 'This function is deprecated, please use stdlib::fqdn_rand_string instead.')
+    call_function('deprecation', 'fqdn_rand_string', 'This function is deprecated, please use stdlib::fqdn_rand_string instead.', false)
     call_function('stdlib::fqdn_rand_string', *args)
   end
 end

lib/puppet/functions/has_interface_with.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'has_interface_with', 'This function is deprecated, please use stdlib::has_interface_with instead.')
+    call_function('deprecation', 'has_interface_with', 'This function is deprecated, please use stdlib::has_interface_with instead.', false)
     call_function('stdlib::has_interface_with', *args)
   end
 end

lib/puppet/functions/merge.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'merge', 'This function is deprecated, please use stdlib::merge instead.')
+    call_function('deprecation', 'merge', 'This function is deprecated, please use stdlib::merge instead.', false)
     call_function('stdlib::merge', *args)
   end
 end

lib/puppet/functions/os_version_gte.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'os_version_gte', 'This function is deprecated, please use stdlib::os_version_gte instead.')
+    call_function('deprecation', 'os_version_gte', 'This function is deprecated, please use stdlib::os_version_gte instead.', false)
     call_function('stdlib::os_version_gte', *args)
   end
 end

lib/puppet/functions/parsehocon.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'parsehocon', 'This function is deprecated, please use stdlib::parsehocon instead.')
+    call_function('deprecation', 'parsehocon', 'This function is deprecated, please use stdlib::parsehocon instead.', false)
     call_function('stdlib::parsehocon', *args)
   end
 end

lib/puppet/functions/powershell_escape.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'powershell_escape', 'This function is deprecated, please use stdlib::powershell_escape instead.')
+    call_function('deprecation', 'powershell_escape', 'This function is deprecated, please use stdlib::powershell_escape instead.', false)
     call_function('stdlib::powershell_escape', *args)
   end
 end