NAME
File::Raw::XML::Reader - one event at a time, at a flat cost
SYNOPSIS
use File::Raw::XML qw(:const);
use File::Raw::XML::Reader;
my $r = File::Raw::XML::Reader->new(profile => 'full');
$r->feed($bytes); # any number of times
$r->feed('', 1); # eof
while (my $kind = $r->next) {
if ($kind == FRX_START && $r->local eq 'Record') {
my $doc = $r->subtree;
...
}
}
my $r = File::Raw::XML::Reader->from_file($path, profile => 'full');
while (defined(my $kind = $r->next)) { ... }DESCRIPTION
A pull reader over the same parser the codec uses. Bytes go in through feed, events come out through next, and the memory a reader holds is the memory of one record: what a token allocates is released when the end event of the record it belonged to has been consumed. A stream of a million records costs what one costs.
Every well-formedness constraint the codec enforces is enforced here, on the same offsets: a refusal dies from next, feed or subtree with the message the codec would give, the offset counted from the start of the stream.
A reader is not shareable across interpreter threads.
METHODS
new(%options)
The options of "OPTIONS" in File::Raw::XML, with two differences: id_attrs is accepted and ignored, because a reader builds no index, and max_token_bytes bounds the largest single token (a text run, a tag, a comment, a DOCTYPE with its subset) the reader will hold while waiting for its end. A token the input ends inside is retried whole when more bytes arrive, so that bound is what keeps the retry linear; the default is 16 MiB, and a text node larger than it cannot be streamed.
from_file($path, %options)
A reader that pulls from the file as next needs bytes, in chunks of 64 KiB. The file is opened at once and read as the events are asked for.
feed($bytes, $eof)
Bytes from the stream, in any sizes; a true $eof says these are the last, and an empty string with $eof ends a stream whose last bytes were already fed. Under profile => 'full' the first four bytes choose the encoding as they do for the codec, and every later feed is transcoded as it arrives; a feed may end inside a character.
next
The next event's kind: FRX_START, FRX_END, FRX_TEXT, FRX_COMMENT, FRX_PI or FRX_DOCTYPE, constants from File::Raw::XML's :const. Returns 0 when the reader needs more bytes and undef when the document has ended, so a loop over a socket feeds on 0 and stops on undef; a reader from from_file reads its own bytes and returns 0 only when the file is exhausted before the document is.
kind
The current event's kind, undef before the first event.
name, local, ns, prefix
Of the current start or end event's element: the name as written, its local part, its namespace name (empty when none) and its prefix (empty when none). For a processing instruction name and local are the target.
attrs, attr($local), attr_ns($ns, $local)
The current start event's attributes, as File::Raw::XML::Node reports them: attrs is an arrayref of [ns, prefix, local, value], attr finds one by local name in any namespace, attr_ns by namespace name and local name, undef for the namespace meaning any and the empty string meaning none. Namespace declarations are never attributes. Defaulted attributes from a DOCTYPE are present, as in the tree.
value
A text event's characters, a comment's body, a processing instruction's data. Adjacent character data and CDATA sections are one text event, as in the tree, except that text from an entity is its own event.
target
A processing instruction's target; undef for any other event.
entity
For a text event, the name of the entity the text came from, undef when it came from the document itself. This is the boundary the tree does not keep.
depth
The number of elements open at the current event, counting a start event's own element: the root's start and end events are at depth 1, a child's at depth 2. Text, comments and processing instructions report the depth of the element they are in, 0 outside the root.
offset
The byte offset the current event began at, counted from the start of the stream.
empty
True at a start event whose element was written <a/>: no end event follows it.
doctype
What "doctype" in File::Raw::XML::Document returns, once the DOCTYPE has been read; undef before it and for a document without one.
subtree
At a start event, the element and everything under it as a File::Raw::XML::Document of its own, independent of the reader: the namespace bindings in scope at the element are carried into it, so the document canonicalises as the element would in place. The document carries no ID index.
A reader fed by hand returns undef when the fed bytes ended inside the element; feed more and call subtree again, not next, until it returns the document. A reader from from_file reads its own bytes here as it does in next, so it never answers undef for want of them.
capturing
True between a subtree that returned undef and the one that returns the document.
done
True once next has returned undef.
SEE ALSO
File::Raw::XML, File::Raw::XML::Document, 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)