The vom Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The vom Reference Manual

This is the vom Reference Manual, version 0.1.4, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 16:00:15 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Vom - A tiny logging library for Common Lisp

Vom is a logging library for lisp. It's goal is to be useful and small. It does not provide a lot of features as other loggers do, but has a small codebase that's easy to understand and use.

Documentation

Logging is done by calling one of the logging macros:

Each of these is a macro defined as such:

(defmacro notice (format-str &rest args) ...)

They are used almost exactly like format (but without specifying the stream):

(vom:error "there was a problem setting up your database: ~a" error)

Configuration

You can set a global logging level:

;; set the default loglevel such that only errors (or higher) get logged
(vom:config t :error)

or you can set per-package loglevels:

(vom:config :my-package :notice)

In the above examples, any unconfigured package will have the loglevel of :error, but the package my-package will log anything that's a :notice or above.

*log-stream*

The stream that vom logs to by default. This defaults to t (aka *standard-output*)

*log-hook*

This is a function of 3 arguments that takes a log level, a package keyword name, and that package's configured log level and returns one or more streams as multiple values that the log entry will be logged to:

;; example: this hook logs the request to multiple streams if we're getting a
;; log entry from the "particle-accelerator" package
(setf vom:*log-hook*
  (lambda (level package package-level)
    (declare (ignore level package-level))
    (if (eq package :particle-accelerator)
        (values t *my-file-log-stream* *another-stream*)
        t)))

License

MIT. Do what you want with it. Just give me credit. Or I'll come to your house for two weeks and eat your food and sleep on your couch and use your toothbrush.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 vom

Author

Andrew Danger Lyon <orthecreedence@gmail.com>

License

MIT

Description

A tiny logging utility.

Version

0.1.4

Source

vom.asd (file)

Component

vom.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 vom.asd

Location

vom.asd

Systems

vom (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 vom/vom.lisp

Parent

vom (system)

Location

vom.lisp

Packages

vom

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 vom

Source

vom.lisp (file)

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *config*

Holds the logging config as a plist. Holds package -> level mappings, using T as the default (used if logging from a package that hasn’t been configured).

Package

vom

Source

vom.lisp (file)

Special Variable: *log-formatter*

A function that takes a format string (user-supplied), a level string (eg ’notice’ or ’error’), a keyword of the current package, and a list of args the user supplied with the format string and returns a string of the log line we want logged.

Package

vom

Source

vom.lisp (file)

Special Variable: *log-hook*

Holds a function that, given a log-level, a package name, and the effective log-level for that package, returns one or more (via (values ...)) streams that this log will be sent to.

Package

vom

Source

vom.lisp (file)

Special Variable: *log-stream*

Holds the default stream we’re logging to.

Package

vom

Source

vom.lisp (file)

Special Variable: *time-formatter*

A function of 0 args that returns the current time in the desired format.

Package

vom

Source

vom.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: alert FORMAT-STR &rest ARGS

Log output to the :ALERT log level (2)

Package

vom

Source

vom.lisp (file)

Macro: crit FORMAT-STR &rest ARGS

Log output to the :CRIT log level (3)

Package

vom

Source

vom.lisp (file)

Macro: debug FORMAT-STR &rest ARGS

Log output to the :DEBUG log level (8)

Package

vom

Source

vom.lisp (file)

Macro: debug1 FORMAT-STR &rest ARGS

Log output to the :DEBUG1 log level (9)

Package

vom

Source

vom.lisp (file)

Macro: debug2 FORMAT-STR &rest ARGS

Log output to the :DEBUG2 log level (10)

Package

vom

Source

vom.lisp (file)

Macro: debug3 FORMAT-STR &rest ARGS

Log output to the :DEBUG3 log level (11)

Package

vom

Source

vom.lisp (file)

Macro: debug4 FORMAT-STR &rest ARGS

Log output to the :DEBUG4 log level (12)

Package

vom

Source

vom.lisp (file)

Macro: emerg FORMAT-STR &rest ARGS

Log output to the :EMERG log level (1)

Package

vom

Source

vom.lisp (file)

Macro: error FORMAT-STR &rest ARGS

Log output to the :ERROR log level (4)

Package

vom

Source

vom.lisp (file)

Macro: info FORMAT-STR &rest ARGS

Log output to the :INFO log level (7)

Package

vom

Source

vom.lisp (file)

Macro: notice FORMAT-STR &rest ARGS

Log output to the :NOTICE log level (6)

Package

vom

Source

vom.lisp (file)

Macro: warn FORMAT-STR &rest ARGS

Log output to the :WARN log level (5)

Package

vom

Source

vom.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: config PACKAGE-KEYWORD LEVEL-NAME

Configure the log level for a package (or use t for the package name to set the default log level). The log level is given as a keyword.

Package

vom

Source

vom.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *levels*

Holds the log level mappings (keyword -> value).

Package

vom

Source

vom.lisp (file)

Special Variable: *max-level-name-length*

Holds the number of characters in the longest log-level name.

Package

vom

Source

vom.lisp (file)

Special Variable: *package-level-cache*

A cache that holds package alias -> package loglevel values for quick lookup.

Package

vom

Source

vom.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: define-level NAME LEVEL-VALUE

Define a log level.

Package

vom

Source

vom.lisp (file)

Macro: log-alert FORMAT-STR &rest ARGS

Log output to the :ALERT log level (2)

Package

vom

Source

vom.lisp (file)

Macro: log-crit FORMAT-STR &rest ARGS

Log output to the :CRIT log level (3)

Package

vom

Source

vom.lisp (file)

Macro: log-debug FORMAT-STR &rest ARGS

Log output to the :DEBUG log level (8)

Package

vom

Source

vom.lisp (file)

Macro: log-debug1 FORMAT-STR &rest ARGS

Log output to the :DEBUG1 log level (9)

Package

vom

Source

vom.lisp (file)

Macro: log-debug2 FORMAT-STR &rest ARGS

Log output to the :DEBUG2 log level (10)

Package

vom

Source

vom.lisp (file)

Macro: log-debug3 FORMAT-STR &rest ARGS

Log output to the :DEBUG3 log level (11)

Package

vom

Source

vom.lisp (file)

Macro: log-debug4 FORMAT-STR &rest ARGS

Log output to the :DEBUG4 log level (12)

Package

vom

Source

vom.lisp (file)

Macro: log-emerg FORMAT-STR &rest ARGS

Log output to the :EMERG log level (1)

Package

vom

Source

vom.lisp (file)

Macro: log-error FORMAT-STR &rest ARGS

Log output to the :ERROR log level (4)

Package

vom

Source

vom.lisp (file)

Macro: log-info FORMAT-STR &rest ARGS

Log output to the :INFO log level (7)

Package

vom

Source

vom.lisp (file)

Macro: log-notice FORMAT-STR &rest ARGS

Log output to the :NOTICE log level (6)

Package

vom

Source

vom.lisp (file)

Macro: log-warn FORMAT-STR &rest ARGS

Log output to the :WARN log level (5)

Package

vom

Source

vom.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: clear-level-cache ()

Clears the package loglevel cache.

Package

vom

Source

vom.lisp (file)

Function: do-log ()

The given data to the current *log-stream* stream.

Package

vom

Source

vom.lisp (file)

Function: find-package-level ()

Given package keyword (doesn’t have to be an exact match, can be an alias), find the configured loglevel of that package.

This caches the package->level connection in *package-level-cache*.

Package

vom

Source

vom.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   V  
Index Entry  Section

F
File, Lisp, vom.asd: The vom<dot>asd file
File, Lisp, vom/vom.lisp: The vom/vom<dot>lisp file

L
Lisp File, vom.asd: The vom<dot>asd file
Lisp File, vom/vom.lisp: The vom/vom<dot>lisp file

V
vom.asd: The vom<dot>asd file
vom/vom.lisp: The vom/vom<dot>lisp file

Jump to:   F   L   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   E   F   I   L   M   N   W  
Index Entry  Section

A
alert: Exported macros

C
clear-level-cache: Internal functions
config: Exported functions
crit: Exported macros

D
debug: Exported macros
debug1: Exported macros
debug2: Exported macros
debug3: Exported macros
debug4: Exported macros
define-level: Internal macros
do-log: Internal functions

E
emerg: Exported macros
error: Exported macros

F
find-package-level: Internal functions
Function, clear-level-cache: Internal functions
Function, config: Exported functions
Function, do-log: Internal functions
Function, find-package-level: Internal functions

I
info: Exported macros

L
log-alert: Internal macros
log-crit: Internal macros
log-debug: Internal macros
log-debug1: Internal macros
log-debug2: Internal macros
log-debug3: Internal macros
log-debug4: Internal macros
log-emerg: Internal macros
log-error: Internal macros
log-info: Internal macros
log-notice: Internal macros
log-warn: Internal macros

M
Macro, alert: Exported macros
Macro, crit: Exported macros
Macro, debug: Exported macros
Macro, debug1: Exported macros
Macro, debug2: Exported macros
Macro, debug3: Exported macros
Macro, debug4: Exported macros
Macro, define-level: Internal macros
Macro, emerg: Exported macros
Macro, error: Exported macros
Macro, info: Exported macros
Macro, log-alert: Internal macros
Macro, log-crit: Internal macros
Macro, log-debug: Internal macros
Macro, log-debug1: Internal macros
Macro, log-debug2: Internal macros
Macro, log-debug3: Internal macros
Macro, log-debug4: Internal macros
Macro, log-emerg: Internal macros
Macro, log-error: Internal macros
Macro, log-info: Internal macros
Macro, log-notice: Internal macros
Macro, log-warn: Internal macros
Macro, notice: Exported macros
Macro, warn: Exported macros

N
notice: Exported macros

W
warn: Exported macros

Jump to:   A   C   D   E   F   I   L   M   N   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*config*: Exported special variables
*levels*: Internal special variables
*log-formatter*: Exported special variables
*log-hook*: Exported special variables
*log-stream*: Exported special variables
*max-level-name-length*: Internal special variables
*package-level-cache*: Internal special variables
*time-formatter*: Exported special variables

S
Special Variable, *config*: Exported special variables
Special Variable, *levels*: Internal special variables
Special Variable, *log-formatter*: Exported special variables
Special Variable, *log-hook*: Exported special variables
Special Variable, *log-stream*: Exported special variables
Special Variable, *max-level-name-length*: Internal special variables
Special Variable, *package-level-cache*: Internal special variables
Special Variable, *time-formatter*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   V  
Index Entry  Section

P
Package, vom: The vom package

S
System, vom: The vom system

V
vom: The vom system
vom: The vom package

Jump to:   P   S   V