/ 
Path-Find-0.04
River stage zero No dependents
/ Path::Find

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.