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


    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";
        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";
        -d => sub {
            print "Directory: $_[0]\n";
        # 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";



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.


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

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

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

See "RULES" for a detailed description.


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

The return value of this function is unimportant.


Two constants are exported: IGNORE and MATCH.

See "Actions" for usage.


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.


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.


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.


None known. Bug reports are welcome.

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


Dylan William Hardison <>


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


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.