NAME¶
Dir::Purge - Purge directories to a given number of files.
SYNOPSIS¶
perl -MDir::Purge -e 'purgedir (5, @ARGV)' /spare/backups
use Dir::Purge;
purgedir ({keep => 5, strategy => "by_age", verbose => 1}, "/spare/backups");
use Dir::Purge qw(purgedir_by_age);
purgedir_by_age (5, "/spare/backups");
DESCRIPTION¶
Dir::Purge implements functions to reduce the number of files in a directory
according to a strategy. It currently provides one strategy: removal of files
by age.
By default, the module exports one user subroutine: "purgedir".
The first argument of "purgedir" should either be an integer,
indicating the number of files to keep in each of the directories, or a
reference to a hash with options. In either case, a value for the number of
files to keep is mandatory.
The other arguments are the names of the directories that must be purged. Note
that this process is not recursive. Also, hidden files (name starts with a
".") and non-plain files (e.g., directories, symbolic links) are not
taken into account.
All directory arguments and options are checked before anything else is done. In
particular, all arguments should point to existing directories and the program
must have read, write, and search (execute) access to the directories.
One additional function, "purgedir_by_age", can be exported on demand,
or called by its fully qualified name. "purgedir_by_age" calls
"purgedir" with the "by age" purge strategy preselected.
Since this happens to be the default strategy for "purgedir",
calling "purgedir_by_age" is roughly equivalent to calling
"purgedir".
WARNING¶
Removing files is a quite destructive operation. Supply the "test"
option, described below, to dry-run before production.
OPTIONS¶
Options are suppled by providing a hash reference as the first argument. The
following calls are equivalent:
purgedir ({keep => 3, test => 1}, "/spare/backups");
purgedir_by_age ({keep => 3, test => 1}, "/spare/backups");
purgedir ({strategy => "by_age", keep => 3, test => 1}, "/spare/backups");
All subroutines take the same arguments.
- keep
- The number of files to keep. A negative number will reverse
the strategy. See option "reverse" below.
- strategy
- Specifies the purge strategy. Default (and only allowed)
value is "by_age".
This option is for "purgedir" only. The other subroutines should
not be provided with a "strategy" option.
- include
- If this is a reference to a subroutine, this subroutine is
called with arguments ($file,$dir) and must return true for the file to be
included in the list of candidates,
If this is a regular expression, the file file will be included only if the
expression matches the file name.
- reverse
- If true, the strategy will be reversed. For example, if the
strategy is "by_age", the oldest files will be kept instead of
the newest files.
Another way to reverse the strategy is using a negative "keep"
value. This is not unlike Perl's array subscripts, which count from the
end if negative.
A negative "keep" value can be combined with "reverse"
to reverse the reversed strategy again.
- verbose
- Verbosity of messages. Default value is 1, which will
report the names of the files being removed. A value greater than 1 will
produce more messages about what's going on. A value of 0 (zero) will
suppress messages.
- debug
- For internal debugging only.
- test
- If true, no files will be removed. For testing.
EXPORT¶
Subroutine "purgedir" is exported by default.
Subroutine "purgedir_by_age" may be exported on demand.
Calling
purgedir_by_age() is roughly equivalent to calling
purgedir() with an options hash that includes "strategy ="
"by_age">.
The variable $Dir::Purge::VERSION may be used to inspect the version of the
module.
AUTHOR¶
Johan Vromans (jvromans@squirrel.nl) wrote this module.
COPYRIGHT AND DISCLAIMER¶
This program is Copyright 2000 by Squirrel Consultancy. All rights reserved.
This program is free software; you can redistribute it and/or modify it under
the terms of either: a) the GNU General Public License as published by the
Free Software Foundation; either version 1, or (at your option) any later
version, or b) the "Artistic License" which comes with Perl.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See either the GNU General Public License or the
Artistic License for more details.