--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.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. | will give a
+.\" real vertical bar. \*(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-|\(bv\*(Tr
+.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" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Tree::Simple 3"
+.TH Tree::Simple 3 "2007-11-11" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Tree::Simple \- A simple tree object
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use Tree::Simple;
+.Ve
+.PP
+.Vb 2
+\& # make a tree root
+\& my $tree = Tree::Simple\->new("0", Tree::Simple\->ROOT);
+.Ve
+.PP
+.Vb 2
+\& # explicity add a child to it
+\& $tree\->addChild(Tree::Simple\->new("1"));
+.Ve
+.PP
+.Vb 3
+\& # specify the parent when creating
+\& # an instance and it adds the child implicity
+\& my $sub_tree = Tree::Simple\->new("2", $tree);
+.Ve
+.PP
+.Vb 2
+\& # chain method calls
+\& $tree\->getChild(0)\->addChild(Tree::Simple\->new("1.1"));
+.Ve
+.PP
+.Vb 5
+\& # add more than one child at a time
+\& $sub_tree\->addChildren(
+\& Tree::Simple\->new("2.1"),
+\& Tree::Simple\->new("2.2")
+\& );
+.Ve
+.PP
+.Vb 2
+\& # add siblings
+\& $sub_tree\->addSibling(Tree::Simple\->new("3"));
+.Ve
+.PP
+.Vb 2
+\& # insert children a specified index
+\& $sub_tree\->insertChild(1, Tree::Simple\->new("2.1a"));
+.Ve
+.PP
+.Vb 2
+\& # clean up circular references
+\& $tree\->DESTROY();
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This module in an fully object-oriented implementation of a simple n\-ary
+tree. It is built upon the concept of parent-child relationships, so
+therefore every \fBTree::Simple\fR object has both a parent and a set of
+children (who themselves may have children, and so on). Every \fBTree::Simple\fR
+object also has siblings, as they are just the children of their immediate
+parent.
+.PP
+It is can be used to model hierarchal information such as a file\-system,
+the organizational structure of a company, an object inheritance hierarchy,
+versioned files from a version control system or even an abstract syntax
+tree for use in a parser. It makes no assumptions as to your intended usage,
+but instead simply provides the structure and means of accessing and
+traversing said structure.
+.PP
+This module uses exceptions and a minimal Design By Contract style. All method
+arguments are required unless specified in the documentation, if a required
+argument is not defined an exception will usually be thrown. Many arguments
+are also required to be of a specific type, for instance the \f(CW$parent\fR
+argument to the constructor \fBmust\fR be a \fBTree::Simple\fR object or an object
+derived from \fBTree::Simple\fR, otherwise an exception is thrown. This may seems
+harsh to some, but this allows me to have the confidence that my code works as
+I intend, and for you to enjoy the same level of confidence when using this
+module. Note however that this module does not use any Exception or Error module,
+the exceptions are just strings thrown with \f(CW\*(C`die\*(C'\fR.
+.PP
+I consider this module to be production stable, it is based on a module which has
+been in use on a few production systems for approx. 2 years now with no issue.
+The only difference is that the code has been cleaned up a bit, comments added and
+the thorough tests written for its public release. I am confident it behaves as
+I would expect it to, and is (as far as I know) bug\-free. I have not stress-tested
+it under extreme duress, but I don't so much intend for it to be used in that
+type of situation. If this module cannot keep up with your Tree needs, i suggest
+switching to one of the modules listed in the \*(L"\s-1OTHER\s0 \s-1TREE\s0 \s-1MODULES\s0\*(R" section below.
+.SH "CONSTANTS"
+.IX Header "CONSTANTS"
+.IP "\fB\s-1ROOT\s0\fR" 4
+.IX Item "ROOT"
+This class constant serves as a placeholder for the root of our tree. If a tree
+does not have a parent, then it is considered a root.
+.SH "METHODS"
+.IX Header "METHODS"
+.Sh "Constructor"
+.IX Subsection "Constructor"
+.ie n .IP "\fBnew ($node, \fB$parent\fB)\fR" 4
+.el .IP "\fBnew ($node, \f(CB$parent\fB)\fR" 4
+.IX Item "new ($node, $parent)"
+The constructor accepts two arguments a \f(CW$node\fR value and an optional \f(CW$parent\fR.
+The \f(CW$node\fR value can be any scalar value (which includes references and objects).
+The optional \f(CW$parent\fR value must be a \fBTree::Simple\fR object, or an object
+derived from \fBTree::Simple\fR. Setting this value implies that your new tree is a
+child of the parent tree, and therefore adds it to the parent's children. If the
+\&\f(CW$parent\fR is not specified then its value defaults to \s-1ROOT\s0.
+.Sh "Mutator Methods"
+.IX Subsection "Mutator Methods"
+.IP "\fBsetNodeValue ($node_value)\fR" 4
+.IX Item "setNodeValue ($node_value)"
+This sets the node value to the scalar \f(CW$node_value\fR, an exception is thrown if
+\&\f(CW$node_value\fR is not defined.
+.IP "\fBsetUID ($uid)\fR" 4
+.IX Item "setUID ($uid)"
+This allows you to set your own unique \s-1ID\s0 for this specific Tree::Simple object.
+A default value derived from the object's hex address is provided for you, so use
+of this method is entirely optional. It is the responsibility of the user to
+ensure the value's uniqueness, all that is tested by this method is that \f(CW$uid\fR
+is a true value (evaluates to true in a boolean context). For even more information
+about the Tree::Simple \s-1UID\s0 see the \f(CW\*(C`getUID\*(C'\fR method.
+.IP "\fBaddChild ($tree)\fR" 4
+.IX Item "addChild ($tree)"
+This method accepts only \fBTree::Simple\fR objects or objects derived from
+\&\fBTree::Simple\fR, an exception is thrown otherwise. This method will append
+the given \f(CW$tree\fR to the end of it's children list, and set up the correct
+parent-child relationships. This method is set up to return its invocant so
+that method call chaining can be possible. Such as:
+.Sp
+.Vb 1
+\& my $tree = Tree::Simple\->new("root")\->addChild(Tree::Simple\->new("child one"));
+.Ve
+.Sp
+Or the more complex:
+.Sp
+.Vb 5
+\& my $tree = Tree::Simple\->new("root")\->addChild(
+\& Tree::Simple\->new("1.0")\->addChild(
+\& Tree::Simple\->new("1.0.1")
+\& )
+\& );
+.Ve
+.IP "\fBaddChildren (@trees)\fR" 4
+.IX Item "addChildren (@trees)"
+This method accepts an array of \fBTree::Simple\fR objects, and adds them to
+it's children list. Like \f(CW\*(C`addChild\*(C'\fR this method will return its invocant
+to allow for method call chaining.
+.ie n .IP "\fBinsertChild ($index, \fB$tree\fB)\fR" 4
+.el .IP "\fBinsertChild ($index, \f(CB$tree\fB)\fR" 4
+.IX Item "insertChild ($index, $tree)"
+This method accepts a numeric \f(CW$index\fR and a \fBTree::Simple\fR object (\f(CW$tree\fR),
+and inserts the \f(CW$tree\fR into the children list at the specified \f(CW$index\fR.
+This results in the shifting down of all children after the \f(CW$index\fR. The
+\&\f(CW$index\fR is checked to be sure it is the bounds of the child list, if it
+out of bounds an exception is thrown. The \f(CW$tree\fR argument's type is
+verified to be a \fBTree::Simple\fR or \fBTree::Simple\fR derived object, if
+this condition fails, an exception is thrown.
+.ie n .IP "\fBinsertChildren ($index, \fB@trees\fB)\fR" 4
+.el .IP "\fBinsertChildren ($index, \f(CB@trees\fB)\fR" 4
+.IX Item "insertChildren ($index, @trees)"
+This method functions much as insertChild does, but instead of inserting a
+single \fBTree::Simple\fR, it inserts an array of \fBTree::Simple\fR objects. It
+too bounds checks the value of \f(CW$index\fR and type checks the objects in
+\&\f(CW@trees\fR just as \f(CW\*(C`insertChild\*(C'\fR does.
+.ie n .IP "\fBremoveChild\fR ($child | $index)>" 4
+.el .IP "\fBremoveChild\fR ($child | \f(CW$index\fR)>" 4
+.IX Item "removeChild ($child | $index)>"
+Accepts two different arguemnts. If given a \fBTree::Simple\fR object (\f(CW$child\fR),
+this method finds that specific \f(CW$child\fR by comparing it with all the other
+children until it finds a match. At which point the \f(CW$child\fR is removed. If
+no match is found, and exception is thrown. If a non\-\fBTree::Simple\fR object
+is given as the \f(CW$child\fR argument, an exception is thrown.
+.Sp
+This method also accepts a numeric \f(CW$index\fR and removes the child found at
+that index from it's list of children. The \f(CW$index\fR is bounds checked, if
+this condition fail, an exception is thrown.
+.Sp
+When a child is removed, it results in the shifting up of all children after
+it, and the removed child is returned. The removed child is properly
+disconnected from the tree and all its references to its old parent are
+removed. However, in order to properly clean up and circular references
+the removed child might have, it is advised to call it's \f(CW\*(C`DESTROY\*(C'\fR method.
+See the \*(L"\s-1CIRCULAR\s0 \s-1REFERENCES\s0\*(R" section for more information.
+.IP "\fBaddSibling ($tree)\fR" 4
+.IX Item "addSibling ($tree)"
+.PD 0
+.IP "\fBaddSiblings (@trees)\fR" 4
+.IX Item "addSiblings (@trees)"
+.ie n .IP "\fBinsertSibling ($index, \fB$tree\fB)\fR" 4
+.el .IP "\fBinsertSibling ($index, \f(CB$tree\fB)\fR" 4
+.IX Item "insertSibling ($index, $tree)"
+.ie n .IP "\fBinsertSiblings ($index, \fB@trees\fB)\fR" 4
+.el .IP "\fBinsertSiblings ($index, \f(CB@trees\fB)\fR" 4
+.IX Item "insertSiblings ($index, @trees)"
+.PD
+The \f(CW\*(C`addSibling\*(C'\fR, \f(CW\*(C`addSiblings\*(C'\fR, \f(CW\*(C`insertSibling\*(C'\fR and \f(CW\*(C`insertSiblings\*(C'\fR
+methods pass along their arguments to the \f(CW\*(C`addChild\*(C'\fR, \f(CW\*(C`addChildren\*(C'\fR,
+\&\f(CW\*(C`insertChild\*(C'\fR and \f(CW\*(C`insertChildren\*(C'\fR methods of their parent object
+respectively. This eliminates the need to overload these methods in subclasses
+which may have specialized versions of the *Child(ren) methods. The one
+exceptions is that if an attempt it made to add or insert siblings to the
+\&\fB\s-1ROOT\s0\fR of the tree then an exception is thrown.
+.PP
+\&\fB\s-1NOTE:\s0\fR
+There is no \f(CW\*(C`removeSibling\*(C'\fR method as I felt it was probably a bad idea.
+The same effect can be achieved by manual upwards traversal.
+.Sh "Accessor Methods"
+.IX Subsection "Accessor Methods"
+.IP "\fBgetNodeValue\fR" 4
+.IX Item "getNodeValue"
+This returns the value stored in the object's node field.
+.IP "\fBgetUID\fR" 4
+.IX Item "getUID"
+This returns the unique \s-1ID\s0 associated with this particular tree. This can
+be custom set using the \f(CW\*(C`setUID\*(C'\fR method, or you can just use the default.
+The default is the hex-address extracted from the stringified Tree::Simple
+object. This may not be a \fIuniversally\fR unique identifier, but it should
+be adequate for at least the current instance of your perl interpreter. If
+you need a \s-1UUID\s0, one can be generated with an outside module (there are
+ many to choose from on \s-1CPAN\s0) and the \f(CW\*(C`setUID\*(C'\fR method (see above).
+.IP "\fBgetChild ($index)\fR" 4
+.IX Item "getChild ($index)"
+This returns the child (a \fBTree::Simple\fR object) found at the specified
+\&\f(CW$index\fR. Note that we do use standard zero-based array indexing.
+.IP "\fBgetAllChildren\fR" 4
+.IX Item "getAllChildren"
+This returns an array of all the children (all \fBTree::Simple\fR objects).
+It will return an array reference in scalar context.
+.IP "\fBgetSibling ($index)\fR" 4
+.IX Item "getSibling ($index)"
+.PD 0
+.IP "\fBgetAllSiblings\fR" 4
+.IX Item "getAllSiblings"
+.PD
+Much like \f(CW\*(C`addSibling\*(C'\fR and \f(CW\*(C`addSiblings\*(C'\fR, these two methods simply call
+\&\f(CW\*(C`getChild\*(C'\fR and \f(CW\*(C`getAllChildren\*(C'\fR on the invocant's parent.
+.IP "\fBgetDepth\fR" 4
+.IX Item "getDepth"
+Returns a number representing the invocant's depth within the hierarchy of
+\&\fBTree::Simple\fR objects.
+.Sp
+\&\fB\s-1NOTE:\s0\fR A \f(CW\*(C`ROOT\*(C'\fR tree has the depth of \-1. This be because Tree::Simple
+assumes that a tree's root will usually not contain data, but just be an
+anchor for the data-containing branches. This may not be intuitive in all
+cases, so I mention it here.
+.IP "\fBgetParent\fR" 4
+.IX Item "getParent"
+Returns the invocant's parent, which could be either \fB\s-1ROOT\s0\fR or a
+\&\fBTree::Simple\fR object.
+.IP "\fBgetHeight\fR" 4
+.IX Item "getHeight"
+Returns a number representing the length of the longest path from the current
+tree to the furthest leaf node.
+.IP "\fBgetWidth\fR" 4
+.IX Item "getWidth"
+Returns the a number representing the breadth of the current tree, basically
+it is a count of all the leaf nodes.
+.IP "\fBgetChildCount\fR" 4
+.IX Item "getChildCount"
+Returns the number of children the invocant contains.
+.IP "\fBgetIndex\fR" 4
+.IX Item "getIndex"
+Returns the index of this tree within its parent's child list. Returns \-1 if
+the tree is the root.
+.Sh "Predicate Methods"
+.IX Subsection "Predicate Methods"
+.IP "\fBisLeaf\fR" 4
+.IX Item "isLeaf"
+Returns true (1) if the invocant does not have any children, false (0) otherwise.
+.IP "\fBisRoot\fR" 4
+.IX Item "isRoot"
+Returns true (1) if the invocant's \*(L"parent\*(R" field is \fB\s-1ROOT\s0\fR, returns false
+(0) otherwise.
+.Sh "Recursive Methods"
+.IX Subsection "Recursive Methods"
+.IP "\fBtraverse ($func, ?$postfunc)\fR" 4
+.IX Item "traverse ($func, ?$postfunc)"
+This method accepts two arguments a mandatory \f(CW$func\fR and an optional
+\&\f(CW$postfunc\fR. If the argument \f(CW$func\fR is not defined then an exception
+is thrown. If \f(CW$func\fR or \f(CW$postfunc\fR are not in fact \s-1CODE\s0 references
+then an exception is thrown. The function \f(CW$func\fR is then applied
+recursively to all the children of the invocant. If given, the function
+\&\f(CW$postfunc\fR will be applied to each child after the child's children
+have been traversed.
+.Sp
+Here is an example of a traversal function that will print out the
+hierarchy as a tabbed in list.
+.Sp
+.Vb 4
+\& $tree\->traverse(sub {
+\& my ($_tree) = @_;
+\& print (("\et" x $_tree\->getDepth()), $_tree\->getNodeValue(), "\en");
+\& });
+.Ve
+.Sp
+Here is an example of a traversal function that will print out the
+hierarchy in an XML-style format.
+.Sp
+.Vb 10
+\& $tree\->traverse(sub {
+\& my ($_tree) = @_;
+\& print ((' ' x $_tree\->getDepth()),
+\& '<', $_tree\->getNodeValue(),'>',"\en");
+\& },
+\& sub {
+\& my ($_tree) = @_;
+\& print ((' ' x $_tree\->getDepth()),
+\& '</', $_tree\->getNodeValue(),'>',"\en");
+\& });
+.Ve
+.IP "\fBsize\fR" 4
+.IX Item "size"
+Returns the total number of nodes in the current tree and all its sub\-trees.
+.IP "\fBheight\fR" 4
+.IX Item "height"
+This method has also been \fBdeprecated\fR in favor of the \f(CW\*(C`getHeight\*(C'\fR method above,
+it remains as an alias to \f(CW\*(C`getHeight\*(C'\fR for backwards compatability.
+.Sp
+\&\fB\s-1NOTE:\s0\fR This is also no longer a recursive method which get's it's value on demand,
+but a value stored in the Tree::Simple object itself, hopefully making it much
+more efficient and usable.
+.Sh "Visitor Methods"
+.IX Subsection "Visitor Methods"
+.IP "\fBaccept ($visitor)\fR" 4
+.IX Item "accept ($visitor)"
+It accepts either a \fBTree::Simple::Visitor\fR object (which includes classes derived
+ from \fBTree::Simple::Visitor\fR), or an object who has the \f(CW\*(C`visit\*(C'\fR method available
+ (tested with \f(CW\*(C`$visitor\->can('visit')\*(C'\fR). If these qualifications are not met,
+ and exception will be thrown. We then run the Visitor's \f(CW\*(C`visit\*(C'\fR method giving the
+ current tree as its argument.
+.Sp
+I have also created a number of Visitor objects and packaged them into the
+\&\fBTree::Simple::VisitorFactory\fR.
+.Sh "Cloning Methods"
+.IX Subsection "Cloning Methods"
+Cloning a tree can be an extremly expensive operation for large trees, so we provide
+two options for cloning, a deep clone and a shallow clone.
+.PP
+When a Tree::Simple object is cloned, the node is deep-copied in the following manner.
+If we find a normal scalar value (non\-reference), we simply copy it. If we find an
+object, we attempt to call \f(CW\*(C`clone\*(C'\fR on it, otherwise we just copy the reference (since
+we assume the object does not want to be cloned). If we find a \s-1SCALAR\s0, \s-1REF\s0 reference we
+copy the value contained within it. If we find a \s-1HASH\s0 or \s-1ARRAY\s0 reference we copy the
+reference and recursively copy all the elements within it (following these exact
+guidelines). We also do our best to assure that circular references are cloned
+only once and connections restored correctly. This cloning will not be able to copy
+\&\s-1CODE\s0, RegExp and \s-1GLOB\s0 references, as they are pretty much impossible to clone. We
+also do not handle \f(CW\*(C`tied\*(C'\fR objects, and they will simply be copied as plain
+references, and not re\-\f(CW\*(C`tied\*(C'\fR.
+.IP "\fBclone\fR" 4
+.IX Item "clone"
+The clone method does a full deep-copy clone of the object, calling \f(CW\*(C`clone\*(C'\fR recursively
+on all its children. This does not call \f(CW\*(C`clone\*(C'\fR on the parent tree however. Doing
+this would result in a slowly degenerating spiral of recursive death, so it is not
+recommended and therefore not implemented. What happens is that the tree instance
+that \f(CW\*(C`clone\*(C'\fR is actually called upon is detached from the tree, and becomes a root
+node, all if the cloned children are then attached as children of that tree. I personally
+think this is more intuitive then to have the cloning crawl back \fIup\fR the tree is not
+what I think most people would expect.
+.IP "\fBcloneShallow\fR" 4
+.IX Item "cloneShallow"
+This method is an alternate option to the plain \f(CW\*(C`clone\*(C'\fR method. This method allows the
+cloning of single \fBTree::Simple\fR object while retaining connections to the rest of the
+tree/hierarchy.
+.Sh "Misc. Methods"
+.IX Subsection "Misc. Methods"
+.IP "\fB\s-1DESTROY\s0\fR" 4
+.IX Item "DESTROY"
+To avoid memory leaks through uncleaned-up circular references, we implement the
+\&\f(CW\*(C`DESTROY\*(C'\fR method. This method will attempt to call \f(CW\*(C`DESTROY\*(C'\fR on each of its
+children (if it has any). This will result in a cascade of calls to \f(CW\*(C`DESTROY\*(C'\fR on
+down the tree. It also cleans up it's parental relations as well.
+.Sp
+Because of perl's reference counting scheme and how that interacts with circular
+references, if you want an object to be properly reaped you should manually call
+\&\f(CW\*(C`DESTROY\*(C'\fR. This is especially nessecary if your object has any children. See the
+section on \*(L"\s-1CIRCULAR\s0 \s-1REFERENCES\s0\*(R" for more information.
+.IP "\fBfixDepth\fR" 4
+.IX Item "fixDepth"
+Tree::Simple will manage your tree's depth field for you using this method. You
+should never need to call it on your own, however if you ever did need to, here
+is it. Running this method will traverse your all the invocant's sub-trees
+correcting the depth as it goes.
+.IP "\fBfixHeight\fR" 4
+.IX Item "fixHeight"
+Tree::Simple will manage your tree's height field for you using this method.
+You should never need to call it on your own, however if you ever did need to,
+here is it. Running this method will correct the heights of the current tree
+and all it's ancestors.
+.IP "\fBfixWidth\fR" 4
+.IX Item "fixWidth"
+Tree::Simple will manage your tree's width field for you using this method. You
+should never need to call it on your own, however if you ever did need to,
+here is it. Running this method will correct the widths of the current tree
+and all it's ancestors.
+.Sh "Private Methods"
+.IX Subsection "Private Methods"
+I would not normally document private methods, but in case you need to subclass
+Tree::Simple, here they are.
+.ie n .IP "\fB_init ($node, \fB$parent\fB, \f(BI$children\fB)\fR" 4
+.el .IP "\fB_init ($node, \f(CB$parent\fB, \f(CB$children\fB)\fR" 4
+.IX Item "_init ($node, $parent, $children)"
+This method is here largely to facilitate subclassing. This method is called by
+new to initialize the object, where new's primary responsibility is creating
+the instance.
+.IP "\fB_setParent ($parent)\fR" 4
+.IX Item "_setParent ($parent)"
+This method sets up the parental relationship. It is for internal use only.
+.IP "\fB_setHeight ($child)\fR" 4
+.IX Item "_setHeight ($child)"
+This method will set the height field based upon the height of the given \f(CW$child\fR.
+.SH "CIRCULAR REFERENCES"
+.IX Header "CIRCULAR REFERENCES"
+I have revised the model by which Tree::Simple deals with ciruclar references.
+In the past all circular references had to be manually destroyed by calling
+\&\s-1DESTROY\s0. The call to \s-1DESTROY\s0 would then call \s-1DESTROY\s0 on all the children, and
+therefore cascade down the tree. This however was not always what was needed,
+nor what made sense, so I have now revised the model to handle things in what
+I feel is a more consistent and sane way.
+.PP
+Circular references are now managed with the simple idea that the parent makes
+the descisions for the child. This means that child-to-parent references are
+weak, while parent-to-child references are strong. So if a parent is destroyed
+it will force all it's children to detach from it, however, if a child is
+destroyed it will not be detached from it's parent.
+.Sh "Optional Weak References"
+.IX Subsection "Optional Weak References"
+By default, you are still required to call \s-1DESTROY\s0 in order for things to
+happen. However I have now added the option to use weak references, which
+alleviates the need for the manual call to \s-1DESTROY\s0 and allows Tree::Simple
+to manage this automatically. This is accomplished with a compile time
+setting like this:
+.PP
+.Vb 1
+\& use Tree::Simple 'use_weak_refs';
+.Ve
+.PP
+And from that point on Tree::Simple will use weak references to allow for
+perl's reference counting to clean things up properly.
+.PP
+For those who are unfamilar with weak references, and how they affect the
+reference counts, here is a simple illustration. First is the normal model
+that Tree::Simple uses:
+.PP
+.Vb 13
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& | Tree::Simple1 |<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ |
+\& | parent | |
+\& | children |\-+ |
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | |
+\& | |
+\& | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ |
+\& +\->| Tree::Simple2 | |
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ |
+\& | parent |\-+
+\& | children |
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+.Ve
+.PP
+Here, Tree::Simple1 has a reference count of 2 (one for the original
+variable it is assigned to, and one for the parent reference in
+Tree::Simple2), and Tree::Simple2 has a reference count of 1 (for the
+child reference in Tree::Simple2).
+.PP
+Now, with weak references:
+.PP
+.Vb 13
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+\& | Tree::Simple1 |.......................
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ :
+\& | parent | :
+\& | children |\-+ : <\-\-[ weak reference ]
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | :
+\& | :
+\& | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ :
+\& +\->| Tree::Simple2 | :
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ :
+\& | parent |..
+\& | children |
+\& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
+.Ve
+.PP
+Now Tree::Simple1 has a reference count of 1 (for the variable it is
+assigned to) and 1 weakened reference (for the parent reference in
+Tree::Simple2). And Tree::Simple2 has a reference count of 1, just
+as before.
+.SH "BUGS"
+.IX Header "BUGS"
+None that I am aware of. The code is pretty thoroughly tested (see
+\&\*(L"\s-1CODE\s0 \s-1COVERAGE\s0\*(R" below) and is based on an (non\-publicly released)
+module which I had used in production systems for about 3 years without
+incident. Of course, if you find a bug, let me know, and I will be sure
+to fix it.
+.SH "CODE COVERAGE"
+.IX Header "CODE COVERAGE"
+I use Devel::Cover to test the code coverage of my tests, below
+is the Devel::Cover report on this module's test suite.
+.PP
+.Vb 8
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
+\& File stmt branch cond sub pod time total
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
+\& Tree/Simple.pm 99.6 96.0 92.3 100.0 97.0 95.5 98.0
+\& Tree/Simple/Visitor.pm 100.0 96.2 88.2 100.0 100.0 4.5 97.7
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
+\& Total 99.7 96.1 91.1 100.0 97.6 100.0 97.9
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+I have written a number of other modules which use or augment this
+module, they are describes below and available on \s-1CPAN\s0.
+.IP "Tree::Parser \- A module for parsing formatted files into Tree::Simple hierarchies." 4
+.IX Item "Tree::Parser - A module for parsing formatted files into Tree::Simple hierarchies."
+.PD 0
+.IP "Tree::Simple::View \- A set of classes for viewing Tree::Simple hierarchies in various output formats." 4
+.IX Item "Tree::Simple::View - A set of classes for viewing Tree::Simple hierarchies in various output formats."
+.IP "Tree::Simple::VisitorFactory \- A set of several useful Visitor objects for Tree::Simple objects." 4
+.IX Item "Tree::Simple::VisitorFactory - A set of several useful Visitor objects for Tree::Simple objects."
+.IP "Tree::Binary \- If you are looking for a binary tree, this you might want to check this one out." 4
+.IX Item "Tree::Binary - If you are looking for a binary tree, this you might want to check this one out."
+.PD
+.PP
+Also, the author of Data::TreeDumper and I have worked together
+to make sure that \fBTree::Simple\fR and his module work well together.
+If you need a quick and handy way to dump out a Tree::Simple heirarchy,
+this module does an excellent job (and plenty more as well).
+.PP
+I have also recently stumbled upon some packaged distributions of
+Tree::Simple for the various Unix flavors. Here are some links:
+.IP "FreeBSD Port \- <http://www.freshports.org/devel/p5\-Tree\-Simple/>" 4
+.IX Item "FreeBSD Port - <http://www.freshports.org/devel/p5-Tree-Simple/>"
+.PD 0
+.IP "Debian Package \- <http://packages.debian.org/unstable/perl/libtree\-simple\-perl>" 4
+.IX Item "Debian Package - <http://packages.debian.org/unstable/perl/libtree-simple-perl>"
+.IP "Linux \s-1RPM\s0 \- <http://rpmpan.sourceforge.net/Tree.html>" 4
+.IX Item "Linux RPM - <http://rpmpan.sourceforge.net/Tree.html>"
+.PD
+.SH "OTHER TREE MODULES"
+.IX Header "OTHER TREE MODULES"
+There are a few other Tree modules out there, here is a quick comparison
+between \fBTree::Simple\fR and them. Obviously I am biased, so take what I say
+with a grain of salt, and keep in mind, I wrote \fBTree::Simple\fR because I
+could not find a Tree module that suited my needs. If \fBTree::Simple\fR does
+not fit your needs, I recommend looking at these modules. Please note that
+I am only listing Tree::* modules I am familiar with here, if you think I
+have missed a module, please let me know. I have also seen a few tree-ish
+modules outside of the Tree::* namespace, but most of them are part of
+another distribution (\fBHTML::Tree\fR, \fBPod::Tree\fR, etc) and are likely
+specialized in purpose.
+.IP "Tree::DAG_Node" 4
+.IX Item "Tree::DAG_Node"
+This module seems pretty stable and very robust with a lot of functionality.
+However, \fBTree::DAG_Node\fR does not come with any automated tests. It's
+\&\fItest.pl\fR file simply checks the module loads and nothing else. While I
+am sure the author tested his code, I would feel better if I was able to
+see that. The module is approx. 3000 lines with \s-1POD\s0, and 1,500 without the
+\&\s-1POD\s0. The shear depth and detail of the documentation and the ratio of code
+to documentation is impressive, and not to be taken lightly. But given that
+it is a well known fact that the likeliness of bugs increases along side the
+size of the code, I do not feel comfortable with large modules like this
+which have no tests.
+.Sp
+All this said, I am not a huge fan of the \s-1API\s0 either, I prefer the gender
+neutral approach in \fBTree::Simple\fR to the mother/daughter style of \fBTree::DAG_Node\fR.
+I also feel very strongly that \fBTree::DAG_Node\fR is trying to do much more
+than makes sense in a single module, and is offering too many ways to do
+the same or similar things.
+.Sp
+However, of all the Tree::* modules out there, \fBTree::DAG_Node\fR seems to
+be one of the favorites, so it may be worth investigating.
+.IP "Tree::MultiNode" 4
+.IX Item "Tree::MultiNode"
+I am not very familiar with this module, however, I have heard some good
+reviews of it, so I thought it deserved mention here. I believe it is
+based upon \*(C+ code found in the book \fIAlgorithms in \*(C+\fR by Robert Sedgwick.
+It uses a number of interesting ideas, such as a ::Handle object to traverse
+the tree with (similar to Visitors, but also seem to be to be kind of like
+a cursor). However, like \fBTree::DAG_Node\fR, it is somewhat lacking in tests
+and has only 6 tests in its suite. It also has one glaring bug, which is
+that there is currently no way to remove a child node.
+.IP "Tree::Nary" 4
+.IX Item "Tree::Nary"
+It is a (somewhat) direct translation of the N\-ary tree from the \s-1GLIB\s0
+library, and the \s-1API\s0 is based on that. \s-1GLIB\s0 is a C library, which means
+this is a very C\-ish \s-1API\s0. That doesn't appeal to me, it might to you, to
+each their own.
+.Sp
+This module is similar in intent to \fBTree::Simple\fR. It implements a tree
+with \fIn\fR branches and has polymorphic node containers. It implements much
+of the same methods as \fBTree::Simple\fR and a few others on top of that, but
+being based on a C library, is not very \s-1OO\s0. In most of the method calls
+the \f(CW$self\fR argument is not used and the second argument \f(CW$node\fR is.
+\&\fBTree::Simple\fR is a much more \s-1OO\s0 module than \fBTree::Nary\fR, so while they
+are similar in functionality they greatly differ in implementation style.
+.IP "Tree" 4
+.IX Item "Tree"
+This module is pretty old, it has not been updated since Oct. 31, 1999 and
+is still on version 0.01. It also seems to be (from the limited documentation)
+a binary and a balanced binary tree, \fBTree::Simple\fR is an \fIn\fR\-ary tree, and
+makes no attempt to balance anything.
+.IP "Tree::Ternary" 4
+.IX Item "Tree::Ternary"
+This module is older than \fBTree\fR, last update was Sept. 24th, 1999. It
+seems to be a special purpose tree, for storing and accessing strings,
+not general purpose like \fBTree::Simple\fR.
+.IP "Tree::Ternary_XS" 4
+.IX Item "Tree::Ternary_XS"
+This module is an \s-1XS\s0 implementation of the above tree type.
+.IP "Tree::Trie" 4
+.IX Item "Tree::Trie"
+This too is a specialized tree type, it sounds similar to the \fBTree::Ternary\fR,
+but it much newer (latest release in 2003). It seems specialized for the lookup
+and retrieval of information like a hash.
+.IP "Tree::M" 4
+.IX Item "Tree::M"
+Is a wrapper for a \*(C+ library, whereas \fBTree::Simple\fR is pure\-perl. It also
+seems to be a more specialized implementation of a tree, therefore not really
+the same as \fBTree::Simple\fR.
+.IP "Tree::Fat" 4
+.IX Item "Tree::Fat"
+Is a wrapper around a C library, again \fBTree::Simple\fR is pure\-perl. The author
+describes FAT-trees as a combination of a Tree and an array. It looks like a
+pretty mean and lean module, and good if you need speed and are implementing a
+custom data-store of some kind. The author points out too that the module is
+designed for embedding and there is not default embedding, so you can't really
+use it \*(L"out of the box\*(R".
+.SH "ACKNOWLEDGEMENTS"
+.IX Header "ACKNOWLEDGEMENTS"
+.IP "Thanks to Nadim Ibn Hamouda El Khemir for making Data::TreeDumper work with \fBTree::Simple\fR." 4
+.IX Item "Thanks to Nadim Ibn Hamouda El Khemir for making Data::TreeDumper work with Tree::Simple."
+.PD 0
+.ie n .IP "Thanks to Brett Nuske for his idea for the ""getUID""\fR and \f(CW""setUID"" methods." 4
+.el .IP "Thanks to Brett Nuske for his idea for the \f(CWgetUID\fR and \f(CWsetUID\fR methods." 4
+.IX Item "Thanks to Brett Nuske for his idea for the getUID and setUID methods."
+.IP "Thanks to whomever submitted the memory leak bug to \s-1RT\s0 (#7512)." 4
+.IX Item "Thanks to whomever submitted the memory leak bug to RT (#7512)."
+.IP "Thanks to Mark Thomas for his insight into how to best handle the \fIheight\fR and \fIwidth\fR properties without unessecary recursion." 4
+.IX Item "Thanks to Mark Thomas for his insight into how to best handle the height and width properties without unessecary recursion."
+.IP "Thanks for Mark Lawrence for the &traverse post-func patch, tests and docs." 4
+.IX Item "Thanks for Mark Lawrence for the &traverse post-func patch, tests and docs."
+.PD
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Stevan Little, <stevan@iinteractive.com>
+.PP
+Rob Kinyon, <rob@iinteractive.com>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2004\-2006 by 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.
projects / catagits/Gitalist.git / blobdiff