NAME

File::Log - A simple Object Orientated Logger

SYNOPSIS

use File::Log;

# Pretty format, all the parameters
my $log = File::Log->new({
  debug           => 4,                   # Set the debug level
  logFileName     => 'myLogFile.log',     # define the log filename
  logFileMode     => '>',                 # '>>' Append or '>' overwrite
  dateTimeStamp   => 1,                   # Timestamp log data entries
  stderrRedirect  => 1,                   # Redirect STDERR to the log file
  defaultFile     => 1,                   # Use the log file as the default filehandle
  logFileDateTime => 1,                   # Timestamp the log filename
  appName         => 'myApplicationName', # The name of the application
  PIDstamp        => 1,                   # Stamp the log data with the Process ID
  storeExpText    => 1,                   # Store internally all exp text
  msgprepend      => '',                  # Text to prepend to each message
  say             => 1,                   # msg() and exp() methode act like the perl6 say
                                          #  command (default off) requested by Aaleem Jiwa
                                          #  however it might be better to just use the say()
                                          #  method
});

# Minimal instance, logfile name based on application name
my $log = File::Log->new();

# Typical usage, set the debug level and log filename (say from a config file)
my $log = File::Log->new(debug => $debugLevel, logFileName => $logFileName,);

# Print message to the log file if the debug is >= 2
$log->msg(2, "Add this to the log file if debug >= 2\n");

# Print message to the log file if the debug is >= 2 (but in a perl6 way)
$log->say(2, "Add this to the log file if debug >= 2");

# Print an exception (error) message to the log file
$log->exp("Something went wrong\n");

# Close the log file (optional at exit)
$log->close();

# Change the debug level, capturing the old value
$oldDebugValue     = $log->debugValue($newDebugValue);

$currentDebugValue = $log->debugValue();

# Get all the exceptions text (so you can do something with all the errors, eg email them)
$allExceptions     = $log->getExpText();

$numberErrors      = $log->expCnt();        # How many times has $log->exp been called

DESCRIPTION

File::Log is a class providing methods to log data to a file. There are a number of parameters that can be passed to allow configuration of the logger.

REQUIRED MODULES

Carp (confess is used), FindBin and Symbol;

METHODS

There are no class methods, the object methods are described below. Private class method start with the underscore character '_' and should be treated as Private.

new

Called to create a File::Log object. The following optional named parameters can be passed to the constructor via an anonymous hash:

debug: Used to set the debug level. The default level is 9. The debug level is used by other methods to determine if data is logged or ignored. See msg and exp methods.
logFileName: Defines the path and name of the log file that is written too. If not defined then the value of appName with '.log' appended is used. If appName is not defined in the constructor then BinFind is used to determine the name of the application.
logFileMode: Used to determine if the log file is overwritten or appended too. Default is append. Valid value are '>' for overwrite and '>>' for append.
dateTimeStamp: If true (default is false), then each entry written to the log file using the msg and exp methods has the current date and time prepended to the data.
stderrRedirect: If true (default is true), then redirect STDERR to the log file.
defaultFile: If true (default is false), then select the log file as the default output file.
logFileDateTime: If true (default is false), then include the date and time into the name of the log file just before the '.log'. The format of the date and time used is _YYYYMMDD-HHMMSS
appName: If logFileName is not defined then the appName is used as the basis of the log file. If appName is not defined then the FindBin module is use to determine the name of the application and is stored within the appName hash variable.
PIDstamp: If true (default is false), then the Process ID is prepended to the data written to the log file by the msg and exp methods. This is handy when there are more than one processes writting to the same log file.
storeExpText: If true (default is false), then any data written with the exp method is also stored internally for later retrival with the getExpText method. The stored data can also be cleared with the clearExpText method. This can be useful if there may be multiple exceptions which you then want to report on (other than in the log file) as one text string.
msgprepend: If anything (default is nothing), prepends its value to the end of each message passed to msg()/exp()/say() methods.
dateFormat: If defined, holds the strftime-compatible format for dateTimeStamp.
say: If true (default false) causes msg() and exp() methods to append a newline character to the end of the passed message. A (possibly) better approach is to just use the say() method rather then msg().

_init & Private methods

Private method to initialise the object on construction. Called by new(). All Private methods start with _ and should be treated as PRIVATE. No other private methods are documented (since they are private).

msg

The msg method is used to log a message to the log file. The first POSITIONAL argument to msg is the "debug level" at which the message should be added to the log file if the instance "debug value" is greater than or equal to the "debug level".

The second and optional subsiquent arguments are treated as text to print to the log file.

eg. $log->msg(2, "Printed to log file if 'debug' is greater than or equal to 2 \n");

Note that newline characters are not automatically appended by this method.

say

Same as msg except a newline '\n' is appended to the end of the line

exp

exp is used to report exceptions. There is no "debug level" parameter, just one or more text strings which are printed to the log file. The text printed has "**" prepended to each line (this occurs before prepended timestamp or PID values).

Note that newline characters are not automatically appended by this method.

close

Closes the file handle associated with the log file.

DESTROY

DESTROY is defined and closes the file handle associated with the log file.

PIDstamp

The PIDstamp method can be used to set or get the value of the PIDstamp instance variable. If called without parameters, the current value of the PIDstamp instance variable is returned. If called with a parameter, the parameter is used to set the PIDstamp instance variable and the previous value is returned.

Refer to the new method for further information.

dateTimeStamp

The dateTimeStamp method can be used to set or get the value of the dateTimeStamp instance variable. If called without parameters, the current value of the dateTimeStamp instance variable is returned. If called with a parameter, the parameter is used to set the dateTimeStamp instance variable and the previous value is returned.

Refer to the new method for further information.

debugValue

The debugValue method can be used to set or get the value of the debugValue instance variable. If called without parameters, the current value of the debugValue instance variable is returned. If called with a parameter, the parameter is used to set the debugValue instance variable and the previous value is returned.

Refer to the new method for further information.

expText

The expText method can be used to set or get the value of the storeexptext instance variable. If called without parameters, the current value of the storeexptext instance variable is returned. If called with a parameter, the parameter is used to set the storeexptext instance variable and the previous value is returned.

Refer to the new method for further information.

getExpText

The expText method is used to retreive the stored value of the instance "Exception Text".

clearExpText

The clearExpText method is used to clear the stored value of the instance "Exception Text".

expCnt

The expCnt method is used to retreive the number of times that the exp method has been called for this object.

getLogFileName

The getLogFileName method is used to retreive the actual log file name used for this object.

PROPERTIES

see the new method.

KNOWN ISSUES

None, however please contact the author at gng@cpan.org should you find any problems and I will endevour to resolve then as soon as possible.

If you have any enhancement suggestions please send me an email and I will try to accommodate your suggestion.

Setting 'say' to true in the new() method and then using the say() method will give you two newlines.

ENHANCEMENT REQUEST/BUGS

Thanks to the following for enhancement suggestions or bug reports:

Aaleem Jiwa - say() method
Paul K - msgprepend and dateformat

AUTHOR

Greg George, IT Technology Solutions P/L, Australia
Mobile: +61-404-892-159, Email: gng@cpan.org

LICENSE

CVS ID

$Id: Log.pm,v 1.5 2008/03/01 02:56:01 Greg Exp $

CHANGE HISTORY

$Log: Log.pm,v $
Revision 1.5  2008/03/01 02:56:01  Greg
- Updated Makefile.PL to include prereq for Encode as I was getting cpan tester errors. NO CODE CHANGES


Revision 1.4  2008/02/26 08:54:31  Greg
- Updated POD

Revision 1.3  2007/07/17 11:23:49  Greg
- Added say() method
- Added say, msgprepend and dateFormat arguments to new()
- Added pre close of STDERR

Revision 1.2  2004/10/08 23:10:14  Greg
- Changed new() to allow named argument as well as the anonymous hash reference.

Revision 1.1.1.1  2004/07/29 11:15:06  Greg
- Initial release to CPAN

To install File::Log, copy and paste the appropriate command in to your terminal.

cpanm

cpanm File::Log

CPAN shell

perl -MCPAN -e shell
install File::Log

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

REQUIRED MODULES

METHODS

new

_init & Private methods

msg

say

exp

close

DESTROY

PIDstamp

dateTimeStamp

debugValue

expText

getExpText

clearExpText

expCnt

getLogFileName

PROPERTIES

KNOWN ISSUES

ENHANCEMENT REQUEST/BUGS

AUTHOR

LICENSE

CVS ID

CHANGE HISTORY

Module Install Instructions