/ 
File-Raw-XML-0.04
/ File::Raw::XML::Document

NAME

File::Raw::XML::Document - a parsed XML document

SYNOPSIS

my $doc  = file_xml_decode($bytes, id_attrs => ['ID']);
my $root = $doc->root;
my $node = $doc->by_id(ID => $value);

DESCRIPTION

What "file_xml_decode" in File::Raw::XML and the xml plugin return. The document owns the tree, and every node handed out keeps the document alive for as long as the node exists; there is nothing the caller has to do about lifetime.

A document is read-only. It is not shareable across interpreter threads: a cloned copy answers every method with an error naming the class.

METHODS

root

The root element, a File::Raw::XML::Node.

document

The document node, whose children are the top-level comments and processing instructions with the root element among them. This is the apex for a whole-document canonicalisation.

by_id($attr => $value)

The one element whose attribute named $attr - by local name, in any namespace - carries $value, or undef. Only the attribute names given in id_attrs at parse time are indexed, and two elements sharing a value were refused at parse time, so this cannot be steered to a second element.

c14n(%options)

The canonical form of the whole document, with the top-level comments and processing instructions rendered under the document-level rules. The options are those of "c14n" in File::Raw::XML::Node.

to_string(%options)

my $bytes = $doc->to_string(indent => 2);
my $chars = $doc->to_string(encoding => 'perl');

The document as markup: bytes with no character flag, in the encoding asked for, with the XML declaration and the recorded DOCTYPE by default. The options:

  • declaration - write the XML declaration; on for a document, off for a node.

  • encoding - UTF-8, the default; UTF-16 or UTF-16LE and UTF-16BE, with a byte order mark; ISO-8859-1; US-ASCII. A character the encoding cannot hold becomes a hexadecimal character reference in text and attribute values, and is an error in a comment, a processing instruction or a name, where no reference can stand. The one exception is perl, which returns a character string, for the caller about to print to a handle with a layer, and whose declaration names no encoding; file_spew refuses it, since a file takes bytes.

  • indent - spaces per level, 0 for none. Indentation never touches text: an element holding text that is not whitespace, or named in preserve, or under xml:space="preserve", is written as it is, and so is one holding whitespace-only text unless drop_ws is set.

  • preserve - an arrayref of element local names written as they are, whatever indent says.

  • drop_ws - drop whitespace-only text under an indented element so its children can be laid out. Off by default: it is the one option that changes the document.

  • empty_short - <a/> for an element with no children, the default; off writes <a></a>.

  • quote - the attribute quote, " by default or '; the chosen quote is escaped inside values, the other is not.

  • escape_all - escape " and ' in text as well as &, < and >.

  • doctype - write the recorded DOCTYPE back, with its identifiers and its internal subset as written; on for a document.

Entity references were resolved when the document was parsed and are not written back: the text is the replacement text, and an internal subset that declares an entity the text no longer uses is still well-formed. CDATA sections are written where they were read. A text node's characters are written as they are, so a carriage return that arrived as a character reference leaves as one.

equals($other)

True when the two documents are equal as data: the same elements by namespace name and local name with the same attributes as an unordered set of namespace, local name and value, the same text, comments and processing instructions, the same children in the same order. Prefixes, CDATA boundaries, which attributes were defaulted, and offsets do not count. Parsing what to_string wrote gives a document equal to this one.

version

The XML version the document declared, 1.0 when it declared none.

standalone

True when the XML declaration said standalone="yes", false otherwise.

doctype

undef when the document has no document type declaration. Otherwise a hashref with name, the document type name; public_id and system_id, each undef when the declaration gave none; and internal_subset, the text between the brackets as written, undef when there were no brackets and the empty string when they were empty. Only a parse under profile => 'full' reads a document type declaration; the default profile refuses every one.

What the internal subset declared has already been applied to the tree: attribute defaults are present on every element that lacked them, attribute values are normalised by their declared type, and internal entity references have been replaced by their text. There is no entity reference node.

BUILDING

A document made by "new_document" in File::Raw::XML starts with only its document node; a parsed document can be edited the same way. Nodes are made here, detached, and put in place with the methods of "EDITING" in File::Raw::XML::Node.

new_element($ns, $name)

A new, detached element in the namespace $ns (the empty string or undef for none) named $name, which may be prefix:local; a prefix needs a namespace. When it is appended, a declaration for its prefix is added where one is needed.

new_text($text), new_comment($text), new_pi($target, $data)

New, detached nodes of those kinds. A comment may not contain --, a processing instruction may not contain ?> or be targeted at xml.

import_node($node), import($node)

A detached deep copy, in this document, of a node from another document, with the namespace bindings in scope at its source declared on the copy's root so it means the same wherever it is appended. The source document is untouched, and the copy outlives it.

import is the same call under the name the family reads. Perl calls import on the class itself for every use of it, so that call, which carries no document and no node, is answered with nothing.

xpath($expression, %options)

my @items = $doc->xpath('//item');
my $n     = $doc->xpath('count(//item)');

"xpath" in File::Raw::XML::Node with the document node as the context node, which is the context an absolute expression starts from anyway.

errors

The validity constraints this document breaks, in document order, each a message naming the constraint and the byte offset it was found at. Empty unless the document was parsed with validate => 'collect', which is the one mode that gathers them rather than dying at the first; with validate => 1 a violation is a refusal and there is no document to ask.

my $doc = file_xml_decode($bytes, profile => 'full', validate => 'collect');
warn "$_\n" for $doc->errors;

SEE ALSO

File::Raw::XML, File::Raw::XML::Node.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)