Dir::Write::Rotate - Write files to a directory, with rotate options

    This document describes version 0.004 of Dir::Write::Rotate (from Perl
    distribution Dir-Write-Rotate), released on 2020-11-17.

     use Dir::Write::Rotate;

     my $dwr = Dir::Write::Rotate->new(
         path               => 'somedir.log',            # required
         filename_pattern   => '{pid}.%{ext}', # optional
         filename_sub       => sub { ... },              # optional
         max_size           => undef,                    # optional
         max_files          => undef,                    # optional
         max_age            => undef,                    # optional
         rotate_probability => 0.25,                     # optional

     # will write to a file in the dir and return its name

    To limit total size of files in the directory, e.g. 10MB, set "max_size"
    to 10*1024*1024. To limit number of files, e.g. 5000, set "max_files" to
    5000. To keep only files that are at most 10 days old, set "max_age" to

    This module provides a simple object for writing files to directory.
    There are options to delete older files to keep the size of the
    directory in check.

    Syntax: $dwr = Dir::Write::Rotate->new(%args);

    Constructor. Arguments:

    *   path => str

        The directory path to write to. Must already exist.

    *   filename_pattern => str

        Names to give to each file, expressed in pattern a la strftime()'s.
        Optional. Default is '{pid}.%{ext}'. Time is
        expressed in local time.

        If file of the same name already exists, a suffix ".1", ".2", and so
        on will be appended.

        Available pattern:

        %Y - 4-digit year number, e.g. 2009
        %y - 2-digit year number, e.g. 09 for year 2009
        %m - 2-digit month, e.g. 04 for April
        %d - 2-digit day of month, e.g. 28
        %H - 2-digit hour, e.g. 01
        %M - 2-digit minute, e.g. 57
        %S - 2-digit second, e.g. 59
        %z - the time zone as hour offset from GMT
        %Z - the time zone or name or abbreviation
        %{pid} - Process ID
        %{ext} - Guessed file extension
                Try to detect appropriate file extension based on the
                content using File::LibMagic (if that module is available).
                For example, if message message looks like an HTML document,
                then 'html'. If File::LibMagic is not available or type
                cannot be detected, defaults to 'log'.

        %% - literal '%' character

    *   filename_sub => code

        A more generic mechanism for filename_pattern. If filename_sub is
        given, filename_pattern will be ignored. The code will be called
        with the same arguments as log_message() and is expected to return a
        filename. Will die if code returns undef.

    *   max_size => num

        Maximum total size of files, in bytes. After the size is surpassed,
        oldest files (based on ctime) will be deleted. Optional. Default is
        undefined, which means unlimited.

    *   max_files => int

        Maximum number of files. After this number is surpassed, oldest
        files (based on ctime) will be deleted. Optional. Default is
        undefined, which means unlimited.

    *   max_age => num

        Maximum age of files (based on ctime), in seconds. After the age is
        surpassed, files older than this age will be deleted. Optional.
        Default is undefined, which means unlimited.

    *   rotate_probability => num

        A number between 0 and 1 which specifies the probability that
        write() will call rotate(). This is a balance between performance
        and rotate size accuracy. 1 means always rotate, 0 means never
        rotate. Optional. Default is 0.25.

    Syntax: $dwr->write($msg) => $filename

    Write a file with content $msg.

    Will be called automatically by write.

    Bool. If set to true, will print debug messages to stderr (particularly
    when instantiated and when deleting rotated files).

    Please visit the project's homepage at

    Source repository is at

    Please report any bugs or feature requests on the bugtracker website

    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.


    perlancar <>

    This software is copyright (c) 2020, 2017 by

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.