view release on metacpan or  search on metacpan

lib/Badger/Filesystem/Visitor.pm  view on Meta::CPAN

        files => 1,                 # collect all files
        dirs  => 0,                 # ignore all dirs
    );

    $dir->visit( 
        files => '*.pm',            # collect all .pm files
        dirs  => 0,                 # ignore all dirs
    );

    $dir->visit(
        files   => '*.pm',          # as above, no dirs are collected
        dirs    => 0,               # but we do enter into them to 
        in_dirs => 1,               # find more files
    );

    $dir->visit( 
        files       => '*.pm',      # collect *.pm files
        dirs        => 0,           # don't collect dirs
        in_dirs     => 1,           # do recurse into them
        not_in_dirs => '.svn',      # but don't look in .svn dirs
    );
    
    $dir->visit(
        files   => 'foo'            # find all files named 'foo'
        dirs    => qr/ba[rz]/,      # and all dirs named 'bar' or 'baz'
        in_dirs => 1,               # recurse into subdirs
    );

You can also define subroutines to filter the files and/or directories that
you're interested in. The first argument passed to the subroutine is the
L<Badger::Filesystem::File> or L<Badger::Filesystem::Directory> object being
visited.  The second argument is a reference to the visitor object. 

In the following example, we collect files that are smaller than 420 bytes in
size, and directories that contain a F<metadata.yaml> file.

    $dir->visit(
        files   => sub { shift->size < 420 },
        dirs    => sub { shift->file('metadata.yaml')->exists }
        in_dirs => 1,
    );

You can also specify a reference to a list of items, each of which can be 
a simple flag (0/1), a name to match, regular expression or subroutine
reference.  Each will be tested in turn until the I<first> one matches.
If none match then the file or directory will be ignored.

    $dir->visit(
        files   => ['foo', qr/wiz/i, \&my_file_sub ],
        dirs    => [ qr/ba[rz]/, \&my_dir_sub ],
        in_dirs => 1,
    );

In addition to the inclusive matches show above, you can also tell the visitor
what to exclude. You can use any of the same pattern specifications as for the
inclusive options (0/1 flags, names, regexen, subroutines, or list refs
containing any of the above).

    $dir->visit( 
        no_files    => '*.bak',     
        no_dirs     => ['tmp', qr/backup/i],
        not_in_dirs => ['.svn', '.DS_Store'],
    );

When the visit is done, the L<collect()> method can be called to return
a list (in list context) or reference to a list (in scalar context) of the 
items that were collected.  The list will contain L<Badger::Filesystem::File>
and L<Badger::Filesystem::Directory> objects.

    my $collect = $visitor->collect;        # list ref in scalar context
    my @collect = $visitor->collect;        # list in list context

=head1 CONFIGURATION OPTIONS

NOTE: I'm planning the add the 'accept', 'ignore', 'enter', and 'leave'
aliases for 'files', 'no_files', 'in_dirs' and 'not_in_dirs'.  Can't think
of better names for 'dirs' and 'no_dirs' though...

=head2 files / accept (todo)

A pattern specifier indicating the files that you want to match.

=head2 no_files / ignore (todo)

A pattern specifier indicating the files that you don't want to match.

=head2 dirs / directories 

A pattern specifier indicating the directories that you want to match.

=head2 no_dirs / no_directories

A pattern specifier indicating the directories that you don't want to match.

=head2 in_dirs / in_directories / enter (todo)

A pattern specifier indicating the directories that you want to enter to 
search for further files and directories.

=head2 not_in_dirs / not_in_directories / leave (todo)

A pattern specifier indicating the directories that you don't want to enter to
search for further files and directories.

=head2 at_file

A reference to a subroutine that you want called whenever a file of interest
(i.e. one that is included by L<files> and not excluded by L<no_files>) is
visited.  The subroutine is passed a reference to the visitor object and
a reference to a L<Badger::Filesystem::File> object representing the file.

    $dir->visit(
        at_file => sub {
            my ($visitor, $file) = @_;
            print "visiting file: ", $file->name, "\n";
        }
    );

=head2 at_dir / at_directory

A reference to a subroutine that you want called whenever a directory of