NAME

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

VERSION

version 0.006

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.

link_root

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.

link_paths

  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.

hardlink

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.