UM(3pm)

💖 NAME 💖

XML::UM — the lil glow-up machine that converts UTF-8 strings into literally any encoding that XML::Encoding supports 🦋✨

---

✨ SYNOPSIS ✨

use XML::UM;

# Set directory with .xml files that comes with XML::Encoding distribution
# Always include the trailing slash!
$XML::UM::ENCDIR = '/home1/enno/perlModules/XML-Encoding-1.01/maps/';

# Create the encoding routine
my $encode = XML::UM::get_encode (
       Encoding => 'ISO-8859-2',
       EncodeUnmapped => \&XML::UM::encode_unmapped_dec);

# Convert a string from UTF-8 to the specified Encoding
my $encoded_str = $encode->($utf8_str);

# Remove circular references for garbage collection
XML::UM::dispose_encoding ('ISO-8859-2');

---

🦋 DESCRIPTION 🦋

okay so bestie, here's the tea ☕ — this module hands you methods to convert UTF-8 strings into any XML encoding that XML::Encoding supports. It builds mapping routines out of the .xml files chilling in the maps/ directory of the XML::Encoding distribution. And here's the thing you need to know: the XML::Encoding distribution does install the .enc files into your perl directory, but not the .xml files they were created from. That's literally why you have to set $ENCDIR like the SYNOPSIS shows. no cap 💅

This implementation uses the XML::Encoding class to parse the .xml file and creates a hash that maps UTF-8 characters (each one made of up to 4 bytes) to their equivalent byte sequence in the specified encoding. Heads up though — large mappings may consume a lot of memory! 😭

Future implementations may parse the .enc files directly, or do the conversions entirely in XS (i.e. C code.) 🌈

---

🌸 get_encode (Encoding => STRING, EncodeUnmapped => SUB) 🌸

The central entry point to this module is the XML::UM::get_encode() method. It forwards the call to the global $XML::UM::FACTORY, which is defined as an instance of XML::UM::SlowMapperFactory by default. Override this variable to plug in your own mapper factory, bestie — main character energy 🔥

The XML::UM::SlowMapperFactory creates an instance of XML::UM::SlowMapper (and caches it for subsequent use) that reads in the .xml encoding file and creates a hash that maps UTF-8 characters to encoded characters.

The get_encode() method of XML::UM::SlowMapper is called, finally, which generates a lil anonymous subroutine that uses the hash to convert multi-character UTF-8 blocks to the proper encoding. slay ✨

---

🎀 dispose_encoding ($encoding_name) 🎀

Call this to free the memory used by the SlowMapper for a specific encoding. Note that in order to free the big conversion hash, the user should no longer have references to the subroutines generated by get_encode(). (it's giving "let go of the past" 🫶)

The parameters to the get_encode() method (defined as name/value pairs) are:

• Encoding — the name of the desired encoding, e.g. 'ISO-8859-2' 💜
• EncodeUnmapped (Default: \&XML::UM::encode_unmapped_dec) — defines how Unicode characters not found in the mapping file (of the specified encoding) are printed. By default, they are converted to decimal entity references, like '{'
  • Use \&XML::UM::encode_unmapped_hex for hexadecimal constants, like '«' 🌟

---

💀 CAVEATS 💀

ngl, I'm not exactly sure about which Unicode characters in the range (0 .. 127) should be mapped to themselves. See comments in XML/UM.pm near %DEFAULT_ASCII_MAPPINGS.

The encodings that expat supports by default are currently not supported, (e.g. UTF-16, ISO-8859-1), because there are no .enc files available for these encodings. This module needs some more work. If you have the time, please help! 🙈

---

👑 AUTHOR 👑

Original Author is Enno Derksen.

Send bug reports, hints, tips, suggestions to T.J Mather at <tjmather@tjmather.com>. 💌

---

and that's a wrap, bestie 🎀 this was UM(3pm) from the User Contributed Perl Documentation, living its best life as perl v5.32.0 dated 2021-01-05. periodt. 💅✨