From 31287e6c0be9cb8e752e8c8a949314d194f5625e Mon Sep 17 00:00:00 2001 From: Nick Allen Date: Sat, 28 Mar 2009 14:52:01 -0700 Subject: [PATCH] adding markdown documention [README.md] --- README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d06a163 --- /dev/null +++ b/README.md @@ -0,0 +1,146 @@ + +# 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](http://cloud.github.com/downloads/nallen05/pretty-function/pretty-function_0.1.1.tar.gz) 3.28.2009 -- Updated documentation for Github, converted to Markdown +* [Version 0.1](http://cloud.github.com/downloads/nallen05/pretty-function/pretty-cuntion_0.1.tar.gz) 21.09.2007 + +or get the latest version from the [Git](http://git-scm.com/) repository: + + git clone git://github.com/nallen05/pretty-function.git + +## License + +[BSD](http://en.wikipedia.org/wiki/BSD_License). 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](http://weitz.de/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](http://weitz.de/hunchentoot/#handlers). 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`](http://weitz.de/hunchentoot/#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. + + # + +instead of the usual + + # + +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](http://en.wikipedia.org/wiki/Indefinite_and_fictitious_large_numbers) 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 + + # + + 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 + +* `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 "#" n)) + (lambda () (incf n))))) + + # + + CL-USER> (funcall x) + 1 + + CL-USER> x + # + +* `*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` + + + +