# Module erl_prettypr

Pretty printing of abstract Erlang syntax trees.

- Description
- Data Types
- Function Index
- Function Details

## Description

Pretty printing of abstract Erlang syntax trees.

This module is a front end to the pretty-printing library module `prettypr`, for text formatting of abstract syntax trees defined by the module `erl_syntax`.

## Data Types

### context()

abstract datatype: `context()`

A representation of the current context of the pretty-printer. Can be accessed in hook functions.

### hook()

`hook() = (syntaxTree(), context(), Continuation) -> document()`

- `Continuation = (syntaxTree(), context()) -> document()`

A call-back function for user-controlled formatting. See `format/2`.

## Function Index

best/1 | Equivalent to `best(Tree, [])`.
best/2 | Creates a fixed "best" abstract layout for a syntax tree.
format/1 | Equivalent to `format(Tree, [])`.
format/2 | Prettyprint-formats an abstract Erlang syntax tree as text.
get_ctxt_hook/1 | Returns the hook function field of the prettyprinter context.
get_ctxt_linewidth/1 | Returns the line widh field of the prettyprinter context.
get_ctxt_paperwidth/1 | Returns the paper widh field of the prettyprinter context.
get_ctxt_precedence/1 | Returns the operator precedence field of the prettyprinter context.
get_ctxt_user/1 | Returns the user data field of the prettyprinter context.
layout/1 | Equivalent to `layout(Tree, [])`.
layout/2 | Creates an abstract document layout for a syntax tree.
set_ctxt_hook/2 | Updates the hook function field of the prettyprinter context.
set_ctxt_linewidth/2 | Updates the line widh field of the prettyprinter context.
set_ctxt_paperwidth/2 | Updates the paper widh field of the prettyprinter context.
set_ctxt_precedence/2 | Updates the operator precedence field of the prettyprinter context.
set_ctxt_user/2 | Updates the user data field of the prettyprinter context.

## Function Details

### best/1

`best(Tree::syntaxTree()) -> empty | document()`

Equivalent to `best(Tree, [])`.

### best/2

`best(Tree::syntaxTree(), Options::[term()]) -> empty | document()`

Creates a fixed "best" abstract layout for a syntax tree. This is similar to the `layout/2` function, except that here, the final layout has been selected with respect to the given options. The atom `empty` is returned if no such layout could be produced. For information on the options, see the `format/2` function.

See also: best/1, format/2, layout/2, prettypr:best/2.

### format/1

`format(Tree::syntaxTree()) -> string()`

Equivalent to `format(Tree, [])`.

### format/2

`format(Tree::syntaxTree(), Options::[term()]) -> string()`

- `syntaxTree() = erl_syntax:syntaxTree()`

Prettyprint-formats an abstract Erlang syntax tree as text.

Available options:

{hook, none | hook()}
  Unless the value is `none`, the given function is called for each node whose list of annotations is not empty; see below for details. The default value is `none`.
{paper, integer()}
  Specifies the preferred maximum number of characters on any line, including indentation. The default value is 80.
{ribbon, integer()}
  Specifies the preferred maximum number of characters on any line, not counting indentation. The default value is 65.
{user, term()}
  User-specific data for use in hook functions. The default value is `undefined`.

A hook function (cf. the `hook()` type) is passed the current syntax tree node, the context, and a continuation. The context can be examined and manipulated by functions such as `get_ctxt_user/1` and `set_ctxt_user/2`. The hook must return a "document" data structure (see `layout/2` and `best/2`); this may be constructed in part or in whole by applying the continuation function. For example, the following is a trivial hook:

          fun (Node, Ctxt, Cont) -> Cont(Node, Ctxt) end

which yields the same result as if no hook was given. The following, however:

          fun (Node, Ctxt, Cont) ->
              Doc = Cont(Node, Ctxt),
              prettypr:beside(prettypr:text("<b>"),
                              prettypr:beside(Doc,
                                              prettypr:text("</b>")))
          end

will place the text of any annotated node (regardless of the annotation data) between HTML "boldface begin" and "boldface end" tags.

See also: erl_syntax, best/2, format/1, get_ctxt_user/1, layout/2, set_ctxt_user/2.

### get_ctxt_hook/1

`get_ctxt_hook(Ctxt::context()) -> hook()`

Returns the hook function field of the prettyprinter context.

See also: set_ctxt_hook/2.

### get_ctxt_linewidth/1

`get_ctxt_linewidth(Ctxt::context()) -> integer()`

Returns the line widh field of the prettyprinter context.

See also: set_ctxt_linewidth/2.

### get_ctxt_paperwidth/1

`get_ctxt_paperwidth(Ctxt::context()) -> integer()`

Returns the paper widh field of the prettyprinter context.

See also: set_ctxt_paperwidth/2.

### get_ctxt_precedence/1

`get_ctxt_precedence(Ctxt::context()) -> context()`

Returns the operator precedence field of the prettyprinter context.

See also: set_ctxt_precedence/2.

### get_ctxt_user/1

`get_ctxt_user(Ctxt::context()) -> term()`

Returns the user data field of the prettyprinter context.

See also: set_ctxt_user/2.

### layout/1

`layout(Tree::syntaxTree()) -> document()`

Equivalent to `layout(Tree, [])`.

### layout/2

`layout(Tree::syntaxTree(), Options::[term()]) -> document()`

- `document() = prettypr:document()`

Creates an abstract document layout for a syntax tree. The result represents a set of possible layouts (cf. module `prettypr`). For information on the options, see `format/2`; note, however, that the `paper` and `ribbon` options are ignored by this function.

This function provides a low-level interface to the pretty printer, returning a flexible representation of possible layouts, independent of the paper width eventually to be used for formatting. This can be included as part of another document and/or further processed directly by the functions in the `prettypr` module, or used in a hook function (see `format/2` for details).

See also: prettypr, format/2, layout/1.

### set_ctxt_hook/2

`set_ctxt_hook(Ctxt::context(), Hook::hook()) -> context()`

Updates the hook function field of the prettyprinter context.

See also: get_ctxt_hook/1.

### set_ctxt_linewidth/2

`set_ctxt_linewidth(Ctxt::context(), W::integer()) -> context()`

Updates the line widh field of the prettyprinter context.

Note: changing this value (and passing the resulting context to a continuation function) does not affect the normal formatting, but may affect user-defined behaviour in hook functions.

See also: get_ctxt_linewidth/1.

### set_ctxt_paperwidth/2

`set_ctxt_paperwidth(Ctxt::context(), W::integer()) -> context()`

Updates the paper widh field of the prettyprinter context.

Note: changing this value (and passing the resulting context to a continuation function) does not affect the normal formatting, but may affect user-defined behaviour in hook functions.

See also: get_ctxt_paperwidth/1.

### set_ctxt_precedence/2

`set_ctxt_precedence(Ctxt::context(), Prec::integer()) -> context()`

Updates the operator precedence field of the prettyprinter context. See the `erl_parse` module for operator precedences.

See also: erl_parse, get_ctxt_precedence/1.

### set_ctxt_user/2

`set_ctxt_user(Ctxt::context(), X::term()) -> context()`

Updates the user data field of the prettyprinter context.

See also: get_ctxt_user/1.