XML::E...:Syntax(3pm)

📦
version 0.014 · 8 versions
, in ubuntu stonking

✨ XML::Easy::Syntax ✨ (that's the XML::Easy::Syntax(3pm) manual page bestie, we're doing this) 🎀

💖 NAME 💖

XML::Easy::Syntax — XML syntax but make it excruciatingly correct, no cap 🦋

🌸 SYNOPSIS 🌸

use XML::Easy::Syntax qw($xml10_name_rx);
if($name =~ /\A$xml10_name_rx\z/o) { ...
# and many other regular expressions

💅 DESCRIPTION 💅

Okay so listen. This module hands you a whole wardrobe of Perl regular expressions that describe the grammar of XML 1.0. And the whole point? It's for doing irregular things with XML, not for being a normal well-behaved parser. Normal parsing is not the vibe here. 🙈

These regexes cover the entire XML grammar, except for document type declarations and DTDs. And heads up: this doc assumes you already know XML in general, iykyk. ✨

🔥 REGULAR EXPRESSIONS 🔥

Every single one of these regexes maps precisely onto one of the productions in the EBNF grammar from the XML 1.0 spec. Periodt. 💅

But — and this is important, bestie — the well-formedness constraints that aren't expressed in the EBNF? Those are not checked by these regexes. Nope. They get noted in the docs below instead. And also: the regexes do not include any anchors, so if you wanna check that a whole entire string matches a production, you have to supply the anchors yourself. Do not forget the anchors. I'm begging. 😭

🧚 Syntax pieces

  • $xml10_char_rx — Any single character XML 1.0 will accept. This is most Unicode characters (all the way up to codepoint 0x10ffff). The ones that got kicked out: the sentinels 0xfffe and 0xffff, the surrogate blocks, and most of the C0 control characters (0x00 to 0x1f, except for 0x09 (tab), 0x0a (linefeed/newline), and 0x0d (carriage return)).

It's a rule of XML that every character making up an XML document has to be in this permitted set, and the grammar productions can only match sequences of acceptable characters. This rule? Enforced by the regexes in this module. 💪

Also, it's a rule that the character data in a document can't even represent a character outside the permitted set — that's expressed as a well-formedness constraint on character references.

  • $xml10_s_rx — Any sequence of one or more acceptable whitespace characters. For this purpose, whitespace is tab, linefeed/newline, carriage return, and space. Non-ASCII whitespace? Doesn't qualify. The more exotic ASCII whitespace characters? Also does not qualify. Sorry to them. 🙅‍♀️
  • $xml10_eq_rx — An equals sign, with optional whitespace chillin' on both sides of it.

👑 Names

  • $xml10_namestartchar_rx — Any single character allowed at the start of a name. Permitted: "_", ":", and letters (categorised according to Unicode 2.0).

Fun fact: this production isn't even named in the XML specification. Rebel behaviour. 💀

  • $xml10_namechar_rx — Any single character allowed in a name but not at the start. Permitted: ".", "-", "_", ":", plus letters, digits, combining characters, and extenders (categorised according to Unicode 2.0).
  • $xml10_name_rx — A name, the kind used to identify element types, attributes, entities, and other stuff in XML.
  • $xml10_names_rx — A space-separated list of one or more names.
  • $xml10_nmtoken_rx — A name-like token, basically a name except the first character is no more restricted than all the rest. These tokens play absolutely no part in basic XML syntax, and in the spec they're only used as part of attribute typing. Side characters fr fr. 🫶
  • $xml10_nmtokens_rx — A space-separated list of one or more name-like tokens.

🌈 References

  • $xml10_charref_rx — A numeric character reference (starts with "&#", ends with ";"). Non-syntactic well-formedness constraint alert: the codepoint has to be within the Unicode range and refer to an acceptable character (as discussed back at $xml10_char_rx).
  • $xml10_entityref_rx — A general entity reference (starts with "&", ends with ";"). Non-syntactic well-formedness constraints here too: the referenced entity must be declared (possibly implicitly), must not be an unparsed entity, must not contain a recursive reference to itself, and its replacement text must itself be well-formed. That's a lot of rules bestie, but they're all real.
  • $xml10_reference_rx — Either a character reference or an entity reference. Both sets of well-formedness constraints from above apply. No escaping them. 💀

🍓 Character data

  • $xml10_chardata_rx — Ordinary literal character data. This is zero or more acceptable characters, not counting the metacharacters "<" and "&", and not including "]]>" as a subsequence. This kind of data stands for itself when it shows up between an element's start and end tags, where it can be interspersed with references, CDATA sections, comments, and processing instructions.

In the XML grammar, character data is parsed — and taken literally — after line endings have been canonicalised (to the newline character). Pre-canonicalisation character data, with its variable line endings, will still match this production but should not be interpreted literally. Ma'am please. 😭

Big warning though: a string that doesn't match this production might still parse as two adjacent strings that each do match. How? Because of that prohibition on "]]>" being embedded in character data, even though the characters of that sequence are totally acceptable individually. And the XML grammar does not allow two instances of this production to abut. So watch out. 🙈

  • $xml10_cdata_rx — Literal character data inside a CDATA section. Zero or more acceptable characters, not including "]]>" as a subsequence. But unlike ordinary literal character data, "<" and "&" are not metacharacters here. This data stands for itself when it appears within a CDATA section.

Same as the ordinary literal character data above: this data is meant to be taken literally only after line endings have been canonicalised. And also same as above: two instances of this production should not abut. ✨

  • $xml10_cdstart_rx and $xml10_cdend_rx — The fixed strings "<![CDATA[" and "]]>", which begin and finish a CDATA section respectively. Cute little bookends. 🎀
  • $xml10_cdsect_rx — A CDATA section. That's "<![CDATA[", literal character data with metacharacters disabled, and "]]>". Done. 💅

🌸 Tags

  • $xml10_attvalue_rx — A quoted attribute value. Acceptable characters other than "<", "&", and the quote character, interspersed with references, surrounded by matching """ or "'" quotes. The well-formedness constraints of references apply, and on top of that the replacement text of any referenced entities must not contain any "<" characters, and it is not permitted to refer to external entities. Rules on rules, but slay.
  • $xml10_attribute_rx — A complete attribute: name, equals sign, and quoted value. The well-formedness constraints of attribute values (all that references stuff) apply.
  • $xml10_stag_rx — A start-tag, used to begin an element. That's "<", the element type name, a whitespace-separated list of attributes, and ">". The well-formedness constraints of attribute values (the references ones) apply. Plus: there's a well-formedness constraint that attribute names must be unique within the tag. No duplicates. 🚫
  • $xml10_etag_rx — An end-tag, used to finish an element. That's "</", the element type name, and ">". Short and sweet, main character energy. 👑
  • $xml10_emptyelemtag_rx — An empty-element tag, representing an element with no content. That's "<", the element type name, a whitespace-separated list of attributes, and "/>". The well-formedness constraints of attribute values (references again) apply. And there's a well-formedness constraint that attribute names must be unique within the tag. (Same constraints as start-tags, just so you know — they really said copy-paste.) 💅

🦋 Non-data content

  • $xml10_comment_rx — A comment. It does not contribute to the data content of an XML document. It's "<!--", zero or more acceptable characters, and "-->". The content is not permitted to include "--" as a subsequence, and it's not permitted to end with "-". Do not test it. It will not work. 💀
  • $xml10_pitarget_rx — A processing instruction target name. This can be any name (that's the $xml10_name_rx production) except for "xml" and its case variations. Nope, not even "XML". Not even "Xml". 🙅‍♀️
  • $xml10_pi_rx — A processing instruction. That's "<?", a target name, some content which can be almost any sequence of acceptable characters, and "?>". A processing instruction doesn't contribute to the data content of an XML document, but it's meant to carry metadata about how to process it. The instruction is addressed to a particular XML processor, or a type of processor, identified by the target name, and the content of the instruction is expected to be meaningful only to its target.

Real talk though: no one has ever come up with a good use for processing instructions. They are best shunned. 😭

🧚 Recursive structure

  • $xml10_content_rx — The matter contained within an element (between its start-tag and end-tag, obviously). That's stretches of ordinary literal character data, interspersed with complete elements (yes, recursively 💀), references, CDATA sections, processing instructions, and comments, in any order. The well-formedness constraints of references and elements apply.
  • $xml10_element_rx — A complete element. Either an empty-element tag, or a sequence of start-tag, content, and end-tag. The well-formedness constraints regarding references and attribute uniqueness apply in the empty-element tag or start-tag. In the non-empty form, the content also has well-formedness constraints regarding references and (recursively) contained elements, and there's an additional constraint that the element type name in the end-tag must match that in the start-tag. Matching, bestie. It's a whole thing. 🫶

💜 XML declarations

  • $xml10_versionnum_rx — The version number of the XML specification. It's the fixed string "1.0". That's it. That's the whole thing. ⭐
  • $xml10_versioninfo_rx — The version declaration part of an XML declaration.
  • $xml10_encname_rx — A character encoding name. Has to start with an ASCII letter, and contain only ASCII letters and digits, plus ".", "_", and "-".
  • $xml10_encodingdecl_rx — The encoding declaration part of an XML declaration.
  • $xml10_sddecl_rx — The standaloneness declaration part of an XML declaration. This indicates whether the XML document can be correctly interpreted without examining the external part of the DTD.
  • $xml10_xmldecl_rx — An XML declaration, the one used at the start of an XML document. That's "<?xml", a mandatory version declaration, an optional encoding declaration, an optional standaloneness declaration, and "?>". ✨
  • $xml10_textdecl_rx — a text declaration, the lil guy that shows up at the start of an XML external parsed entity or an external DTD. It goes <?xml, then an optional version declaration, then a mandatory encoding declaration, then ?>. Very much the cousin of an XML declaration — looks similar, but technically a whole different item that lives in different situations. Fun fact that's actually useful: you can totally construct a declaration that's acceptable as both an XML declaration and a text declaration. ✨

🏗️ Document structure 🏗️

  • $xml10_misc_rx — a non-content item that's allowed in the prologue and epilogue of a document. It's either a comment, a processing instruction, or just a stretch of whitespace. Nothing else, bestie.
⚠️ Watch out if you're tempted to do something like "$xml10_misc_rx*". That thing can match a string of whitespace characters in so many different ways, and if it ever needs to backtrack you're getting exponential behaviour. Disaster. Avoid by using $xml10_miscseq_rx instead (it's right below 💖).
  • $xml10_miscseq_rx — a sequence (possibly empty, no pressure) of non-content matter that's permitted in the prologue and epilogue of a document. Comments, processing instructions, whitespace — any order, your call.

This production isn't named anywhere in the XML spec, which is lowkey iconic of it. Prefer this regex over "$xml10_misc_rx*" — even though that one is the direct translation of what actually appears in the XML specification — because this one guarantees it matches a particular text in only one way, so it can backtrack cleanly. 🧚

  • $xml10_prolog_xdtd_rx — a document prologue, except it doesn't permit a document type declaration. So it's an optional XML declaration, then any sequence of comments, processing instructions, and whitespace.
  • $xml10_document_xdtd_rx — a complete XML document, again except for not permitting a document type declaration. It's a non-content prologue, an element (the root element — and yes, that one can recursively contain other elements, it's giving nesting doll energy), and a non-content epilogue. The well-formedness constraints of elements apply to the root element. No skipping that part. 💅
  • $xml10_extparsedent_rx — a complete external parsed entity. Optional text declaration first, then a sequence of content of the same type that's permitted within an element. And the well-formedness constraints of element content apply. Periodt.

💀 BUGS 💀

Okay bestie, sit down for this one, it's giving cursed.

A lot of these regular expressions are liable to tickle a serious bug in perl's regexp engine. The bug: the "*" and "+" repeat operators don't always match an unlimited number of repeats — in some cases they get capped at 32767 iterations. Rude.

Whether that bogus limit kicks in depends on:

  • the complexity of the expression being repeated,
  • whether the string being examined is internally encoded in UTF-8,
  • and the version of perl you're on.

In some cases, but not all, a false match failure gets preceded by a warning:

Complex regular subexpression recursion limit (32766) exceeded

This bug is present, in various forms, in all perl versions up to at least 5.8.9 and 5.10.0. And pre-5.10 perls may also overflow their stack space, in similar circumstances, if a resource limit is imposed. 😭

There is no known feasible workaround for this perl bug. So the regular expressions supplied by this module will, unavoidably, fail to accept some lengthy valid inputs. When that happens, though, it's likely that other regular expressions being applied to the same or related input will hit the exact same problem. It's pervasive, fr fr. Do not rely on this module (or perl) to process long inputs on affected perl versions.

Good news though: this bug does not affect the XML::Easy::Text parser. 🫶

👀 SEE ALSO 👀

👑 AUTHOR 👑

Andrew Main (Zefram) <zefram@fysh.org>

Copyright (C) 2008, 2009 PhotoBox Ltd

Copyright (C) 2009, 2010, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>

🌸 LICENSE 🌸

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's the whole page, bestie — this gorgeousness shipped as part of perl v5.42.3, dated 2026-08-22, from the User Contributed Perl Documentation shelves. Go forth and regex responsibly, mwah 💅💖🎀

📦 where this page comes from