cc.pretty

Provides a "pretty printer", for rendering data structures in an aesthetically pleasing manner.

In order to display something using cc.pretty, you build up a series of documents. These behave a little bit like strings; you can concatenate them together and then print them to the screen.

However, documents also allow you to control how they should be printed. There are several functions (such as nest and group) which allow you to control the "layout" of the document. When you come to display the document, the 'best' (most compact) layout is used.

Usage

emptyAn empty document.
spaceA document with a single space in it.
lineA line break.
space_lineA line break.
text(text[, colour])Create a new document from a string.
concat(...)Concatenate several documents together.
nest(depth, doc)Indent later lines of the given document with the given number of spaces.
group(doc)Builds a document which is displayed on a single line if there is enough room, or as normal if not.
write(doc[, ribbon_frac])Display a document on the terminal.
print(doc[, ribbon_frac])Display a document on the terminal with a trailing new line.
render(doc[, width[, ribbon_frac]])Render a document, converting it into a string.
pretty(obj[, options])Pretty-print an arbitrary object, converting it into a document.
emptySource

An empty document.

spaceSource

A document with a single space in it.

lineSource

A line break. When collapsed with group, this will be replaced with empty.

space_lineSource

A line break. When collapsed with group, this will be replaced with space.

text(text[, colour])Source

Create a new document from a string.

If your string contains multiple lines, group will flatten the string into a single line, with spaces between each line.

Parameters

  1. text string The string to construct a new document with.
  2. colour? number The colour this text should be printed with. If not given, we default to the current colour.

Returns

  1. Doc The document with the provided text.

Usage

concat(...)Source

Concatenate several documents together. This behaves very similar to string concatenation.

Parameters

  1. ... Doc | string The documents to concatenate.

Returns

  1. Doc The concatenated documents.

Usage

nest(depth, doc)Source

Indent later lines of the given document with the given number of spaces.

For instance, nesting the document

foo
bar

by two spaces will produce

foo
  bar

Parameters

  1. depth number The number of spaces with which the document should be indented.
  2. doc Doc The document to indent.

Returns

  1. Doc The nested document.

Usage

group(doc)Source

Builds a document which is displayed on a single line if there is enough room, or as normal if not.

Parameters

  1. doc Doc The document to group.

Returns

  1. Doc The grouped document.

Usage

write(doc[, ribbon_frac])Source

Display a document on the terminal.

Parameters

  1. doc Doc The document to render
  2. ribbon_frac? number The maximum fraction of the width that we should write in.
print(doc[, ribbon_frac])Source

Display a document on the terminal with a trailing new line.

Parameters

  1. doc Doc The document to render.
  2. ribbon_frac? number The maximum fraction of the width that we should write in.
render(doc[, width[, ribbon_frac]])Source

Render a document, converting it into a string.

Parameters

  1. doc Doc The document to render.
  2. width? number The maximum width of this document. Note that long strings will not be wrapped to fit this width - it is only used for finding the best layout.
  3. ribbon_frac? number The maximum fraction of the width that we should write in.

Returns

  1. string The rendered document as a string.
pretty(obj[, options])Source

Pretty-print an arbitrary object, converting it into a document.

This can then be rendered with write or print.

Parameters

  1. obj The object to pretty-print.
  2. options? { function_args = boolean, function_source = boolean }

    Controls how various properties are displayed.

    • function_args: Show the arguments to a function if known (false by default).
    • function_source: Show where the function was defined, instead of function: xxxxxxxx (false by default).

Returns

  1. Doc The object formatted as a document.

Usage

Types

Doc

A document containing formatted text, with multiple possible layouts.

Documents effectively represent a sequence of strings in alternative layouts, which we will try to print in the most compact form necessary.