doc.txt

PPrint

_PPrint_
_pprint_

This collection provides two files:

 _pprint.ss_: a pretty-printing library
 _pprint-haskell.ss_: a compatibility library with names similar to Haskell
 _pprint-idioms.ss_: combinators for common programming language patterns

This library is based on Daan Leijen's PPrint library for Haskell:

    http://www.cs.uu.nl/~daan/pprint.html

The implementation is also based on Ralph Becket's port of PPrint for
the strict functional/logic language Mercury:

    http://www.cs.mu.oz.au/research/mercury/information/doc-release/library_37.html

See _design.txt_ for details on the implementation.

CAVEAT: This is an alpha version. I still have to do performance tests
to see if I've dealt with the strictness issues properly.

[TODO: more detailed documentation coming soon]

======================================================================

pprint.ss
---------

FRONT END ------------------------------------------------------------

> type doc

A _doc_ is an abstract datatype representing a pretty document. Pretty-printing
involves applying the constructors provided by this library to construct a
pretty document and then applying _pretty-print_ to that document.

> (doc? x) :: any -> boolean

Determines whether a value is a member of the _doc_ datatype.

> (pretty-print d [out width]) :: doc [output-port nat] -> any
> (current-page-width [w]) :: (parameterof nat)


BASIC COMBINATORS ----------------------------------------------------

> empty :: doc
> (char c) :: character -> doc
> (text s) :: string -> doc
> (nest n d) :: nat doc -> doc

NOTE: The _nest_ combinator does NOT affect the current line's
indentation. Indentation is only inserted after a _line_ or a
_break_. [TODO: example]

> (group d) :: doc -> doc

> line :: doc
> break :: doc
> soft-line :: doc
> soft-break :: doc


DOC COMBINATORS ------------------------------------------------------

> (h-append d ...) :: doc ... -> doc
> (hs-append d ...) :: doc ... -> doc
> (v-append d ...) :: doc ... -> doc
> (vs-append d ...) :: doc ... -> doc
> (vb-append d ...) :: doc ... -> doc
> (vsb-append d ...) :: doc ... -> doc


LIST COMBINATORS -----------------------------------------------------

> (h-concat ds) :: (listof doc) -> doc
> (hs-concat ds) :: (listof doc) -> doc
> (v-concat ds) :: (listof doc) -> doc
> (vs-concat ds) :: (listof doc) -> doc
> (v-concat/s ds) :: (listof doc) -> doc
> (vb-concat ds) :: (listof doc) -> doc
> (vsb-concat ds) :: (listof doc) -> doc
> (vb-concat/s ds) :: (listof doc) -> doc

> (apply-infix d ds) :: doc (listof doc) -> (listof doc)


FILLERS --------------------------------------------------------------

> (fill n d) :: nat doc -> doc
> (fill/break n d) :: nat doc -> doc


ALIGNMENT ------------------------------------------------------------

> (align d) :: doc -> doc
> (hang d) :: doc -> doc
> (indent d) :: doc -> doc


DOCUMENT CONSTANTS ---------------------------------------------------

> comma :: doc
> semi :: doc
> colon :: doc
> lparen :: doc
> rparen :: doc
> lbracket :: doc
> rbracket :: doc
> lbrace :: doc
> rbrace :: doc
> langle :: doc
> rangle :: doc
> space :: doc
> ellipsis :: doc
> squote :: doc
> dquote :: doc
> dot :: doc
> backslash :: doc
> equals :: doc


pprint-idioms.ss
----------------

[TODO: coming soon]


pprint-haskell.ss
-----------------

For those who are more familiar with the names in the Haskell library,
this library is provided as a compatibility mode. (This might be
useful for porting existing Haskell code, for example.)

> empty  = empty
> char   = char
> text   = text
> nest   = nest
> group  = group

> line       = line
> linebreak  = break
> softline   = soft-line
> softbreak  = soft-break

> <>    = h-append
> <+>   = hs-append
> <$>   = v-append
> </>   = vs-append
> <$$>  = vb-append
> <//>  = vsb-append

> hcat       = h-concat
> hsep       = hs-concat
> vsep       = v-concat
> fill-sep   = vs-concat
> sep        = v-concat/s
> vcat       = vb-concat
> fill-cat   = vsb-concat
> cat        = vb-concat/s
> punctuate  = apply-infix

> fill        = fill
> fill-break  = fill/break

> align   = align
> hang    = hang
> indent  = indent

> comma     = comma
> semi      = semi
> colon     = colon
> lparen    = lparen
> rparen    = rparen
> lbrace    = lbrace
> rbrace    = rbrace
> lbracket  = lbracket
> rbracket  = rbracket
> langle    = langle
> rangle    = rangle
> space     = space
> ellipsis  = ellipsis
> squote    = squote
> dquote    = dquote
> dot       = dot
> backslash = backslash
> equals    = equals


EXAMPLES -------------------------------------------------------------

[TODO: coming soon]


REFERENCES -----------------------------------------------------------

[1] Ralph Becket, pprint.m (2002)
    http://www.cs.mu.oz.au/research/mercury/information/doc-latest/mercury_library/pprint.html

[2] John Hughes, "The Design of a Pretty-Printing Library" (1995)
    http://www.cs.chalmers.se/~rjmh/Papers/pretty.html

[3] Daan Leijen, "PPrint, a Prettier Printer" (2001)
    http://www.cs.uu.nl/~daan/download/pprint/pprint.html

[4] Simon Peyton Jones, "A Pretty-Printer Library in Haskell" (1997)
    http://research.microsoft.com/~simonpj/downloads/pretty-printer/pretty.html

[5] Philip Wadler, "A Prettier Printer" (1998)
    http://homepages.inf.ed.ac.uk/wadler/topics/language-design.html#prettier