pretty-function

http://github.com/nallen05/pretty-function

Introduction

pretty-function provides an API for making individual functions pprint differently when written to an output stream

Download

Download the latest gzipped tarball:

Version 0.1.1 3.28.2009 -- Updated documentation for Github, converted to Markdown
Version 0.1 21.09.2007

or get the latest version from the Git repository:

git clone git://github.com/nallen05/pretty-function.git

License

BSD. Thanks to Streamtech for letting me open source this tool.

Supported Implementations

ENABLE-PRETTY-FUNCTION-PRINTING seems to work and the tests in pretty-function-test.lisp pass on the following implimentations:

ACL
Clisp
CMUCL
Lispworks
OpenMCL/MCL
SBCL

the rest should fail gracefully by not pprinting pretty functions any differently from normal functions

When to use pretty functions

pretty-function is intended to make code with a lot of first class functions and closures saner to debug.

There is a little extra work involved when creating or garbage-collecting pretty functions, so they probubly shouldn't be used in situations where arbitrarily large amounts of closures being created and garbage-collected at runtime.

A good example use-case is a Hunchentoot-powered web application (note: Hunchentoot underwent major API changes to become Hunchentoot 1.x, does it still behave like this?):

Hunchentoot deals with HTTP requests by means of a global dispatch table. The dispatch table is a list of function indicators ("dispatchers") that often contains a buch of closures (such as the one created by CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER). When hunchentoot gets an HTTP request, each dispatcher is called with the request object as an argument. when a dispatcher decides to handle this request, it signals its intent by returning another function (a "handler") that, when called, does all the HTML/HTTP stuff associated with handling the request.

Dspatchers are perfect canidates for pretty-functions since, as pretty functions, they can pprint something informative like.

#<static-file-dispatcher "/foo/bar.html">

instead of the usual

#<what-the-hell-am-i>

in a stack trace or when a programmer is visually inspecting the dispatch table via the REPL.

Hunchentoot's dynamically generated handlers, on the other hand, are not good canidates for pretty function forms because there could be zillions of them being created and garbage collected at runtime.

The existence of pretty functions in a lisp image does not create any more work when creating or garbage collecting "normal" functions or closures (those not created with pretty function forms).

API

ENABLE-PRETTY-FUNCTION-PRINTING (&optional (priority 0) (table *print-pprint-dispatch*))

Function that modifies the pprint dispatch table TABLE to pprint functions using their pretty function printer (see GET-FUNCTION-PRINTER).

this means that you can make all the pretty functions you want, but until you run

(enable-pretty-function-printing)

the won't pprint differently in the REPL or in stack traces!

for info in its arguments, see Common Lisp's SET-PPRINT-DISPATCH.

NAMED-LAMBDA (name lambda-list &body body)

Macro like LAMBDA except the resultant function is prittern as

#<named-lambda NAME>

when pprinted to a stream and pretty printing functions has been enabled (see ENABLE-PRETTy-FUNCTION-PRINTING).

NAME is not evaluated.

Caveat: unlike LAMBDA, NAMED-LAMBDA cannot be used as the first element of a list

((lambda (a b) (+ a b)) 5 6) => 11

but

((named-lambda mistake (a b) (+ a b)) 5 6) ==> THROWS AN ERROR

NAMED-LAMBDA (name-form lambda-list &body body)

Macro like NAMED-LAMBDA except NAME-FORM is evaluated

WITH-FUNCTION-PRINTER (printer fn-form)

Macro returns the result of evaluating FN-FORM, which should return a function.

The resultant function will be writtern by PRINTER when pprinted to a stream and pretty printing functions has been enabled (see ENABLE-PRETTY-FUNCTION-PRINTING).

PRINTER should be a lambda expression or name of a function that takes STREAM as it's only argument and prints a pretty representation of FUNCTION to that STREAM.

CL-USER> (enable-pretty-function-printing)

CL-USER> (let ((n 0))
           (setf x (with-function-printer (lambda (s) (format s "#<counter ~A>" n))
                      (lambda () (incf n)))))

#<counter 0>

CL-USER> (funcall x)
1

CL-USER> x
#<counter 1>

*PRETTY-FUNCTION-PRINTING-SUPPORTED-P*

Variable. Is T on implementations that support pretty function printing, `NIL, on the rest.

PRINT-PRETTY-FUNCTION-TABLE (&optional (stream *standard-output*))

Function. prints all known pretty functions to STREAM

CLEAR-PRETTY-FUNCTION-TABLE ()

Function that turns all known pretty functions into normal, non-pretty functions.

Individual pretty functions can also be turned back into normal functions by SETF-ing their GET-FUNCTION-PRINTER to NIL

GET-FUNCTION-PRINTER (function)

SETF-able Function for accessing the pretty function printer of FUNCTION or NIL if FUNCTION is not a pretty function.

You can turn a non-pretty function into a pretty function by SETF-ing GET-FUNCTION-PRINTER to a an acceptible printer (see WITH-FUNCTION-PRINTER). You can also turn a pretty function back into a normal function by SETF-ing its GET-FUNCTION-PRINTER to NIL

malisper/pretty-function