CleanCode Perl Libraries
Multi-Lingual Library Maintainability
available: Perl not available: Java not available: JavaScript not available: Certified
not available: Testable
not available: Standalone
not available: Diagnostic


Log::Writer - Provides data logging facilities.


        use Log::Writer;
        # a Log object with defaults
        $log = Log::Writer->new("logDir/mylog");
        # a Log object with verbose and autoFlush specified
        $diaglog = Log::Writer->new("logDir/diaglog", 0, 1);
        # a Log object fully specified
        $diaglog = Log::Writer->new("logDir/diaglog", $inputOptionsObject);
        # scalar and list versions of write method


Perl5.005, File::Path, Fcntl, File::Handy, Data::Handy


Each message is written as a single record to a plain text log file. Records are separated by the system-dependent line terminator. Fields are separated by the value specified in the LOG_FIELD_SEPARATOR property. The first few fields of every record are added automatically. These are the date, the time, and optionally, the thread which is logging the message.

Each time a program is invoked, the log file will be appended to. There is currently no facility for length-limiting the file, so it must be archived per your system requirements from time to time.

Settings properties used by this class

InputOptions properties used by this class
Property Type Default Specifies...
LOG_VERBOSE boolean 1 Specifies to write LOG_START_TEXT and LOG_END_TEXT values to log file.
LOG_AUTOFLUSH boolean 0 Specifies to flush write buffer after each call or not.
LOG_FILE_EXT String .log Extension for log file name.
LOG_FIELD_SEPARATOR String | (a vertical bar) Field separator in each record of the log file.
LOG_START_TEXT String === Starting log session === Initial text written when Log object is created.
LOG_END_TEXT String === Ending log session === Final text written when Log object is created.
LOG_DATE_FMT String yyyy-MM-dd Format string for date field of each log record.
LOG_TIME_FMT String HH:mm:ss Format string for time field of each log record.

A couple of these parameters warrant further explanation.

The LOG_AUTOFLUSH parameter is a boolean switch. Turned on, every write call will flush immediately to the file. Turned off, no flushing will be done. You may at any time invoke the flush method to do it manually, or wait until program termination. The immediate-flush may be desirable, for instance, when attempting to diagnose a problem where the program is long-running and/or log messages occur infrequently.

The LOG_VERBOSE parameter is also a boolean switch. Turned on, a standard phrase (the value of the LOG_START_TEXT property, even if empty) is written to the log file when a Log object is created. Similarly, at the termination of the program (when close is called) the value of the LOG_END_TEXT property is written. These phrases serves to demark session boundaries for ease in reviewing the log file. The absence of the LOG_END_TEXT marker, for instance, might indicate abnormal program termination. Turned off, the demarcation phrases are not written to the log file. Additionally, the log file is not even created until the first write is invoked. Thus, for an error log, for example, if no errors occur during a program invocation, the log file will not be created (or not updated if one already exists).



Current version of this class.



PACKAGE->new(logName, settings)

PACKAGE->new(logName, autoFlush, verbose)


Creates a Log object, verifies the log directory exists (or creates it if needed), and initializes the log file. The settings parameter allows full control of all parameters used by this class, while the alternate version allows you to specify "inline" the two common parameters, autoFlush and verbose.


logName - string; base name of log file including path but no extension

settings - optional; InputOptions object specifying object parameters; see the introduction of this page for details.

autoFlush - optional; boolean indicating to flush after every write

verbose - optional; boolean directing opening and closing behavior


a newly created object




Returns an error message, if any, from initializing the log file (creating the log directory if needed, and opening the log file if verbose is set). If no errors, returns undef.


boolean indicating whether file initialization was successful



Flush the log stream.



Close the log stream and returns the status of the close. If no log stream was ever opened (i.e. verbose was false and no messages were written to the log), just returns 1 indicating no failure.


boolean indicating whether close was successful



Write a log record with one or more data fields. The date and time are the initial fields of the record; the specified list of one or more messages is concatenated. Thus, each record will contain at least 3 fields. The DEFAULT_LOG_FIELD_SEPARATOR string separates fields in each record. (You may elect to change this field separator string via the LOG_FIELD_SEPARATOR property.) If your data contains the field separator you have chosen, it will automatically be changed to DEFAULT_NON_CONFLICTING_STRING so as to maintain the ability to properly distinguish fields of the record.


msgList - list of strings to output to log file


boolean indicating whether write was successful




Michael Sorens


$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $


CleanCode 0.9


Hey! The above document had some coding errors, which are explained below:

Around line 214:

=back doesn't take any parameters, but you said =back -- end of CLASS VARIABLES section

Around line 281:

=back doesn't take any parameters, but you said =back -- end of CONSTRUCTOR

CleanCode Perl Libraries Copyright © 2001-2013 Michael Sorens - Revised 2013.06.30 Get CleanCode at Fast, secure and Free Open Source software downloads