P36-LOG

P36-Log is a simple logging library for Common Lisp. Logging and Debug Logging are conceptually separate in this library.

How do I get set up?

• Clone the repository locally
• Use ASDF to load the system inside of your Lisp implementation (e.g., (asdf:load-system :p36-log))
• Read the Wiki to see how to use the library

The Two APIs

There are two APIs in P36-LOG: the "Normal Logging API" and the "Simple Logging API". The difference is that the Normal one allows for more control over when messages get displayed. The Simple API, however, always prints something.

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 Simple Logging API - the appropriate section for more info.

Normal Logging Functions/Macros

[Function]
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, FORMATted 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]
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]
LOG (min-level &optional (header *default-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.

[Macro]
FLOG (&optional (header *default-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.

[Macro]
LOG/NO-EXTRAS (min-level &optional (header *default-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.

[Macro]
FLOG/NO-EXTRAS (&optional (header *default-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.

[Macro]
WITH-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 LOG/BASE with the the finished string.

If HEADER is supplied and is an empty string, no header will be output at all.

[Macro]
WITH-FLOGGING (log-output-var &optional (header *default-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.

[Macro]
WITH-LOGGING/NO-EXTRAS (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 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.

[Macro]
WITH-FLOGGING (log-output-var &optional (header *default-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.

Debug Logging Functions/Macros

[Macro]
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, FORMATted 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]
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]
DEBUG-LOG (min-level &optional (header *default-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]
DEBUG-FLOG (&optional (header *default-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]
DEBUG-LOG/NO-EXTRAS (min-level &optional (header *default-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]
DEBUG-FLOG/NO-EXTRAS (&optional (header *default-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]
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]
WITH-DEBUG-FLOGGING (log-output-var &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, 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]
WITH-DEBUG-LOGGING/NO-EXTRAS (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, 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]
WITH-DEBUG-FLOGGING (log-output-var &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, 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>

Simple Logging API

The Simple Logging API is designed so that there are only three functions (actually macros) that you use. It is still somewhat configurable, though not to the same degree as the Normal Logging API

Types

• T/SIMPLE-LOG-TYPE: A keyword that is one of: :INFO, :ERROR, or :WARN.

Globals

These are the various special variables that will influence how the Simple Logging API functions.

• *SIMPLE-HEADER/INFO*: The header for info messages printed using the Simple Logging API. Default: "Info".
• *SIMPLE-HEADER/WARN*: The header for warning messages printed using the Simple Logging API. Default: "Warning".
• *SIMPLE-HEADER/ERROR*: The header for error messages printed using the Simple Logging API. Default: "Error".
• *SIMPLE-COLOR/INFO*: The color of the header for info messages printed using the Simple Logging API. Default: :CYAN.
• *SIMPLE-COLOR/WARN*: The color of the header for warning messages printed using the Simple Logging API. Default: :YELLOW.
• *SIMPLE-COLOR/ERROR*: The color of the header for error messages printed using the Simple Logging API. Default: :RED.
• *SIMPLE-STREAM/INFO*: The stream to write info messages when using the Simple Logging API. Default: *STANDARD-OUTPUT*
• *SIMPLE-STREAM/WARN*: The stream to write warning messages when using the Simple Logging API. Default: *ERROR-OUTPUT*
• *SIMPLE-STREAM/ERROR*: The stream to error warning messages when using the Simple Logging API. Default: *ERROR-OUTPUT*
• *SIMPLE/NO-COLOR*: When non-NIL, do not use ANSI color sequences when logging with the Simple Logging API. This will cause the various *SIMPLE-COLOR/ variables to be ignored. Default: NIL.
• *FORCE-OUTPUT*: When non-NIL, FORCE-OUTPUT will be called after each logging call. NOTE: this also affects the Normal Logging API - the appropriate section for more info.

The various -COLOR/ variables should be of type P36:T/ANSI-SIMPLE-COLOR, as defined in the P36-LIB package.

Simple API Logging Macros

[Macro]
SINFO msg &rest fmt-args

Writes the *SIMPLE-HEADER/INFO* string in brackets, followed by a colon and space, and then formats MSG with FMT-ARGS to *SIMPLE-STREAM/INFO*. The header is colored with *SIMPLE-COLOR/INFO* unless *SIMPLE/NO-COLOR* is NIL.

The resulting output will look like this (assuming the default header):

  [Info]: <your message>

[Macro]
SWARN msg &rest fmt-args

Writes the *SIMPLE-HEADER/WARN* string in brackets, followed by a colon and space, and then formats MSG with FMT-ARGS to *SIMPLE-STREAM/WARN*. The header is colored with *SIMPLE-COLOR/WARN* unless *SIMPLE/NO-COLOR* is NIL.

The resulting output will look like this (assuming the default header):

  [Warning]: <your message>

[Macro]
SERROR msg &rest fmt-args

Writes the *SIMPLE-HEADER/ERROR* string in brackets, followed by a colon and space, and then formats MSG with FMT-ARGS to *SIMPLE-STREAM/ERROR*. The header is colored with *SIMPLE-COLOR/ERROR* unless *SIMPLE/NO-COLOR* is NIL.

The resulting output will look like this (assuming the default header):

  [Error]: <your message>