What it is

On of the many things that didn't quite get into the Common Lisp standard was how to get a Lisp to output its call stack when something has gone wrong. As such, each Lisp has developed its own notion of what to display, how to display it, and what sort of arguments can be used to customize it. trivial-backtrace is a simple solution to generating a backtrace portably. As of 16 May 2012, it supports Allegro Common Lisp, LispWorks, ECL, MCL, SCL, SBCL and CMUCL. Its interface consists of three functions and one variable:

You can probably already guess what they do, but they are described in more detail below.

Mailing Lists

API

print-backtrace error &key output if-exists verbose
function

Send a backtrace for the error error to output.

The keywords arguments are:

  • :output - where to send the output. This can be:
    • a string (which is assumed to designate a pathname)
    • an open stream
    • nil to indicate that the backtrace information should be returned as a string

  • if-exists - what to do if output designates a pathname and the pathname already exists. Defaults to :append.

  • verbose - if true, then a message about the backtrace is sent to *terminal-io*. Defaults to nil.

If the output is nil, the returns the backtrace output as a string. Otherwise, returns nil.

print-backtrace-to-stream stream
function

Send a backtrace of the current error to stream.

Stream is assumed to be an open writable file stream or a string-output-stream. Note that print-backtrace-to-stream will print a backtrace for whatever the Lisp deems to be the current error.

print-condition condition stream
function
Print condition to stream using the pretty printer.
*date-time-format*
variable

The default format to use when printing dates and times.

  • %% - A '%' character
  • %d - Day of the month as a decimal number [01-31]
  • %e - Same as %d but does not print the leading 0 for days 1 through 9 [unlike strftime[], does not print a leading space]
  • %H - Hour based on a 24-hour clock as a decimal number [00-23] *%I - Hour based on a 12-hour clock as a decimal number [01-12]
  • %m - Month as a decimal number [01-12]
  • %M - Minute as a decimal number [00-59]
  • %S - Second as a decimal number [00-59]
  • %w - Weekday as a decimal number [0-6], where Sunday is 0
  • %y - Year without century [00-99]
  • %Y - Year with century [such as 1990]

This code is borrowed from the format-date function in metatilities-base.

Where is it

A git repository is available using 

git clone http://common-lisp.net/project/trivial-backtrace/trivial-backtrace.git

The darcs repository is still around but is not being updated. The command to get it is below: 

;;; WARNING: out of date  
darcs get http://common-lisp.net/project/trivial-backtrace/

trivial-backtrace is also ASDF installable. Its CLiki home is right where you'd expect.

There's also a handy gzipped tar file.

What is happening

14 May 2009
Moved to git; John Fremlin adds map-backtrace

1 June 2008
Release version 1.0