NAME

       Badger::Log::File - writes log messages to a log file

SYNOPSIS

           use Badger::Log::File;

           my $log = Badger::Log::File->new({
               filename  => '/var/log/badger.log',
               keep_open => 1,
           });

           $log->log('a debug message');
           $log->info('an info message');
           $log->warn('a warning message');
           $log->error('an error message');
           $log->fatal('a fatal error message');

DESCRIPTION

       This module is a subclass of Badger::Log that implements a simple mechanism for logging
       messages to a file.  It uses Badger::Filesystem for all the underlying file operations.

CONFIGURATION OPTIONS

       The following configuration options are available in addition to those inherited form the
       Badger::Log base class.

   filename
       The name of the log file which you want messages appended to.  Either this or the
       filename_format option must be provided.

   filename_format
       A format which can be used to generate a filename to write messages to.  This can include
       any of the "strftime()" character sequences, e.g.  %Y for the four digit year, %m for a
       two digit month number, %d for a two digit day of the month, etc.

           my $log = Badger::Log::File->new({
               filename_format  => '/var/log/badger-%Y-%m-%d.log',
               keep_open => 1,
           });

       If, like me, you find it hard to remember the "strftime()" character sequences, then you
       can use an alternate format where the elements of the date and/or time are encoded as
       upper case words embedded in angle brackets.  e.g. "badger-<DATE>.log", or
       "badger-<YEAR>-<MONTH>.log".

       The words that can be embedded this way, and their corresponding "strftime()" character
       sequences are:

           DATE    => '%Y-%m-%d'       # e.g. 2022-08-24
           TIME    => '%H-%M-%S'       # e.g. 13:54:07
           YEAR    => '%Y'             # e.g. 2022
           MONTH   => '%m'             # e.g. 08
           DAY     => '%d'             # e.g. 24
           HOURS   => '%H'             # e.g. 13
           MINUTES => '%M'             # e.g. 54
           SECONDS => '%S'             # e.g. 07

       The module will automatically create a new logfile when the "filename_format" generates a
       filename that is different to any previous value.

   filesystem
       An optional reference to a Badger::Filesystem object, or the name of a filesystem class
       having a file() method similar to that in Badger::Filesystem. This defaults to the
       Badger::Filesystem class.

   keep_open
       A flag indicating if the log file should be kept open between calls to logging methods.
       The default value is 0 meaning that the file will be opened for each message and closed
       again afterwards.  Set it to any true value to have the file kept open.

METHODS

       The following methods are implemented in addition to those inherited from Badger::Log and
       its base classes.

   log($level,$message)
       This method redefines the log() method in Badger::Log to write logging messages to the log
       file.

   INTERNAL METHODS
   init(\%config)
       Custom initialiser method which calls the base class init_log() method followed by the
       init_file() method.

   init_file(\%config)
       Custom initialiser method which handles the configuration and initialisation of the file-
       specific parts of the logger.

   expand_filename()
       Expands the format defined by the "filename_format" configuration option to a filename
       using the current date and time.

       If "filename_format" has not been specified then it returns the value of the "filename"
       configuration option.

   filename_changed()
       Calls expand_filename() to expand any "filename_format" and compares it to the current
       "filename" (which may have been generated by a previous call to this method).

       If they are the same then it returns "undef".  Otherwise it saves the new filename to the
       internal "filename" value and returns it.

   file()
       Returns a reference to a Badger::Filesystem::File object based on the "filename" which can
       either be defined as a static configuration option or will be generated by the
       expand_filename() method from the "filename_format" configuration option.

   filehandle()
       Returns a filehandle for the current logfile.  If the filename has changed since the last
       call this method (determined by calling filename_changed()) then any existing filehandle
       is closed (by calling release()) and the new file is opened to return a new filehandle (by
       calling acquire()).

   acquire()
       This method acquires a file handle (an IO::File object) for the specified filename, opened
       ready for appending log messages.

   release()
       The method releases a previously acquired file handle.  i.e. it closes the log file.

AUTHOR

       Andy Wardley <http://wardley.org/>

COPYRIGHT

       Copyright (C) 2005-2022 Andy Wardley.  All Rights Reserved.

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

SEE ALSO

       Badger::Log