/ 
File-Locate-Iterator-1
River stage zero No dependents
/ File::Locate::Iterator

NAME

File::Locate::Iterator -- read "locate" database with an iterator

SYNOPSIS

use File::Locate::Iterator;
my $it = File::Locate::Iterator->new;
while (defined (my $entry = $it->next)) {
  print $entry,"\n";
}

DESCRIPTION

File::Locate::Iterator reads a "locate" database file in iterator style. Each next() call on the iterator returns the next entry from the database.

Locate databases normally hold filenames, as a way of finding files faster than churning through all directories. Optional glob, suffix and regexp options on the iterator let you restrict the entries returned.

Only "LOCATE02" files are supported, per current versions of GNU locate, not the "slocate" format.

The iterators from this module are stand-alone, they don't need any of the various iterator module frameworks. See Iterator::Locate or Iterator::Simple::Locate to inter-operate with those frameworks. They have the advantage of various convenient ways to grep, map or manipulate the iterated sequence.

FUNCTIONS

$it = File::Locate::Iterator->new (key=>value,...)

Create and return a new locate iterator object. The following following optional key/value pairs are available,

database_file (default the system locate database)
database_fh

The file to read, either by filename or file handle. The default is per default_database_file below, usually /var/cache/locate/locatedb.

$it = File::Locate::Iterator->new
        (database_file => '/foo/bar.db');
suffix (string)
suffixes (arrayref of strings)
glob (string)
globs (arrayref of strings)
regexp (string or regexp object)
regexps (arrayref of string)

Restrict the entries returned to those of given suffix(es) or matching the given glob(s) or regexp(s). For example,

# C code files on the system
$it = File::Locate::Iterator->new
        (suffixes => ['.c','.h']);

Globs are in the style of the locate program, which means "*" for zero or more chars (including slashes), "?" for one char, "[abc]" char classes and "[^abc]" or "[!abc]" negated classes. Backslash "\" escapes any char. A pattern without wildcards matches anywhere, but with any wildcard it's anchored to start and end (use leading or trailing "*" to avoid that).

$entry = $it->next

Return the next entry from the database, or an empty list at end of file. Recall that an empty list return means undef in scalar context or no values in array context. So you can loop with either

while (defined (my $filename = $it->next)) ...

or

while (my ($filename) = $it->next) ...
$filename = File::Locate::Iterator->default_database_file

Return the default database file used in new above. Currently this is always /var/cache/locate/locatedb, though the intention is to make it the system default, if that can be found easily.

FILES

/var/cache/locate/locatedb

Default locate database.

OTHER WAYS

The plain File::Locate reads a locate database with callbacks. Whether you prefer callbacks or an iterator is a matter of style. Iterators let you write your own loop, and you can have a few of searches on the go simultaneously.

Iterators are also good for cooperative coroutining like POE or Gtk where you must hold state in some sort of variable, to be progressed by callbacks from the main loop. (Note that next will block reading from the database, so the database generally should be a plain file rather than a socket or something, so as not to hold up a main loop.)

SEE ALSO

File::Locate, Iterator::Locate, Iterator::Simple::Locate, locate(1) and the GNU Findutils manual

FUTURE

The current implementation is pure-Perl and for that reason isn't very fast. Some XS (in progress) should make it as fast as File::Locate in the future.

Currently each File::Locate::Iterator holds a separate open handle on the database, which means a file descriptor and buffering per iterator. In the future hopefully some sharing between iterators can reduce resource requirements.

Sharing an open handle between iterators with each seeking to its desired position would be possible, but a seek drops buffered data and so would go slower than ever. There's some secret undocumented mmap code in progress which should be both small and fast, when an mmap is possible, and isn't so huge as to eat up all your address space.

Glob patterns are converted to Perl regexps for matching. It might be worth making that public or splitting it out. It's slightly different from what Text::Glob does. (If you want shell globs then convert with Text::Glob and pass as regexps to new above.)

HOME PAGE

http://user42.tuxfamily.org/file-locate-iterator/index.html

COPYRIGHT

Copyright 2009 Kevin Ryde

File-Locate-Iterator is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

File-Locate-Iterator 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with File-Locate-Iterator. If not, see http://www.gnu.org/licenses/