uberpt
Erlang support library for writing parse transforms.
Use this as a parse transform.
Examples below frequently use atoms in place of valid syntax trees to simplify the documentation; in your own code you might pass quote(ConstantHere) or some other value which resolves to a valid abstract expression.
ast
Calls to ast/1 will be replaced with the abstract syntax tree of their parameter. This can be used as shorthand for declaring variables and so-on.
Example: ast(1) will become {integer, _Line, 1}.
ast_function
Calls to ast_function/2 will be replaced with the abstract syntax tree of a function whose name is the first parameter and whose body is the body of the fun in the second parameter. This is great for injecting new functions.
ast_function(foo, fun (1) -> 1; (2) -> 2 end) will be replaced with:
{function,_Line,
{atom,_Line,foo},
1,
[{clause,_Line,[{integer,_Line,1}],[],[{integer,_Line,1}]},
{clause,_Line,[{integer,_Line,2}],[],[{integer,_Line,2}]}]}
quote
Calls to quote/1 inside an ast block will be replaced by the verbatim contents of their parameter. This effectively cancels the ast wrapper and allows parametrization of the contents..
Example: ast(quote(A) + 1) will become {op,_Line,'+',A,{integer,_Line,1}}.
quote_block
If a function body in an ast block is just a call to quote_block/1, the body will become the parameter. This allows the replacement of the body with a list of statements without wrapping them in a begin/end block.
Example:
test1(Ast) -> ast_function(foo, fun (1) -> quote(Ast); (2) -> quote_block(Ast) end).
test7([statement1, statement2]) will be replaced with:
{function,_Line,
{atom,_Line,foo},
1,
[{clause,_Line,[{integer,_Line,1}],[],[[statement1,statement2]]},
{clause,_Line,[{integer,_Line,2}],[],[statement1,statement2]}]}
Note the first clause is an invalid syntax tree.
'$uberpt_quote'
Newer erlangs report syntax errors if you write a function call in a match clause. As an alternative, quote(X) can be replaced with {'$uberpt_quote', X}. For example, ast(fun ({'$uberpt_quote', X}) -> ok end) will insert the abstract code X as the first match in the function clause, being replaced with:
{'fun', _Line, {clauses, [{clause, _Line, [X], [], [{atom, _Line, ok}]}]}}
ast_fragment
Preceed a function declaration with -ast_fragment([]). to cause the function to return its own abstract syntax tree. Note that this is a list of syntax elements.
-compile({parse_transform, uberpt}).
-ast_fragment([]).
test() -> 1.
test() returns [{integer, _Line, 1}].
You can have (simple) parameters, which will be replaced into the abstract syntax tree (hence should be valid ast elements!):
-compile({parse_transform, uberpt}).
-ast_fragment([]).
test1(A) -> A.
-ast_fragment([]).
test2(A) -> B.
-ast_fragment([]).
test3(A) -> A + B.
test1(1) returns [1]. test2(1) returns [{var, _Line, 'B'}]. test3(1) returns [{op, _Line, '+', 1, {var, _Line, 'B'}}]. Note that only the second of these is a valid abstract syntax tree.
ast_fragment2
A different form for ast_fragment. You may specify "in params" and "out params" (which are currently equivalent), and a list of "temp params". Calls must pass a temp_suffix third argument which can be used to parametrize the variable names which are neither in nor out.
-compile({parse_transform, uberpt}).
-ast_fragment2([]).
test({in, [Foo]}, {out, [Bar]}, {temp, [Baz]}) -> Bar = Foo + Baz.
test({in, [param1]}, {out, [param2]}, {temp_suffix, "blah"}) returns [{match, _Line, param2, {op, _Line, '+', param1, {var, _Line, 'Bazblah'}}}].
ast_forms_function
Generate a function which returns the complete AST for all forms between this and the next -end_ast_forms_function([]).
-compile({parse_transform, uberpt}).
-ast_forms_function(#{name => ast_forms_stuff, params => ['Param1']}).
a() -> Param1.
-end_ast_forms_function([]).
ast_forms_stuff(ast(1)) returns the form for a function called a which returns the integer 1. params is optional; if not provided, a 0-arity function will be generated.
Note that any unbound variables in the form currently won't generate compile errors until the generated form is itself compiled (that is to say, dropping , params => ['Param1'] above would not create a compile warning or error).
Some attributes are handled by the preprocessor and either can't be parse-transformed at all or have some verification on their parameters. Any attribute whose name begins uberpt_raw_ will have that prefix removed, allowing a means of generating these in a semi-natural way.
Additionally, if you want variables in attributes, they must be manually quoted, as the terms in attributes are passed through verbatim and can't contain free variables. Example:
-compile({parse_transform, uberpt}).
-ast_forms_function(#{name => ast_attribute_example, params => ['Param1']}).
-uberpt_raw_module({raw, {var, 1, 'Param1'}}).
-end_ast_forms_function([]).
Then ast_attribute_example(foo) will produce -module(foo)..