Search documentation of syntax_tools

# erl_prettypr (syntax_tools v4.0)

View Source

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`.

# Summary

## Types

clause_t()
context()
hook()
syntaxTree()

An abstract syntax tree.

## Functions

best(Node)

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

best(Node, Options)

Creates a fixed "best" abstract layout for a syntax tree.

format(Node)

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

format(Node, Options)

Prettyprint-formats an abstract Erlang syntax tree as text.

get_ctxt_hook(Ctxt)

Returns the hook function field of the prettyprinter context.

get_ctxt_linewidth(Ctxt)

Returns the line widh field of the prettyprinter context.

get_ctxt_paperwidth(Ctxt)

Returns the paper widh field of the prettyprinter context.

get_ctxt_precedence(Ctxt)

Returns the operator precedence field of the prettyprinter context.

get_ctxt_user(Ctxt)

Returns the user data field of the prettyprinter context.

layout(Node)

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

layout(Node, Options)

Creates an abstract document layout for a syntax tree.

set_ctxt_hook(Ctxt, Hook)

Updates the hook function field of the prettyprinter context.

set_ctxt_linewidth(Ctxt, W)

Updates the line widh field of the prettyprinter context.

set_ctxt_paperwidth(Ctxt, W)

Updates the paper widh field of the prettyprinter context.

set_ctxt_precedence(Ctxt, Prec)

Updates the operator precedence field of the prettyprinter context.

set_ctxt_user(Ctxt, X)

Updates the user data field of the prettyprinter context.

# Types

# clause_t()

(not exported)

    -type clause_t() ::
              case_expr | fun_expr | if_expr | maybe_expr | receive_expr | try_expr |
              {function, prettypr:document()} |
              spec.

# context()

(not exported)

    -type context() ::
              #ctxt{prec :: integer(),
                    sub_indent :: non_neg_integer(),
                    break_indent :: non_neg_integer(),
                    clause :: clause_t() | undefined,
                    hook :: hook(),
                    paper :: integer(),
                    ribbon :: integer(),
                    user :: term(),
                    encoding :: epp:source_encoding(),
                    empty_lines :: sets:set(integer())}.

# hook()

(not exported)

    -type hook() :: none | fun((syntaxTree(), _, _) -> prettypr:document()).

# syntaxTree()

(not exported)

    -type syntaxTree() :: erl_syntax:syntaxTree().

An abstract syntax tree.

See the `erl_syntax` module for details.

# Functions

# best(Node)

    -spec best(syntaxTree()) -> empty | prettypr:document().

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

# best(Node, Options)

    -spec best(syntaxTree(), [term()]) -> empty | prettypr: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/3`.

# format(Node)

    -spec format(syntaxTree()) -> string().

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

# format(Node, Options)

    -spec format(syntaxTree(), [term()]) -> string().

Prettyprint-formats an abstract Erlang syntax tree as text.

For example, if you have a `.beam` file that has been compiled with `debug_info`, the following should print the source code for the module (as it looks in the debug info representation):

         {ok,{_,[{abstract_code,{_,AC}}]}} =
                 beam_lib:chunks("myfile.beam",[abstract_code]),
         io:put_chars(erl_prettypr:format(erl_syntax:form_list(AC)))

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. 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`.

- `{encoding, epp:source_encoding()}` - Specifies the encoding of the generated file.

A hook function (see 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(Ctxt)

    -spec get_ctxt_hook(context()) -> hook().

Returns the hook function field of the prettyprinter context.

See also: `set_ctxt_hook/2`.

# get_ctxt_linewidth(Ctxt)

    -spec get_ctxt_linewidth(context()) -> integer().

Returns the line widh field of the prettyprinter context.

See also: `set_ctxt_linewidth/2`.

# get_ctxt_paperwidth(Ctxt)

    -spec get_ctxt_paperwidth(context()) -> integer().

Returns the paper widh field of the prettyprinter context.

See also: `set_ctxt_paperwidth/2`.

# get_ctxt_precedence(Ctxt)

    -spec get_ctxt_precedence(context()) -> integer().

Returns the operator precedence field of the prettyprinter context.

See also: `set_ctxt_precedence/2`.

# get_ctxt_user(Ctxt)

    -spec get_ctxt_user(context()) -> term().

Returns the user data field of the prettyprinter context.

See also: `set_ctxt_user/2`.

# layout(Node)

    -spec layout(syntaxTree()) -> prettypr:document().

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

# layout(Node, Options)

    -spec layout(syntaxTree(), [term()]) -> prettypr:document().

Creates an abstract document layout for a syntax tree.

The result represents a set of possible layouts (see module `prettypr`). For information on the options, see `format/2`; however, note 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(Ctxt, Hook)

    -spec set_ctxt_hook(context(), hook()) -> context().

Updates the hook function field of the prettyprinter context.

See also: `get_ctxt_hook/1`.

# set_ctxt_linewidth(Ctxt, W)

    -spec set_ctxt_linewidth(context(), 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(Ctxt, W)

    -spec set_ctxt_paperwidth(context(), 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(Ctxt, Prec)

    -spec set_ctxt_precedence(context(), integer()) -> context().

Updates the operator precedence field of the prettyprinter context.

See the `//stdlib/erl_parse` module for operator precedences.

See also: //stdlib/erl_parse, `get_ctxt_precedence/1`.

# set_ctxt_user(Ctxt, X)

    -spec set_ctxt_user(context(), term()) -> context().

Updates the user data field of the prettyprinter context.

See also: `get_ctxt_user/1`.