File::Find::Rule::Age(3)

NAME
File::Find::Rule::Age - rule to match on file age

SYNOPSIS
    # Legacy API
    use File::Find::Rule::Age;
    my @old_files = find( file   => age => [ older => '1M' ], in => '.' );
    my @today     = find( exists => age => [ newer => '1D' ], in => '.' );

DESCRIPTION
File::Find::Rule::Age makes it easy to search for files based on their age. DateTime and File::stat are used to do the behind the scenes work, with File::Find::Rule doing the Heavy Lifting.

FUNCTIONS

  Legacy Interface
    age( [ $criterion => $age ] )

$criterion
    must be one of "older" or "newer", respectively.

$age
    must match /^(\d+)([DWMYhms])$/ where D, W, M, Y, h, m and s are "day(s)", "week(s)", "month(s)", "year(s)", "hour(s)", "minute(s)" and "second(s)", respectively - I bet you weren't expecting that.

    The given interval is subtracted from "now" for every file which is checked to ensure search rules instantiated once and executed several times in process lifetime.

By 'age' I mean 'time elapsed after mtime' (the last time the file was modified) - without the equal timestamp.

    # now is 2014-05-01T00:00:00, start of this years workers day
    # let's see what has been worked last week
    my @old_files = find( file => age => [ older => "1W" ], in => $ENV{HOME} );
    # @old_files will now contain all files changed 2014-04-24T00:00:01 or later,
    # 2014-04-24T00:00:00 is ignored

  Modern API
The modern API provides 12 functions to match timestamps:

             | before  | until    | since    | after
   ----------+---------+----------+----------+---------
    modfied  | mtime < | mtime <= | mtime >= | mtime >
   ----------+---------+----------+----------+---------
    accessed | atime < | atime <= | atime >= | atime >
   ----------+---------+----------+----------+---------
    created  | ctime < | ctime <= | ctime >= | ctime >
   ----------+---------+----------+----------+---------

Each function takes one argument - the referring timestamp. Following representations are supported (in order of check):

File name
    The corresponding "mtime", "atime" or "ctime" or the specified file is used to do the appropriate equation, respectively.

    If a relative path name is specified and the current working directory is changed since rule instantiation, the result is undefined.

seconds since epoch
    Each's file "mtime", "atime" or "ctime" is compared as requested to given number.

DateTime object
    Each's file "mtime", "atime" or "ctime" is compared as requested to given DateTime.

DateTime::Duration object
    Each's file "mtime", "atime" or "ctime" is compared as requested to given "now - $duration". "now" is determined at each check again, for same reasons as in legacy API.

Examples

    use File::Find::Rule;
    use File::Fine::Rule::Age;

    my $today = DateTime->now->truncate( to => "today" );
    my @today = find( owned => modified_since => $today, in => $ENV{PROJECT_ROOT} );

    my @updated = find( file => mofified_after => $self->get_cache_timestamp,
                        in => $self->inbox );

AUTHOR
Pedro Figueiredo, "<pedro period figueiredo at sns dot bskyb dotty com>"

Jens Rehsack, C << rehsack at cpan dot org

BUGS
Please report any bugs or feature requests to "bug-find-find-rule-age at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Find-Find-Rule-Age>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT
You can find documentation for this module with the perldoc command.

    perldoc Find::Find::Rule::Age

You can also look for information at:

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Find-Find-Rule-Age>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Find-Find-Rule-Age>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Find-Find-Rule-Age>

•   Search CPAN

    <http://search.cpan.org/dist/Find-Find-Rule-Age>

ACKNOWLEDGEMENTS
Richard Clamp, the author of File::Find::Rule, for putting up with me.

COPYRIGHT
Copyright (C) 2008 Sky Network Services. All Rights Reserved.

Copyright (C) 2013-2014 Jens Rehsack. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO
File::Find::Rule, DateTime, File::stat