Common Lisp Package: LOG5

A Common Lisp logging library; CLLL? No, it's log5. Log5 is organized around 5 things: * Categories, * Senders, * Outputs, * Messages, and * the Context

README:

FUNCTION

Public

CATEGORY-SPECS

Returns a list of the defined category specs in alphatetical order.

CONFIGURATION-FILE (&KEY (NAME logging) (TYPE config) (PREFER-CURRENT-DIRECTORY-P T))

Returns the path to the standard log5 configuration file. This is used by `configure-from-file` to setup logging activitiy. `Configuration-file looks in the user's home directory (using `user-homedir-pathname`) and the directory specified by `*default-pathname-defaults*`. The default is to use a file named "logging.config" but you can use the `:name` and `:type` parameters to customize this. If files exist in both directories, the `configuration-file` will use the one in the home directory unless `:prefer-current-directory-p` is true.

DRIBBLE (&OPTIONAL PATHNAME &KEY (IF-EXISTS APPEND))

With a file name as an argument, dribble opens the file and sends a record of further I/O to that file. Without an argument, it closes the dribble file, and quits logging.

ERROR (DATUM &REST ARGUMENTS)

Invoke the signal facility on a condition formed from DATUM and ARGUMENTS. If the condition is not handled, the debugger is invoked.

ID->CATEGORY (ID)

Returns the category whose id is id (a number).

IGNORE-ERRORS-P

If true, then log5 will ignore any errors that occur during logging actions. If false, log5 will enter the debugging. This is setfable.

SETFIGNORE-ERRORS-P (VALUE)

If true, then log5 will ignore any errors that occur during logging actions. If false, log5 will enter the debugger. This is setfable.

LOG-MANAGER

Returns the component that handles all of log5's bookkeeping.

OUTPUT-SPECS

Returns a list of the current output specs in alphatetical order.

SENDERS

Returns a list of the current senders.

STOP-ALL-SENDERS

Stops all logging.

WARN (DATUM &REST ARGUMENTS)

Warn about a situation by signalling a condition formed by DATUM and ARGUMENTS. While the condition is being signaled, a MUFFLE-WARNING restart exists that causes WARN to immediately return NIL.

Undocumented

COMPILE-CATEGORY-SPEC

SETFCOMPILE-CATEGORY-SPEC (CATEGORY-SPEC)

CONFIGURE-FROM-FILE (PATH &KEY (STOP-SENDERS-FIRST? NIL))

DEBUGGING (&OPTIONAL CATEGORY-SPEC &KEY (OUTPUT-SPEC NIL SUPPLIED?) RESET?)

POP-CONTEXT

POP-INDENT

PUSH-CONTEXT (CONTEXT)

PUSH-INDENT (AMOUNT &REST ARGS &KEY &ALLOW-OTHER-KEYS)

UNDEBUGGING (&OPTIONAL CATEGORY-SPEC)

Private

CATEGORY-DOCUMENTATION (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

CATEGORY-EXPANDED-SPECIFICATION (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

CATEGORY-ID (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

CATEGORY-NAME (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

CATEGORY-NEGATED-VARIABLES (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

CATEGORY-SPECIFICATION (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

CATEGORY-VARIABLES (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

DOTTED-PAIR-P (PUTATIVE-PAIR)

Returns true if and only if `putative-pair` is a dotted-list. I.e., if `putative-pair` is a cons cell with a non-nil cdr.

FLATTEN (LIST)

Flattens LIST. Does not handle circular lists but does handle dotted lists.

LOG5-COMPILE-CATEGORY-SPEC (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOG5-CONTEXT (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOG5-DEBUG-CONSOLE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOG5-EXPANDED-COMPILE-CATEGORY-SPEC (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOG5-IGNORE-ERRORS? (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOG5-INDENTS (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

LOG5-SENDERS (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

NAME->CATEGORY (NAME)

Returns the category whose name (assumed to be properly **canonized**) is name.

OUTPUT-FORM (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

OUTPUT-FORMAT (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

OUTPUT-NAME (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

OUTPUT-STATIC? (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

RESET-CATEGORIES!

Remove all category definitions; In general, it's not a good idea to use this but it can be handy if you need a clean slate.

RESET-OUTPUT-SPECS!

Remove all output-specs; In general, it's not a good idea to use this but it can be handy if you need a clean slate.

Undocumented

%HANDLE-MESSAGE (ID MESSAGE ARG-THUNK)

%LOG-P (CATEGORY-SPEC)

ACTIVE-CATEGORY-P (ID)

BUILD-HANDLE-MESSAGE-FN (SENDER)

BUILT-IN-OUTPUT-SPECS

CANONIZE-CATEGORY-NAME (NAME &KEY (SIMPLE? NIL))

CANONIZE-CATEGORY-SPECIFICATION (SPECIFICATION)

SETFCATEGORY-DOCUMENTATION (NEW-VALUE INSTANCE)

SETFCATEGORY-EXPANDED-SPECIFICATION (NEW-VALUE INSTANCE)

SETFCATEGORY-ID (NEW-VALUE INSTANCE)

SETFCATEGORY-NAME (NEW-VALUE INSTANCE)

SETFCATEGORY-NEGATED-VARIABLES (NEW-VALUE INSTANCE)

SETFCATEGORY-SPECIFICATION (NEW-VALUE INSTANCE)

SETFCATEGORY-VARIABLES (NEW-VALUE INSTANCE)

COLLECT-KEY-VALUE (HT &KEY (TRANSFORM 'CONS))

COMPILE-HANDLE-MESSAGE-FN (FN)

COPY-LOG-CATEGORY (INSTANCE)

COPY-LOG-MANAGER (INSTANCE)

COPY-LOG-OUTPUT (INSTANCE)

DETERMINE-CATEGORY-VARIABLES (SPEC)

ENSURE-STREAM-OPEN (STREAM-SENDER)

EXPAND-CATEGORY (NAME)

FIND-OR-CREATE-DEBUG-CONSOLE (&OPTIONAL (OUTPUT-SPEC '(MESSAGE) SUPPLIED?))

INITIALIZE-CATEGORY-SPEC (SENDER)

LOG-CATEGORY-P (OBJECT)

LOG-MANAGER-P (OBJECT)

LOG-OUTPUT-P (OBJECT)

SETFLOG5-COMPILE-CATEGORY-SPEC (NEW-VALUE INSTANCE)

SETFLOG5-CONTEXT (NEW-VALUE INSTANCE)

SETFLOG5-DEBUG-CONSOLE (NEW-VALUE INSTANCE)

SETFLOG5-EXPANDED-COMPILE-CATEGORY-SPEC (NEW-VALUE INSTANCE)

SETFLOG5-IGNORE-ERRORS? (NEW-VALUE INSTANCE)

SETFLOG5-INDENTS (NEW-VALUE INSTANCE)

SETFLOG5-SENDERS (NEW-VALUE INSTANCE)

LOGICAL-CONNECTIVE-P (X)

MAKE-ACTIVE-CATEGORY-ARRAY (SENDER)

MAKE-CATEGORY-ARRAY (SIZE)

MAKE-INDENT-SPACE

MAKE-LOG-CATEGORY (&KEY ((NAME DUM227) NIL) ((SPECIFICATION DUM228) NIL) ((DOCUMENTATION DUM229) NIL) ((ID DUM230) NIL) ((EXPANDED-SPECIFICATION DUM231) NIL) ((VARIABLES DUM232) NIL) ((NEGATED-VARIABLES DUM233) NIL))

MAKE-LOG-MANAGER (&KEY ((SENDERS DUM72) NIL) ((CONTEXT DUM73) NIL) ((IGNORE-ERRORS? DUM74) NIL) ((COMPILE-CATEGORY-SPEC DUM75) NIL) ((EXPANDED-COMPILE-CATEGORY-SPEC DUM76) NIL) ((DEBUG-CONSOLE DUM77) NIL) ((INDENTS DUM78) NIL))

MAKE-LOG-OUTPUT (&KEY ((NAME DUM493) NIL) ((FORM DUM494) NIL) ((FORMAT DUM495) ~a) ((STATIC? DUM496) NIL))

MASSAGE-ARGUMENTS (ARGS)

MESSAGE-CREATOR-CLASS (SENDER)

SETFOUTPUT-FORM (NEW-VALUE INSTANCE)

SETFOUTPUT-FORMAT (NEW-VALUE INSTANCE)

SETFOUTPUT-NAME (NEW-VALUE INSTANCE)

SETFOUTPUT-STATIC? (NEW-VALUE INSTANCE)

PREDEFINED-OUTPUT-P (NAME)

SENDER-RESPONDS-TO-CATEGORY-P (SENDER-SPEC CATEGORY)

START-SENDER-FN (NAME CATEGORY-SPEC OUTPUT-SPEC SENDER-TYPE &REST ARGS)

STOP-SENDER-FN (NAME &KEY (WARN-IF-NOT-FOUND-P T))

UPDATE-CATEGORY-SPEC (NAME SPECIFICATION &KEY (DOCUMENTATION NIL DOCUMENTATION-SUPPLIED?))

UPDATE-OUTPUT-SPEC (NAME FORM &KEY FORMAT STATIC?)

VALID-OUTPUT-P (NAME)

MACRO

Public

DEFCATEGORY (NAME &OPTIONAL CATEGORY-SPEC DOCUMENTATION)

Define a category named `name`. This can be a simple category like (defcategory :error) (defcategory prize-allocation) of a complex category like (defcategory :bad-thing (or :error :warning :fatal)) (defcategory non-file-foo (and (or foo bar biz) (not file-access))) Specifically, a simple category is just a name whereas a complex category is a boolean combination of other categories (either simple or complex). See `category-specs` if you want a list of defined categories.

DEFOUTPUT (NAME FORM &KEY FORMAT STATIC?)

Define an output specification: a link between a `name` and a `form` that will be called during logging to put something in the log file. You can specify a `format` string (as in a call to `format`) with the :format keyword argument. You can use the keyword :static? to indicate that the form's value will not change (e.g., the time of day is _not_ static but the process id of the current Lisp is).

START-SENDER (NAME (SENDER-TYPE &REST ARGS) &KEY CATEGORY-SPEC OUTPUT-SPEC)

Create a log-message sender and add it to the list of active senders. Each sender has a `name`, a category-spec, an output-spec and a class (with optional initialization arguments). The `name` should be symbol and only one sender of any particular name can exist at a time. The category-spec is a boolean combination of categories (see `defcategory`). A sender will send any message whose message-category satisfies the sender's category-spec. The output-spec is a list of outputs defined with `defoutput`. You can also include strings and the special, predefined, outputs: * message - the text of the current log message * context - the contents of the current context (as a list) * category - the value of the category of the current message

STOP-SENDER (NAME &KEY (WARN-IF-NOT-FOUND-P T))

Find the sender named `name` and stop it. If the sender is not active, then a `sender-not-found-warning` will be signaled unless `warn-if-not-found-p` is set to nil.

TIME (FORM)

Execute FORM and print timing information on *TRACE-OUTPUT*. On some hardware platforms estimated processor cycle counts are included in this output; this number is slightly inflated, since it includes the pipeline involved in reading the cycle counter -- executing (TIME NIL) a few times will give you an idea of the overhead, and its variance. The cycle counters are also per processor, not per thread: if multiple threads are running on the same processor, the reported counts will include cycles taken up by all threads running on the processor where TIME was executed. Furthermore, if the operating system migrates the thread to another processor between reads of the cycle counter, the results will be completely bogus. Finally, the counter is cycle counter, incremented by the hardware even when the process is halted -- which is to say that cycles pass normally during operations like SLEEP.

TRACE (&REST SPECS)

TRACE {Option Global-Value}* {Name {Option Value}*}* TRACE is a debugging tool that provides information when specified functions are called. In its simplest form: (TRACE NAME-1 NAME-2 ...) The NAMEs are not evaluated. Each may be a symbol, denoting an individual function, or a string, denoting all functions fbound to symbols whose home package is the package with the given name. Options allow modification of the default behavior. Each option is a pair of an option keyword and a value form. Global options are specified before the first name, and affect all functions traced by a given use of TRACE. Options may also be interspersed with function names, in which case they act as local options, only affecting tracing of the immediately preceding function name. Local options override global options. By default, TRACE causes a printout on *TRACE-OUTPUT* each time that one of the named functions is entered or returns. (This is the basic, ANSI Common Lisp behavior of TRACE.) As an SBCL extension, the :REPORT SB-EXT:PROFILE option can be used to instead cause information to be silently recorded to be inspected later using the SB-EXT:PROFILE function. The following options are defined: :REPORT Report-Type If Report-Type is TRACE (the default) then information is reported by printing immediately. If Report-Type is SB-EXT:PROFILE, information is recorded for later summary by calls to SB-EXT:PROFILE. If Report-Type is NIL, then the only effect of the trace is to execute other options (e.g. PRINT or BREAK). :CONDITION Form :CONDITION-AFTER Form :CONDITION-ALL Form If :CONDITION is specified, then TRACE does nothing unless Form evaluates to true at the time of the call. :CONDITION-AFTER is similar, but suppresses the initial printout, and is tested when the function returns. :CONDITION-ALL tries both before and after. This option is not supported with :REPORT PROFILE. :BREAK Form :BREAK-AFTER Form :BREAK-ALL Form If specified, and Form evaluates to true, then the debugger is invoked at the start of the function, at the end of the function, or both, according to the respective option. :PRINT Form :PRINT-AFTER Form :PRINT-ALL Form In addition to the usual printout, the result of evaluating Form is printed at the start of the function, at the end of the function, or both, according to the respective option. Multiple print options cause multiple values to be printed. :WHEREIN Names If specified, Names is a function name or list of names. TRACE does nothing unless a call to one of those functions encloses the call to this function (i.e. it would appear in a backtrace.) Anonymous functions have string names like "DEFUN FOO". This option is not supported with :REPORT PROFILE. :ENCAPSULATE {:DEFAULT | T | NIL} If T, the tracing is done via encapsulation (redefining the function name) rather than by modifying the function. :DEFAULT is the default, and means to use encapsulation for interpreted functions and funcallable instances, breakpoints otherwise. When encapsulation is used, forms are *not* evaluated in the function's lexical environment, but SB-DEBUG:ARG can still be used. :METHODS {T | NIL} If T, any function argument naming a generic function will have its methods traced in addition to the generic function itself. :FUNCTION Function-Form This is a not really an option, but rather another way of specifying what function to trace. The Function-Form is evaluated immediately, and the resulting function is instrumented, i.e. traced or profiled as specified in REPORT. :CONDITION, :BREAK and :PRINT forms are evaluated in a context which mocks up the lexical environment of the called function, so that SB-DEBUG:VAR and SB-DEBUG:ARG can be used. The -AFTER and -ALL forms are evaluated in the null environment.

Undocumented

LOG-FOR (CATEGORY-SPEC MESSAGE &REST ARGS)

LOG-IF (PREDICATE CATEGORY-SPEC MESSAGE &REST ARGS)

START-STREAM-SENDER (NAME LOCATION &KEY OUTPUT-SPEC CATEGORY-SPEC)

WHEN-LOGGING (CATEGORY-SPEC &BODY BODY)

WITH-CONTEXT (CONTEXT &BODY BODY)

WITH-CONTEXT-FOR (CATEGORY-SPEC CONTEXT &BODY BODY)

WITH-INDENT ((AMOUNT &REST ARGS &KEY &ALLOW-OTHER-KEYS) &BODY BODY)

Private

Undocumented

%WITH-VARS (VARS DEFAULT &BODY BODY)

HANDLE-MESSAGE (ID MESSAGE &REST ARGS)

GENERIC-FUNCTION

Public

Undocumented

CLOSE-SENDER (SENDER)

CREATE-HANDLE-MESSAGE-CONTEXT (SENDER)

FINISH-HANDLING (SENDER)

START-HANDLING (SENDER)

Private

Undocumented

CREATE-MESSAGE-FOR-SENDER (MESSAGE-CREATOR MESSAGE ARGS)

HANDLE-OUTPUT (SENDER OUTPUT)

SENDER-NAME (CONDITION)

SEPARATE-PROPERTIES (SENDER)

UPDATE-ACTIVE-CATEGORIES (SENDER MAXIMUM-ID)

SLOT-ACCESSOR

Public

Undocumented

CATEGORY-SPEC (OBJECT)

CLOSE-STREAM? (OBJECT)

LOCATION (OBJECT)

NAME (CONDITION)

OUTPUT-SPEC (OBJECT)

OUTPUT-STREAM (OBJECT)

Private

Undocumented

%SET-MESSAGE-CREATOR (NEW-VALUE OBJECT)

ACTIVE-CATEGORIES (OBJECT)

EXPANDED-SPECIFICATION (OBJECT)

HANDLE-MESSAGE-FN (OBJECT)

LOCK (OBJECT)

MESSAGE-CREATOR (OBJECT)

SPECS (OBJECT)

SETFSPECS (NEW-VALUE OBJECT)

VARIABLE

Private

Undocumented

*CATEGORY-SPECS*

*DEFAULT-LOGICAL-CONNECTIVE*

*ID->CATEGORY*

*LOG-MANAGER*

*NAME->CATEGORY*

*OUTPUT-SPECS*

CLASS

Public

BASIC-SENDER

The root sender class from which all senders ~ should descend.

SENDER-WITH-CATEGORIES

A sender that responds only to certain log categories.

Undocumented

LOG-MANAGER

STREAM-SENDER

STREAM-SENDER-MIXIN

Private

Undocumented

BASIC-MESSAGE-CREATOR

DEBUG-CONSOLE-SENDER

LOG-CATEGORY

LOG-OUTPUT

CONDITION

Public

Undocumented

ERROR (DATUM &REST ARGUMENTS)

Private

Undocumented

BAD-CATEGORY-TYPE-ERROR

OUTPUT-NOT-FOUND-ERROR

SENDER-NOT-FOUND-WARNING

SIMPLE-CATEGORY-NOT-FOUND-ERROR