/ 
Tree-File-0.111
River stage zero No dependents
/ Tree::File

NAME

Tree::File - store a data structure in a file tree

VERSION

version 0.111

$Id$

SYNOPSIS

use Tree::File::Subclass;

my $tree = Tree::File::Subclass->new($treerot);

die "death mandated" if $tree->get("/master/die")

print "Hello, ", $tree->get("/login/user/name");

$tree->set("/login/user/lastlogin", time);
$tree->write;

DESCRIPTION

This module stores configuration in a series of files spread across a directory tree, and provides uniform access to the data structure.

It can load a single file or a directory tree containing files as leaves. The tree's branches can be returned as data structures, and the tree can be modified and rewritten. Directory-based branches can be collapsed back into files and file-based branches can be exploded into directories.

METHODS

Tree::File->new($treeroot, \%arg)

This loads the tree at the named root, which may be a file or a directory. The %arg hash is optional, the following options are recognized:

readonly  - if true, set and delete methods croak (default: false)
preload   - the number of levels of directories to preload (default: none)
            pass -1 to preload as deep as required
found     - a closure called when a node or value is found; it is passed the
            Tree::File object, the id requested, and the data retrieved; it
            should apply any transformations and return the 'real' value desired.
not_found - a closure called if a node cannot be found; it is passed the id
            requested and the root of the last node reached; by default,
            Tree::File will return undef in this situation

$tree->load_file($filename)

This method is used internally by Tree::File subclasses, which must implement it. Given the name of a file on disk, this method returns the data structure contained in the file.

$tree->get($id)

This returns the branch with the given name. If the name contains slashes, they indicate recursive fetches, so that these two calls are identical:

$tree->get("foo")->get("bar")->get("baz");

$tree->get("foo/bar/baz");

Leading slashes are ignored.

If a second, true argument is passed to get, any missing data structures will be autovivified as needed to get to the leaf.

$tree->set($id, $value)

This sets the identified branch's value to the given value. Hash references are automatically expanded into trees.

$tree->delete($id)

This method deletes the identified branch (and returns the deleted value).

$tree->move($old_id, $new_id)

This method deletes the value at the old id and places it at the new id.

$tree->path()

This method returns the path to this node from the root.

$tree->basename()

This method retuns the base name of the node. (If, for example, the path to the node is "/things/good/all" then its base name is "all".)

$tree->node_names()

This method returns the names of all the nodes beneath this branch.

$tree->nodes()

This method returns each node beneath this branch.

$tree->branch_names

$tree->branches

This method returns all the nodes on this branch which are also branches (that is, are also Tree::File objects).

$tree->data()

This method returns the entire tree of data as an unblessed Perl data structure.

$tree->write($basedir)

This method forces the object to write itself out to disk. It will write out branches to directories if a directory for the branch already exists, or if it was orginally loaded as a directory.

$tree->write_file($filename)

This method is used by Tree::File's write method. It must be implement in subclasses of Tree::File. Given the name of a file on disk and a data structure, this method writes the data structure to the file.

$tree->type($type)

This method returns the branch type for the given branch. If $type is defined and one of "dir" or "file" it will set the type and return the new value.

$tree->explode()

$tree->collapse()

These methods set the type of the branch to "dir" and "file" respectively.

TODO

  • symlinks and references

  • serialization through delegation, not inheritance

  • make locking methods pluggable

  • callback for determining which files to skip

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

BUGS

Please report any bugs or feature requests to bug-tree-file@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT

Copyright 2005 Ricardo Signes, All Rights Reserved.

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