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.

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.