This is meant to be a full-featured N-ary tree representation with configurable error-handling and a simple events system that allows for transparent persistence to a variety of datastores. It is derived from Tree::Simple, but has a simpler interface and much, much more.

This will add all the @nodes as children of $tree. $options is a optional unblessed hashref that specifies options for add_child(). The optional parameters are:

at

This specifies the index to add @nodes at. If specified, this will be passed into splice(). The only exceptions are if this is 0, it will act as an unshift(). If it is unset or undefined, it will act as a push(). Lastly, if it is out of range (too negative or too big [beyond the number of children]) the child is not added, and an error msg will be available in "last_error()".

This will return a hashref that can be used to store whatever metadata the client wishes to store. For example, Tree::Persist::DB uses this to store database row ids.

It is recommended that you store your metadata in a subhashref and not in the top-level metadata hashref, keyed by your package name. Tree::Persist does this, using a unique key for each persistence layer associated with that tree. This will help prevent clobbering of metadata.

Call this when you wish to report an error using the currently defined error_handler for the tree. The only guaranteed parameter is an error string describing the issue. There may be other arguments, and you may certainly provide other arguments in your subclass to be passed to your custom handler.

Use this error handler if you want to have quiet error-handling. The "last_error()" method will retrieve the error from the last operation, if there was one. If an error occurs, the operation will return undefined.

This will trigger an event of type $type. All event handlers registered on $tree will be called with parameters of ($actor, @args). Then, the parent will be notified of the event and its handlers will be called, on up to the root.

This allows you specify an event handler on the root and be guaranteed that it will fire every time the appropriate event occurs anywhere in the tree.

If you call $self->parent on a root node, it will return a Tree::Null object. This is an implementation of the Null Object pattern optimized for usage with Tree. It will evaluate as false in every case (using overload) and all methods called on it will return a Tree::Null object.

I have deliberately chosen to not implement the Visitor pattern as described by Gamma et al. Given a sufficiently powerful traverse() and the capabilities of Perl, an explicit visitor object is almost always unneeded. If you want one, it is easy to write one yourself. Here is a simple one I wrote in 5 minutes: