You are looking at historical revision 21443 of this page. It may differ significantly from its current revision.

log5scm

Introduction

A logging library based on the ideas of CL's log5

Examples

(use log5scm syslog)

(define-category info)
(define-category debug)
(define-category warn)
(define-category warn+ (or info debug warn))

(define-category controller)
(define-category model)
(define-category app (or controller model))

(define-output model-out "model-out")
(define-output controller-out "controller-out")
(define-output app-out "app-out")

;;start port senders
(start-sender model-sender (port-sender (current-error-port)) (output (model-out message)) (category model))
(start-sender controller-sender (port-sender (current-error-port)) (output (controller-out message)) (category controller))
(start-sender app-sender (port-sender (current-error-port)) ( output (app-out message))  (category app))

;;additionally send every warning to syslog
(start-sender syslog-warn (syslog-sender "test" opt/pid facility/local0 prio/warning) (category warn))

(log-for (model warn) "just a ~A" "Test")
(log-for (app) "nother Test")

Authors

David Krentzlin

License

 Copyright (c) 2010 David Krentzlin 

 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.

Documentation

[parameter] *default-logical-connective*

As the name suggests this is the connective that is assumed, if you do not explicitly specify it in the category-spec.

Categories

Categories are just a way to organize your logmessages. You may arrange as many and as complex categories as you wish. They're, as the name suggests, a way to express buckets for log-messages. Those buckets may later be bound to senders and thus enable the program to put messages at the right places

[syntax] (define-category category-spec)

Syntax to define categories. You can define simple and complex categories.

(define-category info)
(define-category debug)
(define-category warn)
(define-category warn+ (or info debug warn))
[procedure] (dump-categories)

Print all currently known categories to (current-output-port).

Senders

Senders are basically filtered sinks for messages. Any message that comes in, will be analyzed against the category-specification and only if a match is found the message is send to its destination. Furthermore senders decide where the output goes. The most commonly used senders will be port-senders. But you could as well send messages to syslog or to a port or via email or whatever. You're free to define a custom sender-type and use it for logging.

[syntax] (start-sender sender-constructor (category category-spec) [(output output-spec)])

Create and register a sender for the given categories. This sender will only react on matching categories.

;;start a port-sender for the category 'model' that outputs the data as "category message"
(start-sender model-sender (port-sender (current-output-port)) (output (category message)) (category model))
[procedure] (dump-senders)

Print the list of all known senders to current-output-port.

Sender constructors
[procedure] (port-sender port-or-path)

Creates a sender that outputs to a port. If port-or-path is a port, all data will be send to this port. If port-or-path is a string, it is considered a path to a file. The file will be opened and all messages will be send to this file.

[procedure] (syslog-sender ident options facility prio)

Creates a syslog-sender. All messages will be send to syslog with the given parameters. See also syslog.

Outputs

Outputs are just a way to format your message. Technically an output is a procedure that returns a string. Multiple outputs can be combined into a list of outputs that are processed in order when a message is generated

[syntax] (define-output name code)

Register an output with the given name. The output will be generated by evaluating code. During the evaluation of code the following parameters will be bound.

(define-output test-output (string-join (shuffle (string-split (*current-message*) " ") random) " "))
Predefined outputs

There are some outputs predefined that can be used inside output-specifications

[parameter] *default-output-spec*

This is the output-specification that is used by default when a sender is invoked.

Logging

The actual logging is done using the log-for syntax.

[syntax] (log-for spec fmt . args)

This form will invoke the logging machinery. It will find the senders that match the given spec, and send the message to all senders that have a matching category-specification.