NAME

Liz::Tree - create structures of ID's


SYNOPSIS

 use Liz::Tree;
 $tree = new Liz::Tree;


EXAMPLES


DESCRIPTION

The Liz::Tree package allows a tree-structure to be created for any ID's that are compatible with the Liz::SQL package.


CONSTRUCTOR METHODS

The following methods create new objects.


trees

Return list of file identification names of all tree(sets) in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 wildcard specification to match
   (default: all)
Output Parameters

 1 reference to list of identification names in the current database
 2 reference to hash with full names
 2 reference to hash with version info
Example

 $hn = new HN;
 ($id,$name) = $hn->Trees;
 $trees = @{$id};
 print "All $trees trees in Hospitality Net:\n";
 foreach( @{$id} ) {
   print " Tree '$$name{$_}' ($_)\n";
 }

In HN.pm:

 sub Trees { Liz::Tree->trees( @_ ) }


new

Create a new Liz::Tree object. Normally not called by itself, but with the within a client module.

Input Parameters

 1 Liz::SQL compatible object to be used
 2 identification name of tree
   (default: the default name of the tree object)
Output Parameters

 1 instantiated object
 2 flag: whether the table was just created
Example

 $tree = new Liz::Tree( 'ModPerl' );


Cache

Create a cache object that contains all possible structure information for the whole tree, or from a specific parentID down. It in fact creates a Liz::Tree::Cache object, see that module for more information.

Input Parameters

 1 parent ID of which to create a cache
   (default: list from top)
 2 number of levels of recursion for creation of cache
   (default: 0, -1 for maximum number of levels, >0 limited number of levels)
 3 maximum number of ID's to obtain
   (default: unlimited)
Output Parameters

 1 instantiated cache object
Example

 $cache = $tree->Cache;
 $cache = $tree->Cache( $parentID );


CONTENT METHODS

The following methods allow changes to information that is associated with the list object.


reset

Reset all ID information in the table.

Example

 $tree->Reset;
 print "All structure to messages has been removed\n";


AddID

Add an ID at the specified position. Move the ID to the indicated position if the ID is already in the list.

Input Parameters

 1 ID to be added or moved
 2 ID of parent to which this ID belongs
   (default: 0 = top level)
 3 ID (if top level) after which this ID should be added
   (default: at end)
Example

 $tree->AddID( $newthreadID );
 $tree->AddID( $newresponseID,$parentID );


DeleteID

Delete an ID and all the ID's that have that ID as a (grand) parent. Optionally allows the ID's below to be saved: in that case they will appended to the children list of the parent of the ID being deleted.

Input Parameters

 1    ID to be deleted
 2    flag: whether to delete just this ID
      (default: delete all ID's below also)
Output Parameters

 1..N ID's that were deleted
Example

 @removedID = $tree->DeleteID( $deleteID );


ExistsID

Returns whether an ID exists in the list.

Input Parameters

 1 ID to check for
Output Parameters

 1 flag: true if ID found
Example

 if( $tree->ExistsID( $isitID ) ) {
   print "ID $isitID exists in this list\n";
 }


ChildIDs

Return the child ID's of an ID

Input Parameters

 1   ID of which to obtain children
     (default: top = 0)
 2   flag: whether to obtain all grandchildren also
     (default: just own children)
Output Parameters

 1..N ID's of the children of given ID
Example

 @childID = $tree->ChildIDs( $currentID );


DIRECTION METHODS

The following methods can be used to ``move'' between messages in the Liz::Tree object.


NextID

Return the ID of the next ID in the tree. By default, this is the first child of the current ID, or the next ID if there are no children. If children search is inhibited, then the next ID on the same level will be returned.

The ID of the next ID will always be returned, unless the current ID is actually the very, very last ID in the tree.

Input Parameters

 1 ID of which to return the next ID
 2 flag: whether to not search for children
   (default: search for children)
Output Parameters

 1 next ID
   (undef = no next ID)
Example

 $nextID = $tree->NextID( $currentID );


PreviousID

Return the ID of the previous ID in the tree

Input Parameters

 1 ID of which to return the previous ID
Output Parameters

 1 previous ID
   (undef = no previous ID)
Example

 $previousID = $tree->PreviousID( $currentID );


OriginalID

Return the ID of the original ID (to which the first child was given) in the tree.

Input Parameters

 1 ID of which to return the original ID
Output Parameters

 1 original ID
   (undef = invalid ID to start with)
Example

 $originalID = $tree->OriginalID( $currentID );


ParentID

Return the parent ID of an ID

Input Parameters

 1 ID of which to obtain the parent ID
Output Parameters

 1 parent ID
   (undef: invalid ID specified)
Example

 $parentID = $tree->ParentID( $currentID );


NextThreadID

Return the first ID in the next thread

Input Parameters

 1 ID of which to return the first ID in next thread
 2 original ID
   (default: lookup)
Output Parameters

 1 first ID in next thread
   (undef = no next thread)
Example

 $nextthreadID = $tree->NextThreadID( $currentID );


PreviousThreadID

Return the first ID in the previous thread

Input Parameters

 1 ID of which to return the first ID in previous thread
 2 original ID
   (default: lookup)
Output Parameters

 1 first ID in previous thread
   (undef = no previous thread)
Example

 $previousthreadID = $tree->PreviousThreadID( $currentID );


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )

With contributions by:

- Sjoerd Lawende ( sjoerd@xxLINK.nl )


COPYRIGHT

(C) 1998-1999 International Network Consultants


HISTORY

Version 0.18, 25 November 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Cache.

Version 0.17, 30 September 1999

Now no longer puts Exporter in ISA: it was not needed.

Version 0.16, 17 August 1999

New method trees added: list all possible tree(sets) in the client module.

Method new now also returns the created flag.

Support for field ``TOKEN'' added.

Version 0.15, 16 August 1999

Method new now uses the Liz::SQL ``new'' method to create the object.

Version 0.14, 15 August 1999

Made regular expressions constant were possible, thereby increasing execution speed at the expense of memory footprint.

Change to new source typography.

Version 0.13, 30 July 1999

Changed field 'responses' to 'children' in update query of method AddID.

Version 0.12, 9 July 1999

Changed CREATE TABLE to new Liz::SQL 'create' method format.

Version 0.11, 23 June 1999

Changed from using method ``Exists'' to ``Count'' in method new to allow for a much faster check for the existence of a table.

Version 0.1, 19 January 1999

First version based on the Liz::Forum::List module.