NAME

File::DirWalk - walk through a directory tree and run callbacks on files, symlinks and directories.

SYNOPSIS

    use File::DirWalk;

    my $dw = File::DirWalk->new;

Walk through your homedir and print out all filenames:

    $dw->onFile(sub {
        my ($file) = @_;
        print "$file\n";

        return SUCCESS;
    });

    $dw->walk($ENV{'HOME'});

Walk through your homedir and print out all directories:

    $dw->onDirEnter(sub {
        my ($path) = @_;
        print "$path\n";

        return SUCCESS;
    });

    $dw->walk($ENV{'HOME'});

Walk through your homedir and print out all directories with depth 3:

    $dw->onDirEnter(sub {
        my ($path) = @_;
        print "$path\n";

        return SUCCESS;
    });

    $dw->setDepth(3);
    $dw->walk($ENV{'HOME'});

DESCRIPTION

This module can be used to walk through a directory tree and run own functions on files, directories and symlinks.

METHODS

new()

Create a new File::DirWalk object. The constructor takes no arguments.

onBeginWalk(\&func)

Specify a function to be be run on beginning of a walk.

onLink(\&func)

Specify a function to be run on symlinks.

onFile(\&func)

Specify a function to be run on regular files.

onDirEnter(\&func)

Specify a function to be run before entering a directory.

onDirLeave(\&func)

Specify a function to be run when leaving a directory.

setDepth($int)

Set the directory traversal depth. Once the specified directory depth has been reached, the walk method returns. The default value is 0. Precondition: The value has to be positive. The method will die if called with a negative value.

getDepth

Returns the user-specified directory traversal depth. The default value is 0.

currentDepth

Returns the current directory traversal depth.

currentDir

Returns the directory part of the current path.

    $dw->onBeginWalk(sub {
        my ($path) = @_;

        print "path: " . $path,            "\n"; # /usr/bin/perl
        print "directory: " . $dw->currentDir(), "\n"; # /usr/bin

        return SUCCESS;
    });

currentPath

Returns the current path. The string is identical to the $path argument passed to the callback:

    $dw->onBeginWalk(sub {
        my ($path) = @_;

        print "path: " . $path,            "\n";        # /usr/bin/perl
        print "directory: " . $dw->currentPath(), "\n"; # /usr/bin/perl

        return SUCCESS;
    });

currentBasename

Returns the current base name of the current path:

    $dw->onBeginWalk(sub {
        my ($path) = @_;

        print "path: " . $path,            "\n";            # /usr/bin/perl
        print "directory: " . $dw->currentBasename(), "\n"; # perl

        return SUCCESS;
    });

count

Returns the number of elements wthin the current directory. Excludes . and ..

entryList

Returns an array reference to the elements wthin the current directory. Excludes . and ..

walk($path)

Begin the walk through the given directory tree. This method returns if the walk is finished or if one of the callbacks doesn't return SUCCESS. If the callback function returns PRUNE, walk will skip to the next element within the current directory hierarchy. You can use PRUNE to exclude files or folders:

    $dw->onBeginWalk(sub {
        my ($path) = @_;

        if ($path =~ /ignore/) {
            return PRUNE;
        }

        return SUCCESS;
    });

CALLBACKS

All callback-methods expect a function reference as their argument. The current path is passed to the callback function.

The callback function must return SUCCESS, otherwise the recursive walk is aborted and walk returns. Furthermore, walk expects a numeric return value.

CONSTANTS

File::DirWalk exports the following predefined constants as return values:

SUCCESS (1)

FAILED (0)

ABORTED (-1)

PRUNE (-10)

DEVELOPMENT

Please mail the author if you encounter any bugs. The most recent development version can be found on GitHub: https://github.com/nullmedium/File-DirWalk

CHANGES

Version 0.5: bugfixes, improved testing, new currentDepth() method.

Version 0.4: add more methods, better testing, more documentation.

Version 0.3: add PRUNE constant. add option to specify the directory depth.

Version 0.2: platform portability fixes and more documentation

Version 0.1: first CPAN release

HISTORY

I wrote DirWalk.pm module for use within my 'Filer' file manager as a directory traversing backend and I thought it might be useful for others. It is my first CPAN module.

AUTHOR

Jens Luedicke <jensl@cpan.org>

COPYRIGHT AND LICENCE

Copyright (c) 2005-2013 Jens Luedicke <jensl@cpan.org>.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm File::DirWalk

perl -MCPAN -e shell
install File::DirWalk