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

1File::Find::Rule::Age(3U)ser Contributed Perl DocumentatiFoinle::Find::Rule::Age(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

20   Legacy Interface
21           age( [ $criterion => $age ] )
22
23       $criterion
24           must be one of "older" or "newer", respectively.
25
26       $age
27           must match /^(\d+)([DWMYhms])$/ where D, W, M, Y, h, m and s are
28           "day(s)", "week(s)", "month(s)", "year(s)", "hour(s)", "minute(s)"
29           and "second(s)", respectively - I bet you weren't expecting that.
30
31           The given interval is subtracted from "now" for every file which is
32           checked to ensure search rules instantiated once and executed
33           several times in process lifetime.
34
35       By 'age' I mean 'time elapsed after mtime' (the last time the file was
36       modified) - without the equal timestamp.
37
38           # now is 2014-05-01T00:00:00, start of this years workers day
39           # let's see what has been worked last week
40           my @old_files = find( file => age => [ older => "1W" ], in => $ENV{HOME} );
41           # @old_files will now contain all files changed 2014-04-24T00:00:01 or later,
42           # 2014-04-24T00:00:00 is ignored
43
44   Modern API
45       The modern API provides 12 functions to match timestamps:
46
47                    | before  | until    | since    | after
48          ----------+---------+----------+----------+---------
49           modfied  | mtime < | mtime <= | mtime >= | mtime >
50          ----------+---------+----------+----------+---------
51           accessed | atime < | atime <= | atime >= | atime >
52          ----------+---------+----------+----------+---------
53           created  | ctime < | ctime <= | ctime >= | ctime >
54          ----------+---------+----------+----------+---------
55
56       Each function takes one argument - the referring timestamp. Following
57       representations are supported (in order of check):
58
59       File name
60           The corresponding "mtime", "atime" or "ctime" or the specified file
61           is used to do the appropriate equation, respectively.
62
63           If a relative path name is specified and the current working
64           directory is changed since rule instantiation, the result is
65           undefined.
66
67       seconds since epoch
68           Each's file "mtime", "atime" or "ctime" is compared as requested to
69           given number.
70
71       DateTime object
72           Each's file "mtime", "atime" or "ctime" is compared as requested to
73           given DateTime.
74
75       DateTime::Duration object
76           Each's file "mtime", "atime" or "ctime" is compared as requested to
77           given "now - $duration". "now" is determined at each check again,
78           for same reasons as in legacy API.
79
80       Examples
81
82           use File::Find::Rule;
83           use File::Fine::Rule::Age;
84
85           my $today = DateTime->now->truncate( to => "today" );
86           my @today = find( owned => modified_since => $today, in => $ENV{PROJECT_ROOT} );
87
88           my @updated = find( file => mofified_after => $self->get_cache_timestamp,
89                               in => $self->inbox );
90

AUTHOR

92       Pedro Figueiredo, "<pedro period figueiredo at sns dot bskyb dotty
93       com>"
94
95       Jens Rehsack, C << rehsack at cpan dot org
96

BUGS

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

SUPPORT

105       You can find documentation for this module with the perldoc command.
106
107           perldoc Find::Find::Rule::Age
108
109       You can also look for information at:
110
111       •   RT: CPAN's request tracker
112
113           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Find-Find-Rule-Age>
114
115       •   AnnoCPAN: Annotated CPAN documentation
116
117           <http://annocpan.org/dist/Find-Find-Rule-Age>
118
119       •   CPAN Ratings
120
121           <http://cpanratings.perl.org/d/Find-Find-Rule-Age>
122
123       •   Search CPAN
124
125           <http://search.cpan.org/dist/Find-Find-Rule-Age>
126

ACKNOWLEDGEMENTS

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

COPYRIGHT

131       Copyright (C) 2008 Sky Network Services. All Rights Reserved.
132
133       Copyright (C) 2013-2014 Jens Rehsack. All Rights Reserved.
134
135       This module is free software; you can redistribute it and/or modify it
136       under the same terms as Perl itself.
137