NAME

Pitonyak::SmallLogger - File and/or screen logging with message types


SYNOPSIS

use Pitonyak::SmallLogger;

my $log = new Pitonyak::SmallLogger(); # Do not use any time/date in the file name $log->log_name_date(''); # send debug output to the screen $log->screen_output('D', 1); $log->debug("Debug 1"); $log->warn("Hello I Warn you"); $log->debug("Hello I debug you"); $log->info("Hello I info you"); $log->error("Hello I error you");


DESCRIPTION

new

new()

Note that this is written in such a manner that it can be inherited. Also note that it is written such that $obj2 = $obj1->new() is valid!

copy

copy($small_logger_object)

Make a copy of one SmallLogger into another

$obj1-copy($obj2)> is the same as $obj1 = $obj2. The file handle is not copied and the the receiving SmallLogger is closed first.

build_name

$obj->build_name($path, $base_file_name, $time_format, $extension)

Returns non-zero on success.

The complete log file name will be named as "$path$base_file_name$time_format$extension" with some caveats.

The $time_format is converted to a time date string and is used as part of the file name if it does not have a zero length. A popular format for this is '.YYYYMMDD.hhmmss' to have a log file that contains the date and time included as part of the file name. This is a good way to have a unique log file every time you run and yet still know the application to which it is attached. This should contain a leading '.' if one is desired.

The $path indicates where the log file will exist.

The $extension should contain a leading '.' if one is desired.

If the file is open, it will be closed before the name is changed.

close_log

close_log()

If the file is open, it is closed.

debug

debug($message)

This is used as an abreviation for write_log_type('D', $message);

returns 1 if successful, 0 otherwise

error

error($message)

This is used as an abreviation for write_log_type('E', $message);

returns 1 if successful, 0 otherwise

file_output

When a message is written, a message type is included. I use one character to indicate the message type. The screen output hash is then checked to see if that message type should be logged. This is similar to how log4j does things.

SmallLogger::file_output()

Return the default hash of values.

$obj->file_output()

Return the current hash of values.

$obj->file_output(HASH)

Sets the hash to use for output.

$obj->file_output($message_type)

Returns the output value for the specified $message_type.

$o->file_output('E') is the same as $o->file_output()->{'E'}.

$obj->file_output($message_type, $message_value)

Sets and then returns the output value for the specified $message_type.

$o->file_output('E', 1) is the same as $o->file_output()->{'E'} = 1.

get_class_attribute

Remember that the call $obj->method(@parms) is the same as method($obj, @parms).

SmallLogger::get_class_attribute($attribute_name)

If there is only one paramter, the first parameter is assumed to be an attribute name and the default attribute value is returned.

$obj->get_class_attribute($attribute_name)

If there are two parameters, then the first parameter is assumed to be a SmallLogger object and the second parameter is assumed to be an attribute name. The attribute value for the object is returned.

$obj->get_class_attribute($attribute_name, $attribute_value)

If three parameters are given, then the first parameter is the object, the second parameter is used to set a new value for the attribute, and the third parameter is the attribute name, The attribute value is then returned.

hold_log_open

hold_log_open([0|1])

If a message is written to the log and it is not yet open, it is opened. If the hold_log_open attribute is non-zero (the default value) then the file is left open, otherwise, it is closed after writing. Note write_log() will only close the log if it opened the log, so you can clear hold_log_open and then manually open the the log before a lot of writing and then manually close the log.

No value is required, in which case, only the status is returned and the value is not changed.

If hold_log_open is set to true, you probably want open_append set to true as well. See open_append() for more details.

info

info($message)

This is used as an abreviation for write_log_type('I', $message);

returns 1 if successful, 0 otherwise

is_log_open

is_log_open()

Returns non-zero if the log is open and zero if it is closed.

Do not attempt to set this directly, use the open_log() or close_log() methods instead.

is_ok

is_ok([0|1])

Returns non-zero if the log object is ok and zero otherwise.

Although you may set this, there is no real reason to do so. This will be set if there is a problem opening the file, for example.

log_ext

log_ext([$log_extension])

The default extension is '.log'. You can set a new one with this method. The current value is returned.

If the log is currently open, it will be closed when the name changes.

log_name

log_name()

Returns Full path to and name of log file being used.

log_name_date

log_name_date([$new_date_format])

The file name used for a log file contains a date format. This sets the date format portion to use. This may be an empty string.

log_path

log_path([$new_log_path])

This will optionally set a new location for the logfile. The current value is returned.

If the log is currently open, it will be closed when the name changes.

log_primary_name

log_primary_name([$new_primary_name])

This is the primary name for the logfile. Logs are assumed to be made of a primary name, date portion, and an extension.

If the logfile is currently open, then the file is closed before changing the name. The default value is the base name of $0 with the extension removed. This is what is used if set_log_primary_name() is used.

No value is required, in which case, only the primary name is returned and the value is not changed.

message_front

message_front([$front_string])

Returns the front lne used to write messages to the logs.

A message is printed as $mesage_type message_front() message_time_format() message_loc_format()

message_loc_format

message_loc_format([$location_format])

Returns the output format used to write message location information to the logs.

This determines the format of the location information, if any, that is printed to the log file. The text with fields replaced will be used. The default value for the location format is '(file):(sub):(line)'. The (package) token is not used because the sub name contains the package.

A message is printed as $mesage_type message_front() message_time_format() message_loc_format()

message_time_format

message_time_format([$time_format])

Returns the output format for the time information used to write messages to the logs.

When a line is printed, it contains the message type, message_front() formatted time/date stamp as stored by message_time_format(), this location format string, and then finally the message.

A message is printed as $mesage_type message_front() message_time_format() message_loc_format()

open_append

open_append([0|1])

If the open_append attribute is set then log files are opened in append mode. If not, then the log file will over-write any existing file. If the hold_log_open attribute is set, you really probably want open_append set as well.

Returns the current value of the attribute.

open_log

open_log()

Open the logfile. returns non-zero on success and zero on failure.

read_from_file

Pitonyak::SmallLogger::read_from_file($file_name)

This will create an appropriate object and then read the file.

$obj->read_from_file($file_name)

Read the current file and then return the object used to read it.

rebuild_name

rebuild_name()

Causes the name of the log file to be rebuilt. Any date/time stamp portion is also redone. This calls build_name() with appropriate parameters.

This value is then returned.

screen_output

When a message is written, a message type is included. I use one character to indicate the message type. The screen output hash is then checked to see if that message type should be logged. This is similar to how log4j does things. See file_output().

SmallLogger::screen_output()

Return the default hash of values.

$obj->screen_output()

Return the current hash of values.

$obj->screen_output(HASH)

Sets the hash to use for output.

$obj->screen_output($message_type)

Returns the output value for the specified $message_type.

$o->screen_output('E') is the same as $o->screen_output()->{'E'}.

$obj->screen_output($message_type, $message_value)

Sets and then returns the output value for the specified $message_type.

$o->screen_output('E', 1) is the same as $o->screen_output()->{'E'} = 1.

set_log_primary_name

set_log_primary_name([$new_primary_name])

This will always set a new primary name. If a parameter is included, then it is used. If the parameter is not included, then the basename is take from $0 and then the portion before the last period is used. The log_primary_name() method is then used to set the primary name.

trace

trace($message)

This is used as an abreviation for write_log_type('T', $message);

returns 1 if successful, 0 otherwise

warn

warn($message)

This is used as an abreviation for write_log_type('W', $message);

returns 1 if successful, 0 otherwise

write_log

write_log($message_type, $message)

This builds the log message to actually write (including time stamps and such) and then calls write_string_to_log().

returns 1 if successful, 0 otherwise

write_log_type

write_log_type($message_type, $message)

The $message_type is usually a single character such as 'D', 'E', 'W', 'T', 'I' etc. representing things such as debug, error, warning, trace, info, etc.

The $message_type determines if the message should be printed to the file and/or screen.

The $message_type is always printed as the first thing on the line.

returns 1 if successful, 0 otherwise

write_string_to_log

write_string_to_log($to_screen, $to_file, $message)

This writes the $message to the screen if $to_screen evaluates to true. This writes the $message to the file if $to_file evaluates to true.

returns 1 if successful, 0 otherwise

This will open the file if it must. This will never close the file unless it opened the file and hold_log_open() is false.

write_to_file

write_to_file([$file_name])

Write the current configuration to the file.


COPYRIGHT

Copyright 1998-2002, Andrew Pitonyak (perlboy@pitonyak.org)

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


Modification History

March 13, 1998

Version 1.00 First release

September 10, 2002

Version 1.01 Changed internal documentation to POD