add deprecation function

Author: tphoney

README.markdown

@@ -289,6 +289,10 @@ Deletes all instances of a given value from a hash. For example, `delete_values(
 
 Deletes all instances of the undef value from an array or hash. For example, `$hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false})` returns {a => 'A', b => '', d => false}. *Type*: rvalue.
 
+#### `deprecation`
+
+Function to print deprecation warnings, Logs a (non deprecation) warning once for a given key. A key, that can be used to denote this particular type of deprecation (for instance also adding it to disabled_warnings). The second is the uniqueness key - in the example, the deprecation can appear once per module name. 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, String.
+
 #### `difference`
 
 Returns the difference between two arrays. The returned array is a copy of the original array, removing any items that also appear in the second array. For example, `difference(["a","b","c"],["b","c","d"])` returns ["a"]. *Type*: rvalue.

lib/puppet/functions/deprecation.rb

@@ -0,0 +1,23 @@
+# Function to print deprecation warnings, Logs a (non deprecation) warning once for a given key
+# It is affected by the puppet setting 'strict', which can be set to :error, :off and :warning (default)
+#
+
+Puppet::Functions.create_function(:deprecation) do
+  dispatch :deprecation do
+    param 'String', :kind
+    param 'String', :key
+    param 'String', :message
+  end
+
+  def deprecation(kind, key, message)
+    # depending on configuration setting of strict
+    case Puppet.settings[:strict]
+    when :off
+      # do nothing 
+    when :error
+      Puppet.fail("#{kind}. #{key}. #{message}")
+    else
+      Puppet.warn_once(kind, key, message)
+    end
+  end
+end

spec/functions/deprecation_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+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 strict variable to default
+      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'))
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+    end
+  
+    it 'should display a single warning, despite multiple calls' do
+      Puppet.expects(:warning).with(includes('heelo')).once
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+    end
+
+    it 'should fail twice with message, with multiple calls. when strict= :error' do
+      Puppet.settings[:strict] = :error
+      Puppet.expects(:fail).with(includes('heelo')).twice
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+    end
+
+    it 'should display nothing, despite multiple calls. strict= :off' do
+      Puppet.settings[:strict] = :off
+      Puppet.expects(:fail).with(any_parameters).never
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+      is_expected.to run.with_params('kind', 'key', 'heelo')
+    end
+
+    after(:all) {
+      # this is to reset the strict variable to default
+      Puppet.settings[:strict] = :warning
+    }
+  end
+end