= Normal Logging API
The Normal Logging API differentiates between "normal" log messages and "debug" log messages. This gives you two separate streams to write logging messages to. It also allows you to save all messages (normal and debug) to a set of other streams. This will let you, for example, save all the messages to a file as well as output them to the console.
== Types
* '''{{{T/LOG-LEVEL}}}''': Equivalent to {{{(UNSIGNED-BYTE 8)}}}.
== Globals
These are the various special variables that will influence how the Normal Logging API functions.
* '''{{{*LOG-LEVEL*}}}''': The minimum level required to log messages. This can be any number of type {{{T/LOG-LEVEL}}}.
* '''{{{*debug-LEVEL*}}}''': The minimum level required to log a debug message. This can be any number of type {{{T/LOG-LEVEL}}}.
* '''{{{*LOG-STREAM*}}}''': The main stream to log messages to. Default is {{{*STANDARD-OUTPUT*}}}.
* '''{{{*DEBUG-STREAM*}}}''': The main stream to log debugging messages to. Default is {{{*ERROR-OUTPUT*}}}.
* '''{{{*MORE-LOG-STREAMS*}}}''': A list of additional streams to write normal and debug log messages to.
* '''{{{*DEFAULT-HEADER*}}}''': When no header is specified in a normal logging function, this one will be displayed instead.
* '''{{{*DEBUG-HEADER*}}}''': The default header for debug logging. This is always output.
* '''{{{*FORCE-OUTPUT*}}}''': When non-{{{NIL}}}, {{{FORCE-OUTPUT}}} will be called after each logging call (though it can still be controlled with the lower-level function {{{LOG/BASE}}}). '''NOTE''': this also affects the SimpleLoggingApi.
== Normal Logging Functions/Macros
![Function][[BR]]
'''{{{LOG/BASE}}}''' ''{{{min-level}}} {{{header}}} {{{stream}}} {{{force-output}}} {{{dont-output-to-extras}}} {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Low-level logging function. The output message is constructed so that {{{HEADER}}} appears first in brackets, followed by a colon and space, and then {{{MSG}}}, {{{FORMAT}}}ted with {{{FMT-ARGS}}}. In other words, the output format is such:
{{{
[header]: <formatted message>
}}}
Alternatively, if {{{HEADER}}} is an empty string, no header is output at all. Thus the output format is just:
{{{
<formatted output>
}}}
This message is only printed to {{{STREAM}}} if {{{MIN-LEVEL}}} is less than or equal to {{{LOG-LEVEL}}}, or {{{FORCE-OUTPUT}}} is non-{{{NIL}}}. Otherwise, nothing is printed.
If something is output to the primary stream, and {{{DONT-OUTPUT-TO-EXTRAS}}} is {{{NIL}}}, the formatted message is also printed to all extra streams defined in {{{MORE-LOG-STREAMS}}}.
![Macro][[BR]]
'''{{{WITH-LOGGING/BASE}}}''' ’’({{{log-output-var}}} {{{min-level}}} {{{header}}} {{{stream}}} {{{force-output}}} {{{dont-output-to-extras}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{LOG/BASE}}} with the the finished string. Returns a string when finished.
![Macro][[BR]]
'''{{{LOG}}}''' ''({{{min-level}}} ,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the log stream and all extra log streams, except if {{{MIN-LEVEL}}} is greater than the current {{{LOG-LEVEL}}}. If {{{MIN-LEVEL}}} is higher than {{{LOG-LEVEL}}}, nothing is actually written to any log stream.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{FLOG}}}''' ''(,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the log stream and all extra log streams. This ignores {{{LOG-LEVEL}}}, and thus always outputs something.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{LOG/NO-EXTRAS}}}''' ''({{{min-level}}} ,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the main log stream, but does not output anything to any extra log stream. However, if {{{MIN-LEVEL}}} is greater than the current {{{LOG-LEVEL}}}, nothing is actually written to ''any'' log stream and this effectively does nothing.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{FLOG/NO-EXTRAS}}}''' ''(,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the main log stream, but does not output anything to any extra log stream. This ignores {{{LOG-LEVEL}}}, and thus always outputs something.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{WITH-LOGGING}}}''' ''({{{log-output-var}}} {{{min-level}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{LOG/BASE}}} with the the finished string.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{WITH-FLOGGING}}}''' ''({{{log-output-var}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{LOG/BASE}}} with the the finished string, forcing the output.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{WITH-LOGGING/NO-EXTRAS}}}''' ''({{{log-output-var}}} {{{min-level}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{LOG/BASE}}} with the the finished string, specifying that no extra streams should be written to.
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
![Macro][[BR]]
'''{{{WITH-FLOGGING}}}''' ''({{{log-output-var}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{LOG/BASE}}} with the the finished string, forcing the output to the main
stream, but skipping output to extra streams
If {{{HEADER}}} is supplied and is an empty string, no header will be output at all. If {{{HEADER}}} is not supplied at all, it will default to {{{*DEFAULT-HEADER*}}}.
== Debug Logging Functions/Macros
![Function][[BR]]
'''{{{DEBUG-LOG/BASE}}}''' ''{{{min-level}}} {{{header}}} {{{stream}}} {{{force-output}}} {{{dont-output-to-extras}}} {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Low-level logging function. The output message is constructed so that {{{HEADER}}} appears first in brackets, followed by a colon and space, and then {{{MSG}}}, {{{FORMAT}}}ted with {{{FMT-ARGS}}}. In other words, the output format is such:
{{{
[header]: <formatted message>
}}}
Alternatively, if {{{HEADER}}} is an empty string, no header is output at all. Thus the output format is just:
{{{
<formatted output>
}}}
This message is only printed to {{{STREAM}}} if {{{MIN-LEVEL}}} is less than or equal to {{{*DEBUG-LEVEL*}}}, or {{{FORCE-OUTPUT}}} is non-{{{NIL}}}. Otherwise, nothing is printed. If something is output to the primary stream, and {{{DONT-OUTPUT-TO-EXTRAS}}} is {{{NIL}}}, the formatted message is also printed to all extra streams defined in {{{*MORE-LOG-STREAMS*}}}.
![Macro][[BR]]
'''{{{WITH-DEBUG-LOGGING/BASE}}}''' ''({{{log-output-var}}} {{{min-level}}} {{{header}}} {{{stream}}} {{{force-output}}} {{{dont-output-to-extras}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{DEBUG-LOG/BASE}}} with the the finished string. Returns a string when finished.
![Macro][[BR]]
'''{{{DEBUG-LOG}}}''' ''({{{min-level}}} ,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the log stream and all extra log streams, except if {{{MIN-LEVEL}}} is greater than the current {{{{{{DEBUG-LOG-LEVEL}}}}}}. If {{{MIN-LEVEL}}} is higher than {{{{{{DEBUG-LOG-LEVEL}}}}}}, nothing is actually written to any log stream. The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{DEBUG-FLOG}}}''' ''(,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the log stream and all extra log streams. This ignores {{{{{{DEBUG-LOG-LEVEL}}}}}}, and thus always outputs something.
The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{DEBUG-LOG/NO-EXTRAS}}}''' ''({{{min-level}}} ,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the main log stream, but does not output anything to any extra log stream. However, if {{{MIN-LEVEL}}} is greater than the current {{{{{{LOG-LEVEL}}}}}}, nothing is actually written to any log stream and this effectly does nothing. The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{DEBUG-FLOG/NO-EXTRAS}}}''' ''(,,{{{&optional}}},, {{{header}}}) {{{msg}}} ,,{{{&rest}}},, {{{fmt-args}}}''
Logs a message to the main log stream, but does not output anything to any extra log stream. This ignores {{{{{{DEBUG-LOG-LEVEL}}}}}}, and thus always outputs something. The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{WITH-DEBUG-LOGGING}}}''' ({{{log-output-var}}} {{{min-level}}} ,,{{{&optional}}},, ({{{header}}} {{{\*default-header\*}}})) ,,{{{&body}}},, {{{forms}}}
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{DEBUG-LOG/BASE}}} with the the finished string.
The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{WITH-DEBUG-FLOGGING}}}''' ''({{{log-output-var}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{DEBUG-LOG/BASE}}} with the the finished string, forcing the output.
The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{WITH-DEBUG-LOGGING/NO-EXTRAS}}}''' ''({{{log-output-var}}} {{{min-level}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{DEBUG-LOG/BASE}}} with the the finished string, specifying that no extra streams should be written to.
The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}
![Macro][[BR]]
'''{{{WITH-DEBUG-FLOGGING}}}''' ''({{{log-output-var}}} ,,{{{&optional}}},, {{{header}}}) ,,{{{&body}}},, {{{forms}}}''
Binds {{{LOG-OUTPUT-VAR}}} to a string stream that you can write to in {{{FORMS}}}, then calls {{{DEBUG-LOG/BASE}}} with the the finished string, forcing the output to the main stream, but skipping output to extra streams.
The default header is always the same as {{{{{{DEBUG-HEADER}}}}}}. If you would like to prepend an extra header, you must supply {{{EXTRA-HEADER}}}. The header format will then be as such:
{{{
[extraheader-DEBUGHEADER]: <formatted message>
}}}