Pretty-Printing
Atomo provides a handy wrapper for the Haskell Text.PrettyPrint system. The documentation here is largely based off of its own.
o pretty → Pretty
Turn an object into a pretty-printed document, which can be used in other pretty-printers. This is defined on Object, so everything has it, but you should override this if possible.
Pretty-printing a value should yield something that looks like the expression that created that value. If it cannot be pretty-printed cleanly, make it obvious, usually via surrounding some description with angle brackets (<>).
x doc → Pretty | x is-a?: Block
Used for writing pretty-printed forms; basically a shortcut for @(Pretty join: x).
Documents From Values
Pretty char: c → Pretty | c is-a?: Character
A document of height and width 1, containing a literal character.
Pretty text: s → Pretty | s is-a?: String
A document of height 1 containing a literal string.
Satisfies the following laws:
text: s <> text: t == text: (s .. t) text: "" <> x == x, if x is non-empty
The side condition on the last law is necessary because text "" has height 1, while empty has no height.
Pretty zero-width-text: s → Pretty | s is-a?: String
Some text, but without any width. Use for non-printing text such as a HTML or Latex tags.
Example:
> Pretty zero-width-text: "hello!" hello!
Simple Shortcuts
Wrapping Documents
Pretty double-quotes: p → Pretty | p is-a?: Pretty
Wrap p in "...".
Example:
> { double-quotes: (text: "hi!") } doc "hi!"
Combining Documents
Pretty empty → Pretty
The empty document, with no height and no width. empty is the identity for <>, <+>, \\ and \+\ and anywhere in the argument list for sep:, hcat:, hsep:, vcat:, fcat:, etc.
(Just a blank line.)
a <+> b → Pretty | a is-a?: Pretty | b is-a?: Pretty
Beside, separated by a space, unless one of the arguments is empty. <+> is associative, with identity empty.
a \\ b → Pretty | a is-a?: Pretty | b is-a?: Pretty
Position a above b, except that if the last line of the first argument stops at least one position before the first line of the second begins, these two lines are overlapped.
Example:
> { text: "hi" \\ (text: "there") nest: 1 } doc hi there > { text: "hi" \\ (text: "there") nest: 5 } doc hi there
\\ is associative, with identity empty, and also satisfies:
(x \\ y) <> z == x $$ (y <> z), if y is non-empty
a \+\ b → Pretty | a is-a?: Pretty | b is-a?: Pretty
Position a above b, with no overlapping. \+\ is associative, with identity empty.
p nest: n → Pretty | p is-a?: Pretty | n is-a?: Integer
Nest (or indent) a document by a given number of positions (which may also be negative). nest: satisfies the laws:
x nest: 0 == x (x nest: a) nest: b == x nest: (a + b) (x <> y) nest: a == x nest: a <> y nest: a (x \\ y) nest: a == x nest: a \\ y nest: a Pretty empty nest: a == Pretty empty x <> y nest: a = x <> y, if x is non-empty
The side condition on the last law is needed because empty is a left identity for <>.
delim punctuate: ps → Pretty | delim is-a?: Pretty | ps is-a?: List
Intersperse delim through ps.
That is, x punctuate: [p1, ... pn] is [p1 <> x, p2 <> x, ... pn-1 <> x, pn].
Example:
> { semi punctuate: [text: "a", text: "b", char: $c] } doc [a;, b;, c]