/ 
Text-KDL-XS-0.002
/ Text::KDL::XS::Node

NAME

Text::KDL::XS::Node - A KDL node: name, type annotation, arguments, properties, children

SYNOPSIS

# From a parsed document:
my $node = $doc->nodes->[0];

$node->name;                    # 'server'
$node->type_annotation;         # 'primary' for (primary)server, else undef
$node->args;                    # [ Text::KDL::XS::Value, ... ]
$node->props;                   # [ [ 'port', Text::KDL::XS::Value ], ... ]
$node->prop('port');            # Text::KDL::XS::Value or undef
$node->children;                # [ Text::KDL::XS::Node, ... ]
$node->as_data;                 # plain hash, see below

# Built by hand:
my $node = Text::KDL::XS::Node->new(
    name            => 'server',
    type_annotation => 'primary',                       # optional
    args            => [ Text::KDL::XS::Value->new(type => 'string', value => 'web-1') ],
    props           => [ [ port => Text::KDL::XS::Value->new(type => 'number', kind => 'integer', value => 8080) ] ],
    children        => [ Text::KDL::XS::Node->new(name => 'tls') ],
);

DESCRIPTION

Each KDL node

(type)name arg1 arg2 key=value {
    child
}

is represented by one Text::KDL::XS::Node. The object is a blessed hash whose contents you may read and modify directly; the accessors below are the supported way to do so, but pushing onto @{ $node->args } or assigning to $node->{name} works and is used in the examples of Text::KDL::XS::Cookbook.

CONSTRUCTOR

new

my $node = Text::KDL::XS::Node->new(name => $name, %fields);

Fields (all optional except name, which must be defined):

name

The node name, a string. Any string is allowed; it is quoted on output if necessary.

type_annotation

The node's (type) annotation as a string, or undef (the default) for none.

args

Array reference of argument values, in order. Elements are normally Text::KDL::XS::Value objects. Plain scalars, undef and the objects listed under "Scalar coercion" in Text::KDL::XS are accepted as well and are converted by "emit_kdl" in Text::KDL::XS when the node is emitted; "as_data" returns them as they are. The Value methods are of course not available for such elements.

props

Array reference of [ $key, $value ] pairs, in order. The same rules for $value apply as for args.

children

Array reference of child Text::KDL::XS::Node objects.

The array references are stored, not copied. A missing or undefined name, an args, props or children value that is not an array reference, any other field and an odd number of arguments die, for example with Text::KDL::XS::Node->new: 'name' is required. new may be called on a subclass.

METHODS

name

The node name as a character string. Never undef for a parsed node.

type_annotation

The (type) written before the node name, or undef if there is none.

args

Array reference of the node's arguments as Text::KDL::XS::Value objects, in document order. Empty array reference when there are none.

my @strings = map { $_->as_string } @{ $node->args };
my $first   = $node->args->[0];      # undef if there are no arguments

props

Array reference of [ $key, $value ] pairs in document order, one pair per property as written, including repeated keys. $value is a Text::KDL::XS::Value.

for my $pair (@{ $node->props }) {
    my ($key, $value) = @$pair;
    ...
}

prop

my $value = $node->prop($key);   # Text::KDL::XS::Value, or undef if absent

Looks up a property by key. When the key appears more than once the last occurrence is returned, as the KDL specification requires. Returns undef for a missing key; a property whose value is #null returns a Value object with is_null true, so the two cases can be told apart. undef as the key dies.

prop searches the props array from the end, so it always reflects its current contents: on hand-built nodes, and after properties have been added, removed or reordered. The search is linear in the number of properties, which is small in practice; build a hash from props when a node has very many.

children

Array reference of child nodes, in document order. Empty when the node has no children block (or an empty one).

as_data

my $data = $node->as_data;

Returns the node and its subtree as plain Perl data:

{
    name     => $string,
    type     => $string_or_undef,             # node type annotation
    args     => [ $scalar, ... ],             # Value->as_perl for each argument
    props    => { $key => $scalar, ... },     # last value wins for repeated keys
    children => [ \%child, ... ],             # same shape, recursively
}

Values are converted with "as_perl" in Text::KDL::XS::Value: undef for null, 1/0 for booleans, numbers as numbers (or digit strings for arbitrary precision values), strings as strings. Plain scalars in hand-built nodes are returned as they are. Type annotations on values and the number kind are dropped.

INTERNAL METHODS

_new_parsed is the constructor used by the tree builder; it may change without notice.

SEE ALSO

Text::KDL::XS, Text::KDL::XS::Value, Text::KDL::XS::Document, "Building nodes and values by hand" in Text::KDL::XS::Cookbook.

AUTHOR

Davenonymous <perl@davenonymous.com>

LICENSE

Copyright (C) 2026 Davenonymous.

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