Dir::Purge - Purge directories to a given number of files.

       Johan Vromans (jvromans@squirrel.nl) wrote this module.

       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.

perl v5.36.0                                       2022-10-13                                    Dir::Purge(3pm)

       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".

       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.

       Dir::Purge - Purge directories to a given number of files.

       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.

         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");

       Removing files is a quite destructive operation. Supply the "test" option, described below, to dry-run
       before production.