NAME

File::Find::Match - Perform different actions on files based on file name.

SYNOPSIS

    #!/usr/bin/perl
    use strict;
    use warnings;
    use File::Find::Match qw( :constants );
        use File::Find::Match::Util qw( filename );

    my $finder = new File::Find::Match(
        filename('.svn') => sub { IGNORE },
        qr/\.pm$/ => sub {
            print "Perl module: $_[0]\n";
            MATCH;
        },
        qr/\.pl$/ => sub {
            print "This is a perl script: $_[0]\n";
            # let the following rules have a crack at it.
        },
        qr/filer\.pl$/ => sub {
            print "myself!!! $_[0]\n";
            MATCH;
        },
        -d => sub {
            print "Directory: $_[0]\n";
            MATCH;
        },
        # default is like an else clause for an if statement.
        # It is run if none of the other rules return MATCH or IGNORE.
        default => sub {
            print "Default handler.\n";
            MATCH;
        },
    );

    $finder->find;

DESCRIPTION

This module is allows one to recursively process files and directories based on the filename. It is meant to be more flexible than File::Find.

METHODS

new($predicate => $action, ...)

Creates a new File::Find::Match object.

new() accepts a list of $predicate => $action pairs.

See "RULES" for a detailed description.

find(@dirs)

Start the breadth-first search of @dirs (defaults to '.' if empty) using the specified rules.

The return value of this function is unimportant.

EXPORTS

Two constants are exported: IGNORE and MATCH.

See "Actions" for usage.

RULES

A rule is a predicate => action pair.

A predicate is the code (or regexp, see below) used to determine if we want to process a file.

An action is the code we use to process the file. By process, I mean anything from sending it through a templating engine to printing its name to STDOUT.

Predicates

A predicate is one of: a Regexp reference from qr//, a subroutine reference, or a string.

Naturally for regexp predicates, matching occures when the pattern matches the filename.

For coderef predicates, the coderef is called with one argument: the filename to be matched. If it returns a true value, the predicate is true. Else the predicate is false.

The 'default' string predicate is magical. It must only be specified as a predicate once, and it is called after all predicates, regardless of the order.

Any other string will be evaluated as perl code. In addition, $_ will be set to the first argument. Thus a predicate of '-r' is the same as sub { -r $_[0] } (because -r defaults to using $_).

Any exceptions (e.g. calling die(), or synax errors) within the eval'd perl code will be raised to the caller.

Actions

An action is just a subroutine reference that is called when its associated predicate matches a file. When an action is called, its first argument will be the filename.

If an action returns IGNORE or MATCH, all following rules will not be tried. You should return IGNORE when you do not want to recurse into a directory, and MATCH otherwise. On non-directories, both MATCH and IGNORE do the same thing: they prevent the next rule from being tried.

If an action returns niether IGNORE nor MATCH, the next rule will be tried.

BUGS

None known. Bug reports are welcome.

Please use the CPAN bug ticketing system at http://rt.cpan.org/. You can also mail bugs, fixes and enhancements to <bug-file-find-match at rt.cpan.org>.

AUTHOR

Dylan William Hardison <dhardison@cpan.org>

http://dylan.hardison.net/

SEE ALSO

File::Find::Match::Util, File::Find, perl(1).

COPYRIGHT and LICENSE

Copyright (C) 2004, 2005 Dylan William Hardison. All Rights Reserved.

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

cpanm File::Find::Match

perl -MCPAN -e shell
install File::Find::Match