On this page:
3.15.1 The PPrint  Doc Datatype
PPrint  Doc
mt-doc
str
hardline
blank
concat
nest
if-flat
align
align-spaces
group
3.15.2 PPrint  Doc Methods
._  plus
._  output
.pretty
3.15.3 Functions
str
number
blank
sbreak
concat
nest
if-flat
group
flow
vert
flow-map
parens
braces
brackets
dquote
squote
align
hang
prefix
infix
infix-break
separate
surround
soft-surround
surround-separate
label-align-surround

3.15 pprint

Usage:
include pprint
import pprint as ...

3.15.1 The PPrintDoc Datatype

This datatype is not exported directly to users; there are easier-to-use helper functions that are exported instead.

data PPrintDoc:
| mt-doc(flat-width :: Number, has-hardline :: Boolean)
| str(s :: String, flat-width :: Number, has-hardline :: Boolean)
| hardline(has-hardline :: Boolean)
| blank(n :: Number, flat-width :: Number, has-hardline :: Boolean)
| concat(fst :: PPrintDoc, snd :: PPrintDoc, flat-width :: Number, has-hardline :: Boolean)
| nest(indent :: Number, d :: PPrintDoc, flat-width :: Number, has-hardline :: Boolean)
| if-flat(flat :: PPrintDoc, vert :: PPrintDoc, flat-width :: Number, has-hardline :: Boolean)
| align(d :: PPrintDoc, flat-width :: Number, has-hardline :: Boolean)
| align-spaces(n :: Number, flat-width :: Number, has-hardline :: Boolean)
| group(D :: PPrintDoc, flat-width :: Number, has-hardline :: Boolean)
end

Each of the raw constructors for PPrintDoc contains two fields that memoize how wide the document is when printed flat, and whether the document contains a hard linebreak.

mt-doc :: (flat-width :: Number, has-hardline :: Boolean) -> PPrintDoc

Represents an empty document.

str :: (
s :: String,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

Represents a simple string, that cannot be broken into smaller pieces. Any whitespace in this string is treated as a normal, unbreakable character.

hardline :: (has-hardline :: Boolean) -> PPrintDoc

Forces a line break: no group containing this document can print flat.

blank :: (
n :: Number,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

Represents n spaces. (This is simply a memory optimization over storing a str of the actual whitespace string.)

concat :: (
fst :: PPrintDoc,
snd :: PPrintDoc,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

Represents printing two documents, one after another. PPrintDoc both documents will be printed in flat mode, or neither will.

nest :: (
indent :: Number,
d :: PPrintDoc,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

Adds n spaces to any line breaks that result from printing the given document in vertical mode. This forms an indented paragraph.

if-flat :: (
flat :: PPrintDoc,
vert :: PPrintDoc,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

Allows choosing between two documents, depending on whether the document is being printed flat or not. This can be used to implement soft line breaks, which turn into whitespace when flat.

align :: (
d :: PPrintDoc,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

This aligns its nested content to the current column. (Unlike nest, which adds or removes indentation relative to the current indentation, this aligns to the current position regardless of current indentation.)

align-spaces :: (
n :: Number,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

In flat mode, this vanishes, but in vertical mode it adds a linebreak and a given number of spaces to the next line.

group :: (
D :: PPrintDoc,
flat-width :: Number,
has-hardline :: Boolean
)
-> PPrintDoc

This applies “scoping” to the current nesting level or flatness mode. If a group can be typeset in flat mode, it will, regardless of the surrounding mode.

3.15.2 PPrintDoc Methods

These methods are available on all PPrintDocs.

._plus :: (other :: PPrintDoc) -> PPrintDoc

Combines two PPrintDocs into a single document.

._output :: () -> Any

Internal method for displaying the structure of this PPrintDoc.

.pretty :: (width :: Number) -> List<String>

Renders this PPrintDoc at the desired line width. Returns a list of the individual lines of output.

3.15.3 Functions

str :: (s :: Any) -> Any

Constructs a document containing the given string. Any whitespace in this string is considered unbreakable.

number :: (n :: Number) -> Any

Constructs a document containing the number n printed as a string. This is merely a convenient shorthand for str(tostring(n)).

blank :: (n :: Any) -> Any

Produces the requested number of non-breaking spaces.

sbreak :: (n :: Any) -> Any

When typeset in flat mode, this produces the requested number of non-breaking spaces. When typeset in vertical mode, produces a single linebreak.

concat :: (fst :: Any, snd :: Any) -> Any

Combines two documents into one, consecutively.

nest :: (n :: Any, d :: Any) -> Any

Adds n to the current indentation level while typesetting the given document.

if-flat :: (flat :: Any, vert :: Any) -> Any

Allows choosing between two documents, depending on whether this combined document is typeset in flat mode or not.

group :: (d :: Any) -> Any

Wraps the given document in a group, so that it can be typeset in flat mode (if possible) even if the surrounding document is in vertical mode. This helps ensure that linebreaks happen at the “outer” layers of the document, and nested groups stay intact whenever possible.

flow :: (items :: Any) -> Any

Combines a given list of documents with soft line breaks. When given a list of words, for example, this produces a paragraph that automatially line-wraps to fit the available space.

vert :: (items :: Any) -> Any

Combines a given list of documents with hard line breaks. Note that unless the individual items are grouped, this will cause them all to be typeset vertically as well.

flow-map :: (
sep :: Any,
f :: Any,
items :: Any
)
-> Any

A shorthand to map a given list of values into a list of documents, then combine them with some separator via separate.

parens :: (d :: Any) -> Any

Surrounds the given document in parentheses, and surrounds them all in a group.

braces :: (d :: Any) -> Any

Surrounds the given document in curly braces, and surrounds them all in a group.

brackets :: (d :: Any) -> Any

Surrounds the given document in square brackets, and surrounds them all in a group.

dquote :: (s :: Any) -> Any

Surrounds the given document in double-quotes, and surrounds them all in a group.

squote :: (s :: Any) -> Any

Surrounds the given document in single-quotes, and surrounds them all in a group.

align :: (d :: Any) -> Any

Aligns the given document to the current column, wherever it might be.

hang :: (i :: Any, d :: Any) -> Any

Typesets the given document with a hanging indent of the given length. The first line is typeset at the current position, and the remaining lines are all indented.

prefix :: (
n :: Any,
b :: Any,
x :: Any,
y :: Any
)
-> Any

Takes two documents and typesets them together as a pyret-id{group}. If they can fit on one line, this is equivalent to concatenating them. Otherwise, this increases the nesting level of the second document by n.

infix :: (
n :: Number,
b :: Number,
op :: PPrintDoc,
x :: PPrintDoc,
y :: PPrintDoc
)
-> Any

Typesets infix operators as a group, preferring to break lines after the operator. Surrounds the operator with b blank spaces on either side, and indents any new lines by n spaces.

infix-break :: (
n :: Number,
b :: Number,
op :: PPrintDoc,
x :: PPrintDoc,
y :: PPrintDoc
)
-> Any

Typesets infix operators as a group, preferring to break lines before the operator. Surrounds the operator with b blank spaces on either side, and indents any new lines by n spaces.

separate :: (sep :: PPrintDoc, docs :: lists.List) -> Any

Interleaves each document of the provided list with the given separator document.

surround :: (
n :: Number,
b :: Number,
open :: PPrintDoc,
contents :: PPrintDoc,
close :: PPrintDoc
)
-> Any

Given a document with many potential line breaks, and an opening and a closing document to surround it with, this function produces a document that either typesets everything on one line with b spaces between the contents and the enclosing documents, or typesets the opening, closing and contents on separate lines and indents the contents by n. Useful for typesetting things like data definitions, where each variant goes on its own line, as does the data and end keywords.

soft-surround :: (
n :: Number,
b :: Number,
open :: PPrintDoc,
contents :: PPrintDoc,
close :: PPrintDoc
)
-> Any

Like surround, but tries to keep the closing document on the same line as the last line of the contents. Useful for typesetting things like s-expressions, where the closing parentheses look better on the last line of the content.

surround-separate :: (
n :: Number,
b :: Number,
void :: PPrintDoc,
open :: PPrintDoc,
sep :: PPrintDoc,
close :: PPrintDoc,
docs :: lists.List
)
-> Any

A combination of surround and separate. Useful for typesetting delimited, comma-separated lists of items, or similar other other output.

label-align-surround :: (
label :: Any,
open :: Any,
sep :: Any,
contents :: Any,
close :: Any
)
-> Any

Similar to soft-surround, but with different alignment.