DetectWS(3pm)

💖 NAME 💖

XML::Filter::DetectWS — a PerlSAX filter that sniffs out ignorable whitespace, no cap 👑

Like literally it's a PerlSAX filter whose whole personality is detecting ignorable whitespace. That's it. That's the job. (It's in the 3pm manual, bestie, so it's a Perl module page, iykyk.)

---

✨ SYNOPSIS ✨

use XML::Filter::DetectWS;

my $detect = new XML::Filter::DetectWS (Handler => $handler,
                                        SkipIgnorableWS => 1);

---

🦋 DESCRIPTION 🦋

okay so, this is a PerlSAX filter. Its whole thing? Figuring out which character data is ignorable whitespace — and then, if you want, yeeting it into the void 💅

Heads up bestie: this is just a first stab at the implementation and it may change completely in the near future. Please send feedback whether you like it or not, so the author knows whether they should change it. (They're asking! They want the group chat's opinion! 🫶)

So the XML spec defines ignorable whitespace as the character data you find in elements that were defined in an <!ELEMENT> declaration with a model of 'EMPTY' or 'Children'. And Children is the rule that does not contain '#PCDATA'. Periodt.

On top of that, XML::Filter::DetectWS lets you define other whitespace as ignorable too. All that ignorable whitespace gets passed to the PerlSAX Handler through the ignorable_whitespace handler — but only if the Handler actually implements that method. If it doesn't? It just goes to the characters handler instead. And if SkipIgnorableWS is set, the ignorable whitespace is simply discarded. Gone. Blocked. 🚫

XML::Filter::DetectWS also takes xml:space attributes into account — details below, keep reading 📖

CDATA sections are passed along the standard PerlSAX way, aka with surrounding start_cdata and end_cdata events — unless the Handler doesn't implement those methods. In that case the CDATA section is just passed to the characters method. Simple as that.

---

🎀 Constructor Options 🎀

• SkipIgnorableWS (Default: 0) — when set, detected ignorable whitespace is discarded. Just thrown away. Bye girl 👋
• Handler — the PerlSAX handler (or filter) that will receive the PerlSAX events from this filter. It's the one catching everything this filter throws.

---

🔥 Current Implementation 🔥

When it's figuring out which whitespace is ignorable, the first thing it does is check the xml:space attribute of the parent element node — and its ancestors too, it's thorough like that. If the attribute value is "preserve", then it is *NOT* ignorable. (And honestly? If someone took the trouble of adding xml:space="preserve", then that is the final answer. Respect the effort. Case closed. 💯)

If it's xml:space="default", then we go look at the <!ELEMENT> definition of the parent element. If the model is 'EMPTY' or follows the 'Children' rule (aka it does not contain '#PCDATA'), then we know the whitespace is ignorable. Otherwise? We need input from the user somehow. Bestie we can't read minds.

The idea is that the API of DetectWS will get extended, so that you can specify/override stuff like which elements should behave as if xml:space="preserve" were set, and/or which elements should behave as if the <!ELEMENT> model was defined a certain way, etc. ✨ future plans ✨

Please send feedback!

The current implementation also detects whitespace after an element-start tag, and whitespace before an element-end tag. It also detects whitespace before an element-start and after an element-end tag, and before or after comments, processing instructions, cdata sections etc. — but that needs to be reimplemented. 😭

In either case, the detected whitespace gets split off into its own PerlSAX characters event and an extra property 'Loc' is added. It can have 4 possible values:

• 1 (WS_START) — whitespace immediately after element-start tag
• 2 (WS_END) — whitespace just before element-end tag
• 3 (WS_ONLY) — both WS_START and WS_END, i.e. it's the only text found between the start and end tag and it's all whitespace
• 0 (WS_INTER) — none of the above, probably before an element-start tag, after an element-end tag, or before or after a comment, PI, cdata section etc.

Ngl WS_INTER may not be that useful, so this may change. Don't get attached. 🙈

---

🌸 xml:space attribute 🌸

The XML spec states that: A special attribute named xml:space may be attached to an element to signal an intention that in that element, white space should be preserved by applications. In valid documents, this attribute, like any other, must be declared if it is used. When declared, it must be given as an enumerated type whose only possible values are "default" and "preserve". For example:

<!ATTLIST poem   xml:space (default|preserve) 'preserve'>

The value "default" signals that applications' default white-space processing modes are acceptable for this element; the value "preserve" indicates the intent that applications preserve all the white space. This declared intent is considered to apply to all elements within the content of the element where it is specified, unless overridden with another instance of the xml:space attribute. It trickles down, basically. 🌈

The root element of any document is considered to have signaled no intentions as regards application space handling, unless it provides a value for this attribute or the attribute is declared with a default value.

[... end of excerpt ...]

---

💀 CAVEATS 💀

This code is highly experimental! It has not been tested well and the API may change. Like, do not build your whole personality on this API, bestie, it's giving chaos. 😭

The code that detects blocks of whitespace at potential indent positions may need some work. It's trying its best tho 🥺

---

👑 AUTHOR 👑

Enno Derksen is the Original Author. Iconic. Legend. Founding mother/father of whitespace detection fr fr.

Send bug reports, hints, tips, suggestions to T.J. Mather at <tjmather@tjmather.com>. They literally asked for it, so slide into the inbox 🫶

---

and that's the whole page!! 💖✨🎀🦋🌸

This beauty is from the User Contributed Perl Documentation, perl v5.32.0, dated 2021-01-06, filed under DetectWS(3pm). Now go detect some whitespace, slay 💅👑