NAME

Tree::Simple::Manager - A class for managing multiple Tree::Simple hierarchies

SYNOPSIS

  use Tree::Simple::Manager;
  
  # use the default index and default views
  my $tree_manager = Tree::Simple::Manager->new(
        "Organizational Level" => {
            tree_file_path => "data/organization_level.tree",        
            tree_root      => Tree::Simple->new(Tree::Simple->ROOT),
        }
  );    

  # specify your own index class and your own view class
  my $tree_manager = Tree::Simple::Manager->new(
        "Organizational Level" => {
            tree_file_path => "data/organization_level.tree",        
            tree_root      => Tree::Simple->new(Tree::Simple->ROOT),
            tree_index     => "My::Tree::Indexing::Class",
            tree_view      => "My::Tree::Simple::View::Class",            
        }
  );   

DESCRIPTION

This is a class for managing multiple Tree::Simple hierarchies at a time. It integrates several Tree::Simple classes together to attempt to make things easier to manage. This is the third release of this module. It is currently tailored to my current needs, and will likely get more flexible later on. If you want to use it, and need it to work differently, let me know and I can try to help, or you can submit a patch.

The basic idea of this module is that you can load and store Tree::Simple hierarchies by name. You use Tree::Parser to load the hierarchy from disk, the tree is then indexed for fast node retrieval by Tree::Simple::Manager::Index. If you need a Tree::Simple::View of the tree, you can create one with this class, or get the Tree::Simple::View subclass which is associated with this tree.

METHODS

new (%tree_configs)

This will load all the tree heirachies from disk, index them. The config format is show above in SYNOPSIS, and described in detail below:

Required Fields

tree_root

This must be a Tree::Simple object (or a subclass of Tree::Simple) it will serve as the root of this particular tree.

tree_file_path

This must be a valid path to a tree file which Tree::Parser will understand.

Optional Fields

tree_index

This must be a package name for a Tree::Simple::Manager::Index subclass. The default is Tree::Simple::Manager::Index.

tree_view

This must be a package name for a Tree::Simple::View subclass. The default is Tree::Simple::View::DHTML.

tree_parse_filter

This must be a subroutine reference which is compatible with Tree::Parser's parse filters. It's first argument is an Array::Iterator object which has all the lines in the tree file. It's second argument is the tree class name as specified in the tree_root field. Here is an example custom parse filter:

  # this will parse tree files formated like this:
  # uid:node
  #     uid:node
  #             uid:node
  #     uid:node
  tree_parse_filter => sub {
      my ($line_iterator, $tree_type) = @_;
      my $line = $line_iterator->next();
      my ($tabs, $id, $node) = ($line =~ /(\t+)?(\d+)\:(.*)/);
      my $depth = 0;
      $depth = length $tabs if $tabs;
      my $tree = $tree_type->new($node);
      $tree->setUID($id);
      return ($depth, $tree);                  
  }
        

The default parse filter will parse tree files which look like this:

  uid    node
  uid        node
  uid            node
  uid        node

Where the UID is first, followed by a tab, then either the node value or more tabs to indicate the tree depth.

tree_cache_path

This must be a valid file path, and can be used to cache a parsed tree. It serializes the tree using Storable and then if a valid cache file is present, it will us that instead of re-parsing. This can potentially save a lot of time during startup for large trees.

tree_meta_data

This is a HASH ref whose keys are tree ids (fetchable through Tree::Simple::Manager::Index) and then accompanying metadata (which can pretty much be anything actually).

tree_file_encoding

This will pass on the encoding type to be used when reading in the file with Tree::Parser.

getTreeList

This will return a list of names of the tree hierarchies currently being managed.

getRootTree ($tree_name)

This will return the root of the tree found at $tree_name.

getTreeIndex ($tree_name)

This will return the Tree::Simple::Manager::Index object found at $tree_name.

getTreeByID ($tree_name, $tree_id)

This will ask the tree index (found at $tree_name) for the tree whose id is $tree_id.

getTreeViewClass ($tree_name)

This will return the Tree::Simple::View class associated with $tree_name.

getNewTreeView ($tree_name, @view_args)

This will return an instance of the Tree::Simple::View class associated with $tree_name, passing in the @view_args to the view constructor.

isTreeLoadedFromCache ($tree_name)

This will return true if the tree has been loaded from cache with the tree_cache_path option.

BUGS

None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.

SEE ALSO

Tree::Parser
Tree::Simple
Tree::Simple::WithMetaData
Tree::Simple::View::DHTML

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2004-2007 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.