The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
File-Find-Declare-0.62
River stage zero No dependents
++
/ File::Find::Declare

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         -B

is 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-declare

AUTHOR

  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