The pretty-function Reference Manual

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

The pretty-function Reference Manual

This is the pretty-function Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 05:37:38 2022 GMT+0.

Table of Contents


1 Introduction

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:

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:

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


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.


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

so

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

but

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

Macro like NAMED-LAMBDA except NAME-FORM is evaluated


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>

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


Function. prints all known pretty functions to STREAM


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


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


2 Systems

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


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

2.1 pretty-function

Version

0.1

Source

pretty-function.asd.

Child Component

pretty-function.lisp (file).


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


3.1.1 pretty-function/pretty-function.asd

Source

pretty-function.asd.

Parent Component

pretty-function (system).

ASDF Systems

pretty-function.

Packages

pretty-function.system.


3.1.2 pretty-function/pretty-function.lisp

Source

pretty-function.asd.

Parent Component

pretty-function (system).

Packages

pretty-function.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


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

4.1 pretty-function.system

Source

pretty-function.asd.

Use List
  • asdf/interface.
  • common-lisp.

4.2 pretty-function

Source

pretty-function.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *pretty-function-printing-supported-p*
Package

pretty-function.

Source

pretty-function.lisp.


5.1.2 Macros

Macro: named-lambda (name lambda-list &body body)
Package

pretty-function.

Source

pretty-function.lisp.

Macro: named-lambda* (name-form lambda-list &body body)
Package

pretty-function.

Source

pretty-function.lisp.

Macro: with-function-printer (printer fn)
Package

pretty-function.

Source

pretty-function.lisp.


Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: clear-pretty-function-table (&optional stream)
Package

pretty-function.

Source

pretty-function.lisp.

Function: enable-pretty-function-printing (&optional priority table)
Package

pretty-function.

Source

pretty-function.lisp.

Function: get-function-printer (fn)
Setf Expander: (setf get-function-printer) (fn)
Package

pretty-function.

Source

pretty-function.lisp.

Function: print-pretty-function-table (&optional stream)
Package

pretty-function.

Source

pretty-function.lisp.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *pretty-function-printing-enabled-p*
Package

pretty-function.

Source

pretty-function.lisp.

Special Variable: *weak-fn-alist*
Package

pretty-function.

Source

pretty-function.lisp.

Special Variable: *weak-fn-alist-outdated-p*
Package

pretty-function.

Source

pretty-function.lisp.


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

5.2.2 Ordinary functions

Function: .outdate-weak-fn-alist ()
Package

pretty-function.

Source

pretty-function.lisp.

Function: .print-pretty-function (s fn)
Package

pretty-function.

Source

pretty-function.lisp.

Function: .update-weak-fn-alist ()
Package

pretty-function.

Source

pretty-function.lisp.


Appendix A Indexes


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

A.1 Concepts