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

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

       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.

       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.

       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.

       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.

   INTERNALMETHODSinit(\%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.

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

       Badger::Log

perl v5.36.0                                       2023-08-28                             Badger::Log::File(3pm)

           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');