NAME

File::Locate - Search the (s)locate-database from Perl

SYNOPSIS

    use File::Locate;

    print join "\n", locate "mp3", "/usr/var/locatedb";

    # or only test of something is in the database

    if (locate("mp3", "/usr/var/locatedb")) {
        print "yep...sort of mp3 there";
    }

    # do regex search
    print join "\n", locate "^/usr", -rex => 1, "/usr/var/locatedb";

ABSTRACT

    Search the (s)locate-database from Perl

DESCRIPTION

File::Locate provides the locate() function that scans the locate database for a given substring or POSIX regular expression. The module can handle both plain old locate databases as well as the more hip slocate format.

FUNCTIONS

The module exports exactly one function.

• locate ($pattern, [ $database ], [ -rex = 1> ], [ -rexopt => 'e'|'i'|'ie' ], [ $coderef ])

  Scans a slocate/locate-db file for a given $pattern. $pattern may contain globbing-characters or it can be a POSIX regular expression if -rex is true. It figures out the type of $database and does the right thing. If $database is neither a locate- nor a slocate-db, it will croak.

  locate() can take three additional parameters. A string is taken to be the $database that should be searched:

      print locate "*.mp3", "/usr/var/locatedb";

  If no database is given, locate() looks up the value of the LOCATE_PATH environment variable and uses its value as the database. If this string is empty, it gives up.

  Passing a code-reference makes locate() call the code for each match it finds in the database. The current match will be in $_:

      locate "*.mp3", sub { print "MP3 found: $_\n" };

  This means that no huge return list has to be built and it is therefore more suitable for scans that return a lot of matches.

  Eventually, you can specify two options -rex and -rexopt. When -rex is true, the pattern will be treated as a POSIX regular expression. Note that those are not Perl regular expressions but the rather limited regular expressions that you might know from programs such as grep(1) and the lot. Per default, a match is tried case-sensitively.

  With -rexopt you have slightly finer control over the regex matching. Setting it to i will make the pattern case-insensitive. Setting it to e allows you to use the Extended regular expressions as defined by POSIX. Those two values can be bundled to -rexopt => 'ie' should you so desire.

  All arguments except the first ($pattern) can be given in arbitrary order. Therefore, the following lines are all equivalent:

      locate $pat, -rex => 1, "locatedb", sub { print $_ };
      locate $pat, sub { print $_ }, -rex => 1, "locatedb";
      locate $pat, "locatedb", sub { print $_ }, -rex => 1;
      # etc.

  In list context it returns all entries found. In scalar context, it returns a true or a false value depending on whether any matching entry has been found. It is a short-cut performance-wise in that it immediately returns after anything has been found.

  If $coderef is provided, the function never returns anything regardless of context.

EXPORT

locate() is exported by default. If you don't want that, then pull in the module like that:

    use File::Locate ();

You have to call the function fully qualified in this case: File::Locate::locate().

SEE ALSO

The manpages of your locate(1L)/slocate(1L) program if available.

AUTHOR

Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>

COPYRIGHT AND LICENSE

Copyright 2003-2007 by Tassilo von Parseval

This program 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 2, or (at your option) any later version.