NAME

       XML::Easy::Text - XML parsing and serialisation

SYNOPSIS

               use XML::Easy::Text qw(
                       xml10_read_content_object xml10_read_element
                       xml10_read_document xml10_read_extparsedent_object
               );

               $content = xml10_read_content_object($text);
               $element = xml10_read_element($text);
               $element = xml10_read_document($text);
               $content = xml10_read_extparsedent_object($text);

               use XML::Easy::Text qw(
                       xml10_write_content xml10_write_element
                       xml10_write_document xml10_write_extparsedent
               );

               $text = xml10_write_content($content);
               $text = xml10_write_element($element);
               $text = xml10_write_document($element, "UTF-8");
               $text = xml10_write_extparsedent($content, "UTF-8");

DESCRIPTION

       This module supplies functions that parse and serialise XML data according to the XML 1.0
       specification.

       This module is oriented towards the use of XML to represent data for interchange purposes,
       rather than the use of XML as markup of principally textual data.  It does not perform any
       schema processing, and does not interpret DTDs or any other kind of schema.  It adheres
       strictly to the XML specification, in all its awkward details, except for the
       aforementioned DTDs.

       XML data in memory is represented using a tree of XML::Easy::Content and
       XML::Easy::Element objects.  Such a tree encapsulates all the structure and data content
       of an XML element or document, without any irrelevant detail resulting from the textual
       syntax.  These node trees are readily manipulated by the functions in
       XML::Easy::NodeBasics.

       The functions of this module are implemented in C for performance, with a pure Perl backup
       version (which has good performance compared to other pure Perl parsers) for systems that
       can't handle XS modules.

FUNCTIONS

       All functions "die" on error.

   Parsing
       These function take textual XML and extract the abstract XML content.  In the terminology
       of the XML specification, they constitute a non-validating processor: they check for well-
       formedness of the XML, but not for adherence of the content to any schema.

       The inputs (to be parsed) for these functions are always character strings.  XML text is
       frequently encoded using UTF-8, or some other Unicode encoding, so that it can contain
       characters from the full Unicode repertoire.  In that case, something must perform UTF-8
       decoding (or decoding of some other character encoding) to convert the octets of a file to
       the characters on which these functions operate.  A Perl I/O layer can do the job (see
       perlio), or it can be performed explicitly using the "decode" function in the Encode
       module.

       xml10_read_content_object(TEXT)
           TEXT must be a character string.  It is parsed against the content production of the
           XML 1.0 grammar; i.e., as a sequence of the kind of matter that can appear between the
           start-tag and end-tag of an element.  Returns a reference to an XML::Easy::Content
           object.

           Normally one would not want to use this function directly, but prefer the higher-level
           "xml10_read_document" function.  This function exists for the construction of custom
           XML parsers in situations that don't match the full XML grammar.

       xml10_read_content_twine(TEXT)
           Performs the same parsing job as "xml10_read_content_object", but returns the
           resulting content chunk in the form of twine (see "Twine" in XML::Easy::NodeBasics)
           rather than a content object.

           The returned array must not be subsequently modified.  If possible, it will be marked
           as read-only in order to prevent modification.

       xml10_read_content(TEXT)
           Deprecated alias for "xml10_read_content_twine".

       xml10_read_element(TEXT)
           TEXT must be a character string.  It is parsed against the element production of the
           XML 1.0 grammar; i.e., as an item bracketed by tags and containing content that may
           recursively include other elements.  Returns a reference to an XML::Easy::Element
           object.

           Normally one would not want to use this function directly, but prefer the higher-level
           "xml10_read_document" function.  This function exists for the construction of custom
           XML parsers in situations that don't match the full XML grammar.

       xml10_read_document(TEXT)
           TEXT must be a character string.  It is parsed against the document production of the
           XML 1.0 grammar; i.e., as a root element (possibly containing subelements) optionally
           preceded and followed by non-content matter, possibly headed by an XML declaration.
           (A document type declaration is not accepted; this module does not process schemata.)
           Returns a reference to an XML::Easy::Element object which represents the root element.
           Nothing is returned relating to the XML declaration or other non-content matter.

           This is the most likely function to use to process incoming XML data.  Beware that the
           encoding declaration in the XML declaration, if any, does not affect the
           interpretation of the input as a sequence of characters.

       xml10_read_extparsedent_object(TEXT)
           TEXT must be a character string.  It is parsed against the extParsedEnt production of
           the XML 1.0 grammar; i.e., as a sequence of content (containing character data and
           subelements), possibly headed by a text declaration (which is similar to, but not the
           same as, an XML declaration).  Returns a reference to an XML::Easy::Content object.

           This is a relatively obscure part of the XML grammar, used when a subpart of a
           document is stored in a separate file.  You're more likely to require the
           "xml10_read_document" function.

       xml10_read_extparsedent_twine(TEXT)
           Performs the same parsing job as "xml10_read_extparsedent_object", but returns the
           resulting content chunk in the form of twine (see "Twine" in XML::Easy::NodeBasics)
           rather than a content object.

           The returned array must not be subsequently modified.  If possible, it will be marked
           as read-only in order to prevent modification.

       xml10_read_extparsedent(TEXT)
           Deprecated alias for "xml10_read_extparsedent_twine".

   Serialisation
       These function take abstract XML data and serialise it as textual XML.  They do not
       perform indentation, default attribute suppression, or any other schema-dependent
       processing.

       The outputs of these functions are always character strings.  XML text is frequently
       encoded using UTF-8, or some other Unicode encoding, so that it can contain characters
       from the full Unicode repertoire.  In that case, something must perform UTF-8 encoding (or
       encoding of some other character encoding) to convert the characters generated by these
       functions to the octets of a file.  A Perl I/O layer can do the job (see perlio), or it
       can be performed explicitly using the "encode" function in the Encode module.

       xml10_write_content(CONTENT)
           CONTENT must be a reference to either an XML::Easy::Content object or a twine array
           (see "Twine" in XML::Easy::NodeBasics).  The XML 1.0 textual representation of that
           content is returned.

       xml10_write_element(ELEMENT)
           ELEMENT must be a reference to an XML::Easy::Element object.  The XML 1.0 textual
           representation of that element is returned.

       xml10_write_document(ELEMENT[, ENCODING])
           ELEMENT must be a reference to an XML::Easy::Element object.  The XML 1.0 textual form
           of a document with that element as the root element is returned.  The document
           includes an XML declaration.  If ENCODING is supplied, it must be a valid character
           encoding name, and the XML declaration specifies it in an encoding declaration.  (The
           returned string consists of unencoded characters regardless of the encoding
           specified.)

       xml10_write_extparsedent(CONTENT[, ENCODING])
           CONTENT must be a reference to either an XML::Easy::Content object or a twine array
           (see "Twine" in XML::Easy::NodeBasics).  The XML 1.0 textual form of an external
           parsed entity encapsulating that content is returned.  If ENCODING is supplied, it
           must be a valid character encoding name, and the returned entity includes a text
           declaration that specifies the encoding name in an encoding declaration.  (The
           returned string consists of unencoded characters regardless of the encoding
           specified.)

SEE ALSO

       XML::Easy::NodeBasics, XML::Easy::Syntax, <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.