NAME
File::Find::Declare - File::Find, declaratively
VERSION
version 0.62
SYNOPSIS
use File::Find::Declare;
my $fff = File::Find::Declare->new({ like => qr/foo/, dirs => '/home' });
my @files = $fff->find();DESCRIPTION
File::Find::Declare is an object-oriented way to go about find files. With many ways to specify what your are looking for in a file, File::Find::Declare is both simple and powerful. Configuration may be passed at construction time, or it may be set after a new object is created, or set at construction time and then altered later, should you wish to set defaults and then change them.
File::Find::Declare is an alternative to File::Find and File::Find::Rule. It is meant to be much simpler than File::Find and behaves differently then File::Find::Rule.
Getting Started with File::Find::Declare
File::Find::Declare supports several ways of setting up your search options, and many more ways of specifying file attributes to search for. To use File::Find::Declare, simply,
use File::Find::Declare;No methods are exported. This module is meant to be used solely in an object-oriented manner. You can then specify what you want to search for:
my $sp = { like => qr/foo/, unlike => qr/bar/, dirs => [ '/home', '/etc' ] };This will search for files whose names contain foo, don't contain bar, and which are located in either /home or /etc. Create a File::Find::Declare object, like so:
my $fff = File::Find::Declare->new($sp);Although you could have (of course) simply done this:
my $fff = File::Find::Declare->new({
like => qr/foo/,
unlike => qr/bar/,
dirs => [ '/home', '/etc' ]
});And cut out the use of the intermediate variable $sp entirely. To find your files, call find():
my @files = $fff->find();And that's it. To recap:
use File::Find::Declare;
my $sp = { like => qr/foo/, unlike => qr/bar/, dirs => [ '/home', '/etc' ] };
my $fff = File::Find::Declare->new($sp);
my @files = $fff->find();Search Options
File::Find::Declare has many possible search options. What follows is a listing of all those options, followed by a discussion of them.
my $sp = {
like => qr/foo/,
unlike => qr/bar/,
dirs => '/home',
ext => '.txt',
subs => sub { $_[0] =~ m/baz/ },
size => '>10K',
changed => '<2010-01-30',
modified => '<2010-01-30',
accessed => '>2010-01-30',
recurse => 1,
is => 'readable',
isnt => 'executable',
owner => 'foo',
group => 'none',
perms => 'wr-wr-wr-',
};Specifying like
like is how you specify what a filename should look like. You may use regular expressions (using qr//), globs (as strings), or an array reference containing regular expressions and/or globs. If you provide an array reference, the filename must match ALL the given regexen or globs.
Specifying unlike
unlike is just the opposite of like. It specifies what a filename should not look like. Again, you may use regular expressions (using qr//), globs (as strings), or an array reference containing regular expressions and/or globs. If you provide an array reference, the filename must match NONE of the given regexen or globs.
Specifying dirs
dirs is how you specify where to look. It may be either a string containing a single directory name, or an array reference of directories to use.
Specifying ext
ext allows you to search for files by extension. You may specify either a single string containing an extension, or an array reference of such extensions. If you provide an array reference, the filename will match ANY extension.
Specifying subs
subs gives you the ability to define your own functions to inspect each filename. It expects either a single code reference, or an array reference containing code references. If you provide an array reference, ALL functions must return true for a given file for it to be considered "matched".
Specifying size
size uses Number::Compare semantics to examine the file size. You are therefore free to specify things like 1024, 2K, <=2048, etc. It expects either a single string containing a size specification, or an array reference containing such specifications. If you provide an array reference, a file's size must match ALL the given constraints.
Specifying changed
changed uses Number::Compare::Date semantics to allow you to search based on a file's inode changed time. You may use anything that Date::Parse understands to specify a date, as well as comparison operators to specify a relationship to that date. You should provide either a single string containing such a specification, or an array reference of such specifications. If you provide an array reference, a file's changed time must match ALL of the given conditions.
Specifying modified
modified uses Number::Compare::Date semantics to allow you to search based on a file's last modified time. You may use anything that Date::Parse understands to specify a date, as well as comparison operators to specify a relationship to that date. You should provide either a single string containing such a specification, or an array reference of such specifications. If you provide an array reference, a file's modified time must match ALL of the given conditions.
Specifying accessed
accessed uses Number::Compare::Date semantics to allow you to search based on a file's last accessed time. You may use anything that Date::Parse understands to specify a date, as well as comparison operators to specify a relationship to that date. You should provide either a single string containing such a specification, or an array reference of such specifications. If you provide an array reference, a file's accessed time must match ALL of the given conditions.
Specifying recurse
recurse indicates to the module whether or not it should recursively process any directories it has found. The current behavior is to inspect all directories, not just those that would match the given predicates. In the future, configuration options will be available to modify this behavior.
Specifying is
is allows you to test files using Perl's standard filetest operators. Each is given a string alias, as described below:
Alias: Operator:
readable -r
r_readable -R
writable -w
r_writable -W
executable -x
r_executable -X
owned -o
r_owned -O
exists -e
file -f
empty -z
directory -d
nonempty -s
symlink -l
fifo -p
setuid -u
socket -S
setgid -g
block -b
sticky -k
character -c
tty -t
modified -M
accessed -A
ascii -T
changed -C
binary -Bis expects either a string containing a single alias, or an array reference containing a list of such aliases. If you specify an array reference, any file must pass ALL of the given tests to be considered "matched".
Specifying isnt
isnt is just the opposite of is. isnt expects either a string containing a single alias, or an array reference containing a list of such aliases. If you specify an array reference, any file must pass NONE of the given tests to be considered "matched". See also "Specifying is".
Specifying owner
owner lets you search for a file based on it's owner. It expects either a string containing a username, a user's ID, or an array reference containing either of these things. If you specify an array reference, if a file has ANY matching owner, it will be returned.
Specifying group
group lets you search for a file based on it's group. It expects either a string containing a groupname, a group's ID, or an array reference containing either of these things. If you specify an array reference, if a file has ANY matching group, it will be returned.
Specifying perms
perms gives you the ability to search for a file based on its permissions. You may specify a string such as rwxrw-r-- or three digits such as 752, or an array reference containing either of these. If you specify an array reference, a file that matches ANY of the permissions given will be considered matched.
METHODS
dirs
The method dirs allows you to set the directories to search in after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the directories to search in. See also "Specifying dirs".
ext
The method ext allows you to set the extensions to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the extensions to search for. See also "Specifying ext".
subs
The method subs allows you to set the subroutines to search with after the object has been created. It expects an array reference, or a single CodeRef. If called with no arguments, it will return an array reference containing the subroutines currently set. See also "Specifying subs".
size
The method ext allows you to set the file size(s) to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the file size(s) to search for. See also "Specifying size".
changed
The method changed allows you to set the changed time to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the changed time to search for. See also "Specifying changed".
modified
The method modified allows you to set the modified time to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the modified time to search for. See also "Specifying modified".
accessed
The method accessed allows you to set the accessed time to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the accessed time to search for. See also "Specifying accessed".
is
The method is allows you to set the file tests to search with after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the file tests to search with. See also "Specifying is".
isnt
The method isnt allows you to set the file tests to search against after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the file tests to search against. See also "Specifying isnt".
owner
The method owner allows you to set the owner(s) to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the owner(s) to search for. See also "Specifying owner".
group
The method group allows you to set the group(s) to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the group(s) to search for. See also "Specifying group".
perms
The method perms allows you to set the permuission(s) to search for after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the permission(s) to search for. See also "Specifying perms".
recurse
The method recurse allows you to set the recursion property after the object has been created. It expects a single number, 0 for false, any other for true. If called with no arguments, it will return whatever recurse is currently set to. See also "Specifying recurse".
like
The method like allows you to set the filename tests to search with after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the filename tests to search with. See also "Specifying like".
unlike
The method unlike allows you to set the filename tests to search against after the object has been created. It expects an array reference, or a single string. If called with no arguments, it will return an array reference containing the filename tests to search against. See also "Specifying unlike".
find
Invoking find will cause the module to search for files based on the currently set options. It expects no arguments and returns an array of filenames.
REPOSITORY
The source code repository for this project is located at:
http://github.com/f0rk/file-find-declareAUTHOR
Ryan P. Kelly <rpkelly@cpan.org>COPYRIGHT AND LICENSE
This software is Copyright (c) 2010 by Ryan P. Kelly.
This is free software, licensed under:
The MIT (X11) License