The pretty-function Reference Manual

Table of Contents

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 2.3 "Robert April" on Wed Mar 14 04:26:16 2018 GMT+0.


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

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


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 pretty-function

Version

0.1

Source

pretty-function.asd (file)

Component

pretty-function.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 pretty-function.asd

Location

pretty-function.asd

Systems

pretty-function (system)

Packages

pretty-function.system


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

3.1.2 pretty-function/pretty-function.lisp

Parent

pretty-function (system)

Location

pretty-function.lisp

Packages

pretty-function

Exported Definitions
Internal Definitions

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

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

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

4.2 pretty-function

Source

pretty-function.lisp (file)

Use List

common-lisp

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: *pretty-function-printing-supported-p*
Package

pretty-function

Source

pretty-function.lisp (file)


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

5.1.2 Macros

Macro: named-lambda NAME LAMBDA-LIST &body BODY
Package

pretty-function

Source

pretty-function.lisp (file)

Macro: named-lambda* NAME-FORM LAMBDA-LIST &body BODY
Package

pretty-function

Source

pretty-function.lisp (file)

Macro: with-function-printer PRINTER FN
Package

pretty-function

Source

pretty-function.lisp (file)


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

5.1.3 Functions

Function: clear-pretty-function-table &optional STREAM
Package

pretty-function

Source

pretty-function.lisp (file)

Function: enable-pretty-function-printing &optional PRIORITY TABLE
Package

pretty-function

Source

pretty-function.lisp (file)

Function: get-function-printer FN
Package

pretty-function

Source

pretty-function.lisp (file)

Setf Expander

(setf get-function-printer) (setf expander)

Setf Expander: (setf get-function-printer) FN
Package

pretty-function

Source

pretty-function.lisp (file)

Reader

get-function-printer (function)

Function: print-pretty-function-table &optional STREAM
Package

pretty-function

Source

pretty-function.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: *pretty-function-printing-enabled-p*
Package

pretty-function

Source

pretty-function.lisp (file)

Special Variable: *weak-fn-alist*
Package

pretty-function

Source

pretty-function.lisp (file)

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

pretty-function

Source

pretty-function.lisp (file)


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

5.2.2 Functions

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

pretty-function

Source

pretty-function.lisp (file)

Function: .print-pretty-function S FN
Package

pretty-function

Source

pretty-function.lisp (file)

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

pretty-function

Source

pretty-function.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, pretty-function.asd: The pretty-function<dot>asd file
File, Lisp, pretty-function/pretty-function.lisp: The pretty-function/pretty-function<dot>lisp file

L
Lisp File, pretty-function.asd: The pretty-function<dot>asd file
Lisp File, pretty-function/pretty-function.lisp: The pretty-function/pretty-function<dot>lisp file

P
pretty-function.asd: The pretty-function<dot>asd file
pretty-function/pretty-function.lisp: The pretty-function/pretty-function<dot>lisp file

Jump to:   F   L   P  

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

A.2 Functions

Jump to:   (   .  
C   E   F   G   M   N   P   S   W  
Index Entry  Section

(
(setf get-function-printer): Exported functions

.
.outdate-weak-fn-alist: Internal functions
.print-pretty-function: Internal functions
.update-weak-fn-alist: Internal functions

C
clear-pretty-function-table: Exported functions

E
enable-pretty-function-printing: Exported functions

F
Function, .outdate-weak-fn-alist: Internal functions
Function, .print-pretty-function: Internal functions
Function, .update-weak-fn-alist: Internal functions
Function, clear-pretty-function-table: Exported functions
Function, enable-pretty-function-printing: Exported functions
Function, get-function-printer: Exported functions
Function, print-pretty-function-table: Exported functions

G
get-function-printer: Exported functions

M
Macro, named-lambda: Exported macros
Macro, named-lambda*: Exported macros
Macro, with-function-printer: Exported macros

N
named-lambda: Exported macros
named-lambda*: Exported macros

P
print-pretty-function-table: Exported functions

S
Setf Expander, (setf get-function-printer): Exported functions

W
with-function-printer: Exported macros

Jump to:   (   .  
C   E   F   G   M   N   P   S   W  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*pretty-function-printing-enabled-p*: Internal special variables
*pretty-function-printing-supported-p*: Exported special variables
*weak-fn-alist*: Internal special variables
*weak-fn-alist-outdated-p*: Internal special variables

S
Special Variable, *pretty-function-printing-enabled-p*: Internal special variables
Special Variable, *pretty-function-printing-supported-p*: Exported special variables
Special Variable, *weak-fn-alist*: Internal special variables
Special Variable, *weak-fn-alist-outdated-p*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, pretty-function: The pretty-function package
Package, pretty-function.system: The pretty-function<dot>system package
pretty-function: The pretty-function system
pretty-function: The pretty-function package
pretty-function.system: The pretty-function<dot>system package

S
System, pretty-function: The pretty-function system

Jump to:   P   S