NAME¶
XML::Easy::Syntax - excruciatingly correct XML syntax
SYNOPSIS¶
use XML::Easy::Syntax qw($xml10_name_rx);
if($name =~ /\A$xml10_name_rx\z/o) { ...
# and many other regular expressions
DESCRIPTION¶
This module supplies Perl regular expressions describing the grammar of XML 1.0.
This is intended to support doing irregular things with XML, rather than for
normal parsing.
These regular expressions encompass the entire XML grammar except for document
type declarations and DTDs. This document assumes general familiarity with
XML.
REGULAR EXPRESSIONS¶
Each of these regular expressions corresponds precisely to one of the
productions in the EBNF grammar in the XML 1.0 specification. Well-formedness
constraints that are not expressed in the EBNF are
not checked by the
regular expressions; these are noted in the documentation below. The regular
expressions do not include any anchors, so to check whether an entire string
matches a production you must supply the anchors yourself.
Syntax pieces¶
- $xml10_char_rx
- Any single character that is acceptable to XML 1.0. This
includes most Unicode characters (up to codepoint 0x10ffff). The excluded
codepoints are 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 is a rule of XML that all characters making up an XML document must be in
this permitted set. The grammar productions can only match sequences of
acceptable characters. This rule is enforced by the regular expressions in
this module.
Furthermore, it is a rule that the character data in a document cannot even
represent a character outside the permitted set. This is expressed
as a well-formedness constraint on character references.
- $xml10_s_rx
- Any sequence of one or more acceptable whitespace
characters. The whitespace characters, for this purpose, are tab,
linefeed/newline, carriage return, and space. Non-ASCII whitespace
characters, and the more exotic ASCII whitespace characters, do not
qualify.
- $xml10_eq_rx
- Equals sign, surrounded by optional whitespace.
Names¶
- $xml10_namestartchar_rx
- Any single character that is permitted at the start of a
name. The permitted characters are " _",
":", and letters (categorised according to Unicode 2.0).
This production is not named in the XML specification.
- $xml10_namechar_rx
- Any single character that is permitted in a name other than
at the start. The permitted characters are " .",
"-", "_", ":", and
letters, digits, combining characters, and extenders (categorised
according to Unicode 2.0).
- $xml10_name_rx
- A name, of the type used to identify element types,
attributes, entities, and other things in XML.
- $xml10_names_rx
- A space-separated list of one or more names.
- $xml10_nmtoken_rx
- A name-like token, much like a name except that the first
character is no more restricted than the remaining characters. These
tokens play no part in basic XML syntax, and in the specification are only
used as part of attribute typing.
- $xml10_nmtokens_rx
- A space-separated list of one or more name-like
tokens.
References¶
- $xml10_charref_rx
- A numeric character reference (beginning with
"&#" and ending with " ;"). There is
a non-syntactic well-formedness constraint: the codepoint is required to
be within the Unicode range and to refer to an acceptable character (as
discussed at $xml10_char_rx).
- $xml10_entityref_rx
- A general entity reference (beginning with
"&" and ending with " ;"). There are
non-syntactic well-formedness constraints: 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.
- $xml10_reference_rx
- Either a character reference or an entity reference. The
well-formedness constraints of both reference types (see above)
apply.
Character data¶
- $xml10_chardata_rx
- Ordinary literal character data. This consists of zero or
more acceptable charaters, other than the metacharacters "
<" and " &", and not including "
]]>" as a subsequence. Such data stands for itself when it
appears between the start and end tags of an element, 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 variable line
endings, will still match this production but should not be interpreted
literally.
Beware that a string that does not match this production might parse as two
adjacent strings each of which matches. This can happen because of the
prohibition on " ]]>" being embedded in character
data, while the characters of that sequence are acceptable individually.
The XML grammar does not allow two instances of this production to
abut.
- $xml10_cdata_rx
- Literal character data in a CDATA section. This consists of
zero or more acceptable charaters, not including "
]]>" as a subsequence. Unlike ordinary literal character
data, the characters " <" and "
&" are not metacharacters here. Such data stands for
itself when it appears within a CDATA section.
As with ordinary literal character data (see above), this data is meant to
be taken literally only after line endings have been canonicalised. Also,
as with ordinary literal character data, two instances of this production
should not abut.
- $xml10_cdstart_rx
- $xml10_cdend_rx
- The fixed strings "<![CDATA[" and
" ]]>" which begin and finish a CDATA section.
- $xml10_cdsect_rx
- A CDATA section. This consists of
"<![CDATA[", literal character data with
metacharacters disabled, and " ]]>".
- $xml10_attvalue_rx
- A quoted attribute value. This consists of acceptable
characters other than " <", "&",
and the quote character, interspersed with references, surrounded by
matching " "" or "'" quotes. The
well-formedness constraints of references apply, and additionally the
replacement text of any referenced entities must not contain any "
<" characters, and it is not permitted to refer to external
entities.
- $xml10_attribute_rx
- A complete attribute, consisting of name, equals sign, and
quoted value. The well-formedness constraints of attribute values
(pertaining to references) apply.
- $xml10_stag_rx
- A start-tag, used to begin an element. This consists of
" <", the element type name, whitespace-separated list
of attributes, and " >". The well-formedness
constraints of attribute values (pertaining to references) apply. There is
also a well-formedness constraint that attribute names must be unique
within the tag.
- $xml10_etag_rx
- An end-tag, used to finish an element. This consists of
" </", the element type name, and "
>".
- $xml10_emptyelemtag_rx
- An empty-element tag, used to represent an element with no
content. This consists of " <", the element type name,
whitespace-separated list of attributes, and " />".
The well-formedness constraints of attribute values (pertaining to
references) apply. There is also a well-formedness constraint that
attribute names must be unique within the tag. (These are the same
constraints as for start-tags.)
Non-data content¶
- $xml10_comment_rx
- A comment. This does not contribute to the data content of
an XML document. It consists of " <!--", zero or more
acceptable characters, and " -->". It is not permitted
for the content to include " --" as a subsequence, nor
for it to end with " -".
- $xml10_pitarget_rx
- A processing instruction target name. This can be any name
(the $xml10_name_rx production) except for " xml" and its
case variations.
- $xml10_pi_rx
- A processing instruction. This consists of
"<?", a target name, some content which can be almost
any sequence of acceptable characters, and " ?>". A
processing instruction does not contribute to the data content of an XML
document, but is intended to carry metadata regarding how to process it.
The instruction is addressed to a particular XML processor, or type of
processor, identified by the target name, and the content of the
instruction is expected to be meaningful only to its target.
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). This consists of stretches of ordinary literal
character data, interspersed with complete elements (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. This is 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 is an additional constraint that the element
type name in the end-tag must match that in the start-tag.
XML declarations¶
- $xml10_versionnum_rx
- The version number of the XML specification. This is the
fixed string " 1.0".
- $xml10_versioninfo_rx
- The version declaration part of an XML declaration.
- $xml10_encname_rx
- A character encoding name. This must start with an ASCII
letter, and contain only ASCII letters and digits and "
.", " _", 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, as used at the start of an XML
document. This consists of " <?xml", mandatory version
declaration, optional encoding declaration, optional standaloneness
declaration, and " ?>".
- $xml10_textdecl_rx
- A text declaration, as used at the start of an XML external
parsed entity or external DTD. This consists of "
<?xml", optional version declaration, mandatory encoding
declaration, and " ?>". This is very similar to an XML
declaration, but technically a different item and used in different
situations. It is possible, and useful, to construct a declaration which
is acceptable both as an XML declaration and as a text declaration.
Document structure¶
- $xml10_misc_rx
- Non-content item permitted in the prologue and epilogue of
a document. This is either a comment, a processing instruction, or a
stretch of whitespace.
Beware in using a pattern such as "$xml10_misc_rx*". It could
match a string of whitespace charaters in many ways, leading to
exponential behaviour if it becomes necessary to backtrack. This can be
avoided by using the $xml10_miscseq_rx pattern (below).
- $xml10_miscseq_rx
- A sequence (possibly empty) of non-content matter permitted
in the prologue and epilogue of a document. This can contain comments,
processing instructions, and whitespace, in any order.
This production is not named in the XML specification. This regular
expression should be preferred over "$xml10_misc_rx*" (which is
the direct translation of what appears in the XML specification), because
this one guarantees to match a particular text in only one way, and is
thus able to backtrack cleanly.
- $xml10_prolog_xdtd_rx
- Document prologue, except for not permitting a document
type declaration. This consists of an optional XML declaration followed by
any sequence of comments, processing instructions, and whitespace.
- $xml10_document_xdtd_rx
- A complete XML document, except for not permitting a
document type declaration. This consists of a non-content prologue, an
element (the root element, which can recursively contain other elements),
and a non-content epilogue. The well-formedness constraints of elements
apply to the root element.
- $xml10_extparsedent_rx
- A complete external parsed entity. This consists of an
optional text declaration followed by a sequence of content of the same
type that is permitted within an element. The well-formedness constraints
of element content apply.
BUGS¶
Many of these regular expressions are liable to tickle a serious bug in perl's
regexp engine. The bug is that the "*" and "+" repeat
operators don't always match an unlimited number of repeats: in some cases
they are limited to 32767 iterations. Whether this bogus limit applies 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. In some
cases, but not all, a false match failure is 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. 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. The regular expressions
supplied by this module will therefore, unavoidably, fail to accept some
lengthy valid inputs. Where this occurs, though, it is likely that other
regular expressions being applied to the same or related input will also
suffer the same problem. It is pervasive. Do not rely on this module (or perl)
to process long inputs on affected perl versions.
This bug does not affect the XML::Easy::Text parser.
SEE ALSO¶
XML::Easy::Text,
http://www.w3.org/TR/REC-xml/
<
http://www.w3.org/TR/REC-xml/>
AUTHOR¶
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT¶
Copyright (C) 2008, 2009 PhotoBox Ltd
Copyright (C) 2009, 2010, 2011 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.