.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" 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 "Tree::Simple 3pm" .TH Tree::Simple 3pm "2022-10-13" "perl v5.34.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" Tree::Simple \- A simple tree object .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Tree::Simple; \& \& # make a tree root \& my $tree = Tree::Simple\->new("0", Tree::Simple\->ROOT); \& \& # explicitly add a child to it \& $tree\->addChild(Tree::Simple\->new("1")); \& \& # specify the parent when creating \& # an instance and it adds the child implicitly \& my $sub_tree = Tree::Simple\->new("2", $tree); \& \& # chain method calls \& $tree\->getChild(0)\->addChild(Tree::Simple\->new("1.1")); \& \& # add more than one child at a time \& $sub_tree\->addChildren( \& Tree::Simple\->new("2.1"), \& Tree::Simple\->new("2.2") \& ); \& \& # add siblings \& $sub_tree\->addSibling(Tree::Simple\->new("3")); \& \& # insert children a specified index \& $sub_tree\->insertChild(1, Tree::Simple\->new("2.1a")); \& \& # clean up circular references \& $tree\->DESTROY(); .Ve .PP Alternately, to avoid calling Tree::Simple\->new(...) just to add a node: .PP .Vb 2 \& use Tree::Simple; \& use Data::TreeDumper; # Provides DumpTree(). \& \& # \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& \& my($root) = Tree::Simple\->new(\*(AqRoot\*(Aq, Tree::Simple\->ROOT); \& \& $root\->generateChild(\*(AqChild 1.0\*(Aq); \& $root\->generateChild(\*(AqChild 2.0\*(Aq); \& $root\->getChild(0)\->generateChild(\*(AqGrandchild 1.1\*(Aq); \& \& print DumpTree($root); \& \& $root\->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 do not 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 TREE MODULES\*(R"\s0 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" .SS "Constructor" .IX Subsection "Constructor" .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 children of that parent. If the \&\f(CW$parent\fR is not specified then its value defaults to \s-1ROOT.\s0 .SS "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 hex address of the object is provided for you, so use of this method is entirely optional. It is the responsibility of the user to ensure the value has 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 the 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 "\fBgenerateChild ($scalar)\fR" 4 .IX Item "generateChild ($scalar)" This method accepts a scalar and calls addChild(Tree::Simple\->new($scalar) ) purely to save you the effort of needing to use \f(CW\*(C`Tree::Simple\->new(...)\*(C'\fR as the parameter. .IP "\fBaddChildren (@trees)\fR" 4 .IX Item "addChildren (@trees)" This method accepts an array of \fBTree::Simple\fR objects, and adds them to the children list. Like \f(CW\*(C`addChild\*(C'\fR this method will return its invocant to allow for method call chaining. .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 is verified to be a \fBTree::Simple\fR or \fBTree::Simple\fR derived object, if this condition fails, an exception is thrown. .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 arguments. 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 within the 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 the \f(CW\*(C`DESTROY\*(C'\fR method. See the \*(L"\s-1CIRCULAR REFERENCES\*(R"\s0 section for more information. .IP "\fBaddSibling ($tree)\fR" 4 .IX Item "addSibling ($tree)" .PD 0 .IP "\fBaddSiblings (@trees)\fR" 4 .IX Item "addSiblings (@trees)" .IP "\fBinsertSibling ($index, \f(CB$tree\fB)\fR" 4 .IX Item "insertSibling ($index, $tree)" .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. .SS "Accessor Methods" .IX Subsection "Accessor Methods" .IP "\fBgetNodeValue\fR" 4 .IX Item "getNodeValue" This returns the value stored in the node field of the object. .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 parent of the invocant. .Sp See also . .Sp Warning: This method includes the invocant, so it is not really all siblings but rather all children of the parent! .IP "\fBgetSiblingCount\fR" 4 .IX Item "getSiblingCount" Returns 0 if the invocant is the root node. Otherwise returns the count of siblings, which excludes the invocant. .Sp See also . .Sp Warning: This differs from scalar(parent\->\fBgetAllSiblings()\fR ) just above, which for some reason includes the invocant. I cannot change \fBgetAllSiblings()\fR now for a module first released in 2004. .IP "\fBgetDepth\fR" 4 .IX Item "getDepth" Returns a number representing the depth of the invocant 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 root node 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 parent of the invocant, 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 sibling list. Returns \-1 if the tree is the root. .SS "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 has a \*(L"parent\*(R" of \fB\s-1ROOT\s0\fR, returns false (0) otherwise. .IP "\fBisFistChild\fR" 4 .IX Item "isFistChild" Returns 0 if the invocant is the root node. .Sp Returns 1 if the invocant is the first child in the parental list of children. Otherwise returns 0. .IP "\fBisLastChild\fR" 4 .IX Item "isLastChild" Returns 0 if the invocant is the root node. .Sp Returns 1 if the invocant is the last child in the parental list of children. Otherwise returns 0. .SS "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, or until \f(CW$func\fR returns \f(CW\*(AqABORT\*(Aq\fR. If given, the function \f(CW$postfunc\fR will be applied to each child after the children of the child 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 6 \& $tree\->traverse(sub { \& my ($_tree) = @_; \& my $tag = $_tree\->getNodeValue(); \& print (("\et" x $_tree\->getDepth()), $tag, "\en"); \& return \*(AqABORT\*(Aq if \*(Aqfoo\*(Aq eq $tag; \& }); .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 ((\*(Aq \*(Aq x $_tree\->getDepth()), \& \*(Aq<\*(Aq, $_tree\->getNodeValue(),\*(Aq>\*(Aq,"\en"); \& }, \& sub { \& my ($_tree) = @_; \& print ((\*(Aq \*(Aq x $_tree\->getDepth()), \& \*(AqgetNodeValue(),\*(Aq>\*(Aq,"\en"); \& }); .Ve .Sp Note that aborting traverse is not recommended when using \f(CW$postfunc\fR because post-function will not be called for any nodes after aborting which might lead to less than predictable results. .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 compatibility. .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. .SS "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(\*(Aqvisit\*(Aq)\*(C'\fR). If these qualifications are not met, and exception will be thrown. We then run the Visitor \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. .SS "Cloning Methods" .IX Subsection "Cloning Methods" Cloning a tree can be an extremely 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, REF\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. .SS "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 necessary if your object has any children. See the section on \*(L"\s-1CIRCULAR REFERENCES\*(R"\s0 for more information. .IP "\fBfixDepth\fR" 4 .IX Item "fixDepth" Tree::Simple will manage the 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 sub-trees of the invocant, correcting the depth as it goes. .IP "\fBfixHeight\fR" 4 .IX Item "fixHeight" Tree::Simple will manage the 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 ancestors heights too. .IP "\fBfixWidth\fR" 4 .IX Item "fixWidth" Tree::Simple will manage the 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 ancestors widths too. .SS "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. .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 has the primary responsibility of 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 circular 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 decisions 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 the children to detach from it, however, if a child is destroyed it will not be detached from the parent. .SS "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 \*(Aquse_weak_refs\*(Aq; .Ve .PP And from that point on Tree::Simple will use weak references to allow for reference counting to clean things up properly. .PP For those who are unfamiliar 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 10 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | 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::Simple1). .PP Now, with weak references: .PP .Vb 10 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | 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 COVERAGE\*(R"\s0 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 the 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 \- For viewing Tree::Simple hierarchies in various output formats" 4 .IX Item "Tree::Simple::View - For viewing Tree::Simple hierarchies in various output formats" .IP "Tree::Simple::VisitorFactory \- Useful Visitor objects for Tree::Simple objects" 4 .IX Item "Tree::Simple::VisitorFactory - Useful Visitor objects for Tree::Simple objects" .IP "Tree::Binary \- If you are looking for a binary tree, check this one out" 4 .IX Item "Tree::Binary - If you are looking for a binary tree, 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 hierarchy, 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 \- " 4 .IX Item "FreeBSD Port - " .PD 0 .IP "Debian Package \- " 4 .IX Item "Debian Package - " .IP "Linux \s-1RPM\s0 \- " 4 .IX Item "Linux RPM - " .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. But it only comes with 1 sophisticated test, t/cut.and.paste.subtrees.t. 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 does not 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 cannot 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"" and ""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 unnecessary recursion." 4 .IX Item "Thanks to Mark Thomas for his insight into how to best handle the height and width properties without unnecessary 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 "REPOSITORY" .IX Header "REPOSITORY" . .SH "SUPPORT" .IX Header "SUPPORT" Bugs should be reported via the \s-1CPAN\s0 bug tracker at .PP .SH "AUTHOR" .IX Header "AUTHOR" Stevan Little, .PP Rob Kinyon, .PP Ron Savage has taken over maintenance as of V 1.19. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2004\-2006 by Infinity Interactive, Inc. .PP .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.