(MODULES-3529) add deprecation function

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 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.
+
 #### `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,21 @@
+# 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.
+#
+
+Puppet::Functions.create_function(:deprecation) do
+  dispatch :deprecation do
+    param 'String', :key
+    param 'String', :message
+  end
+
+  def deprecation(key, message)
+    # depending on configuration setting of strict
+    case Puppet.settings[:strict]
+    when :off
+      # do nothing
+    when :error
+      fail("deprecation. #{key}. #{message}")
+    else
+      Puppet.warn_once('deprecation', key, message)
+    end
+  end
+end

spec/acceptance/deprecation_spec.rb

@@ -0,0 +1,75 @@
+#! /usr/bin/env ruby -S rspec
+require 'spec_helper_acceptance'
+require 'shellwords'
+
+describe 'deprecation function' do
+  before :each do
+    FileUtils.rm_rf '/tmp/deprecation'
+  end
+
+  context 'with --strict=error', if: get_puppet_version =~ /^4/ do
+    before :all do
+      pp = <<-EOS
+      deprecation('key', 'message')
+      file { '/tmp/deprecation': ensure => present }
+      EOS
+      @result = on(default, puppet('apply', '--strict=error', '-e', Shellwords.shellescape(pp)), acceptable_exit_codes: (0...256))
+    end
+
+    it "should return an error" do
+      expect(@result.exit_code).to eq(1)
+    end
+
+    it "should show the error message" do
+      expect(@result.stderr).to match(/deprecation. key. message/)
+    end
+
+    describe file('/tmp/deprecation') do
+      it { is_expected.not_to exist }
+    end
+  end
+
+  context 'with --strict=warning', if: get_puppet_version =~ /^4/ do
+    before :all do
+      pp = <<-EOS
+      deprecation('key', 'message')
+      file { '/tmp/deprecation': ensure => present }
+      EOS
+      @result = on(default, puppet('apply', '--strict=warning', '-e', Shellwords.shellescape(pp)), acceptable_exit_codes: (0...256))
+    end
+
+    it "should not return an error" do
+      expect(@result.exit_code).to eq(0)
+    end
+
+    it "should show the error message" do
+      expect(@result.stderr).to match(/Warning: message/)
+    end
+
+    describe file('/tmp/deprecation') do
+      it { is_expected.to exist }
+    end
+  end
+
+  context 'with --strict=off', if: get_puppet_version =~ /^4/ do
+    before :all do
+      pp = <<-EOS
+      deprecation('key', 'message')
+      file { '/tmp/deprecation': ensure => present }
+      EOS
+      @result = on(default, puppet('apply', '--strict=off', '-e', Shellwords.shellescape(pp)), acceptable_exit_codes: (0...256))
+    end
+
+    it "should not return an error" do
+      expect(@result.exit_code).to eq(0)
+    end
+
+    it "should not show the error message" do
+      expect(@result.stderr).not_to match(/Warning: message/)
+    end
+
+    describe file('/tmp/deprecation') do
+      it { is_expected.to exist }
+    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('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('key', 'heelo')
+      is_expected.to run.with_params('key', 'heelo')
+    end
+
+    it 'should fail twice with message, with multiple calls. when strict= :error' do
+      Puppet.settings[:strict] = :error
+      Puppet.expects(:warning).with(includes('heelo')).never
+      is_expected.to run.with_params('key', 'heelo').and_raise_error(RuntimeError, /deprecation. key. heelo/)
+      is_expected.to run.with_params('key', 'heelo').and_raise_error(RuntimeError, /deprecation. key. heelo/)
+    end
+
+    it 'should display nothing, despite multiple calls. strict= :off' do
+      Puppet.settings[:strict] = :off
+      Puppet.expects(:warning).with(includes('heelo')).never
+      is_expected.to run.with_params('key', 'heelo')
+      is_expected.to run.with_params('key', 'heelo')
+    end
+
+    after(:all) {
+      # this is to reset the strict variable to default
+      Puppet.settings[:strict] = :warning
+    }
+  end
+end