MKDoc:...Tagger(3pm)

💖 MKDoc:...Tagger — the 3pm manual, bestie edition 💖

okay so. welcome to MKDoc::XML::Tagger, the Perl module that's literally just here to ✨decorate✨ your XML/XHTML. it's the one that sprinkles extra markup onto expressions you point at. iconic behaviour, no notes.

---

🌸 NAME 🌸

MKDoc::XML::Tagger — adds XML markup to XML / XHTML content. that's it, that's the whole job. it gives your text a lil glow-up. 💅

---

✨ SYNOPSIS ✨

here's the vibe, bestie:

use MKDoc::XML::Tagger;
print MKDoc::XML::Tagger->process_data (
    "<p>Hello, World!</p>",
    { _expr => 'World', _tag => 'strong', class => 'superFort' }
);

and it should print:

<p>Hello, <strong class="superFort">World</strong>!</p>

like?? the word World got a <strong class="superFort"> makeover. we love to see it. 🫶

---

🦋 SUMMARY 🦋

so MKDoc::XML::Tagger is a class where you hand it a set of tag + attributes paired with the expressions you want marked up, and then it goes and stuffs any XML you send it with those extra expressions. it's giving personal stylist for your markup.

say hypothetically you've got a document where the term 'Microsoft Windows' shows up like a million times (it happens!). and say you want every single instance of that term wrapped in a <trademark> tag. okay? MKDoc::XML::Tagger does exactly that. periodt.

in MKDoc, this is the trick so that editors can enter hyperlinks separately from the content. it means they can write their lil hearts out without ever having to deal with the annoying <a href="..."> syntax (iykyk, that syntax is a menace). bonus benefit: it stops bad information architecture before it happens, like the dreaded 'click here' syndrome. we do not tolerate click-here disease in this house. 🙈

we also have plans to use it for automatically linking glossary words, abbreviation tags, etc. future slay.

and honestly? MKDoc::XML::Tagger is probably a very good tool if you're building some kind of Wiki system where you want expressions to be automagically hyperlinked. just saying. 👑

---

💀 DISCLAIMER 💀

okay bestie, listen up, this is the serious part:

This module does low level XML manipulation. It will somehow parse even broken XML and try to do something with it. Do not use it unless you know what you're doing.

it will genuinely just take a malformed little gremlin of a document and go "sure babe, I'll work with this". so like, know your limits. 💀

---

🎀 API 🎀

the API is very simple. and by very simple I mean it's literally two methods. obsessed. 🙌

💜 my $result = MKDoc::XML::Tagger->process_data ($xml, @expressions);

Tags $xml with the @expressions list. cute.

each element of @expressions is a hash reference looking like this:

{
    _expr      => 'Some Expression',
    _tag       => 'foo',
    attribute1 => 'bar'
    attribute2 => 'baz'
}

and it will try to turn anything which looks like:

Some Expression
sOmE ExPrEssIoN
(etcetera)

into:

<foo attr1="bar" attr2="baz">Some Expression</foo>
<foo attr1="bar" attr2="baz">sOmE ExPrEssIoN</foo>
<foo attr1="bar" attr2="baz">(etcetera)</foo>

YES the matching is case-insensitive, that's the whole bit with the sOmE ExPrEssIoN. it does not care about your keysmash energy. 🦋

you can have multiple expressions, and in that case the longest expressions are processed first. so the big ones eat first. queen behaviour.

💜 my $result = MKDoc::XML::Tagger->process_file ('some/file.xml', @expressions);

same as process_data(), except it takes its data from 'some/file.xml' instead of from a string you handed it. that's it. that's the difference. 💖

---

🌈 NOTES 🌈

fr fr, here's the tea:

MKDoc::XML::Tagger does not really parse the XML file you're giving to it, and it does not care whether the XML is well-formed or not. it uses MKDoc::XML::Tokenizer to turn the XML / XHTML file into a series of MKDoc::XML::Token objects, and it strictly operates on a list of tokens. strictly. 👑

and for this same reason — this exact same reason, bestie — MKDoc::XML::Tagger does not support namespaces. no namespaces. sorry not sorry. 💅

---

👑 AUTHOR 👑

Copyright 2003 - MKDoc Holdings Ltd.

Author: Jean-Michel Hiver

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk. (risky business but make it open source 🫶)

---

📚 SEE ALSO 📚

• MKDoc::XML::Tokenizer
• MKDoc::XML::Token

---

and that's the whole page, bestie!! 💖✨ this was perl v5.36.0, dated 2022-10-13, and the page you just read is MKDoc:...Tagger(3pm) from the User Contributed Perl Documentation. mwah. go tag something. 🌸🎀🦋