Multi-Lingual Library

Maintainability

Perl

Java

JavaScript

Certified Class

Testable Class

Standalone Mode

Diagnostic Enabled

• NAME
• SYNOPSIS
• REQUIRES
• DESCRIPTION
  • Settings properties used by this class
• CLASS VARIABLES
• CONSTRUCTOR
• METHODS
• BUGS
• AUTHOR
• VERSION
• SINCE
• POD ERRORS

NAME

Log::Writer - Provides data logging facilities.

SYNOPSIS

        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
        $log->write("message");
        $diaglog->write("field1","field2","field3");
        
        $log->flush();
        $diaglog->close();

REQUIRES

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

DESCRIPTION

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

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).

CLASS VARIABLES

$VERSION

Current version of this class.

CONSTRUCTOR

new

PACKAGE->new(logName, settings)

PACKAGE->new(logName, autoFlush, verbose)

PACKAGE->new(logName)

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.

Parameters:

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

Returns:

a newly created object

METHODS

getErrMsg

OBJ->getErrMsg()

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.

Returns:

boolean indicating whether file initialization was successful

flush

OBJ->flush()

Flush the log stream.

close

OBJ->close()

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.

Returns:

boolean indicating whether close was successful

write

OBJ->write(msgList)

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.

Parameters:

msgList - list of strings to output to log file

Returns:

boolean indicating whether write was successful

BUGS

None

AUTHOR

Michael Sorens

VERSION

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

SINCE

CleanCode 0.9

POD ERRORS

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