rebar3_format v1.2.1

View Source otp_formatter (rebar3_format v1.2.1)

Rebar3 Pretty Printing of abstract Erlang syntax trees, based on original erl_prettypr.

It was taken verbatim from erl_prettypr and it was modified just to fix some bugs.

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.

Link to this section Summary

Types

clause_t/0
context/0
hook/0

Functions

best(Node)

Equivalent to best(Tree, []).

best(Node, Options)
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)

Equivalent to format(Tree, []).

format(Node, EmptyLines, Options)
Pretty-prints/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(otp_formatter: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; 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.
{encoding, epp:source_encoding()}
Specifies the encoding of the generated file.
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.

format_file(File, _, Opts)
Format a file. Apply formatting rules to a file containing erlang code. Use Opts to configure the formatter.
get_ctxt_hook(Ctxt)
Returns the hook function field of the pretty-printer context.

See also: set_ctxt_hook/2.

get_ctxt_linewidth(Ctxt)
Returns the line width field of the pretty-printer context.

See also: set_ctxt_linewidth/2.

get_ctxt_paperwidth(Ctxt)
Returns the paper width field of the pretty-printer context.

See also: set_ctxt_paperwidth/2.

get_ctxt_precedence(Ctxt)
Returns the operator precedence field of the pretty-printer context.

See also: set_ctxt_precedence/2.

get_ctxt_user(Ctxt)
Returns the user data field of the pretty-printer context.

See also: set_ctxt_user/2.

init(_, _)
Initialize the formatter and generate a state that will be passed in when calling other callbacks.
layout(Node)

Equivalent to layout(Tree, []).

layout(Node, Options)

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.

set_ctxt_hook(Ctxt, Hook)
Updates the hook function field of the pretty-printer context.

See also: get_ctxt_hook/1.

set_ctxt_linewidth(Ctxt, W)

Updates the line width field of the pretty-printer context.

set_ctxt_paperwidth(Ctxt, W)

Updates the paper width field of the pretty-printer context.

set_ctxt_precedence(Ctxt, Prec)
Updates the operator precedence field of the pretty-printer context. See the erl_parse module for operator precedences.

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

set_ctxt_user(Ctxt, X)
Updates the user data field of the pretty-printer context.

See also: get_ctxt_user/1.

Link to this section Types

Link to this type

clause_t/0

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

context/0

View Source 
-type context() :: #ctxt{}.
Link to this type

hook/0

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

Link to this section Functions

Link to this function

best(Node)

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

Equivalent to best(Tree, []).

Link to this function

best(Node, Options)

View Source 
-spec best(erl_syntax: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.

Link to this function

format(Node)

View Source 
-spec format(erl_syntax:syntaxTree()) -> string().

Equivalent to format(Tree, []).

Link to this function

format(Node, EmptyLines, Options)

View Source 
-spec format(erl_syntax:syntaxTree(), [pos_integer()], rebar3_formatter:opts()) -> string().
Pretty-prints/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(otp_formatter: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; 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.
{encoding, epp:source_encoding()}
Specifies the encoding of the generated file.
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.

Link to this function

format_file(File, _, Opts)

View Source 
-spec format_file(file:filename_all(), nostate, rebar3_formatter:opts()) -> rebar3_formatter:result().
Format a file. Apply formatting rules to a file containing erlang code. Use Opts to configure the formatter.
Link to this function

get_ctxt_hook(Ctxt)

View Source 
-spec get_ctxt_hook(context()) -> hook().
Returns the hook function field of the pretty-printer context.

See also: set_ctxt_hook/2.

Link to this function

get_ctxt_linewidth(Ctxt)

View Source 
-spec get_ctxt_linewidth(context()) -> integer().
Returns the line width field of the pretty-printer context.

See also: set_ctxt_linewidth/2.

Link to this function

get_ctxt_paperwidth(Ctxt)

View Source 
-spec get_ctxt_paperwidth(context()) -> integer().
Returns the paper width field of the pretty-printer context.

See also: set_ctxt_paperwidth/2.

Link to this function

get_ctxt_precedence(Ctxt)

View Source 
-spec get_ctxt_precedence(context()) -> integer().
Returns the operator precedence field of the pretty-printer context.

See also: set_ctxt_precedence/2.

Link to this function

get_ctxt_user(Ctxt)

View Source 
-spec get_ctxt_user(context()) -> term().
Returns the user data field of the pretty-printer context.

See also: set_ctxt_user/2.

Link to this function

init(_, _)

View Source 
-spec init(rebar3_formatter:opts(), undefined | rebar_state:t()) -> nostate.
Initialize the formatter and generate a state that will be passed in when calling other callbacks.
Link to this function

layout(Node)

View Source 
-spec layout(erl_syntax:syntaxTree()) -> prettypr:document().

Equivalent to layout(Tree, []).

Link to this function

layout(Node, Options)

View Source 
-spec layout(erl_syntax:syntaxTree(), [term()]) -> 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.

Link to this function

set_ctxt_hook(Ctxt, Hook)

View Source 
-spec set_ctxt_hook(context(), hook()) -> context().
Updates the hook function field of the pretty-printer context.

See also: get_ctxt_hook/1.

Link to this function

set_ctxt_linewidth(Ctxt, W)

View Source 
-spec set_ctxt_linewidth(context(), integer()) -> context().

Updates the line width field of the pretty-printer 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.

Link to this function

set_ctxt_paperwidth(Ctxt, W)

View Source 
-spec set_ctxt_paperwidth(context(), integer()) -> context().

Updates the paper width field of the pretty-printer 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.

Link to this function

set_ctxt_precedence(Ctxt, Prec)

View Source 
-spec set_ctxt_precedence(context(), integer()) -> context().
Updates the operator precedence field of the pretty-printer context. See the erl_parse module for operator precedences.

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

Link to this function

set_ctxt_user(Ctxt, X)

View Source 
-spec set_ctxt_user(context(), term()) -> context().
Updates the user data field of the pretty-printer context.

See also: get_ctxt_user/1.