View Source parse_trans (parse_trans v3.4.2)

Generic parse transform library for Erlang.

...

Summary

Functions

Accessor function for the Context record.

Used to report errors detected during the parse transform.

Produces a few lines of user-friendly formatting of exception info

Checks whether the given function is defined in Forms.
Returns the value of the first occurrence of attribute A.
Returns the name of the file being compiled.
Returns the name of the module being compiled.

Fetches a Syntax Tree representing the code before pre-processing, that is, including record and macro definitions. Note that macro definitions must be syntactically complete forms (this function uses epp_dodger).

Tries to retrieve the line number from an erl_syntax form. Returns a (very high) dummy number if not successful.
Initializes a context record. When traversing through the form list, the context is updated to reflect the current function and arity. Static elements in the context are the file name, the module name and the options passed to the transform function.
Equivalent to do_inspect(Fun,Acc,Forms,initial_context(Forms,Options)).

Performs a transform of Forms using the fun Fun(Form). Form is always an Erlang abstract form, i.e. it is not converted to syntax_tools representation. The intention of this transform is for the fun to have a catch-all clause returning continue. This will ensure that it stays robust against additions to the language.

Reads debug_info from the beam file Beam and returns a string containing the pretty-printed corresponding erlang source code.
Reads debug_info from the beam file Beam and pretty-prints it as Erlang source code, storing it in the file Out.
Pretty-prints the erlang source code corresponding to Forms into Out
Checks the transformed result for errors and warnings

Errors and warnings can be produced from inside a parse transform, with a bit of care. The easiest way is to simply produce an {error, Err} or {warning, Warn} form in place. This function finds such forms, and removes them from the form list (otherwise, the linter will crash), and produces a return value that the compiler can work with.

Reverts back from Syntax Tools format to Erlang forms.

Note that the Erlang forms are a subset of the Syntax Tools syntax tree, so this function is safe to call even on a list of regular Erlang forms.

Reverts a single form back from Syntax Tools format to Erlang forms.

erl_syntax:revert/1 has had a long-standing bug where it doesn't completely revert attribute forms. This function deals properly with those cases.

Types

-type form() :: any().
-type forms() :: [form()].
-type insp_f() :: fun((type(), form(), #context{}, A) -> {boolean(), A}).
-type options() :: [{atom(), any()}].
-type type() :: atom().
-type xform_f_df() ::
    fun((type(), form(), #context{}, Acc) -> {form(), Acc} | {forms(), form(), forms(), Acc}).
-type xform_f_rec() ::
    fun((type(), form(), #context{}, Acc) ->
            {form(), boolean(), Acc} | {forms(), form(), forms(), boolean(), Acc}).

Functions

-spec context(atom(), #context{}) -> term().
Accessor function for the Context record.
Link to this function

depth_first(Fun, Acc, Forms, Options)

View Source
-spec depth_first(xform_f_df(), Acc, forms(), options()) -> {forms(), Acc} | {error, list()}.
Link to this function

do_depth_first(F, Acc, Forms, Context)

View Source
-spec do_depth_first(xform_f_df(), term(), forms(), #context{}) -> {forms(), term()}.
Link to this function

do_insert_forms(_, Insert, Forms, Context)

View Source
-spec do_insert_forms(above | below, forms(), forms(), #context{}) -> forms().
Link to this function

do_inspect(F, Acc, Forms, Context)

View Source
-spec do_inspect(insp_f(), term(), forms(), #context{}) -> term().
Link to this function

do_transform(F, Acc, Forms, Context)

View Source
-spec do_transform(xform_f_rec(), term(), forms(), #context{}) -> {forms(), term()}.
-spec error(string(), any(), [{any(), any()}]) -> none().

Used to report errors detected during the parse transform.

Link to this function

export_function(F, Arity, Forms)

View Source
-spec format_error({atom(), term()}) -> iolist().
Link to this function

format_exception(Class, Reason)

View Source

Equivalent to format_exception(Class, Reason, 4).

Link to this function

format_exception(Class, Reason, Lines)

View Source

Produces a few lines of user-friendly formatting of exception info

This function is very similar to the exception pretty-printing in the shell, but returns a string that can be used as error info e.g. by error forms handled by return/2. By default, the first 4 lines of the pretty-printed exception info are returned, but this can be controlled with the Lines parameter.

Note that a stacktrace is generated inside this function.
Link to this function

function_exists(Fname, Arity, Forms)

View Source
-spec function_exists(atom(), integer(), forms()) -> boolean().
Checks whether the given function is defined in Forms.
-spec get_attribute(atom(), [any()]) -> none | [erl_syntax:syntaxTree()].
Returns the value of the first occurrence of attribute A.
Link to this function

get_attribute(A, Forms, Undef)

View Source
-spec get_file(forms()) -> string().
Returns the name of the file being compiled.
-spec get_module([any()]) -> atom().
Returns the name of the module being compiled.
Link to this function

get_orig_syntax_tree(File)

View Source
-spec get_orig_syntax_tree(string()) -> forms().

Fetches a Syntax Tree representing the code before pre-processing, that is, including record and macro definitions. Note that macro definitions must be syntactically complete forms (this function uses epp_dodger).

-spec get_pos(list()) -> erl_anno:location().
Tries to retrieve the line number from an erl_syntax form. Returns a (very high) dummy number if not successful.
Link to this function

initial_context(Forms, Options)

View Source
-spec initial_context(forms(), options()) -> #context{}.
Initializes a context record. When traversing through the form list, the context is updated to reflect the current function and arity. Static elements in the context are the file name, the module name and the options passed to the transform function.
Link to this function

inspect(F, A, Forms, Options)

View Source
-spec inspect(insp_f(), A, forms(), options()) -> A.
Equivalent to do_inspect(Fun,Acc,Forms,initial_context(Forms,Options)).
Link to this function

optionally_pretty_print(Result, Options, Context)

View Source
-spec optionally_pretty_print(forms(), options(), #context{}) -> ok.
Link to this function

plain_transform(Fun, Forms)

View Source

Performs a transform of Forms using the fun Fun(Form). Form is always an Erlang abstract form, i.e. it is not converted to syntax_tools representation. The intention of this transform is for the fun to have a catch-all clause returning continue. This will ensure that it stays robust against additions to the language.

Fun(Form) must return either of the following:

* NewForm - any valid form * continue - dig into the sub-expressions of the form * {done, NewForm} - Replace Form with NewForm; return all following forms unchanged * {error, Reason} - Abort transformation with an error message.

Example - This transform fun would convert all instances of P ! Msg to gproc:send(P, Msg):
  parse_transform(Forms, _Options) ->
      parse_trans:plain_transform(fun do_transform/1, Forms).
 
  do_transform({'op', L, '!', Lhs, Rhs}) ->
       [NewLhs] = parse_trans:plain_transform(fun do_transform/1, [Lhs]),
       [NewRhs] = parse_trans:plain_transform(fun do_transform/1, [Rhs]),
      {call, L, {remote, L, {atom, L, gproc}, {atom, L, send}},
       [NewLhs, NewRhs]};
  do_transform(_) ->
      continue.
  
-spec pp_beam(file:filename()) -> ok.
Reads debug_info from the beam file Beam and returns a string containing the pretty-printed corresponding erlang source code.
-spec pp_beam(file:filename(), file:filename()) -> ok.
Reads debug_info from the beam file Beam and pretty-prints it as Erlang source code, storing it in the file Out.
-spec pp_src(forms(), string()) -> ok.
Pretty-prints the erlang source code corresponding to Forms into Out
Link to this function

replace_function(F, Arity, NewForm, Forms)

View Source
Link to this function

replace_function(F, Arity, NewForm, Forms, Opts)

View Source
Checks the transformed result for errors and warnings

Errors and warnings can be produced from inside a parse transform, with a bit of care. The easiest way is to simply produce an {error, Err} or {warning, Warn} form in place. This function finds such forms, and removes them from the form list (otherwise, the linter will crash), and produces a return value that the compiler can work with.

The format of the error and warning "forms" must be {Tag, {Pos, Module, Info}}, where:
  • Tag :: error | warning
  • Pos :: LineNumber | {LineNumber, ColumnNumber}
  • Module is a module that exports a corresponding Module:format_error(Info)
  • Info :: term()

If the error is in the form of a caught exception, Info may be produced using the function format_exception/2.

-spec revert(forms()) -> forms().
Reverts back from Syntax Tools format to Erlang forms.

Note that the Erlang forms are a subset of the Syntax Tools syntax tree, so this function is safe to call even on a list of regular Erlang forms.

Note2: R16B03 introduced a bug, where forms produced by erl_syntax:revert/1 (specifically, implicit funs) could crash the linter. This function works around that limitation, after first verifying that it's necessary to do so. Use of the workaround can be forced with the help of the parse_trans environment variable {revert_workaround, true}. This variable will be removed when R16B03 is no longer 'supported'.

Reverts a single form back from Syntax Tools format to Erlang forms.

erl_syntax:revert/1 has had a long-standing bug where it doesn't completely revert attribute forms. This function deals properly with those cases.

Note that the Erlang forms are a subset of the Syntax Tools syntax tree, so this function is safe to call even on a regular Erlang form.

Note2: R16B03 introduced a bug, where forms produced by erl_syntax:revert/1 (specifically, implicit funs) could crash the linter. This function works around that limitation, after first verifying that it's necessary to do so. Use of the workaround can be forced with the help of the parse_trans environment variable {revert_workaround, true}. This variable will be removed when R16B03 is no longer 'supported'.

-spec top(function(), forms(), list()) -> forms() | {error, term()}.
Link to this function

transform(Fun, Acc, Forms, Options)

View Source
-spec transform(xform_f_rec(), Acc, forms(), options()) -> {forms(), Acc} | {error, list()}.
Makes one pass