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


version 0.006


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.

    storage_root    => 'trove/files',
    link_root       => 'trove/links',
    metadata_getter => \&coderef,
    link_paths      => [
      [ qw(author subject) ],
      [ qw(subject author) ],




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


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'


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.


  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.


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.


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.


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


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.


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.


Ricardo SIGNES <>


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.