.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::Easy::Text 3pm"
.TH XML::Easy::Text 3pm 2024-03-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
XML::Easy::Text \- XML parsing and serialisation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&    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");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module supplies functions that parse and serialise XML data
according to the XML 1.0 specification.
.PP
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.
.PP
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.
.PP
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.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
All functions \f(CW\*(C`die\*(C'\fR on error.
.SS Parsing
.IX Subsection "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.
.PP
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 \f(CW\*(C`decode\*(C'\fR function in the Encode module.
.IP xml10_read_content_object(TEXT) 4
.IX Item "xml10_read_content_object(TEXT)"
\&\fITEXT\fR must be a character string.  It is parsed against the \fBcontent\fR
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.
.Sp
Normally one would not want to use this function directly, but prefer the
higher-level \f(CW\*(C`xml10_read_document\*(C'\fR function.  This function exists for
the construction of custom XML parsers in situations that don't match
the full XML grammar.
.IP xml10_read_content_twine(TEXT) 4
.IX Item "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.
.Sp
The returned array must not be subsequently modified.  If possible,
it will be marked as read-only in order to prevent modification.
.IP xml10_read_content(TEXT) 4
.IX Item "xml10_read_content(TEXT)"
Deprecated alias for "xml10_read_content_twine".
.IP xml10_read_element(TEXT) 4
.IX Item "xml10_read_element(TEXT)"
\&\fITEXT\fR must be a character string.  It is parsed against the \fBelement\fR
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.
.Sp
Normally one would not want to use this function directly, but prefer the
higher-level \f(CW\*(C`xml10_read_document\*(C'\fR function.  This function exists for
the construction of custom XML parsers in situations that don't match
the full XML grammar.
.IP xml10_read_document(TEXT) 4
.IX Item "xml10_read_document(TEXT)"
\&\fITEXT\fR must be a character string.  It is parsed against the \fBdocument\fR
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 \fInot\fR 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.
.Sp
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.
.IP xml10_read_extparsedent_object(TEXT) 4
.IX Item "xml10_read_extparsedent_object(TEXT)"
\&\fITEXT\fR must be a character string.  It is parsed against the
\&\fBextParsedEnt\fR 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.
.Sp
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 \f(CW\*(C`xml10_read_document\*(C'\fR function.
.IP xml10_read_extparsedent_twine(TEXT) 4
.IX Item "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.
.Sp
The returned array must not be subsequently modified.  If possible,
it will be marked as read-only in order to prevent modification.
.IP xml10_read_extparsedent(TEXT) 4
.IX Item "xml10_read_extparsedent(TEXT)"
Deprecated alias for "xml10_read_extparsedent_twine".
.SS Serialisation
.IX Subsection "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.
.PP
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 \f(CW\*(C`encode\*(C'\fR
function in the Encode module.
.IP xml10_write_content(CONTENT) 4
.IX Item "xml10_write_content(CONTENT)"
\&\fICONTENT\fR 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.
.IP xml10_write_element(ELEMENT) 4
.IX Item "xml10_write_element(ELEMENT)"
\&\fIELEMENT\fR must be a reference to an XML::Easy::Element object.
The XML 1.0 textual representation of that element is returned.
.IP "xml10_write_document(ELEMENT[, ENCODING])" 4
.IX Item "xml10_write_document(ELEMENT[, ENCODING])"
\&\fIELEMENT\fR 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 \fIENCODING\fR 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.)
.IP "xml10_write_extparsedent(CONTENT[, ENCODING])" 4
.IX Item "xml10_write_extparsedent(CONTENT[, ENCODING])"
\&\fICONTENT\fR 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 \fIENCODING\fR 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.)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::Easy::NodeBasics,
XML::Easy::Syntax,
<http://www.w3.org/TR/REC\-xml/>
.SH AUTHOR
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2008, 2009 PhotoBox Ltd
.PP
Copyright (C) 2009, 2010, 2011, 2017
Andrew Main (Zefram) <zefram@fysh.org>
.SH LICENSE
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.