View Source parse_trans (parse_trans v3.4.2)
Generic parse transform library for Erlang.
...
Summary
Functions
Used to report errors detected during the parse transform.
Produces a few lines of user-friendly formatting of exception info
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).
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.
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.
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.
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 options() :: [{atom(), any()}].
-type type() :: atom().
Functions
-spec context(atom(), #context{}) -> term().
-spec depth_first(xform_f_df(), Acc, forms(), options()) -> {forms(), Acc} | {error, list()}.
-spec do_depth_first(xform_f_df(), term(), forms(), #context{}) -> {forms(), term()}.
-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.
-spec format_error({atom(), term()}) -> iolist().
Equivalent to format_exception(Class, Reason, 4).
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.
-spec function_exists(atom(), integer(), forms()) -> boolean().
-spec get_attribute(atom(), [any()]) -> none | [erl_syntax:syntaxTree()].
-spec get_file(forms()) -> string().
-spec get_module([any()]) -> atom().
-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().
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.
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.
-spec pp_beam(file:filename(), file:filename()) -> ok.
-spec pp_src(forms(), string()) -> ok.
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.
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 correspondingModule: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
.
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'.
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 transform(xform_f_rec(), Acc, forms(), options()) -> {forms(), Acc} | {error, list()}.