NAME

Directory::Scanner - Streaming directory scanner

VERSION

version 0.02

SYNOPSIS

    # get all entries in a directory

    Directory::Scanner->for( $dir )->stream;

    # get all entries in a directory recursively

    Directory::Scanner->for( $dir )
                      ->recurse
                      ->stream;

    # get all entries in a directory recusively
    # and filter out anything that is not a directory

    Directory::Scanner->for( $dir )
                      ->recurse
                      ->match(sub { $_->is_dir })
                      ->stream;

    # ignore anything that is a . directory, then recurse

    Directory::Scanner->for( $dir )
                      ->ignore(sub { $_->basename =~ /^\./ })
                      ->recurse
                      ->stream;

DESCRIPTION

This module provides a streaming interface for traversing directories. Unlike most modules that provide similar capabilities, this will not pre-fetch the list of files or directories, but instead will only focus on one thing at a time. This is useful if you have a large directory tree and need to do a lot of resource intensive work on each file.

Builders

This module uses the builder pattern to create the Directory::Scanner stream you need. If you look in the SYNOPSIS above you can see that the for method starts the creation of a builder. All the susequent chained methods simply collect metadata, and not until stream is called is anything constructed.

Streams

If you look at the code in the SYNOPSIS you will see that most of the chained builder calls end with a call to stream. This method will use the builder information and construct an instance which does the Directory::Scanner::API::Stream API role.

METHODS

for($dir)

Begins the construction of a StreamBuilder to eventually create a stream for scanning the given $dir.

concat(@streams)

This concatenates multiple streams into a single stream, and will return an instance that does the Directory::Scanner::API::Stream role.

stream

This is meant as an end to a StreamBuilder process. It will use the collected builder metadata to create an appropriate instance that does the Directory::Scanner::API::Stream role.

BUILDERS

These are all methods of the StreamBuilder, each will set up the metadata needed for stream to construct an actual instance.

recurse

By default a scanner will not try to recurse into subdirectories, if that is what you want, you must call this builder method.

See Directory::Scanner::StreamBuilder::Recursive for more info.

ignore($filter)

Construct a stream that will ignore anything that is matched by the $filter CODE ref.

See Directory::Scanner::StreamBuilder::Ignoring for more info.

match($predicate)

Construct a stream that will keep anything that is matched by the $predicate CODE ref.

See Directory::Scanner::StreamBuilder::Matching for more info.

apply($function)

Construct a stream that will apply the $function to each element in the stream without modifying it.

See Directory::Scanner::StreamBuilder::Application for more info.

transform($transformer)

Construct a stream that will apply the $transformer to each element in the stream and modify it.

See Directory::Scanner::StreamBuilder::Transformer for more info.

AUTHOR

Stevan Little <stevan@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Stevan Little.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Directory::Scanner

perl -MCPAN -e shell
install Directory::Scanner