NAME

Path::Find - Easily find files in a directory tree

SYNOPSIS

    use Path::Find;

    # Recursively find all PNG files
    my @list = path_find( $dir, "*.png" );

    # Find all the jpegs, ignoring case
    @list = path_find( $dir, qr/\.jpe?g$/i );

    # Find all .cnf files in .directories
    @list = path_find( $dir, qr(/^\./), qr/\.cnf$/ );

DESCRIPTION

Path::Find is the simplest way to recursively list all the files in a directory and its subdirectories.

FUNCTIONS

path_find

    @list = find_path( $dir );
    @list = find_path( $dir, $fileglob );
    @list = find_path( $dir, $dirglob, $fileglob );

Recurses $dir and all subdirectories that match $dirglob, returning a list of all files that match $filegob.

$dir

Top directory to search.

$fileglob

Glob or other thing to select which files are returned. Passed to "matchable". Defaults to *.

$dirglob

Glob or other thing to select which subdirectories are recursed. Passed to "matchable". Defaults to *.

Returns the list of files, with $dir prepended.

The globs ($fileglob and $dirglob maybe a string containing a BSD-style glob:

    @list = path_find( "/some-dir", "*.png" );

They may be a regex:

    @list = path_find( "/other-dir", qr(\.png$) );

They may be a coderef:

    @list = path_find( $TOP, sub { $DIRS{$_[0]} }, sub { 1 } );

They may be an object:

    my $dirmatch = My::DirMatch->new;
    my $filematch = My::FileMatch->new;
    @list = path_find( $TOP, $dirmatch, $filematch );

matchable

Convert a glob or other thing into a coderef useful for matching a file or directory. my $sub = matchable( $glob );

Convert a glob into a coderef useful for matching a file or directory. $glob may be one of the following:

Glob string

    my $sub = matchable( "*.txt" );

Uses Text::Glob to convert the string into a regex, then builds a subroutine from that. Not that a leading * does not match a leading ., eg *.txt will not match .foo.txt.

Regexp

    my $sub = matchable( qr(^honk.+txt$) );

Builds a subroutine that matches the directory entry to the given regex. Note that you must anchor the regex if this is important.

CODE

    my $sub = matchable( sub { 
            my( $entry, $directory, $fullname, $depth ) = @_;
            return 1 if length( $entry ) > 3;
            return;
        } );

Returns the coderef as-is. "find_path" will invoke the subref with the following parameters:

$entry

Current directory entry being matched. If the file or directory is called /some/dir/entry then $entry will be just "entry".

$directory

Full path of the directory that the current entry being matched. If the file or directory is called /some/dir/entry then $directory /some/dir.

$fullname

Full path of the directory entry being matched. If the file or directory is called /some/dir/entry then $fullname is the just that, /some/dir/entry.

$depth

Number of subdirectories between the current $directory and the top directory passed to find_path. Invocations in the top directory have $depth=0.

Object

    my $object = MyClass->new;
    my $sub = matchable( $object );

    package MyClass;

    sub new { return bless {}, shift }

    sub match 
    {
        my( $self, $entry, $directory, $fullname ) = @_;
        return 1 if $entry eq 'yes';
        return;
    }

Builds a subroutine that calls object method match for each directory entry. The parameters are the same as CODE invocations, but with the object being first parameter, as is customary.

SEE ALSO

"glob_to_regex" in Text::Glob

AUTHOR

Philip Gwyn, <gwyn -AT- cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2023 by Philip Gwyn. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.26.3 or, at your option, any later version of Perl 5 you may have available.

cpanm Path::Find

perl -MCPAN -e shell
install Path::Find