.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dir::Purge 3pm"
.TH Dir::Purge 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dir::Purge \- Purge directories to a given number of files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  perl \-MDir::Purge \-e \*(Aqpurgedir (5, @ARGV)\*(Aq /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");
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
By default, the module exports one user subroutine: \f(CW\*(C`purgedir\*(C'\fR.
.PP
The first argument of \f(CW\*(C`purgedir\*(C'\fR 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.
.PP
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 \f(CW\*(C`.\*(C'\fR) and non-plain files (e.g., directories,
symbolic links) are not taken into account.
.PP
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.
.PP
One additional function, \f(CW\*(C`purgedir_by_age\*(C'\fR, can be exported on
demand, or called by its fully qualified name. \f(CW\*(C`purgedir_by_age\*(C'\fR
calls \f(CW\*(C`purgedir\*(C'\fR with the \*(L"by age\*(R" purge strategy preselected. Since
this happens to be the default strategy for \f(CW\*(C`purgedir\*(C'\fR, calling
\&\f(CW\*(C`purgedir_by_age\*(C'\fR is roughly equivalent to calling \f(CW\*(C`purgedir\*(C'\fR.
.SH "WARNING"
.IX Header "WARNING"
Removing files is a quite destructive operation. Supply the \f(CW\*(C`test\*(C'\fR
option, described below, to dry-run before production.
.SH "OPTIONS"
.IX Header "OPTIONS"
Options are suppled by providing a hash reference as the first
argument. The following calls are equivalent:
.PP
.Vb 3
\&  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");
.Ve
.PP
All subroutines take the same arguments.
.IP "keep" 4
.IX Item "keep"
The number of files to keep.
A negative number will reverse the strategy. See option \f(CW\*(C`reverse\*(C'\fR below.
.IP "strategy" 4
.IX Item "strategy"
Specifies the purge strategy.
Default (and only allowed) value is \*(L"by_age\*(R".
.Sp
This option is for \f(CW\*(C`purgedir\*(C'\fR only. The other subroutines should not
be provided with a \f(CW\*(C`strategy\*(C'\fR option.
.IP "include" 4
.IX Item "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,
.Sp
If this is a regular expression, the file file will be included only
if the expression matches the file name.
.IP "reverse" 4
.IX Item "reverse"
If true, the strategy will be reversed. For example, if the strategy
is \*(L"by_age\*(R", the oldest files will be kept instead of the newest
files.
.Sp
Another way to reverse the strategy is using a negative \f(CW\*(C`keep\*(C'\fR value.
This is not unlike Perl's array subscripts, which count from the end if
negative.
.Sp
A negative \f(CW\*(C`keep\*(C'\fR value can be combined with \f(CW\*(C`reverse\*(C'\fR to reverse
the reversed strategy again.
.IP "verbose" 4
.IX Item "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.
.IP "debug" 4
.IX Item "debug"
For internal debugging only.
.IP "test" 4
.IX Item "test"
If true, no files will be removed. For testing.
.SH "EXPORT"
.IX Header "EXPORT"
Subroutine \f(CW\*(C`purgedir\*(C'\fR is exported by default.
.PP
Subroutine \f(CW\*(C`purgedir_by_age\*(C'\fR may be exported on demand.
.PP
Calling \fBpurgedir_by_age()\fR is roughly equivalent to calling \fBpurgedir()\fR
with an options hash that includes \f(CW\*(C`strategy =\*(C'\fR \*(L"by_age\*(R">.
.PP
The variable \f(CW$Dir::Purge::VERSION\fR may be used to inspect the version
of the module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Johan Vromans (jvromans@squirrel.nl) wrote this module.
.SH "COPYRIGHT AND DISCLAIMER"
.IX Header "COPYRIGHT AND DISCLAIMER"
This program is Copyright 2000 by Squirrel Consultancy. All rights
reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of either: a) the \s-1GNU\s0 General Public License as
published by the Free Software Foundation; either version 1, or (at
your option) any later version, or b) the \*(L"Artistic License\*(R" which
comes with Perl.
.PP
This program is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See either the
\&\s-1GNU\s0 General Public License or the Artistic License for more details.