add deprecation function

Author: tphoney

lib/puppet/functions/deprecation.rb

@@ -0,0 +1,28 @@
+# Function to print deprecation warnings, it will display a provided message as well as the calling function.
+# The deprecation message will only be displayed once per caller.
+# It is affected by the puppet setting 'strict', which can be set to :error, :off and :warning (default)
+#
+require "puppet_x/puppetlabs/stdlib/deprecation_state"
+
+Puppet::Functions.create_function(:deprecation) do
+  dispatch :deprecation do
+    param 'String', :message
+  end
+
+  def deprecation(message)
+    called_by = Kernel.caller.first
+    # we only want to display a deprecation message once per caller.
+    unless PuppetX::Puppetlabs::Stdlib::DeprecationState.deprecation_warning_said(called_by)
+      # depending on configuration setting of strict
+      case Puppet.settings[:strict]
+      when :off
+        # do nothing 
+      when :error
+        Puppet.err("#{message}, called by #{called_by}")
+      else
+        Puppet.warning("#{message}, called by #{called_by}")
+      end
+      PuppetX::Puppetlabs::Stdlib::DeprecationState.add_deprecation_warning_said(called_by)
+    end
+  end
+end

lib/puppet_x/puppetlabs/stdlib/deprecation_state.rb

@@ -0,0 +1,16 @@
+module PuppetX
+  module Puppetlabs
+    module Stdlib
+      class DeprecationState
+        # This is so we display one message per caller
+        @@deprecation_warning_said = []
+        def self.deprecation_warning_said(calling_method)
+          @@deprecation_warning_said.include?(calling_method)
+        end
+        def self.add_deprecation_warning_said(calling_method)
+          @@deprecation_warning_said.push(calling_method) unless @@deprecation_warning_said.include?(calling_method)
+        end
+      end
+    end
+  end
+end

spec/functions/deprecation_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+require "puppet_x/puppetlabs/stdlib/deprecation_state"
+
+if ENV["FUTURE_PARSER"] == 'yes'
+  describe 'deprecation' do
+    pending 'teach rspec-puppet to load future-only functions under 3.7.5' do
+      it { is_expected.not_to eq(nil) }
+    end
+  end
+end
+
+if Puppet.version.to_f >= 4.0
+  describe 'deprecation' do
+    before(:each) {
+      # this is to reset the deprecation warning track, and strict variable to default
+      PuppetX::Puppetlabs::Stdlib::DeprecationState.class_variable_set :@@deprecation_warning_said, []
+      Puppet.settings[:strict] = :warning
+    }
+
+    it { is_expected.not_to eq(nil) }
+    it { is_expected.to run.with_params().and_raise_error(ArgumentError) }
+
+    it 'should display a single warning' do
+      Puppet.expects(:warning).with(includes('heelo, called by'))
+      is_expected.to run.with_params("heelo")
+    end
+  
+    it 'should display a single warning, despite multiple calls' do
+      Puppet.expects(:warning).with(includes('heelo, called by')).once
+      is_expected.to run.with_params("heelo")
+      is_expected.to run.with_params("heelo")
+    end
+
+    it 'should display a single error, despite multiple calls. strict= :error' do
+      Puppet.settings[:strict] = :error
+      Puppet.expects(:err).with(includes('heelo, called by')).once
+      is_expected.to run.with_params("heelo")
+      is_expected.to run.with_params("heelo")
+    end
+
+    it 'should display nothing, despite multiple calls. strict= :off' do
+      Puppet.settings[:strict] = :off
+      Puppet.expects(:warning).with(includes('heelo, called by')).never
+      Puppet.expects(:err).with(includes('heelo, called by')).never
+      is_expected.to run.with_params("heelo")
+      is_expected.to run.with_params("heelo")
+    end
+
+  end
+end