NAME

Text::KDL::XS::Document - A parsed KDL document: the list of top-level nodes

SYNOPSIS

use Text::KDL::XS qw(parse_kdl emit_kdl);

my $doc = parse_kdl($text);

for my $node (@{ $doc->nodes }) {          # Text::KDL::XS::Node objects
    print $node->name, "\n";
}

my ($server) = grep { $_->name eq 'server' } @{ $doc->nodes };

my $plain = $doc->as_data;                 # arrayref of plain hashes
print emit_kdl($doc);                      # back to KDL text

# Build one by hand from Text::KDL::XS::Node objects:
my $new = Text::KDL::XS::Document->new(nodes => [ $node, Text::KDL::XS::Node->new(name => 'extra') ]);

DESCRIPTION

A Text::KDL::XS::Document is what "parse_kdl" in Text::KDL::XS returns. It is a thin container: an ordered list of the document's top-level Text::KDL::XS::Node objects. Everything else (arguments, properties, children) hangs off the nodes.

Objects are plain blessed hashes and are meant to be modified in place: push nodes onto $doc->nodes, splice them out, reorder them, then pass the document to "emit_kdl" in Text::KDL::XS.

Comments and elements commented out with a slashdash (/-) are never part of a document, whatever options the parser was given.

CONSTRUCTOR

new

my $doc = Text::KDL::XS::Document->new;
my $doc = Text::KDL::XS::Document->new(nodes => \@nodes);

Creates a document holding the given Text::KDL::XS::Node objects, or an empty one. The array reference is stored as is, not copied. nodes must be an array reference (Text::KDL::XS::Document->new: 'nodes' must be an ARRAY reference); any other field, or an odd number of arguments, dies. new may be called on a subclass.

METHODS

nodes

my $nodes = $doc->nodes;   # arrayref of Text::KDL::XS::Node, in document order

The top-level nodes. Always an array reference, empty for an empty document. It is the document's own array, so modifying it modifies the document.

as_data

my $data = $doc->as_data;  # [ { name => ..., args => [...], ... }, ... ]

Returns the whole document as plain Perl data: an array reference with one hash per top-level node, in the shape described in "as_data" in Text::KDL::XS::Node. This is convenient for dumping, comparing in tests, or converting to JSON, but it is lossy: value type annotations, number kinds, repeated properties and the boolean/number distinction are not represented. Use the node objects when those matter.

SEE ALSO

Text::KDL::XS, Text::KDL::XS::Node, Text::KDL::XS::Value.

AUTHOR

Davenonymous <perl@davenonymous.com>

LICENSE

Copyright (C) 2026 Davenonymous.

This Perl distribution is licensed under the same terms as Perl itself.