/ 
File-Rotate-Simple-v0.2.3
River stage zero No dependents
/ File::Rotate::Simple

NAME

File::Rotate::Simple - no-frills file rotation

VERSION

version v0.2.3

SYNOPSIS

use File::Rotate::Simple qw/ rotate_files /;

rotate_files(
    file => '/foo/bar/backup.tar.gz',
    age  => 7,
    max  => 30,
);

rotate_files(
    files => [ qw{ /var/log/foo.log /var/log/bar.log } ],
    max   => 7,
);

or the legacy interface:

File::Rotate::Simple->rotate(
    file => '/foo/bar/backup.tar.gz',
    age  => 7,
    max  => 30,
);

or the object-oriented interface:

my $r = File::Rotate::Simple->new(
    file => '/foo/bar/backup.tar.gz',
    age  => 7,
    max  => 30,
);

$r->rotate;

DESCRIPTION

This module implements simple file rotation.

Files are renamed to have a numeric suffix, e.g. backup.tar.gz is renamed to backup.tar.gz.1. Existing file numbers are incremented.

If "max" is specified, then any files with a larger numeric suffix are deleted.

If "age" is specified, then any files older than that number of days are deleted.

Note that files with the extension 0 are ignored.

ATTRIBUTES

age

The maximum age of files (in days), relative to the "time" attribute. Older files will be deleted.

A value 0 (default) means there is no maximum age.

max

The maximum number of files to keep. Numbered files larger than this will be deleted.

A value of 0 (default) means that there is no maximum number.

Note that it does not track whether intermediate files are missing.

file

The file to rotate. This can be a string or Path::Tiny object.

files

When "rotate" is called as a constructor, you can specify an array reference of files to rotate:

File::Rotate::Simple->rotate(
   files => \@files,
   ...
);

start_num

The starting number to use when rotating files. Defaults to 1.

Added in v0.2.0.

extension_format

The extension to add when rotating. This is a string that is passed to "strftime" in Time::Piece with the following addition of the %# code, which corresponds to the rotation number of the file.

Added in v0.2.0.

replace_extension

If defined, it replaces the extension with the one specified by "extension_format" rather than appending it. Use this when you want to preserve the existing extension in a rotated backup, e.g.

my $r = File::Rotate::Simple->new(
    file              => 'myapp.log',
    extension_format  => '.%#.log',
    replace_extension => '.log',
);

will rotate the log as myapp.1.log.

Added in v0.2.0.

if_missing

When true, rotate the files even when "file" is missing. True by default, for backwards compatability.

Added in v0.2.0.

touch

Touch "file" after rotating.

time

A time object corresponding to the time used for generating timestamped extensions in "extension_format". It defaults to a Time::Piece object with the current local time.

You can specify an alternative time (including time zone) in the constructor, e.g.

use Time::Piece;

my $r = File::Rotate::Simple->new(
    file              => 'myapp.log',
    time              => gmtime(),
    extension_format  => '.%Y%m%d',
);

Time::Moment and DateTime objects can also be given.

Unlike other attributes, "time" is read-write, so that it can be updated between calls to "rotate":

use Time::Piece;

$r->time( localtime );
$r->rotate;

Added in v0.2.0.

METHODS

rotate

Rotates the files.

This can be called as a constructor.

EXPORTS

None by default. All exports must be made manually.

rotate_files

This is an optionally exported function for rotating files.

use File::Rotate::Simple qw/ rotate_files /;

rotate_files(
    file => '/foo/bar/backup.tar.gz',
    age  => 7,
    max  => 30,
);

Added in v0.2.0.

SEE ALSO

The following modules have similar functionality:

There are also several logging modueles that support log rotation.

SOURCE

The development version is on github at https://github.com/robrwo/File-Rotate-Simple and may be cloned from git://github.com/robrwo/File-Rotate-Simple.git

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/robrwo/File-Rotate-Simple/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Robert Rothenberg <rrwo@cpan.org>

CONTRIBUTOR

Mohammad S Anwar <mohammad.anwar@yahoo.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Robert Rothenberg.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)