NAME

Directory::Iterator::XS - Recursive directory listing, fast XS backend

SYNOPSIS

  use Directory::Iterator::XS

  my $list = Directory::Iterator::XS->new($directory);
  while ($list->next) {
    print $list->get, "\n";
  }

DESCRIPTION

The module creates a list-like generator to recursively list files in a directory. The directories are scanned as the list is consumed, so only the one directory handle and a list of directories to scan are stored in memory.

METHODS

new(DIRECTORY)

Create a new instance on the specified DIRECTORY, which must be the name of an existing directory.

next

Advance to the next item. Returns 1 if there is a next item, 0 otherwise.

get

Get the current file (which must be set from a previous call to next).

prune

Prune the current diretory, so no more files are read from it. When scanning the list of files, when you get a file from a directory that you aren't interested in, calling prune will close that directory, to prevent spending time listing its contents.

As currently implemented, it's possible that some subdirectories could've been queued before the first file was seen, so it's not guaranteed that a single call to prune will always suffice. Its purpose is simply to be more efficient than continuing to read files from an unwanted directory.

To skip over a subdirectory with a single call, use show_directories and prune_directory.

show_dotfiles(ARG)

If ARG is true, hidden files & directories, those with names that begin with a . will be processed as regular files. By default, such files are skipped.

show_directories(ARG)

If ARG is true, directories will be returned from the list, in addition to being queued to process their files.

is_directory

Returns true if the most recently returned file entry is a directory; used to enable quickly differentiating directories form plain files.

prune_directory

Removes the most recently queued directory, and returns the name of the removed directory. This allows the module to quickly skip over subdirectories entirely, without ever opening them.

recursive(ARG)

if ARG is false, just look in the top-level directory; don't queue subdirectories for processing.

AUTHOR

Steve Sanbeg

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Steve Sanbeg

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.