1cerl(3) Erlang Module Definition cerl(3)
2
6 cerl - Core Erlang abstract syntax trees.
7
9 Core Erlang abstract syntax trees.
10 This module defines an abstract data type for representing Core Erlang
12 source code as syntax trees.
13 A recommended starting point for the first-time user is the documenta‐
15 tion of the function type/1.
16 NOTES:
18 This module deals with the composition and decomposition of syntactic
20 entities (as opposed to semantic ones); its purpose is to hide all
21 direct references to the data structures used to represent these enti‐
22 ties. With few exceptions, the functions in this module perform no
23 semantic interpretation of their inputs, and in general, the user is
24 assumed to pass type-correct arguments - if this is not done, the
25 effects are not defined.
26 Currently, the internal data structure used is the same as the record-
28 based data structures used traditionally in the Beam compiler.
29 The internal representations of abstract syntax trees are subject to
31 change without notice, and should not be documented outside this mod‐
32 ule. Furthermore, we do not give any guarantees on how an abstract syn‐
33 tax tree may or may not be represented, with the following exceptions:
34 no syntax tree is represented by a single atom, such as none, by a list
35 constructor [X | Y], or by the empty list []. This can be relied on
36 when writing functions that operate on syntax trees.
37
39 c_binary() = #c_binary{}:
40 c_bitstr() = #c_bitstr{}:
43 c_call() = #c_call{}:
46 c_clause() = #c_clause{}:
49 c_cons() = #c_cons{}:
52 c_fun() = #c_fun{}:
55 c_let() = #c_let{}:
58 c_literal() = #c_literal{}:
61 c_map() = #c_map{}:
64 c_map_pair() = #c_map_pair{}:
67 c_module() = #c_module{}:
70 c_tuple() = #c_tuple{}:
73 c_values() = #c_values{}:
76 c_var() = #c_var{}:
79 cerl():
82 An abstract Core Erlang syntax tree.
85 Every abstract syntax tree has a type, given by the function
87 type/1. In addition, each syntax tree has a list of user annota‐
88 tions (cf. get_ann/1), which are included in the Core Erlang syn‐
89 tax.
90 map_op() = #c_literal{val=assoc} | #c_literal{val=exact}:
92 var_name() = integer() | atom() | {atom(), integer()}:
95
98 abstract(Term::term()) -> cerl()
99 Creates a syntax tree corresponding to an Erlang term. Term must
101 be a literal term, i.e., one that can be represented as a source
102 code literal. Thus, it may not contain a process identifier,
103 port, reference, binary or function value as a subterm.
104 Note: This is a constant time operation.
106 See also: ann_abstract/2, concrete/1, is_literal/1, is_lit‐
108 eral_term/1.
109 add_ann(Annotations::[term()], Node::cerl()) -> cerl()
111 Appends Annotations to the list of user annotations of Node.
113 Note: this is equivalent to set_ann(Node, Annotations ++
115 get_ann(Node)), but potentially more efficient.
116 See also: get_ann/1, set_ann/2.
118 alias_pat(Node::cerl()) -> cerl()
120 Returns the pattern subtree of an abstract pattern alias.
122 See also: c_alias/2.
124 alias_var(Node::cerl()) -> cerl()
126 Returns the variable subtree of an abstract pattern alias.
128 See also: c_alias/2.
130 ann_abstract(Annotations::[term()], Term::term()) -> cerl()
132 See also: abstract/1.
134 ann_c_alias(As::[term()], Variable::cerl(), Pattern::cerl()) -> cerl()
136 See also: c_alias/2.
138 ann_c_apply(As::[term()], Operator::cerl(), Arguments::[cerl()]) ->
140 cerl()
141 See also: c_apply/2.
143 ann_c_atom(As::[term()], Name) -> cerl()
145 Types:
147 Name = atom() | string()
149 See also: c_atom/1.
151 ann_c_binary(As::[term()], Segments::[cerl()]) -> cerl()
153 See also: c_binary/1.
155 ann_c_bitstr(As::[term()], Value::cerl(), Size::cerl(), Type::cerl(),
157 Flags::cerl()) -> cerl()
158 Equivalent to ann_c_bitstr(As, Value, Size, abstract(1), Type,
160 Flags).
161 ann_c_bitstr(As::[term()], Value::cerl(), Size::cerl(), Unit::cerl(),
163 Type::cerl(), Flags::cerl()) -> cerl()
164 See also: ann_c_bitstr/5, c_bitstr/5.
166 ann_c_call(As::[term()], Module::cerl(), Name::cerl(), Argu‐
168 ments::[cerl()]) -> cerl()
169 See also: c_call/3.
171 ann_c_case(As::[term()], Argument::cerl(), Clauses::[cerl()]) -> cerl()
173 See also: c_case/2.
175 ann_c_catch(As::[term()], Body::cerl()) -> cerl()
177 See also: c_catch/1.
179 ann_c_char(As::[term()], Value::char()) -> cerl()
181 See also: c_char/1.
183 ann_c_clause(As::[term()], Patterns::[cerl()], Body::cerl()) -> cerl()
185 Equivalent to ann_c_clause(As, Patterns, c_atom(true), Body).
187 See also: c_clause/3.
189 ann_c_clause(As::[term()], Patterns::[cerl()], Guard::cerl(),
191 Body::cerl()) -> cerl()
192 See also: ann_c_clause/3, c_clause/3.
194 ann_c_cons(As::[term()], Head::cerl(), Tail::cerl()) -> cerl()
196 See also: c_cons/2.
198 ann_c_cons_skel(As::[term()], Head::cerl(), Tail::cerl()) -> cerl()
200 See also: c_cons_skel/2.
202 ann_c_float(As::[term()], Value::float()) -> cerl()
204 See also: c_float/1.
206 ann_c_fname(As::[term()], Name::atom(), Arity::arity()) -> cerl()
208 Equivalent to ann_c_var(As, {Atom, Arity}).
210 See also: c_fname/2.
212 ann_c_fun(As::[term()], Variables::[cerl()], Body::cerl()) -> cerl()
214 See also: c_fun/2.
216 ann_c_int(As::[term()], Value::integer()) -> cerl()
218 See also: c_int/1.
220 ann_c_let(As::[term()], Variables::[cerl()], Argument::cerl(),
222 Body::cerl()) -> c_let()
223 See also: c_let/3.
225 ann_c_letrec(As::[term()], Definitions::[{cerl(), cerl()}],
227 Body::cerl()) -> cerl()
228 See also: c_letrec/2.
230 ann_c_map(As::[term()], Es::[c_map_pair()]) -> c_map() | c_literal()
232 ann_c_map(As::[term()], C_literal::c_map() | c_literal(),
234 Es::[c_map_pair()]) -> c_map() | c_literal()
235 ann_c_map_pair(As::[term()], Op::cerl(), K::cerl(), V::cerl()) ->
237 c_map_pair()
238 ann_c_map_pattern(As::[term()], Pairs::[c_map_pair()]) -> c_map()
240 ann_c_module(As::[term()], Name::cerl(), Exports, Es::Definitions) ->
242 cerl()
243 Types:
245 Exports = [cerl()]
247 Definitions = [{cerl(), cerl()}]
248 See also: ann_c_module/5, c_module/3.
250 ann_c_module(As::[term()], Name::cerl(), Exports, Attrs::Attributes,
252 Es::Definitions) -> cerl()
253 Types:
255 Exports = [cerl()]
257 Attributes = [{cerl(), cerl()}]
258 Definitions = [{cerl(), cerl()}]
259 See also: ann_c_module/4, c_module/4.
261 ann_c_nil(As::[term()]) -> cerl()
263 See also: c_nil/0.
265 ann_c_primop(As::[term()], Name::cerl(), Arguments::[cerl()]) -> cerl()
267 See also: c_primop/2.
269 ann_c_receive(As::[term()], Clauses::[cerl()]) -> cerl()
271 Equivalent to ann_c_receive(As, Clauses, c_atom(infinity),
273 c_atom(true)).
274 See also: c_atom/1, c_receive/3.
276 ann_c_receive(As::[term()], Clauses::[cerl()], Timeout::cerl(),
278 Action::cerl()) -> cerl()
279 See also: ann_c_receive/2, c_receive/3.
281 ann_c_seq(As::[term()], Argument::cerl(), Body::cerl()) -> cerl()
283 See also: c_seq/2.
285 ann_c_string(As::[term()], Value::string()) -> cerl()
287 See also: c_string/1.
289 ann_c_try(As::[term()], Expression::cerl(), Variables::[cerl()],
291 Body::cerl(), EVars::[cerl()], Handler::cerl()) -> cerl()
292 See also: c_try/5.
294 ann_c_tuple(As::[term()], Elements::[cerl()]) -> cerl()
296 See also: c_tuple/1.
298 ann_c_tuple_skel(As::[term()], Elements::[cerl()]) -> cerl()
300 See also: c_tuple_skel/1.
302 ann_c_values(As::[term()], Elements::[cerl()]) -> cerl()
304 See also: c_values/1.
306 ann_c_var(As::[term()], Name::var_name()) -> cerl()
308 See also: c_var/1.
310 ann_make_data(As::[term()], Type::dtype(), Elements::[cerl()]) ->
312 cerl()
313 See also: make_data/2.
315 ann_make_data_skel(As::[term()], Type::dtype(), Elements::[cerl()]) ->
317 cerl()
318 See also: make_data_skel/2.
320 ann_make_list(As::[term()], List::[cerl()]) -> cerl()
322 Equivalent to ann_make_list(As, List, none).
324 ann_make_list(As::[term()], List::[cerl()], Tail) -> cerl()
326 Types:
328 Tail = cerl() | none
330 See also: ann_make_list/2, make_list/2.
332 ann_make_tree(As::[term()], Type::ctype(), Groups::[[cerl()]]) ->
334 cerl()
335 Creates a syntax tree with the given annotations, type and sub‐
337 trees. See make_tree/2 for details.
338 See also: make_tree/2.
340 apply_args(Node::cerl()) -> [cerl()]
342 Returns the list of argument subtrees of an abstract function
344 application.
345 See also: apply_arity/1, c_apply/2.
347 apply_arity(Node::cerl()) -> arity()
349 Returns the number of argument subtrees of an abstract function
351 application.
352 Note: this is equivalent to length(apply_args(Node)), but poten‐
354 tially more efficient.
355 See also: apply_args/1, c_apply/2.
357 apply_op(Node::cerl()) -> cerl()
359 Returns the operator subtree of an abstract function applica‐
361 tion.
362 See also: c_apply/2.
364 atom_lit(Node::cerl()) -> string()
366 Returns the literal string represented by an abstract atom. This
368 always includes surrounding single-quote characters.
369 Note that an abstract atom may have several literal representa‐
371 tions, and that the representation yielded by this function is
372 not fixed; e.g., atom_lit(c_atom("a\012b")) could yield the
373 string "\'a\\nb\'".
374 See also: c_atom/1.
376 atom_name(Node::cerl()) -> string()
378 Returns the printname of an abstract atom.
380 See also: c_atom/1.
382 atom_val(Node::cerl()) -> atom()
384 Returns the value represented by an abstract atom.
386 See also: c_atom/1.
388 binary_segments(Node::cerl()) -> [cerl()]
390 Returns the list of segment subtrees of an abstract binary-tem‐
392 plate.
393 See also: c_binary/1, c_bitstr/5.
395 bitstr_bitsize(Node::cerl()) -> any | all | utf | integer()
397 Returns the total size in bits of an abstract bit-string tem‐
399 plate. If the size field is an integer literal, the result is
400 the product of the size and unit values; if the size field is
401 the atom literal all, the atom all is returned. If the size is
402 not a literal, the atom any is returned.
403 See also: c_bitstr/5.
405 bitstr_flags(Node::cerl()) -> cerl()
407 Returns the flags subtree of an abstract bit-string template.
409 See also: c_bitstr/5.
411 bitstr_size(Node::cerl()) -> cerl()
413 Returns the size subtree of an abstract bit-string template.
415 See also: c_bitstr/5.
417 bitstr_type(Node::cerl()) -> cerl()
419 Returns the type subtree of an abstract bit-string template.
421 See also: c_bitstr/5.
423 bitstr_unit(Node::cerl()) -> cerl()
425 Returns the unit subtree of an abstract bit-string template.
427 See also: c_bitstr/5.
429 bitstr_val(Node::cerl()) -> cerl()
431 Returns the value subtree of an abstract bit-string template.
433 See also: c_bitstr/5.
435 c_alias(Variable::cerl(), Pattern::cerl()) -> cerl()
437 Creates an abstract pattern alias. The result represents "Vari‐
439 able = Pattern".
440 See also: alias_pat/1, alias_var/1, ann_c_alias/3, c_clause/3,
442 is_c_alias/1, update_c_alias/3.
443 c_apply(Operator::cerl(), Arguments::[cerl()]) -> cerl()
445 Creates an abstract function application. If Arguments is [A1,
447 ..., An], the result represents "apply Operator(A1, ..., An)".
448 See also: ann_c_apply/3, apply_args/1, apply_arity/1,
450 apply_op/1, c_call/3, c_primop/2, is_c_apply/1,
451 update_c_apply/3.
452 c_atom(Name) -> cerl()
454 Types:
456 Name = atom() | string()
458 Creates an abstract atom literal. The print name of the atom is
460 the character sequence represented by Name.
461 Note: passing a string as argument to this function causes a
463 corresponding atom to be created for the internal representa‐
464 tion.
465 See also: ann_c_atom/2, atom_lit/1, atom_name/1, atom_val/1,
467 is_c_atom/1.
468 c_binary(Segments::[cerl()]) -> cerl()
470 Creates an abstract binary-template. A binary object is in this
472 context a sequence of an arbitrary number of bits. (The number
473 of bits used to be evenly divisible by 8, but after the intro‐
474 duction of bit strings in the Erlang language, the choice was
475 made to use the binary template for all bit strings.) It is
476 specified by zero or more bit-string template segments of arbi‐
477 trary lengths (in number of bits). If Segments is [S1, ..., Sn],
478 the result represents "#{S1, ..., Sn}#". All the Si must have
479 type bitstr.
480 See also: ann_c_binary/2, binary_segments/1, c_bitstr/5,
482 is_c_binary/1, update_c_binary/2.
483 c_bitstr(Value::cerl(), Type::cerl(), Flags::cerl()) -> cerl()
485 Equivalent to c_bitstr(Value, abstract(all), abstract(1), Type,
487 Flags).
488 c_bitstr(Value::cerl(), Size::cerl(), Type::cerl(), Flags::cerl()) ->
490 cerl()
491 Equivalent to c_bitstr(Value, Size, abstract(1), Type, Flags).
493 c_bitstr(Value::cerl(), Size::cerl(), Unit::cerl(), Type::cerl(),
495 Flags::cerl()) -> cerl()
496 Creates an abstract bit-string template. These can only occur as
498 components of an abstract binary-template (see c_binary/1). The
499 result represents "#<Value>(Size, Unit, Type, Flags)", where
500 Unit must represent a positive integer constant, Type must rep‐
501 resent a constant atom (one of 'integer', 'float', or 'binary'),
502 and Flags must represent a constant list "[F1, ..., Fn]" where
503 all the Fi are atoms.
504 See also: ann_c_bitstr/6, bitstr_flags/1, bitstr_size/1, bit‐
506 str_type/1, bitstr_unit/1, bitstr_val/1, c_binary/1, is_c_bit‐
507 str/1, update_c_bitstr/6.
508 c_call(Module::cerl(), Name::cerl(), Arguments::[cerl()]) -> cerl()
510 Creates an abstract inter-module call. If Arguments is [A1, ...,
512 An], the result represents "call Module:Name(A1, ..., An)".
513 See also: ann_c_call/4, c_apply/2, c_primop/2, call_args/1,
515 call_arity/1, call_module/1, call_name/1, is_c_call/1,
516 update_c_call/4.
517 c_case(Argument::cerl(), Clauses::[cerl()]) -> cerl()
519 Creates an abstract case-expression. If Clauses is [C1, ...,
521 Cn], the result represents "case Argument of C1 ... Cn end".
522 Clauses must not be empty.
523 See also: ann_c_case/3, c_clause/3, case_arg/1, case_arity/1,
525 case_clauses/1, is_c_case/1, update_c_case/3.
526 c_catch(Body::cerl()) -> cerl()
528 Creates an abstract catch-expression. The result represents
530 "catch Body".
531 Note: catch-expressions can be rewritten as try-expressions, and
533 will eventually be removed from Core Erlang.
534 See also: ann_c_catch/2, c_try/5, catch_body/1, is_c_catch/1,
536 update_c_catch/2.
537 c_char(Value) -> cerl()
539 Types:
541 Value = char() | integer()
543 Creates an abstract character literal. If the local implementa‐
545 tion of Erlang defines char() as a subset of integer(), this
546 function is equivalent to c_int/1. Otherwise, if the given value
547 is an integer, it will be converted to the character with the
548 corresponding code. The lexical representation of a character is
549 "$Char", where Char is a single printing character or an escape
550 sequence.
551 See also: ann_c_char/2, c_int/1, c_string/1, char_lit/1,
553 char_val/1, is_c_char/1, is_print_char/1.
554 c_clause(Patterns::[cerl()], Body::cerl()) -> cerl()
556 Equivalent to c_clause(Patterns, c_atom(true), Body).
558 See also: c_atom/1.
560 c_clause(Patterns::[cerl()], Guard::cerl(), Body::cerl()) -> cerl()
562 Creates an an abstract clause. If Patterns is [P1, ..., Pn], the
564 result represents "<P1, ..., Pn> when Guard -> Body".
565 See also: ann_c_clause/4, c_case/2, c_clause/2, c_receive/3,
567 clause_arity/1, clause_body/1, clause_guard/1, clause_pats/1,
568 clause_vars/1, is_c_clause/1, update_c_clause/4.
569 c_cons(Head::cerl(), Tail::cerl()) -> cerl()
571 Creates an abstract list constructor. The result represents
573 "[Head | Tail]". Note that if both Head and Tail have type lit‐
574 eral, then the result will also have type literal, and annota‐
575 tions on Head and Tail are lost.
576 Recall that in Erlang, the tail element of a list constructor is
578 not necessarily a list.
579 See also: ann_c_cons/3, c_cons_skel/2, c_nil/0, cons_hd/1,
581 cons_tl/1, is_c_cons/1, is_c_list/1, list_elements/1,
582 list_length/1, make_list/2, update_c_cons/3.
583 c_cons_skel(Head::cerl(), Tail::cerl()) -> cerl()
585 Creates an abstract list constructor skeleton. Does not fold
587 constant literals, i.e., the result always has type cons, repre‐
588 senting "[Head | Tail]".
589 This function is occasionally useful when it is necessary to
591 have annotations on the subnodes of a list constructor node,
592 even when the subnodes are constant literals. Note however that
593 is_literal/1 will yield false and concrete/1 will fail if passed
594 the result from this function.
595 fold_literal/1 can be used to revert a node to the normal-form
597 representation.
598 See also: ann_c_cons_skel/3, c_cons/2, c_nil/0, concrete/1,
600 fold_literal/1, is_c_cons/1, is_c_list/1, is_literal/1,
601 update_c_cons_skel/3.
602 c_float(Value::float()) -> cerl()
604 Creates an abstract floating-point literal. The lexical repre‐
606 sentation is the decimal floating-point numeral of Value.
607 See also: ann_c_float/2, float_lit/1, float_val/1, is_c_float/1.
609 c_fname(Name::atom(), Arity::arity()) -> cerl()
611 Equivalent to c_var({Name, Arity}).
613 See also: ann_c_fname/3, fname_arity/1, fname_id/1,
615 is_c_fname/1, update_c_fname/3.
616 c_fun(Variables::[cerl()], Body::cerl()) -> cerl()
618 Creates an abstract fun-expression. If Variables is [V1, ...,
620 Vn], the result represents "fun (V1, ..., Vn) -> Body". All the
621 Vi must have type var.
622 See also: ann_c_fun/3, fun_arity/1, fun_body/1, fun_vars/1,
624 is_c_fun/1, update_c_fun/3.
625 c_int(Value::integer()) -> cerl()
627 Creates an abstract integer literal. The lexical representation
629 is the canonical decimal numeral of Value.
630 See also: ann_c_int/2, c_char/1, int_lit/1, int_val/1,
632 is_c_int/1.
633 c_let(Variables::[cerl()], Argument::cerl(), Body::cerl()) -> cerl()
635 Creates an abstract let-expression. If Variables is [V1, ...,
637 Vn], the result represents "let <V1, ..., Vn> = Argument in
638 Body". All the Vi must have type var.
639 See also: ann_c_let/4, is_c_let/1, let_arg/1, let_arity/1,
641 let_body/1, let_vars/1, update_c_let/4.
642 c_letrec(Definitions::[{cerl(), cerl()}], Body::cerl()) -> cerl()
644 Creates an abstract letrec-expression. If Definitions is [{V1,
646 F1}, ..., {Vn, Fn}], the result represents "letrec V1 = F1 ...
647 Vn = Fn in Body. All the Vi must have type var and represent
648 function names. All the Fi must have type 'fun'.
649 See also: ann_c_letrec/3, is_c_letrec/1, letrec_body/1,
651 letrec_defs/1, letrec_vars/1, update_c_letrec/3.
652 c_map(Pairs::[c_map_pair()]) -> c_map()
654 c_map_pair(Key::cerl(), Val::cerl()) -> c_map_pair()
656 c_map_pair_exact(Key::cerl(), Val::cerl()) -> c_map_pair()
658 c_map_pattern(Pairs::[c_map_pair()]) -> c_map()
660 c_module(Name::cerl(), Exports, Es::Definitions) -> cerl()
662 Types:
664 Exports = [cerl()]
666 Definitions = [{cerl(), cerl()}]
667 Equivalent to c_module(Name, Exports, [], Definitions).
669 c_module(Name::cerl(), Exports, Attrs::Attributes, Es::Definitions) ->
671 cerl()
672 Types:
674 Exports = [cerl()]
676 Attributes = [{cerl(), cerl()}]
677 Definitions = [{cerl(), cerl()}]
678 Creates an abstract module definition. The result represents
680 module Name [E1, ..., Ek]
682 attributes [K1 = T1, ...,
683 Km = Tm]
684 V1 = F1
685 ...
686 Vn = Fn
687 end
688 if Exports = [E1, ..., Ek], Attributes = [{K1, T1}, ..., {Km,
690 Tm}], and Definitions = [{V1, F1}, ..., {Vn, Fn}].
691 Name and all the Ki must be atom literals, and all the Ti must
693 be constant literals. All the Vi and Ei must have type var and
694 represent function names. All the Fi must have type 'fun'.
695 See also: ann_c_module/4, ann_c_module/5, c_atom/1, c_fun/2,
697 c_module/3, c_var/1, is_literal/1, module_attrs/1, mod‐
698 ule_defs/1, module_exports/1, module_name/1, module_vars/1,
699 update_c_module/5.
700 c_nil() -> cerl()
702 Creates an abstract empty list. The result represents "[]". The
704 empty list is traditionally called "nil".
705 See also: ann_c_nil/1, c_cons/2, is_c_list/1.
707 c_primop(Name::cerl(), Arguments::[cerl()]) -> cerl()
709 Creates an abstract primitive operation call. If Arguments is
711 [A1, ..., An], the result represents "primop Name(A1, ..., An)".
712 Name must be an atom literal.
713 See also: ann_c_primop/3, c_apply/2, c_call/3, is_c_primop/1,
715 primop_args/1, primop_arity/1, primop_name/1, update_c_primop/3.
716 c_receive(Clauses::[cerl()]) -> cerl()
718 Equivalent to c_receive(Clauses, c_atom(infinity),
720 c_atom(true)).
721 See also: c_atom/1.
723 c_receive(Clauses::[cerl()], Timeout::cerl(), Action::cerl()) -> cerl()
725 Creates an abstract receive-expression. If Clauses is [C1, ...,
727 Cn], the result represents "receive C1 ... Cn after Timeout ->
728 Action end".
729 See also: ann_c_receive/4, c_receive/1, is_c_receive/1,
731 receive_action/1, receive_clauses/1, receive_timeout/1,
732 update_c_receive/4.
733 c_seq(Argument::cerl(), Body::cerl()) -> cerl()
735 Creates an abstract sequencing expression. The result represents
737 "do Argument Body".
738 See also: ann_c_seq/3, is_c_seq/1, seq_arg/1, seq_body/1,
740 update_c_seq/3.
741 c_string(Value::string()) -> cerl()
743 Creates an abstract string literal. Equivalent to creating an
745 abstract list of the corresponding character literals (cf.
746 is_c_string/1), but is typically more efficient. The lexical
747 representation of a string is ""Chars"", where Chars is a
748 sequence of printing characters or spaces.
749 See also: ann_c_string/2, c_char/1, is_c_string/1,
751 is_print_string/1, string_lit/1, string_val/1.
752 c_try(Argument::cerl(), Variables::[cerl()], Body::cerl(), Exception‐
754 Vars::[cerl()], Handler::cerl()) -> cerl()
755 Creates an abstract try-expression. If Variables is [V1, ...,
757 Vn] and ExceptionVars is [X1, ..., Xm], the result represents
758 "try Argument of <V1, ..., Vn> -> Body catch <X1, ..., Xm> ->
759 Handler". All the Vi and Xi must have type var.
760 See also: ann_c_try/6, c_catch/1, is_c_try/1, try_arg/1,
762 try_body/1, try_vars/1, update_c_try/6.
763 c_tuple(Elements::[cerl()]) -> cerl()
765 Creates an abstract tuple. If Elements is [E1, ..., En], the
767 result represents "{E1, ..., En}". Note that if all nodes in
768 Elements have type literal, or if Elements is empty, then the
769 result will also have type literal and annotations on nodes in
770 Elements are lost.
771 Recall that Erlang has distinct 1-tuples, i.e., {X} is always
773 distinct from X itself.
774 See also: ann_c_tuple/2, c_tuple_skel/1, is_c_tuple/1,
776 tuple_arity/1, tuple_es/1, update_c_tuple/2.
777 c_tuple_skel(Elements::[cerl()]) -> cerl()
779 Creates an abstract tuple skeleton. Does not fold constant lit‐
781 erals, i.e., the result always has type tuple, representing
782 "{E1, ..., En}", if Elements is [E1, ..., En].
783 This function is occasionally useful when it is necessary to
785 have annotations on the subnodes of a tuple node, even when all
786 the subnodes are constant literals. Note however that is_lit‐
787 eral/1 will yield false and concrete/1 will fail if passed the
788 result from this function.
789 fold_literal/1 can be used to revert a node to the normal-form
791 representation.
792 See also: ann_c_tuple_skel/2, c_tuple/1, concrete/1, fold_lit‐
794 eral/1, is_c_tuple/1, is_literal/1, tuple_es/1,
795 update_c_tuple_skel/2.
796 c_values(Elements::[cerl()]) -> cerl()
798 Creates an abstract value list. If Elements is [E1, ..., En],
800 the result represents "<E1, ..., En>".
801 See also: ann_c_values/2, is_c_values/1, update_c_values/2, val‐
803 ues_arity/1, values_es/1.
804 c_var(Name::var_name()) -> cerl()
806 Types:
808 var_name() = integer() | atom() | {atom(), integer()}
810 Creates an abstract variable. A variable is identified by its
812 name, given by the Name parameter.
813 If a name is given by a single atom, it should either be a "sim‐
815 ple" atom which does not need to be single-quoted in Erlang, or
816 otherwise its print name should correspond to a proper Erlang
817 variable, i.e., begin with an uppercase character or an under‐
818 score. Names on the form {A, N} represent function name vari‐
819 ables "A/N"; these are special variables which may be bound only
820 in the function definitions of a module or a letrec. They may
821 not be bound in let expressions and cannot occur in clause pat‐
822 terns. The atom A in a function name may be any atom; the inte‐
823 ger N must be nonnegative. The functions c_fname/2 etc. are
824 utilities for handling function name variables.
825 When printing variable names, they must have the form of proper
827 Core Erlang variables and function names. E.g., a name repre‐
828 sented by an integer such as 42 could be formatted as "_42", an
829 atom 'Xxx' simply as "Xxx", and an atom foo as "_foo". However,
830 one must assure that any two valid distinct names are never
831 mapped to the same strings. Tuples such as {foo, 2} representing
832 function names can simply by formatted as "'foo'/2", with no
833 risk of conflicts.
834 See also: ann_c_var/2, c_fname/2, c_letrec/2, c_module/4,
836 is_c_var/1, update_c_var/2, var_name/1.
837 call_args(Node::cerl()) -> [cerl()]
839 Returns the list of argument subtrees of an abstract inter-mod‐
841 ule call.
842 See also: c_call/3, call_arity/1.
844 call_arity(Node::cerl()) -> arity()
846 Returns the number of argument subtrees of an abstract inter-
848 module call.
849 Note: this is equivalent to length(call_args(Node)), but poten‐
851 tially more efficient.
852 See also: c_call/3, call_args/1.
854 call_module(Node::cerl()) -> cerl()
856 Returns the module subtree of an abstract inter-module call.
858 See also: c_call/3.
860 call_name(Node::cerl()) -> cerl()
862 Returns the name subtree of an abstract inter-module call.
864 See also: c_call/3.
866 case_arg(Node::cerl()) -> cerl()
868 Returns the argument subtree of an abstract case-expression.
870 See also: c_case/2.
872 case_arity(Node::cerl()) -> integer()
874 Equivalent to clause_arity(hd(case_clauses(Node))), but poten‐
876 tially more efficient.
877 See also: c_case/2, case_clauses/1, clause_arity/1.
879 case_clauses(Node::cerl()) -> [cerl()]
881 Returns the list of clause subtrees of an abstract case-expres‐
883 sion.
884 See also: c_case/2, case_arity/1.
886 catch_body(Node::cerl()) -> cerl()
888 Returns the body subtree of an abstract catch-expression.
890 See also: c_catch/1.
892 char_lit(Node::cerl()) -> string()
894 Returns the literal string represented by an abstract character.
896 This includes a leading $ character. Currently, all characters
897 that are not in the set of ISO 8859-1 (Latin-1) "printing" char‐
898 acters will be escaped.
899 See also: c_char/1.
901 char_val(Node::cerl()) -> char()
903 Returns the value represented by an abstract character literal.
905 See also: c_char/1.
907 clause_arity(Node::cerl()) -> integer()
909 Returns the number of pattern subtrees of an abstract clause.
911 Note: this is equivalent to length(clause_pats(Node)), but
913 potentially more efficient.
914 See also: c_clause/3, clause_pats/1.
916 clause_body(Node::cerl()) -> cerl()
918 Returns the body subtree of an abstract clause.
920 See also: c_clause/3.
922 clause_guard(Node::cerl()) -> cerl()
924 Returns the guard subtree of an abstract clause.
926 See also: c_clause/3.
928 clause_pats(Node::cerl()) -> [cerl()]
930 Returns the list of pattern subtrees of an abstract clause.
932 See also: c_clause/3, clause_arity/1.
934 clause_vars(Clause::cerl()) -> [cerl()]
936 Returns the list of all abstract variables in the patterns of an
938 abstract clause. The order of listing is not defined.
939 See also: c_clause/3, pat_list_vars/1.
941 concrete(Node::cerl()) -> term()
943 Returns the Erlang term represented by a syntax tree. An excep‐
945 tion is thrown if Node does not represent a literal term.
946 Note: This is a constant time operation.
948 See also: abstract/1, is_literal/1.
950 cons_hd(C_cons::cerl()) -> cerl()
952 Returns the head subtree of an abstract list constructor.
954 See also: c_cons/2.
956 cons_tl(C_cons::cerl()) -> cerl()
958 Returns the tail subtree of an abstract list constructor.
960 Recall that the tail does not necessarily represent a proper
962 list.
963 See also: c_cons/2.
965 copy_ann(Source::cerl(), Target::cerl()) -> cerl()
967 Copies the list of user annotations from Source to Target.
969 Note: this is equivalent to set_ann(Target, get_ann(Source)),
971 but potentially more efficient.
972 See also: get_ann/1, set_ann/2.
974 data_arity(Node::cerl()) -> integer()
976 Returns the number of subtrees of a data constructor node. This
978 is equivalent to length(data_es(Node)), but potentially more
979 efficient.
980 See also: data_es/1, is_data/1.
982 data_es(Node::cerl()) -> [cerl()]
984 Returns the list of subtrees of a data constructor node. If the
986 arity of the constructor is zero, the result is the empty list.
987 Note: if data_type(Node) is cons, the number of subtrees is
989 exactly two. If data_type(Node) is {atomic, Value}, the number
990 of subtrees is zero.
991 See also: data_arity/1, data_type/1, is_data/1, make_data/2.
993 data_type(Node::cerl()) -> dtype()
995 Types:
997 dtype() = cons | tuple | {atomic, Value}
999 Value = integer() | float() | atom() | []
1000 Returns a type descriptor for a data constructor node. (Cf.
1002 is_data/1.) This is mainly useful for comparing types and for
1003 constructing new nodes of the same type (cf. make_data/2). If
1004 Node represents an integer, floating-point number, atom or empty
1005 list, the result is {atomic, Value}, where Value is the value of
1006 concrete(Node), otherwise the result is either cons or tuple.
1007 Type descriptors can be compared for equality or order (in the
1009 Erlang term order), but remember that floating-point values
1010 should in general never be tested for equality.
1011 See also: concrete/1, is_data/1, make_data/2, type/1.
1013 float_lit(Node::cerl()) -> string()
1015 Returns the numeral string represented by a floating-point lit‐
1017 eral node.
1018 See also: c_float/1.
1020 float_val(Node::cerl()) -> float()
1022 Returns the value represented by a floating-point literal node.
1024 See also: c_float/1.
1026 fname_arity(C_var::cerl()) -> arity()
1028 Returns the arity part of an abstract function name variable.
1030 See also: c_fname/2, fname_id/1.
1032 fname_id(C_var::cerl()) -> atom()
1034 Returns the identifier part of an abstract function name vari‐
1036 able.
1037 See also: c_fname/2, fname_arity/1.
1039 fold_literal(Node::cerl()) -> cerl()
1041 Assures that literals have a compact representation. This is
1043 occasionally useful if c_cons_skel/2, c_tuple_skel/1 or
1044 unfold_literal/1 were used in the construction of Node, and you
1045 want to revert to the normal "folded" representation of liter‐
1046 als. If Node represents a tuple or list constructor, its ele‐
1047 ments are rewritten recursively, and the node is reconstructed
1048 using c_cons/2 or c_tuple/1, respectively; otherwise, Node is
1049 not changed.
1050 See also: c_cons/2, c_cons_skel/2, c_tuple/1, c_tuple_skel/1,
1052 is_literal/1, unfold_literal/1.
1053 from_records(Tree::record(record_types())) -> cerl()
1055 Types:
1057 record_types() = c_alias | c_apply | c_call | c_case |
1059 c_catch | c_clause | c_cons | c_fun | c_let | c_letrec |
1060 c_lit | c_module | c_primop | c_receive | c_seq | c_try |
1061 c_tuple | c_values | c_var
1062 Translates an explicit record representation to a corresponding
1064 abstract syntax tree. The records are defined in the file
1065 "core_parse.hrl".
1066 See also: to_records/1, type/1.
1068 fun_arity(Node::cerl()) -> arity()
1070 Returns the number of parameter subtrees of an abstract fun-
1072 expression.
1073 Note: this is equivalent to length(fun_vars(Node)), but poten‐
1075 tially more efficient.
1076 See also: c_fun/2, fun_vars/1.
1078 fun_body(Node::cerl()) -> cerl()
1080 Returns the body subtree of an abstract fun-expression.
1082 See also: c_fun/2.
1084 fun_vars(Node::cerl()) -> [cerl()]
1086 Returns the list of parameter subtrees of an abstract fun-
1088 expression.
1089 See also: c_fun/2, fun_arity/1.
1091 get_ann(Node::cerl()) -> [term()]
1093 Returns the list of user annotations associated with a syntax
1095 tree node. For a newly created node, this is the empty list. The
1096 annotations may be any terms.
1097 See also: set_ann/2.
1099 int_lit(Node::cerl()) -> string()
1101 Returns the numeral string represented by an integer literal
1103 node.
1104 See also: c_int/1.
1106 int_val(Node::cerl()) -> integer()
1108 Returns the value represented by an integer literal node.
1110 See also: c_int/1.
1112 is_c_alias(Node::cerl()) -> boolean()
1114 Returns true if Node is an abstract pattern alias, otherwise
1116 false.
1117 See also: c_alias/2.
1119 is_c_apply(Node::cerl()) -> boolean()
1121 Returns true if Node is an abstract function application, other‐
1123 wise false.
1124 See also: c_apply/2.
1126 is_c_atom(Node::cerl()) -> boolean()
1128 Returns true if Node represents an atom literal, otherwise
1130 false.
1131 See also: c_atom/1.
1133 is_c_binary(Node::cerl()) -> boolean()
1135 Returns true if Node is an abstract binary-template; otherwise
1137 false.
1138 See also: c_binary/1.
1140 is_c_bitstr(Node::cerl()) -> boolean()
1142 Returns true if Node is an abstract bit-string template; other‐
1144 wise false.
1145 See also: c_bitstr/5.
1147 is_c_call(Node::cerl()) -> boolean()
1149 Returns true if Node is an abstract inter-module call expres‐
1151 sion; otherwise false.
1152 See also: c_call/3.
1154 is_c_case(C_case::cerl()) -> boolean()
1156 Returns true if Node is an abstract case-expression; otherwise
1158 false.
1159 See also: c_case/2.
1161 is_c_catch(Node::cerl()) -> boolean()
1163 Returns true if Node is an abstract catch-expression, otherwise
1165 false.
1166 See also: c_catch/1.
1168 is_c_char(Node::cerl()) -> boolean()
1170 Returns true if Node may represent a character literal, other‐
1172 wise false.
1173 If the local implementation of Erlang defines char() as a subset
1175 of integer(), then is_c_int(Node) will also yield true.
1176 See also: c_char/1, is_print_char/1.
1178 is_c_clause(Node::cerl()) -> boolean()
1180 Returns true if Node is an abstract clause, otherwise false.
1182 See also: c_clause/3.
1184 is_c_cons(Node::cerl()) -> boolean()
1186 Returns true if Node is an abstract list constructor, otherwise
1188 false.
1189 is_c_float(Node::cerl()) -> boolean()
1191 Returns true if Node represents a floating-point literal, other‐
1193 wise false.
1194 See also: c_float/1.
1196 is_c_fname(Node::cerl()) -> boolean()
1198 Returns true if Node is an abstract function name variable, oth‐
1200 erwise false.
1201 See also: c_fname/2, c_var/1, var_name/1.
1203 is_c_fun(Node::cerl()) -> boolean()
1205 Returns true if Node is an abstract fun-expression, otherwise
1207 false.
1208 See also: c_fun/2.
1210 is_c_int(Node::cerl()) -> boolean()
1212 Returns true if Node represents an integer literal, otherwise
1214 false.
1215 See also: c_int/1.
1217 is_c_let(Node::cerl()) -> boolean()
1219 Returns true if Node is an abstract let-expression, otherwise
1221 false.
1222 See also: c_let/3.
1224 is_c_letrec(Node::cerl()) -> boolean()
1226 Returns true if Node is an abstract letrec-expression, otherwise
1228 false.
1229 See also: c_letrec/2.
1231 is_c_list(Node::cerl()) -> boolean()
1233 Returns true if Node represents a proper list, otherwise false.
1235 A proper list is either the empty list [], or a cons cell [Head
1236 | Tail], where recursively Tail is a proper list.
1237 Note: Because Node is a syntax tree, the actual run-time values
1239 corresponding to its subtrees may often be partially or com‐
1240 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1241 (where Ns is a variable), then the function will return false,
1242 because it is not known whether Ns will be bound to a list at
1243 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1244 []]", then the function will return true.
1245 See also: c_cons/2, c_nil/0, list_elements/1, list_length/1.
1247 is_c_map(Node::cerl()) -> boolean()
1249 Returns true if Node is an abstract map constructor, otherwise
1251 false.
1252 is_c_map_empty(C_map::c_map() | c_literal()) -> boolean()
1254 is_c_map_pattern(C_map::c_map()) -> boolean()
1256 is_c_module(Node::cerl()) -> boolean()
1258 Returns true if Node is an abstract module definition, otherwise
1260 false.
1261 See also: type/1.
1263 is_c_nil(Node::cerl()) -> boolean()
1265 Returns true if Node is an abstract empty list, otherwise false.
1267 is_c_primop(Node::cerl()) -> boolean()
1269 Returns true if Node is an abstract primitive operation call,
1271 otherwise false.
1272 See also: c_primop/2.
1274 is_c_receive(Node::cerl()) -> boolean()
1276 Returns true if Node is an abstract receive-expression, other‐
1278 wise false.
1279 See also: c_receive/3.
1281 is_c_seq(Node::cerl()) -> boolean()
1283 Returns true if Node is an abstract sequencing expression, oth‐
1285 erwise false.
1286 See also: c_seq/2.
1288 is_c_string(Node::cerl()) -> boolean()
1290 Returns true if Node may represent a string literal, otherwise
1292 false. Strings are defined as lists of characters; see
1293 is_c_char/1 for details.
1294 See also: c_string/1, is_c_char/1, is_print_string/1.
1296 is_c_try(Node::cerl()) -> boolean()
1298 Returns true if Node is an abstract try-expression, otherwise
1300 false.
1301 See also: c_try/5.
1303 is_c_tuple(Node::cerl()) -> boolean()
1305 Returns true if Node is an abstract tuple, otherwise false.
1307 See also: c_tuple/1.
1309 is_c_values(Node::cerl()) -> boolean()
1311 Returns true if Node is an abstract value list; otherwise false.
1313 See also: c_values/1.
1315 is_c_var(Node::cerl()) -> boolean()
1317 Returns true if Node is an abstract variable, otherwise false.
1319 See also: c_var/1.
1321 is_data(Node::cerl()) -> boolean()
1323 Returns true if Node represents a data constructor, otherwise
1325 false. Data constructors are cons cells, tuples, and atomic lit‐
1326 erals.
1327 See also: data_arity/1, data_es/1, data_type/1.
1329 is_leaf(Node::cerl()) -> boolean()
1331 Returns true if Node is a leaf node, otherwise false. The cur‐
1333 rent leaf node types are literal and var.
1334 Note: all literals (cf. is_literal/1) are leaf nodes, even if
1336 they represent structured (constant) values such as {foo, [bar,
1337 baz]}. Also note that variables are leaf nodes but not literals.
1338 See also: is_literal/1, type/1.
1340 is_literal(Node::cerl()) -> boolean()
1342 Returns true if Node represents a literal term, otherwise false.
1344 This function returns true if and only if the value of con‐
1345 crete(Node) is defined.
1346 Note: This is a constant time operation.
1348 See also: abstract/1, concrete/1, fold_literal/1.
1350 is_literal_term(Term::term()) -> boolean()
1352 Returns true if Term can be represented as a literal, otherwise
1354 false. This function takes time proportional to the size of
1355 Term.
1356 See also: abstract/1.
1358 is_print_char(Node::cerl()) -> boolean()
1360 Returns true if Node may represent a "printing" character, oth‐
1362 erwise false. (Cf. is_c_char/1.) A "printing" character has
1363 either a given graphical representation, or a "named" escape
1364 sequence such as "\n". Currently, only ISO 8859-1 (Latin-1)
1365 character values are recognized.
1366 See also: c_char/1, is_c_char/1.
1368 is_print_string(Node::cerl()) -> boolean()
1370 Returns true if Node may represent a string literal containing
1372 only "printing" characters, otherwise false. See is_c_string/1
1373 and is_print_char/1 for details. Currently, only ISO 8859-1
1374 (Latin-1) character values are recognized.
1375 See also: c_string/1, is_c_string/1, is_print_char/1.
1377 let_arg(Node::cerl()) -> cerl()
1379 Returns the argument subtree of an abstract let-expression.
1381 See also: c_let/3.
1383 let_arity(Node::cerl()) -> integer()
1385 Returns the number of left-hand side variables of an abstract
1387 let-expression.
1388 Note: this is equivalent to length(let_vars(Node)), but poten‐
1390 tially more efficient.
1391 See also: c_let/3, let_vars/1.
1393 let_body(Node::cerl()) -> cerl()
1395 Returns the body subtree of an abstract let-expression.
1397 See also: c_let/3.
1399 let_vars(Node::cerl()) -> [cerl()]
1401 Returns the list of left-hand side variables of an abstract let-
1403 expression.
1404 See also: c_let/3, let_arity/1.
1406 letrec_body(Node::cerl()) -> cerl()
1408 Returns the body subtree of an abstract letrec-expression.
1410 See also: c_letrec/2.
1412 letrec_defs(Node::cerl()) -> [{cerl(), cerl()}]
1414 Returns the list of definitions of an abstract letrec-expres‐
1416 sion. If Node represents "letrec V1 = F1 ... Vn = Fn in Body",
1417 the returned value is [{V1, F1}, ..., {Vn, Fn}].
1418 See also: c_letrec/2.
1420 letrec_vars(Node::cerl()) -> [cerl()]
1422 Returns the list of left-hand side function variable subtrees of
1424 a letrec-expression. If Node represents "letrec V1 = F1 ... Vn =
1425 Fn in Body", the returned value is [V1, ..., Vn].
1426 See also: c_letrec/2.
1428 list_elements(C_cons::cerl()) -> [cerl()]
1430 Returns the list of element subtrees of an abstract list. Node
1432 must represent a proper list. E.g., if Node represents "[X1, X2
1433 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1434 X2, X3, X4].
1435 See also: c_cons/2, c_nil/0, is_c_list/1, list_length/1,
1437 make_list/2.
1438 list_length(Node::cerl()) -> integer()
1440 Returns the number of element subtrees of an abstract list. Node
1442 must represent a proper list. E.g., if Node represents "[X1 |
1443 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1444 integer 6.
1445 Note: this is equivalent to length(list_elements(Node)), but
1447 potentially more efficient.
1448 See also: c_cons/2, c_nil/0, is_c_list/1, list_elements/1.
1450 make_data(Type::dtype(), Elements::[cerl()]) -> cerl()
1452 Creates a data constructor node with the specified type and sub‐
1454 trees. (Cf. data_type/1.) An exception is thrown if the length
1455 of Elements is invalid for the given Type; see data_es/1 for
1456 arity constraints on constructor types.
1457 See also: ann_make_data/3, data_es/1, data_type/1,
1459 make_data_skel/2, update_data/3.
1460 make_data_skel(Type::dtype(), Elements::[cerl()]) -> cerl()
1462 Like make_data/2, but analogous to c_tuple_skel/1 and
1464 c_cons_skel/2.
1465 See also: ann_make_data_skel/3, c_cons_skel/2, c_tuple_skel/1,
1467 make_data/2, update_data_skel/3.
1468 make_list(List) -> Node
1470 Equivalent to make_list(List, none).
1472 make_list(List::[cerl()], Tail) -> cerl()
1474 Types:
1476 Tail = cerl() | none
1478 Creates an abstract list from the elements in List and the
1480 optional Tail. If Tail is none, the result will represent a nil-
1481 terminated list, otherwise it represents "[... | Tail]".
1482 See also: ann_make_list/3, c_cons/2, c_nil/0, list_elements/1,
1484 update_list/3.
1485 make_tree(Type::ctype(), Groups::[[cerl()]]) -> cerl()
1487 Creates a syntax tree with the given type and subtrees. Type
1489 must be a node type name (cf. type/1) that does not denote a
1490 leaf node type (cf. is_leaf/1). Groups must be a nonempty list
1491 of groups of syntax trees, representing the subtrees of a node
1492 of the given type, in left-to-right order as they would occur in
1493 the printed program text, grouped by category as done by sub‐
1494 trees/1.
1495 The result of ann_make_tree(get_ann(Node), type(Node), sub‐
1497 trees(Node)) (cf. update_tree/2) represents the same source code
1498 text as the original Node, assuming that subtrees(Node) yields a
1499 nonempty list. However, it does not necessarily have the exact
1500 same data representation as Node.
1501 See also: ann_make_tree/3, is_leaf/1, subtrees/1, type/1,
1503 update_tree/2.
1504 map_arg(C_literal::c_map() | c_literal()) -> c_map() | c_literal()
1506 map_es(C_literal::c_map() | c_literal()) -> [c_map_pair()]
1508 map_pair_key(C_map_pair::c_map_pair()) -> cerl()
1510 map_pair_op(C_map_pair::c_map_pair()) -> map_op()
1512 map_pair_val(C_map_pair::c_map_pair()) -> cerl()
1514 meta(Tree::cerl()) -> cerl()
1516 Creates a meta-representation of a syntax tree. The result rep‐
1518 resents an Erlang expression "MetaTree" which, if evaluated,
1519 will yield a new syntax tree representing the same source code
1520 text as Tree (although the actual data representation may be
1521 different). The expression represented by MetaTree is implemen‐
1522 tation independent with regard to the data structures used by
1523 the abstract syntax tree implementation.
1524 Any node in Tree whose node type is var (cf. type/1), and whose
1526 list of annotations (cf. get_ann/1) contains the atom meta_var,
1527 will remain unchanged in the resulting tree, except that exactly
1528 one occurrence of meta_var is removed from its annotation list.
1529 The main use of the function meta/1 is to transform a data
1531 structure Tree, which represents a piece of program code, into a
1532 form that is representation independent when printed. E.g., sup‐
1533 pose Tree represents a variable named "V". Then (assuming a
1534 function print/1 for printing syntax trees), evaluating
1535 print(abstract(Tree)) - simply using abstract/1 to map the
1536 actual data structure onto a syntax tree representation - would
1537 output a string that might look something like "{var, ...,
1538 'V'}", which is obviously dependent on the implementation of the
1539 abstract syntax trees. This could e.g. be useful for caching a
1540 syntax tree in a file. However, in some situations like in a
1541 program generator generator (with two "generator"), it may be
1542 unacceptable. Using print(meta(Tree)) instead would output a
1543 representation independent syntax tree generating expression; in
1544 the above case, something like "cerl:c_var('V')".
1545 The implementation tries to generate compact code with respect
1547 to literals and lists.
1548 See also: abstract/1, get_ann/1, type/1.
1550 module_attrs(Node::cerl()) -> [{cerl(), cerl()}]
1552 Returns the list of pairs of attribute key/value subtrees of an
1554 abstract module definition.
1555 See also: c_module/4.
1557 module_defs(Node::cerl()) -> [{cerl(), cerl()}]
1559 Returns the list of function definitions of an abstract module
1561 definition.
1562 See also: c_module/4.
1564 module_exports(Node::cerl()) -> [cerl()]
1566 Returns the list of exports subtrees of an abstract module defi‐
1568 nition.
1569 See also: c_module/4.
1571 module_name(Node::cerl()) -> cerl()
1573 Returns the name subtree of an abstract module definition.
1575 See also: c_module/4.
1577 module_vars(Node::cerl()) -> [cerl()]
1579 Returns the list of left-hand side function variable subtrees of
1581 an abstract module definition.
1582 See also: c_module/4.
1584 pat_list_vars(Patterns::[cerl()]) -> [cerl()]
1586 Returns the list of all abstract variables in the given pat‐
1588 terns. An exception is thrown if some element in Patterns does
1589 not represent a well-formed Core Erlang clause pattern. The
1590 order of listing is not defined.
1591 See also: clause_vars/1, pat_vars/1.
1593 pat_vars(Pattern::cerl()) -> [cerl()]
1595 Returns the list of all abstract variables in a pattern. An
1597 exception is thrown if Node does not represent a well-formed
1598 Core Erlang clause pattern. The order of listing is not defined.
1599 See also: clause_vars/1, pat_list_vars/1.
1601 primop_args(Node::cerl()) -> [cerl()]
1603 Returns the list of argument subtrees of an abstract primitive
1605 operation call.
1606 See also: c_primop/2, primop_arity/1.
1608 primop_arity(Node::cerl()) -> arity()
1610 Returns the number of argument subtrees of an abstract primitive
1612 operation call.
1613 Note: this is equivalent to length(primop_args(Node)), but
1615 potentially more efficient.
1616 See also: c_primop/2, primop_args/1.
1618 primop_name(Node::cerl()) -> cerl()
1620 Returns the name subtree of an abstract primitive operation
1622 call.
1623 See also: c_primop/2.
1625 receive_action(Node::cerl()) -> cerl()
1627 Returns the action subtree of an abstract receive-expression.
1629 See also: c_receive/3.
1631 receive_clauses(Node::cerl()) -> [cerl()]
1633 Returns the list of clause subtrees of an abstract receive-
1635 expression.
1636 See also: c_receive/3.
1638 receive_timeout(Node::cerl()) -> cerl()
1640 Returns the timeout subtree of an abstract receive-expression.
1642 See also: c_receive/3.
1644 seq_arg(Node::cerl()) -> cerl()
1646 Returns the argument subtree of an abstract sequencing expres‐
1648 sion.
1649 See also: c_seq/2.
1651 seq_body(Node::cerl()) -> cerl()
1653 Returns the body subtree of an abstract sequencing expression.
1655 See also: c_seq/2.
1657 set_ann(Node::cerl(), Annotations::[term()]) -> cerl()
1659 Sets the list of user annotations of Node to Annotations.
1661 See also: add_ann/2, copy_ann/2, get_ann/1.
1663 string_lit(Node::cerl()) -> string()
1665 Returns the literal string represented by an abstract string.
1667 This includes surrounding double-quote characters "...". Cur‐
1668 rently, characters that are not in the set of ISO 8859-1
1669 (Latin-1) "printing" characters will be escaped, except for spa‐
1670 ces.
1671 See also: c_string/1.
1673 string_val(Node::cerl()) -> string()
1675 Returns the value represented by an abstract string literal.
1677 See also: c_string/1.
1679 subtrees(Node::cerl()) -> [[cerl()]]
1681 Returns the grouped list of all subtrees of a node. If Node is a
1683 leaf node (cf. is_leaf/1), this is the empty list, otherwise the
1684 result is always a nonempty list, containing the lists of sub‐
1685 trees of Node, in left-to-right order as they occur in the
1686 printed program text, and grouped by category. Often, each group
1687 contains only a single subtree.
1688 Depending on the type of Node, the size of some groups may be
1690 variable (e.g., the group consisting of all the elements of a
1691 tuple), while others always contain the same number of elements
1692 - usually exactly one (e.g., the group containing the argument
1693 expression of a case-expression). Note, however, that the exact
1694 structure of the returned list (for a given node type) should in
1695 general not be depended upon, since it might be subject to
1696 change without notice.
1697 The function subtrees/1 and the constructor functions
1699 make_tree/2 and update_tree/2 can be a great help if one wants
1700 to traverse a syntax tree, visiting all its subtrees, but treat
1701 nodes of the tree in a uniform way in most or all cases. Using
1702 these functions makes this simple, and also assures that your
1703 code is not overly sensitive to extensions of the syntax tree
1704 data type, because any node types not explicitly handled by your
1705 code can be left to a default case.
1706 For example:
1708 postorder(F, Tree) ->
1710 F(case subtrees(Tree) of
1711 [] -> Tree;
1712 List -> update_tree(Tree,
1713 [[postorder(F, Subtree)
1714 || Subtree <- Group]
1715 || Group <- List])
1716 end).
1717 maps the function F on Tree and all its subtrees, doing a post-
1720 order traversal of the syntax tree. (Note the use of
1721 update_tree/2 to preserve annotations.) For a simple function
1722 like:
1723 f(Node) ->
1725 case type(Node) of
1726 atom -> atom("a_" ++ atom_name(Node));
1727 _ -> Node
1728 end.
1729 the call postorder(fun f/1, Tree) will yield a new representa‐
1732 tion of Tree in which all atom names have been extended with the
1733 prefix "a_", but nothing else (including annotations) has been
1734 changed.
1735 See also: is_leaf/1, make_tree/2, update_tree/2.
1737 to_records(Tree::cerl()) -> record(record_types())
1739 Translates an abstract syntax tree to a corresponding explicit
1741 record representation. The records are defined in the file
1742 "cerl.hrl".
1743 See also: from_records/1, type/1.
1745 try_arg(Node::cerl()) -> cerl()
1747 Returns the expression subtree of an abstract try-expression.
1749 See also: c_try/5.
1751 try_body(Node::cerl()) -> cerl()
1753 Returns the success body subtree of an abstract try-expression.
1755 See also: c_try/5.
1757 try_evars(Node::cerl()) -> [cerl()]
1759 Returns the list of exception variable subtrees of an abstract
1761 try-expression.
1762 See also: c_try/5.
1764 try_handler(Node::cerl()) -> cerl()
1766 Returns the exception body subtree of an abstract try-expres‐
1768 sion.
1769 See also: c_try/5.
1771 try_vars(Node::cerl()) -> [cerl()]
1773 Returns the list of success variable subtrees of an abstract
1775 try-expression.
1776 See also: c_try/5.
1778 tuple_arity(Node::cerl()) -> integer()
1780 Returns the number of element subtrees of an abstract tuple.
1782 Note: this is equivalent to length(tuple_es(Node)), but poten‐
1784 tially more efficient.
1785 See also: c_tuple/1, tuple_es/1.
1787 tuple_es(C_tuple::cerl()) -> [cerl()]
1789 Returns the list of element subtrees of an abstract tuple.
1791 See also: c_tuple/1.
1793 type(Node::cerl()) -> atom()
1795 Returns the type tag of Node. Current node types are:
1797 alias apply binary bitstr call case catch clause
1799 cons fun let letrec literal map map_pair module
1800 primop receive seq try tuple values var
1801 Note: The name of the primary constructor function for a node
1804 type is always the name of the type itself, prefixed by "c_";
1805 recognizer predicates are correspondingly prefixed by "is_c_".
1806 Furthermore, to simplify preservation of annotations (cf.
1807 get_ann/1), there are analogous constructor functions prefixed
1808 by "ann_c_" and "update_c_", for setting the annotation list of
1809 the new node to either a specific value or to the annotations of
1810 an existing node, respectively.
1811 See also: abstract/1, c_alias/2, c_apply/2, c_binary/1, c_bit‐
1813 str/5, c_call/3, c_case/2, c_catch/1, c_clause/3, c_cons/2,
1814 c_fun/2, c_let/3, c_letrec/2, c_module/3, c_primop/2,
1815 c_receive/1, c_seq/2, c_try/5, c_tuple/1, c_values/1, c_var/1,
1816 data_type/1, from_records/1, get_ann/1, meta/1, subtrees/1,
1817 to_records/1.
1818 unfold_literal(Node::cerl()) -> cerl()
1820 Assures that literals have a fully expanded representation. If
1822 Node represents a literal tuple or list constructor, its ele‐
1823 ments are rewritten recursively, and the node is reconstructed
1824 using c_cons_skel/2 or c_tuple_skel/1, respectively; otherwise,
1825 Node is not changed. The fold_literal/1 can be used to revert to
1826 the normal compact representation.
1827 See also: c_cons/2, c_cons_skel/2, c_tuple/1, c_tuple_skel/1,
1829 fold_literal/1, is_literal/1.
1830 update_c_alias(Old::cerl(), Variable::cerl(), Pattern::cerl()) ->
1832 cerl()
1833 See also: c_alias/2.
1835 update_c_apply(Old::cerl(), Operator::cerl(), Arguments::[cerl()]) ->
1837 cerl()
1838 See also: c_apply/2.
1840 update_c_binary(Old::cerl(), Segments::[cerl()]) -> cerl()
1842 See also: c_binary/1.
1844 update_c_bitstr(Old::cerl(), Value::cerl(), Size::cerl(), Type::cerl(),
1846 Flags::cerl()) -> cerl()
1847 Equivalent to update_c_bitstr(Node, Value, Size, abstract(1),
1849 Type, Flags).
1850 update_c_bitstr(Old::cerl(), Value::cerl(), Size::cerl(), Unit::cerl(),
1852 Type::cerl(), Flags::cerl()) -> cerl()
1853 See also: c_bitstr/5, update_c_bitstr/5.
1855 update_c_call(Old::cerl(), Module::cerl(), Name::cerl(), Argu‐
1857 ments::[cerl()]) -> cerl()
1858 See also: c_call/3.
1860 update_c_case(Old::cerl(), Argument::cerl(), Clauses::[cerl()]) ->
1862 cerl()
1863 See also: c_case/2.
1865 update_c_catch(Old::cerl(), Body::cerl()) -> cerl()
1867 See also: c_catch/1.
1869 update_c_clause(Old::cerl(), Patterns::[cerl()], Guard::cerl(),
1871 Body::cerl()) -> cerl()
1872 See also: c_clause/3.
1874 update_c_cons(Old::cerl(), Head::cerl(), Tail::cerl()) -> cerl()
1876 See also: c_cons/2.
1878 update_c_cons_skel(Old::cerl(), Head::cerl(), Tail::cerl()) -> cerl()
1880 See also: c_cons_skel/2.
1882 update_c_fname(Old::cerl(), Name::atom()) -> cerl()
1884 Like update_c_fname/3, but takes the arity from Node.
1886 See also: c_fname/2, update_c_fname/3.
1888 update_c_fname(Old::cerl(), Name::atom(), Arity::arity()) -> cerl()
1890 Equivalent to update_c_var(Old, {Atom, Arity}).
1892 See also: c_fname/2, update_c_fname/2.
1894 update_c_fun(Old::cerl(), Variables::[cerl()], Body::cerl()) -> cerl()
1896 See also: c_fun/2.
1898 update_c_let(Node::c_let(), Variables::[cerl()], Argument::cerl(),
1900 Body::cerl()) -> c_let()
1901 See also: c_let/3.
1903 update_c_letrec(Old::cerl(), Definitions::[{cerl(), cerl()}],
1905 Body::cerl()) -> cerl()
1906 See also: c_letrec/2.
1908 update_c_map(C_map::c_map(), M::cerl(), Es::[cerl()]) -> c_map() |
1910 c_literal()
1911 update_c_map_pair(Old::c_map_pair(), Op::map_op(), K::cerl(),
1913 V::cerl()) -> c_map_pair()
1914 update_c_module(Old::cerl(), Name::cerl(), Exports, Attrs::Attributes,
1916 Es::Definitions) -> cerl()
1917 Types:
1919 Exports = [cerl()]
1921 Attributes = [{cerl(), cerl()}]
1922 Definitions = [{cerl(), cerl()}]
1923 See also: c_module/4.
1925 update_c_primop(Old::cerl(), Name::cerl(), Arguments::[cerl()]) ->
1927 cerl()
1928 See also: c_primop/2.
1930 update_c_receive(Old::cerl(), Clauses::[cerl()], Timeout::cerl(),
1932 Action::cerl()) -> cerl()
1933 See also: c_receive/3.
1935 update_c_seq(Old::cerl(), Argument::cerl(), Body::cerl()) -> cerl()
1937 See also: c_seq/2.
1939 update_c_try(Old::cerl(), Expression::cerl(), Variables::[cerl()],
1941 Body::cerl(), EVars::[cerl()], Handler::cerl()) -> cerl()
1942 See also: c_try/5.
1944 update_c_tuple(Old::cerl(), Elements::[cerl()]) -> cerl()
1946 See also: c_tuple/1.
1948 update_c_tuple_skel(Old::cerl(), Elements::[cerl()]) -> cerl()
1950 See also: c_tuple_skel/1.
1952 update_c_values(Old::cerl(), Elements::[cerl()]) -> cerl()
1954 See also: c_values/1.
1956 update_c_var(Old::cerl(), Name::var_name()) -> cerl()
1958 See also: c_var/1.
1960 update_data(Old::cerl(), Type::dtype(), Elements::[cerl()]) -> cerl()
1962 See also: make_data/2.
1964 update_data_skel(Old::cerl(), Type::dtype(), Elements::[cerl()]) ->
1966 cerl()
1967 See also: make_data_skel/2.
1969 update_list(Old::cerl(), List::[cerl()]) -> cerl()
1971 Equivalent to update_list(Old, List, none).
1973 update_list(Old::cerl(), List::[cerl()], Tail) -> cerl()
1975 Types:
1977 Tail = cerl() | none
1979 See also: make_list/2, update_list/2.
1981 update_tree(Old::cerl(), Groups::[[cerl()]]) -> cerl()
1983 Creates a syntax tree with the given subtrees, and the same type
1985 and annotations as the Old node. This is equivalent to
1986 ann_make_tree(get_ann(Node), type(Node), Groups), but poten‐
1987 tially more efficient.
1988 See also: ann_make_tree/3, get_ann/1, type/1, update_tree/3.
1990 update_tree(Old::cerl(), Type::ctype(), Groups::[[cerl()]]) -> cerl()
1992 Creates a syntax tree with the given type and subtrees, and the
1994 same annotations as the Old node. This is equivalent to
1995 ann_make_tree(get_ann(Node), Type, Groups), but potentially more
1996 efficient.
1997 See also: ann_make_tree/3, get_ann/1, update_tree/2.
1999 values_arity(Node::cerl()) -> integer()
2001 Returns the number of element subtrees of an abstract value
2003 list.
2004 Note: This is equivalent to length(values_es(Node)), but poten‐
2006 tially more efficient.
2007 See also: c_values/1, values_es/1.
2009 values_es(Node::cerl()) -> [cerl()]
2011 Returns the list of element subtrees of an abstract value list.
2013 See also: c_values/1, values_arity/1.
2015 var_name(Node::cerl()) -> var_name()
2017 Returns the name of an abstract variable.
2019 See also: c_var/1.
2021
2023 Richard Carlsson <carlsson.richard@gmail.com>
2024 compiler 7.6.7 cerl(3)