.\" selog lua programmer's manual
.\"
.\" Written by Tony Finch <dot@dotat.at> <fanf2@cam.ac.uk>
.\" at the University of Cambridge Computing Service.
.\" You may do anything with this, at your own risk.
.\"
.\" $Cambridge: users/fanf2/selog/selog-lua.man,v 1.5 2008/04/09 22:08:42 fanf2 Exp $
.\"
.lg 0
.de TQ
. br
. ns
. TP \\$1
..
.de DQ
\\*(lq\\$1\\*(rq\\$2
..
.\"
.TH selog lua
.
.SH NAME
selog \- selective logging
.
.SH SYNOPSIS
.B require
"selog"
.P
\-\- intialization
.br
.RI selog.open( config )
.br
.RI selog.open( config ", {" name1 ", " name2 ", ...})"
.P
\-\- creating selectors
.br
.B local
.I sel
=
.RI selog.new( name ", " level )
.br
.B local
.I sel
=
.RI selog( name ", " level )
.br
.B local
.I sel
=
.RI selog( name ,
.DQ fatal(\fIstatus\fP) )
.br
.B local
.I sel
=
.RI selog( name ,
.DQ fatal ,
.IR status )
.P
\-\- inspecting selectors
.br
.B local
.I name
= sel.name
.br
.B local
.I level
= sel.level
.br
.B local
.I status
= sel.exitval
.P
.B if
sel.on
.BR then " ... " end
.P
\-\- logging
.br
.RI sel( message... )
.
.SH DESCRIPTION
Selog is a library of routines that unifies error reporting,
activity logging, and debug tracing.
It allows programmers to give their users flexible control over
which messages are written and where they are written to.
.P
This manual Lua interface to selog by reference to the C manual,
.BR selog (@lib@),
and the end-user manual,
.BR selog (@misc@).
.
.SS Initialization
To configure and reconfigure selog, call
.B selog.open()
passing the configuration string as the first argument.
The configuration syntax and other details are described in
.BR selog (@misc@).
If you want selog to check the category names in the configuration,
you should pass an array-like table as the second argument that lists
all the valid names.
More details can be found in the
.DQ INITIALIZATION
section of
.BR selog (@lib@).
.
.SS Creating selectors
Logging is performed using selectors, which are created by calling
.B selog.new()
or just
.B selog()
itself.
This takes two string arguments:
the selector's category
.I name
and its
.IR level .
More details can be found in the
.DQ SELECTORS
section of
.BR selog (@lib@).
The string equivalents for the levels are listed in
.BR selog (@misc@).
To specify the exit status of a
.DQ fatal
selector, you can either put it in round brackets at the end of the
level string, or you can pass it as a third argument.
.
.SS Inspecting selectors
You can extract information about a selector by treating it like a table.
The available keys are:
.TP
.B exitval
The exit status for
.DQ fatal
selectors, and
.B nil
for others.
.TP
.B level
The canonical name of the selector's level.
.TP
.B name
The category name given when the selector was created.
.TP
.B on
A boolean value that is true if the selector is enabled.
This can be used to disable message preparation code when a selector
is disabled.
.
.SS Logging
To log a message, just call the selector.
The arguments are concatenated with spaces between.
If the selector's level is
.DQ trace
then the message includes debug information about the caller.
.
.SH SEE ALSO
.BR selog (@lib@),
.BR selog (@misc@)
.
.SH AUTHOR
Written by Tony Finch <dot@dotat.at> <fanf2@cam.ac.uk>
.br
at the University of Cambridge Computing Service.
.br
Source available from <http://dotat.at/prog/selog>
.
.\" eof