Arch::Inventory(3pm)					User Contributed Perl Documentation				      Arch::Inventory(3pm)

NAME

       Arch::Inventory - class representing a tree inventory

SYNOPSIS

	   use Arch::Inventory qw(:category :type);

	   my $inv = Arch::Inventory->new;  # use cwd
	   print Arch::Inventory->to_string($inv->get_root_entry), "
";
	   print $inv->get_listing;

       or (most commonly):

	   use Arch::Tree;

	   my $tree = Arch::Tree->new;
	   my $inv = $tree->get_inventory;
	   print $inv->get_listing;

DESCRIPTION

       Arch::Inventory generates a tree inventory.

       An inventory is a tree structure of elements, each representing a single directory entry of the source tree. Each inventory entry is
       described by an hash with the following fields:

       category
	   The classification of the tree element. category can be one of TREE, SOURCE, PRECIOUS, BACKUP or JUNK.

       untagged
	   A boolean value indicating whether the element was first classified as SOURCE but lacked an inventory id.

       type
	   The tree element type. type can be one of FILE, DIRECTORY or SYMLINK.

       path
	   The complete path to the tree element relative to the inventory base directory.

       id  The elements inventory id. May be "undef".

       children
	   A hash of the elements direct children, idexed by their last path element.

	   This field exists for elements of type DIRECTORY only.

       The category and type constants can be conveniently imported using the tags ":category" and ":type".

	   use Arch::Inventory qw(:category :type);

METHODS

       The following methods are available:

       new, directory, get_root_entry, get_entry, get_listing, annotate_fs, foreach, dump, to_string.

       new [$dir]
	   Create an inventory for $dir or the current directory if $dir is not specified.

       directory
	   Returns the inventories base directory as passed to new.

       get_root_entry
	   Returns the inventory element for the base directory.

	   The root entry always has the following properties:

	       $root = {
		   category => TREE,	   # if {arch} exists, SOURCE otherwise
		   untagged => 1,
		   type     => DIRECTORY,
		   path     => '',
		   id	    => undef,
		   children => { ... },
	       }

       get_entry $path
       get_entry @path_elements
	   Returns the inventory element for the specified path. The path may either be given as a single string or as a list of path elements.

	   If the element does not exist "undef" is returned.

	   Using an empty or no path is equivalent to calling get_root_entry.

       get_listing
	   Generates a textual inventory listing equivalent to the output of

	       tla inventory -tspbju -B --kind --ids --untagged

	   Note: The output order is not equivalent to tla. Instead of strict ASCII order of path names, a directory entry is always directly
	   followed by its child entries. Entries with the same parent entry are ASCII ordered.

       annotate_fs
       annotate_fs $entry
	   Add filesystem information to $entry or every inventory entry if none is provided. This adds the fields stat and symlink to the
	   annotated entries which contain the output of lstat and readlink respectively.

       foreach $coderef
	   Execute $coderef for every inventory entry, passing the entry as $_[0].

       dump
	   Generates a dump of the inventory structure using Data::Dumper.

       to_string $inventory_element
	   Generates an inventory line for the inventory element as produced by tla.

BUGS

       Awaiting for your reports.

AUTHORS

       Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).

       Enno Cramer (uebergeek@web.de--2003/arch-perl--devel).

SEE ALSO

       For more information, see tla, Arch::Util.

perl v5.10.1							    2005-10-23						      Arch::Inventory(3pm)