Deprecate flatten()

Author: pmcmaw

README.md

@@ -1274,6 +1274,8 @@ fact('vmware."VRA.version"')
 
 #### `flatten`
 
+**Deprecated. Puppet 5.5.0 has introduced an inbuilt `flatten` function, that will take precedence over the stdlib function. See [Puppet 5.5.0 Release Notes](https://puppet.com/docs/puppet/5.5/release_notes.html#new-features).**
+
 Flattens deeply nested arrays and returns a single flat array as a result.
 
 For example, `flatten(['a', ['b', ['c']]])` returns ['a','b','c'].

lib/puppet/parser/functions/flatten.rb

@@ -14,6 +14,9 @@ module Puppet::Parser::Functions
   DOC
              ) do |arguments|
 
+    function_deprecation([:flatten, 'This method is deprecated, this function is now shipped in puppet in versions 5.5.0 and later.
+                           For more information please see [puppet 5.5.0 release notes|https://puppet.com/docs/puppet/5.5/release_notes.html#new-features].'])
+
     raise(Puppet::ParseError, "flatten(): Wrong number of arguments given (#{arguments.size} for 1)") if arguments.size != 1
 
     array = arguments[0]

spec/functions/flatten_spec.rb

@@ -2,10 +2,10 @@
 
 describe 'flatten' do
   it { is_expected.not_to eq(nil) }
-  it { is_expected.to run.with_params.and_raise_error(Puppet::ParseError) }
-  it { is_expected.to run.with_params([], []).and_raise_error(Puppet::ParseError) }
-  it { is_expected.to run.with_params(1).and_raise_error(Puppet::ParseError) }
-  it { is_expected.to run.with_params('one').and_raise_error(Puppet::ParseError) }
+  it { is_expected.to run.with_params.and_raise_error(Puppet::ParseError) } if Puppet.version < '5.5.0'
+  it { is_expected.to run.with_params([], []).and_raise_error(Puppet::ParseError) } if Puppet.version < '5.5.0'
+  it { is_expected.to run.with_params(1).and_raise_error(Puppet::ParseError) } if Puppet.version < '5.5.0'
+  it { is_expected.to run.with_params('one').and_raise_error(Puppet::ParseError) } if Puppet.version < '5.5.0'
   it { is_expected.to run.with_params([]).and_return([]) }
   it { is_expected.to run.with_params(['one']).and_return(['one']) }
   it { is_expected.to run.with_params([['one']]).and_return(['one']) }