message
,
warning
, and stop
to provide a simple, but effective,
logging facility: output log messages with timestamps, direct output to the
console and/or to a text file of your choosing, and control the level of
logging.
SetLogFile(base.file="rlogging.log", folder=getwd(), split.files=FALSE) GetLogFile(level)
SetLogLevel(level="INFO") GetLogLevel()
SetTimeStampFormat(ts.format="[%Y-%m-%d %H:%M:%S]") GetTimeStampFormat()
SetFilenameSuffixes(file.name.suffixes=list(INFO="message", WARN="warning", STOP="stop")) GetFilenameSuffixes()
message(..., domain=NULL, appendLF=TRUE) warning(..., call.=TRUE, immediate.=FALSE, domain=NULL) stop(..., call.=TRUE, domain=NULL)
NULL
if no file output is desired.FALSE
, all
logging output will be written into the file provided by the
base.file
parameter. The prefixes INFO, WARN,
and STOP will be used to differentiate the different logging
levels in the log. If set to TRUE
, each level will be logged into
its own log file using respective suffixes for the log filenames. The
suffixes are settable through the SetFilenameSuffixes
function.base::strptime
for a documentation of formatting
options.list
of filename suffixes to be
used when split.files
is set to TRUE
. The list must contain
the three elements INFO, WARN,
and STOP.base::message()
, base::warning()
, and base::stop()
.base::message()
, base::warning()
, and
base::stop()
.base::message()
.base::warning()
and base::stop()
.base::warning()
.GetLogFile
returns a string with the full path to the log
file, possibly specified through the level
parameter.GetLogLevel
returns a string with the current log level.GetTimeStampFormat
returns a string
containing the
timestamp format.GetFilenameSuffixes
Returns the named list
of filename
suffixes.
message()
, warning()
, and stop()
functions. These functions
are matched to the three logging levels INFO, WARN, and
STOP respectively.
When loading the package, the level is set to INFO and messages will be
printed to the console as well as a text file rlogging.log in the working
directory. The name and location of the log file can be changed with
SetLogFile
. If you do not want to write to a file, do
SetLogFile(NULL)
. If the file already exists, then new messages will
be appended to the existing messages. If you wish to split messages, warnings,
and errors accross multiple files, you can do so by setting the
split.files
parameter to the SetLogFile
function to
TRUE
.Log messages start with a timestamp (i.e. the result of
format(Sys.time())
) surrounded by square brackets, followed by the
logging level, also surrounded in square brackets, and finally the message
itself. For example, message("Hello world!")
will print
[2013-09-12 17:14:46] [INFO] Hello world!to the console and append the same message to the log file if this one is not set to
NULL
. If split.files
is set to TRUE
, the logging
level is not printed to file, but is still printed to console. The format of
the timestamp can be changed through the function SetTimeStampFormat
.If the log level is set to INFO, then all three functions will print a
message. If set to WARN then only warning()
and
stop()
will print log messages. Finally, if set to STOP, then
a log message is only printed in case of an error. Note that in case of
warning()
and stop()
the message is always forwarded to the
base function to retain their usual behaviour (i.e. saving warning messages
until later and stopping the execution of a program after an error has
occurred).