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

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:

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