Merge pull request #1236 from alexjfisher/xml_encode

Add `xml_encode` function

Author: david22swan

REFERENCE.md

@@ -167,6 +167,7 @@ the provided regular expression.
 last Period).
 * [`stdlib::ip_in_range`](#stdlibip_in_range): Returns true if the ipaddress is within the given CIDRs
 * [`stdlib::start_with`](#stdlibstart_with): Returns true if str starts with one of the prefixes given. Each of the prefixes should be a String.
+* [`stdlib::xml_encode`](#stdlibxml_encode): Encode strings for XML files
 * [`str2bool`](#str2bool): This converts a string to a boolean.
 * [`str2saltedpbkdf2`](#str2saltedpbkdf2): Convert a string into a salted SHA512 PBKDF2 password hash like requred for OS X / macOS 10.8+
 * [`str2saltedsha512`](#str2saltedsha512): This converts a string to a salted-SHA512 password hash (which is used for
@@ -4300,6 +4301,64 @@ Data type: `Variant[String[1],Array[String[1], 1]]`
 
 The prefixes to check.
 
+### <a name="stdlibxml_encode"></a>`stdlib::xml_encode`
+
+Type: Ruby 4.x API
+
+This function can encode strings such that they can be used directly in XML files.
+It supports encoding for both XML text (CharData) or attribute values (AttValue).
+
+#### Examples
+
+##### Creating an XML file from a template
+
+```puppet
+file { '/path/to/config.xml':
+  ensure  => file,
+  content => epp(
+    'mymodule/config.xml.epp',
+    {
+      password => $password.stdlib::xml_encode,
+    },
+  ),
+}
+```
+
+#### `stdlib::xml_encode(String $str, Optional[Enum['text','attr']] $type)`
+
+This function can encode strings such that they can be used directly in XML files.
+It supports encoding for both XML text (CharData) or attribute values (AttValue).
+
+Returns: `String` Returns the encoded CharData or AttValue string suitable for use in XML
+
+##### Examples
+
+###### Creating an XML file from a template
+
+```puppet
+file { '/path/to/config.xml':
+  ensure  => file,
+  content => epp(
+    'mymodule/config.xml.epp',
+    {
+      password => $password.stdlib::xml_encode,
+    },
+  ),
+}
+```
+
+##### `str`
+
+Data type: `String`
+
+The string to encode
+
+##### `type`
+
+Data type: `Optional[Enum['text','attr']]`
+
+Whether to encode for text or an attribute
+
 ### <a name="str2bool"></a>`str2bool`
 
 Type: Ruby 3.x API

lib/puppet/functions/stdlib/xml_encode.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# @summary Encode strings for XML files
+#
+# This function can encode strings such that they can be used directly in XML files.
+# It supports encoding for both XML text (CharData) or attribute values (AttValue).
+Puppet::Functions.create_function(:'stdlib::xml_encode') do
+  # @param str The string to encode
+  # @param type Whether to encode for text or an attribute
+  # @return Returns the encoded CharData or AttValue string suitable for use in XML
+  # @example Creating an XML file from a template
+  #   file { '/path/to/config.xml':
+  #     ensure  => file,
+  #     content => epp(
+  #       'mymodule/config.xml.epp',
+  #       {
+  #         password => $password.stdlib::xml_encode,
+  #       },
+  #     ),
+  #   }
+  dispatch :xml_encode do
+    param 'String', :str
+    optional_param "Enum['text','attr']", :type
+    return_type 'String'
+  end
+
+  def xml_encode(str, type = 'text')
+    str.encode(xml: type.to_sym)
+  end
+end

spec/functions/xml_encode_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'stdlib::xml_encode' do
+  let(:string) { 'this is "my" complicated <String>' }
+
+  it 'exists' do
+    is_expected.not_to be_nil
+  end
+
+  describe 'for XML text' do
+    let(:expected_result) { 'this is "my" complicated &lt;String&gt;' }
+
+    context 'with `type` parameter not explicity set' do
+      it { is_expected.to run.with_params(string).and_return(expected_result) }
+    end
+
+    context 'with `type` parameter set to `text`' do
+      it { is_expected.to run.with_params(string, 'text').and_return(expected_result) }
+    end
+  end
+
+  describe 'for XML attributes' do
+    it { is_expected.to run.with_params(string, 'attr').and_return('"this is &quot;my&quot; complicated &lt;String&gt;"') }
+  end
+end