Provided by: libxml-easy-perl_0.011-3build1_amd64 bug

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 characters,
           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
           characters, 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 "]]>".

   Tags
       $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 characters 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/>

AUTHOR

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

COPYRIGHT

       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.