/ 
File-LinkTree-Builder-0.005
River stage zero No dependents
/ File::LinkTree::Builder

NAME

File::LinkTree::Builder - builds a tree of symlinks based on file metadata

VERSION

version 0.005

SYNOPSIS

ACHTUNG!: This module is young. The interface may yet change a little, probably mostly around the iterator. Rely on it at your own risk.

This module provides a way to build symlink trees. Given a path to a set of files, a way to find file metadata, and a list of symlink paths to produce, this module will build the symlink trees.

File::LinkTree::Builder->build_tree({
  storage_root    => 'trove/files',
  link_root       => 'trove/links',
  metadata_getter => \&coderef,
  link_paths      => [
    [ qw(author subject) ],
    [ qw(subject author) ],
  ],
});

METHODS

build_tree

File::LinkTree::Builder->build_tree(\%arg);

This method builds a tree of symlinks based on the metadata on the files in the storage root. It is exactly equivalent to:

File::LinkTree::Builder->new(\%arg)->run;

Valid arguments are:

storage_root    - this is a path in which to start looking for files
                  can be an arrayref; can also be given as storage_roots
file_filter     - this filters out unwanted files; see File::Next
metadata_getter - this is a coderef that gets metadata; see below!
link_root       - this is a path in which the link trees will be built
link_paths      - this is an arrayref of metadatum names to use; see below!
hardlink        - if true, the link tree is hard, not symbolic, links
on_existing     - if 'skip' do not write links that already exist
                  if 'die', go ahead and try, thus dying; default: 'die'

new

This method returns a new link tree builder, which exists primarily to have is "run" method called. It accepts exactly the same arguments as "build_tree", above.

metadata_for_file

my $hashref = $builder->metadata_for_file($filename);

Given a filename, this method returns the metadata for a file. The default implementation is to call the coderef given to the object constructor.

storage_roots

This method returns the path in which to start looking for files that the link tree will point to. This can also be called as storage_root for historical reasons.

This method returns the path in which the link tree is to be built.

iterator

This method returns an iterator which, when called as a coderef, returns the next file to process.

my @paths = $link_paths;

This method returns a list of arrayrefs, each of which contains metadata names. These names are used to construct paths under which symlinks will be created to the files found in the storage root.

This method returns true if we've been asked to produce hardlinks.

run

This method works through the iterator, building the needed symlinks for each file.

set_metadata_getter

This method is called during initialization to set the object's metadata getting routine. It's provided as a method so that subclasses with fixed metadata-getting routines can croak if one is provided.

TODO

This module needs a bunch of refactoring and probably some better thinking-out in general.

Specifically, I'd like to make it easier to have relative symlinks.

AUTHOR

Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2007 by Ricardo SIGNES.

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