NAME

File::Set - Mange/build a set of files from a list of file/directories

SYNOPSIS

  use File::Set;

  $FS = File::Set->new();

  # Add directories (and implicitly all files and sub-dirs) to file set
  $FS->add('/etc');
  $FS->add('/usr/lib', '/usr/include');
  # Add files in directory (not recursive);
  $FS->add({ recurse => 0 }, '/usr/local/bin');

  # Exclude particular files/directories
  $FS->exclude('/usr/include/linux', '/etc/shadow');

  # Add/exclude from file (see below for file format)
  $FS->add_from_file('/tmp/config');

  # List files, calling callback for each dir/file
  $FS->list($self, \&list_callback, 0);

  # Save a list of checksums for all files/directories
  $FS->save_checksum_db('/tmp/checksumdb');

  # Compare a list against a previously saved checksum db
  #  and call callback for added/deleted/changed files
  $FS->compare_checksum_db('/tmp/checksumdb', \&callback)

  sub list_callback {
    my ($self, $prefix, $path, $type, $stat) = @_;
    ... called back for each file/dir/etc found ...
  }

DESCRIPTION

This module is designed to build and manipulate a set of files from a list of input directories and files. You can specify whether directories should be recursed or not, or specific sub-directories ignored.

METHODS

new()

Create a new fileset object. Any parameters are passed straight to the add() method

prefix($path)

Sets a path 'prefix' that's prepended to all paths before they are used.

add([ $Opts ], $path1, $Path2, ...)

Add the given paths to the file set.

$Opts is an option hash-reference of options.

recurse: Set if we should recurse into sub-folders as well. True by default
exclude: Set if we should exclude this file/path rather than add it

exclude([ $Opts ], $path1, $Path2, ...)

Exclude the given paths from the file set.

Like calling add() with the exclude option set to true

add_from_file($file)

Open the given file and add the paths to the fileset

The file can have:

Blank lines which are ignored
Lines beginning with # which are ignored
A line with a single path to a file/directory.

Optionally each line with a path can begin with:

!: To exclude the path rather than add it
@: To add the path non-recursively

get_path_list()

Return an array of all paths added/excluded

Each item as an array-ref of 2 items. The first item is the path and the second item is the hash-ref of options

canon_path($path1, $Path2, ...)

Cleanup the given paths to a consistent form

list($Context, $Callback, $ErrorHandler)

The main method call. Iterates through all dirs, sub-dirs and files added through add() but not excluded through exclude()

For each file/directory calls code-ref $Callback passing $Context as the first parameter. Additional parameters are:

$Prefix

Prefix set with the prefix() call or '' if none

$Path

Full path of this file/directory

$Type

A string describing the type of the file/dir

f - a file
d - a directory
l - a symlink
u - other

$Stat

A hash-ref of information from the lstat() system call: Dev Ino Mode NLink Uid Gid RDev Size ATime MTime CTime BlkSize Blocks

The $ErrorHandler parameter controls error handling during the recursion. This can happen for instance if files/directories are deleted during the traversal.

false (eg undef/0/""): If not passed or false value, then any errors are ignored
true (eg 1): If true, then any errors cause a die to occur
sub-ref: If a sub ref, then the sub ref is called with the file/directory name that went missing during the traversal

save_checksum_db($DbFile)

Uses the list() method to iterate through added paths, and outputs a checksum of information about all dirs/files to $DbFile.

For all files this includes mode, gid, uid, size. For files this also includes the md5 checksum.

Can be used for the c<compare_checksum_db()> call below

compare_checksum_db($DbFile, $Context, $Callback)

Uses the list() method to iterate through added paths, and compares to the contents of the $DbFile file. If any files or directories have changed, calls the $Callback code-ref with $Context as the first parameter. Additional parameters are:

$Action

Action that occured on the file