1 Getting Started with PPrint
2 Abstract Documents
3 Rendering Operations
4 Basic Documents
5 Building Compound Documents
Version: 4.0.2.6

PPrint: A General-Purpose Pretty-Printer

  (require (planet dherman/pprint:4))

1 Getting Started with PPrint

2 Abstract Documents

PPrint is organized around the concept of a doc, which encapsulates abstract formatting information for the pretty printer. The combinators of the library build and combine docs and the Rendering Operations consume docs for pretty printing.

(doc? x)  boolean?

  x : any

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

When using the markup constructor, the doc type may be thought of as a parameterized type doc a. See the documentation for markup for details.

3 Rendering Operations

(pretty-print d [out width])  any

  d : doc?

  out : output-port? = (current-output-port)

  width : natural-number/c = (current-page-width)

Pretty prints the doc d to the output out with a maximum page width of width.

(pretty-format d [width])  string?

  d : doc?

  width : natural-number/c = (current-page-width)

Pretty prints the doc d to a string with a maximum page width of width.

(pretty-markup d combine [width])  (or/c string? a)

  d : doc?

  combine : ((or/c string? a) (or/c string? a) -> (or/c string? a))

  width : natural-number/c = (current-page-width)

Pretty prints the doc d to an instance of type a, which is determined by the type of the markup nodes in d, with a maximum page width of width.

The process of generating the markup relies on the ability to concatenate strings or markup, and this concatenation is dependent on the type a. So the combine argument is required in order to concatenate fragments of marked-up text.

(current-page-width)  natural-number/c

(current-page-width w)  void?

  w : natural-number/c

A parameter specifying the default maximum page width for pretty printing.

4 Basic Documents

empty : doc?

The empty document, which contains the empty string.

(char c)  doc?

  c : char?

Constructs a document containing the single character c.

(text s)  doc?

  s : string?

Constructs a document containing the fixed string s.

(nest n d)  doc?

  n : natural-number/c

  d : doc?

Constructs a document like d but with the current indentation level increased by n.

NOTE: The nest combinator does not affect the current line’s indentation. Indentation is only inserted after a line or a break.

Examples:

  > (pretty-format (nest 4 (text "not indented")))

  "not indented"

  > (pretty-format (nest 4 (h-append (text "not indented") line (text "indented"))))

  "not indented\n    indented"

(label s d)  doc?

  s : string?

  d : doc?

Constructs a document like d but with the current indentation suffixed by the string s.

(markup f d)  (doc a)

  f : ((or/c string? a) -> (or/c string? a))

  d : (doc a)

Creates a document node with a markup transformer, which is applied by pretty-markup to produce a pretty-printed document with markup information. The markup is assumed not to affect the width of the string. This allows you, for example, to produce X-expressions from pretty-printed source.

Examples:

  (define (empty-xexpr? x)

    (or (null? x) (equal? x "")))

  (define (combine x1 x2)

    (cond

      [(empty-xexpr? x1) x2]

      [(empty-xexpr? x2) x1]

      [else (list x1 x2)]))

  > (pretty-markup (markup (λ (x) `(em ,x)) (text "hi!")) combine)

  (em "hi!")

(group d)  doc?

  d : doc?

Creates a document like d but with all line breaks removed, if it fits on a single line.

line : doc?

A document containing a line break, which is replaced with a single space when placed in the context of a group.

break : doc?

A document containing a line break, which is replaced with the empty string when placed in the context of a group.

soft-line : doc?

Equivalent to (group line).

soft-break : doc?

Equivalent to (group break).

5 Building Compound Documents