1merl(3)                    Erlang Module Definition                    merl(3)
2
3
4

NAME

6       merl - Metaprogramming in Erlang.
7

DESCRIPTION

9       Metaprogramming  in  Erlang.  Merl is a more user friendly interface to
10       the erl_syntax module, making it easy  both  to  build  new  ASTs  from
11       scratch  and to match and decompose existing ASTs. For details that are
12       outside the scope of Merl  itself,  please  see  the  documentation  of
13       erl_syntax.
14
15       Quick start
16
17       To enable the full power of Merl, your module needs to include the Merl
18       header file:
19
20            -include_lib("syntax_tools/include/merl.hrl").
21
22       Then, you can use the ?Q(Text) macros in your code to  create  ASTs  or
23       match on existing ASTs. For example:
24
25            Tuple = ?Q("{foo, 42}"),
26            ?Q("{foo, _@Number}") = Tuple,
27            Call = ?Q("foo:bar(_@Number)")
28
29       Calling merl:print(Call) will then print the following code:
30
31            foo:bar(42)
32
33       The  ?Q  macros  turn  the  quoted  code fragments into ASTs, and lifts
34       metavariables such as _@Tuple and _@Number to the level of your  Erlang
35       code,  so you can use the corresponding Erlang variables Tuple and Num‐
36       ber directly. This is the most straightforward way to use Merl, and  in
37       many cases it's all you need.
38
39       You can even write case switches using ?Q macros as patterns. For exam‐
40       ple:
41
42            case AST of
43                ?Q("{foo, _@Foo}") -> handle(Foo);
44                ?Q("{bar, _@Bar}") when erl_syntax:is_integer(Bar) -> handle(Bar);
45                _ -> handle_default()
46            end
47
48       These case switches only allow ?Q(...) or _ as clause patterns, and the
49       guards may contain any expressions, not just Erlang guard expressions.
50
51       If  the  macro  MERL_NO_TRANSFORM is defined before the merl.hrl header
52       file is included, the parse transform used by Merl  will  be  disabled,
53       and  in  that  case, the match expressions ?Q(...) = ..., case switches
54       using ?Q(...) patterns, and automatic metavariables like _@Tuple cannot
55       be  used in your code, but the Merl macros and functions still work. To
56       do metavariable substitution, you need to use the ?Q(Text, Map)  macro,
57       e.g.:
58
59            Tuple = ?Q("{foo, _@bar, _@baz}", [{bar, Bar}, {baz,Baz}])
60
61       The  text given to a ?Q(Text) macro can be either a single string, or a
62       list of strings. The latter is useful when you need  to  split  a  long
63       expression over multiple lines, e.g.:
64
65            ?Q(["case _@Expr of",
66                "  {foo, X} -> f(X);",
67                "  {bar, X} -> g(X)",
68                "  _ -> h(X)"
69                "end"])
70
71       If  there  is  a  syntax  error somewhere in the text (like the missing
72       semicolon in the second clause above) this allows Merl to  generate  an
73       error  message  pointing  to  the exact line in your source code. (Just
74       remember to comma-separate the strings in the  list,  otherwise  Erlang
75       will concatenate the string fragments as if they were a single string.)
76
77       Metavariable syntax
78
79       There are several ways to write a metavariable in your quoted code:
80
81         * Atoms starting with @, for example '@foo' or '@Foo'
82
83         * Variables starting with _@, for example _@bar or _@Bar
84
85         * Strings starting with "'@, for example "'@File"
86
87         * Integers starting with 909, for example 9091 or 909123
88
89       Following  the  prefix,  one  or  more _ or 0 characters may be used to
90       indicate "lifting" of the variable one or more levels, and after  that,
91       a @ or 9 character indicates a glob metavariable (matching zero or more
92       elements in a sequence) rather than a normal metavariable. For example:
93
94         * '@_foo' is lifted one level, and _@__foo is lifted two levels
95
96         * _@@bar is a glob variable, and _@_@bar is a lifted glob variable
97
98         * 90901 is a lifted variable,90991 is a glob variable, and 9090091 is
99           a glob variable lifted two levels
100
101       (Note  that  the last character in the name is never considered to be a
102       lift or glob marker, hence, _@__ and 90900 are only lifted  one  level,
103       not two. Also note that globs only matter for matching; when doing sub‐
104       stitutions, a non-glob variable can be used to  inject  a  sequence  of
105       elements, and vice versa.)
106
107       If  the  name after the prefix and any lift and glob markers is _ or 0,
108       the variable is treated as an anonymous catch-all pattern  in  matches.
109       For example, _@_, _@@_, _@__, or even _@__@_.
110
111       Finally,  if  the name without any prefixes or lift/glob markers begins
112       with an uppercase character, as in _@Foo or _@_@Foo, it will  become  a
113       variable on the Erlang level, and can be used to easily deconstruct and
114       construct syntax trees:
115
116            case Input of
117                ?Q("{foo, _@Number}") -> ?Q("foo:bar(_@Number)");
118                ...
119
120       We refer to these as "automatic metavariables". If in addition the name
121       ends  with @, as in _@Foo@, the value of the variable as an Erlang term
122       will be automatically converted to the  corresponding  abstract  syntax
123       tree when used to construct a larger tree. For example, in:
124
125            Bar = {bar, 42},
126            Foo = ?Q("{foo, _@Bar@}")
127
128       (where Bar is just some term, not a syntax tree) the result Foo will be
129       a syntax tree representing {foo, {bar, 42}}. This avoids the  need  for
130       temporary variables in order to inject data, as in
131
132            TmpBar = erl_syntax:abstract(Bar),
133            Foo = ?Q("{foo, _@TmpBar}")
134
135       If  the context requires an integer rather than a variable, an atom, or
136       a string, you cannot use the uppercase convention to mark an  automatic
137       metavariable.  Instead,  if  the  integer  (without  the 909-prefix and
138       lift/glob markers) ends in a 9, the integer will become an Erlang-level
139       variable  prefixed with Q, and if it ends with 99 it will also be auto‐
140       matically abstracted. For example, the  following  will  increment  the
141       arity of the exported function f:
142
143            case Form of
144                ?Q("-export([f/90919]).") ->
145                    Q2 = erl_syntax:concrete(Q1) + 1,
146                    ?Q("-export([f/909299]).");
147                ...
148
149       When to use the various forms of metavariables
150
151       Merl  can only parse a fragment of text if it follows the basic syntac‐
152       tical rules of Erlang. In most places, a normal Erlang variable can  be
153       used as metavariable, for example:
154
155            ?Q("f(_@Arg)") = Expr
156
157       but  if you want to match on something like the name of a function, you
158       have to use an atom as metavariable:
159
160            ?Q("'@Name'() -> _@@_." = Function
161
162       (note the anonymous glob variable _@@_ to ignore the function body).
163
164       In some contexts, only a string or an integer is allowed. For  example,
165       the  directive -file(Name, Line) requires that Name is a string literal
166       and Line an integer literal:
167
168            ?Q("-file(\"'@File\", 9090).") = ?Q("-file(\"foo.erl\", 42).")).
169
170       This will extract the string literal "foo.erl" into the  variable  Foo.
171       Note  the use of the anonymous variable 9090 to ignore the line number.
172       To match and also bind a metavariable that must be an integer  literal,
173       we  can  use  the convention of ending the integer with a 9, turning it
174       into a Q-prefixed variable on the Erlang level (see the  previous  sec‐
175       tion).
176
177       Globs
178
179       Whenever you want to match out a number of elements in a sequence (zero
180       or more) rather than a fixed set of elements, you need to use  a  glob.
181       For example:
182
183            ?Q("{_@@Elements}") = ?Q({a, b, c})
184
185       will  bind Elements to the list of individual syntax trees representing
186       the atoms a, b, and c. This can also be used  with  static  prefix  and
187       suffix elements in the sequence. For example:
188
189            ?Q("{a, b, _@@Elements}") = ?Q({a, b, c, d})
190
191       will bind Elements to the list of the c and d subtrees, and
192
193            ?Q("{_@@Elements, c, d}") = ?Q({a, b, c, d})
194
195       will  bind  Elements  to the list of the a and b subtrees. You can even
196       use plain metavariables in the prefix or suffix:
197
198            ?Q("{_@First, _@@Rest}") = ?Q({a, b, c})
199
200       or
201
202            ?Q("{_@@_, _@Last}") = ?Q({a, b, c})
203
204       (ignoring all but the last element). You cannot however have two  globs
205       as part of the same sequence.
206
207       Lifted metavariables
208
209       In  some  cases,  the Erlang syntax rules make it impossible to place a
210       metavariable directly where you would like it. For example, you  cannot
211       write:
212
213            ?Q("-export([_@@Name]).")
214
215       to  match  out  all name/arity pairs in the export list, or to insert a
216       list of exports in a declaration, because the Erlang parser only allows
217       elements  on  the form A/I (where A is an atom and I an integer) in the
218       export list. A variable like the above is not allowed, but neither is a
219       single atom or integer, so '@@Name' or 909919 wouldn't work either.
220
221       What  you  have  to do in such cases is to write your metavariable in a
222       syntactically valid position, and use lifting markers to  denote  where
223       it should really apply, as in:
224
225            ?Q("-export(['@_@Name'/0]).")
226
227       This  causes  the  variable  to  be  lifted (after parsing) to the next
228       higher level in the syntax tree, replacing that entire subtree. In this
229       case,  the  '@_@Name'/0 will be replaced with '@@Name', and the /0 part
230       was just used as dummy notation and will be discarded.
231
232       You may even need to apply lifting more than once. To match the  entire
233       export list as a single syntax tree, you can write:
234
235            ?Q("-export(['@__Name'/0]).")
236
237       using  two  underscores,  but  with no glob marker this time. This will
238       make the entire ['@__Name'/0] part be replaced with '@Name'.
239
240       Sometimes, the tree structure of a code fragment  isn't  very  obvious,
241       and  parts  of  the  structure  may be invisible when printed as source
242       code. For instance, a simple function definition like the following:
243
244            zero() -> 0.
245
246       consists of the name (the atom zero), and a list of clauses  containing
247       the  single  clause  ()  ->  0. The clause consists of an argument list
248       (empty), a guard (empty), and a body (which is always a list of expres‐
249       sions) containing the single expression 0. This means that to match out
250       the name and the list of clauses of any function, you'll need to use  a
251       pattern  like  ?Q("'@Name'() -> _@_@Body."), using a dummy clause whose
252       body is a glob lifted one level.
253
254       To visualize the structure of a syntax tree, you can use  the  function
255       merl:show(T), which prints a summary. For example, entering
256
257            merl:show(merl:quote("inc(X, Y) when Y > 0 -> X + Y."))
258
259       in  the  Erlang shell will print the following (where the + signs sepa‐
260       rate groups of subtrees on the same level):
261
262            function: inc(X, Y) when ... -> X + Y.
263              atom: inc
264              +
265              clause: (X, Y) when ... -> X + Y
266                variable: X
267                variable: Y
268                +
269                disjunction: Y > 0
270                  conjunction: Y > 0
271                    infix_expr: Y > 0
272                      variable: Y
273                      +
274                      operator: >
275                      +
276                      integer: 0
277                +
278                infix_expr: X + Y
279                  variable: X
280                  +
281                  operator: +
282                  +
283                  variable: Y
284
285       This shows another important non-obvious case: a clause guard, even  if
286       it's as simple as Y > 0, always consists of a single disjunction of one
287       or more conjunctions of tests, much like a tuple of tuples. Thus:
288
289         * "when _@Guard ->" will only match a guard with exactly one test
290
291         * "when _@@Guard ->" will match a guard with one or more  comma-sepa‐
292           rated tests (but no semicolons), binding Guard to the list of tests
293
294         * "when  _@_Guard  ->" will match just like the previous pattern, but
295           binds Guard to the conjunction subtree
296
297         * "when _@_@Guard ->" will match an arbitrary nonempty guard, binding
298           Guard to the list of conjunction subtrees
299
300         * "when _@__Guard ->" will match like the previous pattern, but binds
301           Guard to the whole disjunction subtree
302
303         * and finally, "when _@__@Guard ->" will match  any  clause,  binding
304           Guard to [] if the guard is empty and to [Disjunction] otherwise
305
306       Thus, the following pattern matches all possible clauses:
307
308            "(_@Args) when _@__@Guard -> _@Body"
309

DATA TYPES

311         default_action() = () -> any():
312
313
314         env() = [{Key::id(), pattern_or_patterns()}]:
315
316
317         guard_test() = (env()) -> boolean():
318
319
320         guarded_action() = switch_action() | {guard_test(), switch_action()}:
321
322
323         guarded_actions() = guarded_action() | [guarded_action()]:
324
325
326         id() = atom() | integer():
327
328
329         location() = erl_anno:location():
330
331
332         pattern() = tree() | template():
333
334
335         pattern_or_patterns() = pattern() | [pattern()]:
336
337
338         switch_action() = (env()) -> any():
339
340
341         switch_clause()  = {pattern_or_patterns(), guarded_actions()} | {pat‐
342         tern_or_patterns(),      guard_test(),       switch_action()}       |
343         default_action():
344
345
346         template() = tree() | {id()} | {*, id()} | {template, atom(), term(),
347         [[template()]]}:
348
349
350         template_or_templates() = template() | [template()]:
351
352
353         text() = string() | binary() | [string()] | [binary()]:
354
355
356         tree() = erl_syntax:syntaxTree():
357
358
359         tree_or_trees() = tree() | [tree()]:
360
361

EXPORTS

363       alpha(Trees::pattern_or_patterns(),  Env::[{id(),   id()}])   ->   tem‐
364       plate_or_templates()
365
366              Alpha   converts  a  pattern  (renames  variables).  Similar  to
367              tsubst/1, but only renames variables (including globs).
368
369              See also: tsubst/2.
370
371       compile(Code) -> term()
372
373              Equivalent to compile(Code, []).
374
375       compile(Code, Options) -> term()
376
377              Compile a syntax tree or list of  syntax  trees  representing  a
378              module into a binary BEAM object.
379
380              See also: compile/1, compile_and_load/2.
381
382       compile_and_load(Code) -> term()
383
384              Equivalent to compile_and_load(Code, []).
385
386       compile_and_load(Code, Options) -> term()
387
388              Compile  a  syntax  tree  or list of syntax trees representing a
389              module and load the resulting module into memory.
390
391              See also: compile/2, compile_and_load/1.
392
393       match(Patterns::pattern_or_patterns(), Trees::tree_or_trees()) ->  {ok,
394       env()} | error
395
396              Match  a pattern against a syntax tree (or patterns against syn‐
397              tax trees) returning an environment mapping  variable  names  to
398              subtrees;  the  environment  is always sorted on keys. Note that
399              multiple occurrences of metavariables  in  the  pattern  is  not
400              allowed, but is not checked.
401
402              See also: switch/2, template/1.
403
404       meta_template(Templates::template_or_templates()) -> tree_or_trees()
405
406              Turn  a  template  into a syntax tree representing the template.
407              Meta-variables in the template are  turned  into  normal  Erlang
408              variables  if their names (after the metavariable prefix charac‐
409              ters) begin with an uppercase character. E.g., _@Foo in the tem‐
410              plate  becomes  the  variable Foo in the meta-template. Further‐
411              more, variables ending with @ are  automatically  wrapped  in  a
412              call  to  merl:term/1,  so  e.g.  _@Foo@ in the template becomes
413              `merl:term(Foo) in the meta-template.
414
415       print(Ts) -> term()
416
417              Pretty-print a syntax tree or template to the  standard  output.
418              This is a utility function for development and debugging.
419
420       qquote(Text::text(), Env::env()) -> tree_or_trees()
421
422              Parse text and substitute meta-variables.
423
424       qquote(StartPos::location(),      Text::text(),      Env::env())     ->
425       tree_or_trees()
426
427              Parse text and substitute meta-variables. Takes an initial scan‐
428              ner starting position as first argument.
429
430              The  macro  ?Q(Text,  Env)  expands  to merl:qquote(?LINE, Text,
431              Env).
432
433              See also: quote/2.
434
435       quote(Text::text()) -> tree_or_trees()
436
437              Parse text.
438
439       quote(StartPos::location(), Text::text()) -> tree_or_trees()
440
441              Parse text. Takes an initial scanner starting position as  first
442              argument.
443
444              The macro ?Q(Text) expands to merl:quote(?LINE, Text, Env).
445
446              See also: quote/1.
447
448       show(Ts) -> term()
449
450              Print the structure of a syntax tree or template to the standard
451              output. This is a utility function for  development  and  debug‐
452              ging.
453
454       subst(Trees::pattern_or_patterns(), Env::env()) -> tree_or_trees()
455
456              Substitute  metavariables  in  a  pattern  or  list of patterns,
457              yielding a syntax tree or list of trees as result. Both for nor‐
458              mal  metavariables and glob metavariables, the substituted value
459              may be a single element or a list of elements. For example, if a
460              list  representing  1,  2, 3 is substituted for var in either of
461              [foo, _@var, bar] or [foo, _@var, bar],  the  result  represents
462              [foo, 1, 2, 3, bar].
463
464       switch(Trees::tree_or_trees(), Cs::[switch_clause()]) -> any()
465
466              Match  against  one  or  more clauses with patterns and optional
467              guards.
468
469              Note that clauses following a default action will be ignored.
470
471              See also: match/2.
472
473       template(Trees::pattern_or_patterns()) -> template_or_templates()
474
475              Turn a syntax tree or list of trees  into  a  template  or  tem‐
476              plates.  Templates  can  be instantiated or matched against, and
477              reverted back to normal syntax trees using tree/1. If the  input
478              is already a template, it is not modified further.
479
480              See also: match/2, subst/2, tree/1.
481
482       template_vars(Template::template_or_templates()) -> [id()]
483
484              Return an ordered list of the metavariables in the template.
485
486       term(Term::term()) -> tree()
487
488              Create a syntax tree for a constant term.
489
490       tree(Templates::template_or_templates()) -> tree_or_trees()
491
492              Revert  a  template  to  a  normal  syntax  tree.  Any remaining
493              metavariables are turned into @-prefixed atoms  or  909-prefixed
494              integers.
495
496              See also: template/1.
497
498       tsubst(Trees::pattern_or_patterns(),  Env::env())  ->  template_or_tem‐
499       plates()
500
501              Like subst/2, but does not convert the result  from  a  template
502              back  to a tree. Useful if you want to do multiple separate sub‐
503              stitutions.
504
505              See also: subst/2, tree/1.
506
507       var(Name::atom()) -> tree()
508
509              Create a variable.
510

AUTHORS

512       Richard Carlsson <carlsson.richard@gmail.com>
513
514
515
516                               syntax_tools 2.5                        merl(3)
Impressum