NAME

SYNOPSIS

    use Badger::Filesystem 'FS';
    
    my $controls = {
        files       => '*.pm',           # collect all *.pm files
        dirs        => 0,                # ignore dirs
        in_dirs     => 1,                # but do look in dirs for more files
        not_in_dirs => ['.svn', '.git'], # don't look in these dirs
    };
    
    my @files = FS
        ->dir('/path/to/dir')
        ->visit($controls)
        ->collect;

DESCRIPTION

The most common use of a visitor is to walk a filesystem and locate files and directories matching (or not matching) a particular set of criteria (e.g. file name, type, size, etc). The Badger::Filesystem::Visitor module provides a number of configuration options to assist in these common tasks. For more complex operations, you can subclass the module to create your own custom visitors.

The easiest way to create and use a visitor is to call the visit() method on any of the Badger::Filesystem objects. In most cases, you'll want to call it against a Badger::Filesystem::Directory object, but there's nothing to stop you from calling it against a Badger::Filesystem::File object (although your visitor won't have anywhere to visitor beyond that single file so it doesn't serve any practical purpose). If you call it against a top-level Badger::Filesystem object then it will be applied to the root directory of the filesystem.

    use Badger::Filesystem 'Dir';
    
    my $dir     = Dir('/path/to/search/dir');
    my $visitor = $dir->visit( files => 1, dirs => 0 );
    my $collect = $visitor->collect;

The visit() method will first create a "Badger::Filesystem::Visitor" object by delegating to the Badger::Filesystem visitor() method. This configures the new visitor using any parameters passed as arguments, specified either as a list or reference to a hash array of named parameters. If no parameters are specified then the defaults are used. The visitor's visit() method is then called, passing the Badger::Filesystem::Directory object as an argument. And so begins the visitor's journey into the filesystem...

The configuration parameters are used to define what the visitor should collect on its travels. Here are some examples.

    $dir->visit( 
        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 Badger::Filesystem::File or 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 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 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 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 Badger::Filesystem::File and Badger::Filesystem::Directory objects.

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

CONFIGURATION OPTIONS

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

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

METHODS

TRAVERSAL METHODS

SELECTION METHODS

    return $self->filter( files    => name => $file )
      && ! $self->filter( no_files => name => $file );

COLLECTION METHODS

    $visitor->collect($this, $that);

    my $collect = $visitor->collect;
    my @collect = $visitor->collect;

AUTHOR

COPYRIGHT

SEE ALSO