SYNOPSIS

     use Dir::Write::Rotate;
    
     my $dwr = Dir::Write::Rotate->new(
         name               => 'somedir.log',            # required
         filename_pattern   => '%Y-%m-%d-%H%M%S.pid-%{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
     $dwr->write("some\ncontents\n");

    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
    10*24*3600.

DESCRIPTION

    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.

METHODS

 new

    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 '%Y-%m-%d-%H%M%S.pid-%{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.

 write

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

    Write a file with content $msg.

 rotate

    Will be called automatically by write.

SEE ALSO

    File::Write::Rotate