.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Forest::Tree::Pure 3pm"
.TH Forest::Tree::Pure 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Forest::Tree::Pure \- An n\-ary tree
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Forest::Tree;
\&
\&  my $t = Forest::Tree::Pure\->new(
\&      node     => 1,
\&      children => [
\&          Forest::Tree::Pure\->new(
\&              node     => 1.1,
\&              children => [
\&                  Forest::Tree::Pure\->new(node => 1.1.1),
\&                  Forest::Tree::Pure\->new(node => 1.1.2),
\&                  Forest::Tree::Pure\->new(node => 1.1.3),
\&              ]
\&          ),
\&          Forest::Tree::Pure\->new(node => 1.2),
\&          Forest::Tree::Pure\->new(
\&              node     => 1.3,
\&              children => [
\&                  Forest::Tree::Pure\->new(node => 1.3.1),
\&                  Forest::Tree::Pure\->new(node => 1.3.2),
\&              ]
\&          ),
\&      ]
\&  );
\&
\&  $t\->traverse(sub {
\&      my $t = shift;
\&      print((\*(Aq    \*(Aq x $t\->depth) . ($t\->node || \*(Aq\eundef\*(Aq) . "\en");
\&  });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a base class for Forest::Tree providing functionality for
immutable trees.
.PP
It can be used independently for trees that require sharing of children between
parents.
.PP
There is no single authoritative parent (no upward links at all), and changing
of data is not supported.
.PP
This class is appropriate when many tree roots share the same children (e.g. in
a versioned tree).
.PP
This class is strictly a \s-1DAG,\s0 wheras Forest::Tree produces a graph with back references
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "\fInode\fR" 4
.IX Item "node"
.PD 0
.IP "\fIchildren\fR" 4
.IX Item "children"
.RS 4
.IP "\fBget_child_at ($index)\fR" 4
.IX Item "get_child_at ($index)"
.PD
Return the child at this position. (zero-base index)
.IP "\fBchild_count\fR" 4
.IX Item "child_count"
Returns the number of children this tree has
.RE
.RS 4
.RE
.IP "\fIsize\fR" 4
.IX Item "size"
.RS 4
.PD 0
.IP "\fBsize\fR" 4
.IX Item "size"
.IP "\fBhas_size\fR" 4
.IX Item "has_size"
.RE
.RS 4
.RE
.IP "\fIheight\fR" 4
.IX Item "height"
.RS 4
.IP "\fBheight\fR" 4
.IX Item "height"
.IP "\fBhas_height\fR" 4
.IX Item "has_height"
.RE
.RS 4
.RE
.PD
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBis_leaf\fR" 4
.IX Item "is_leaf"
True if the current tree has no children
.IP "\fBtraverse (\e&func)\fR" 4
.IX Item "traverse (&func)"
Takes a reference to a subroutine and traverses the tree applying this subroutine to
every descendant. (But not the root)
.IP "\fBvisit (&func)\fR" 4
.IX Item "visit (&func)"
Traverse the entire tree, including the root.
.IP "\fBfmap_cont (&func)\fR" 4
.IX Item "fmap_cont (&func)"
A \s-1CPS\s0 form of \f(CW\*(C`visit\*(C'\fR that lets you control when and how data flows from the children.
.Sp
It takes a callback in the form:
.Sp
.Vb 2
\&    sub {
\&        my ( $tree, $cont, @args ) = @_;
\&
\&        ...
\&    }
.Ve
.Sp
and \f(CW$cont\fR is a code ref that when invoked will apply that same function to the children of \f(CW$tree\fR.
.Sp
This allows you to do things like computing the sum of all the node values in a tree, for instance:
.Sp
.Vb 1
\&    use List::Util qw(sum);
\&
\&    my $sum = $tree\->fmap_cont(sub {
\&        my ( $tree, $cont ) = @_;
\&
\&        return sum( $tree\->node, $cont\->() );
\&    });
.Ve
.Sp
And also allows one to stop traversal at a given point.
.IP "\fBadd_children (@children)\fR" 4
.IX Item "add_children (@children)"
.PD 0
.IP "\fBadd_child ($child)\fR" 4
.IX Item "add_child ($child)"
.PD
Create a new tree node with the children appended.
.Sp
The children must inherit \f(CW\*(C`Forest::Tree::Pure\*(C'\fR
.Sp
Note that this method does \fBnot\fR mutate the tree, instead it clones and
returns a tree with the augmented list of children.
.IP "\fBinsert_child_at ($index, \f(CB$child\fB)\fR" 4
.IX Item "insert_child_at ($index, $child)"
Insert a child at this position. (zero-base index)
.Sp
Returns a derived tree with overridden children.
.IP "\fBset_child_at ($index, \f(CB$child\fB)\fR" 4
.IX Item "set_child_at ($index, $child)"
Replaces the child at \f(CW$index\fR with \f(CW$child\fR.
.IP "\fBremove_child_at ($index)\fR" 4
.IX Item "remove_child_at ($index)"
Remove the child at this position. (zero-base index)
.Sp
Returns a derived tree with overridden children.
.IP "\fBlocate (@path)\fR" 4
.IX Item "locate (@path)"
Find a child using a path of child indexes. These two examples return the same object:
.Sp
.Vb 1
\&    $tree\->get_child_at(0)\->get_child_at(1)\->get_child_at(0);
\&
\&    $tree\->locate(0, 1, 0);
.Ve
.IP "\fBdescend (@path)\fR" 4
.IX Item "descend (@path)"
Like \f(CW\*(C`lookup\*(C'\fR except that it returns every object in the path, not just the leaf.
.ie n .IP """transform (\e@path, $method, @args)""" 4
.el .IP "\f(CWtransform (\e@path, $method, @args)\fR" 4
.IX Item "transform (@path, $method, @args)"
Performs a lookup on \f(CW@path\fR, applies the method \f(CW$method\fR with \f(CW@args\fR to
the located node, and clones the path to the parent returning a derived tree.
.Sp
This method is also implemented in Forest::Tree by mutating the tree in
place and returning the original tree, so the same transformations should work
on both pure trees and mutable ones.
.Sp
This code:
.Sp
.Vb 1
\&    my $new = $root\->transform([ 1, 3 ], insert_child_at => 3, $new_child);
.Ve
.Sp
will locate the child at the path \f(CW\*(C`[ 1, 3 ]\*(C'\fR, call \f(CW\*(C`insert_child_at\*(C'\fR on it,
creating a new version of \f(CW\*(C`[ 1, 3 ]\*(C'\fR, and then return a cloned version of
\&\f(CW\*(C`[ 1 ]\*(C'\fR and the root node recursively, such that \f(CW$new\fR appears to be a
mutated \f(CW$root\fR.
.ie n .IP "set_node $new" 4
.el .IP "set_node \f(CW$new\fR" 4
.IX Item "set_node $new"
Returns a clone of the tree node with the node value changed.
.ie n .IP """replace $arg""" 4
.el .IP "\f(CWreplace $arg\fR" 4
.IX Item "replace $arg"
Returns the argument. This is useful when used with \f(CW\*(C`transform\*(C'\fR.
.IP "\fBclone\fR" 4
.IX Item "clone"
Provided by MooseX::Clone.
.Sp
Deeply clones the entire tree.
.Sp
Subclasses should use MooseX::Clone traits to specify the correct cloning
behavior for additional attributes if cloning is used.
.IP "\fBreconstruct_with_class \f(CB$class\fB\fR" 4
.IX Item "reconstruct_with_class $class"
Recursively recreates the tree by passing constructor arguments to \f(CW$class\fR.
.Sp
Does not use \f(CW\*(C`clone\*(C'\fR.
.IP "\fBto_mutable_tree\fR" 4
.IX Item "to_mutable_tree"
Invokes \f(CW\*(C`reconstruct_with_class\*(C'\fR with Forest::Tree as the argument.
.IP "\fBto_pure_tree\fR" 4
.IX Item "to_pure_tree"
Returns the invocant.
.IP "\fBget_child_index ($child)\fR" 4
.IX Item "get_child_index ($child)"
Returns the index of \f(CW$child\fR in \f(CW\*(C`children\*(C'\fR or undef if it isn't a child of
the current tree.
.SH "BUGS"
.IX Header "BUGS"
All complex software has bugs lurking in it, and this module is no
exception. If you find a bug please either email me, or add the bug
to cpan-RT.
.SH "AUTHOR"
.IX Header "AUTHOR"
Yuval Kogman
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2008\-2014 Infinity Interactive, Inc.
.PP
<http://www.iinteractive.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.