(FEAT) Add function parsejson

This commit adds a new function to parse specifically PSON formatted JSON.
This functionality was formally covered by `parsejson` which defaulted to JSON.
However this has now been changed so that the function now accurately uses JSON with this function covering the potential need for PSON too specifically be used.

Author: david22swan

lib/puppet/parser/functions/parsepson.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+#
+# parsepson.rb
+#
+module Puppet::Parser::Functions
+  newfunction(:parsepson, type: :rvalue, doc: <<-DOC
+    @summary
+      This function accepts PSON, a Puppet variant of JSON, as a string and then converts it into the correct
+      Puppet structure
+
+    @return
+      convert PSON into Puppet structure
+
+    > *Note:*
+      The optional second argument can be used to pass a default value that will
+      be returned if the parsing of YAML string have failed.
+      For more information on PSON please see the following link:
+      https://puppet.com/docs/puppet/7/http_api/pson.html
+  DOC
+  ) do |arguments|
+    raise ArgumentError, 'Wrong number of arguments. 1 or 2 arguments should be provided.' unless arguments.length >= 1
+
+    begin
+      PSON.load(arguments[0]) || arguments[1]
+    rescue StandardError => e
+      raise e unless arguments[1]
+      arguments[1]
+    end
+  end
+end
+
+# vim: set ts=2 sw=2 et :

spec/functions/parsepson_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'parsepson' do
+  it 'exists' do
+    is_expected.not_to eq(nil)
+  end
+
+  it 'raises an error if called without any arguments' do
+    is_expected.to run.with_params
+                      .and_raise_error(%r{wrong number of arguments}i)
+  end
+
+  context 'with correct PSON data' do
+    it 'is able to parse PSON data with a Hash' do
+      is_expected.to run.with_params('{"a":"1","b":"2"}')
+                        .and_return('a' => '1', 'b' => '2')
+    end
+
+    it 'is able to parse PSON data with an Array' do
+      is_expected.to run.with_params('["a","b","c"]')
+                        .and_return(['a', 'b', 'c'])
+    end
+
+    it 'is able to parse empty PSON values' do
+      actual_array = ['[]', '{}']
+      expected = [[], {}]
+      actual_array.each_with_index do |actual, index|
+        is_expected.to run.with_params(actual).and_return(expected[index])
+      end
+    end
+
+    it 'is able to parse PSON data with a mixed structure' do
+      is_expected.to run.with_params('{"a":"1","b":2,"c":{"d":[true,false]}}')
+                        .and_return('a' => '1', 'b' => 2, 'c' => { 'd' => [true, false] })
+    end
+
+    it 'is able to parse PSON data with a UTF8 and double byte characters' do
+      is_expected.to run.with_params('{"×":"これ","ý":"記号","です":{"©":["Á","ß"]}}')
+                        .and_return('×' => 'これ', 'ý' => '記号', 'です' => { '©' => ['Á', 'ß'] })
+    end
+
+    it 'does not return the default value if the data was parsed correctly' do
+      is_expected.to run.with_params('{"a":"1"}', 'default_value')
+                        .and_return('a' => '1')
+    end
+  end
+
+  context 'with incorrect PSON data' do
+    it 'raises an error with invalid PSON and no default' do
+      is_expected.to run.with_params('')
+                        .and_raise_error(PSON::ParserError)
+    end
+
+    it 'supports a structure for a default value' do
+      is_expected.to run.with_params('', 'a' => '1')
+                        .and_return('a' => '1')
+    end
+
+    ['', 1, 1.2, nil, true, false, [], {}, :yaml].each do |value|
+      it "returns the default value for an incorrect #{value.inspect} (#{value.class}) parameter" do
+        is_expected.to run.with_params(value, 'default_value')
+                          .and_return('default_value')
+      end
+    end
+  end
+end