/ 
XML-Easy-0.010
River stage two • 7 direct dependents • 14 total dependents
/ XML::Easy::Text

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, 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.