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 di‐
21 rect references to the data structures used to represent these enti‐
22 ties. With few exceptions, the functions in this module perform no se‐
23 mantic interpretation of their inputs, and in general, the user is as‐
24 sumed to pass type-correct arguments - if this is not done, the effects
25 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(), Ac‐
278 tion::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, ap‐
450 ply_op/1, c_call/3, c_primop/2, is_c_apply/1, update_c_apply/3.
451 c_atom(Name) -> cerl()
453 Types:
455 Name = atom() | string()
457 Creates an abstract atom literal. The print name of the atom is
459 the character sequence represented by Name.
460 Note: passing a string as argument to this function causes a
462 corresponding atom to be created for the internal representa‐
463 tion.
464 See also: ann_c_atom/2, atom_lit/1, atom_name/1, atom_val/1,
466 is_c_atom/1.
467 c_binary(Segments::[cerl()]) -> cerl()
469 Creates an abstract binary-template. A binary object is in this
471 context a sequence of an arbitrary number of bits. (The number
472 of bits used to be evenly divisible by 8, but after the intro‐
473 duction of bit strings in the Erlang language, the choice was
474 made to use the binary template for all bit strings.) It is
475 specified by zero or more bit-string template segments of arbi‐
476 trary lengths (in number of bits). If Segments is [S1, ..., Sn],
477 the result represents "#{S1, ..., Sn}#". All the Si must have
478 type bitstr.
479 See also: ann_c_binary/2, binary_segments/1, c_bitstr/5,
481 is_c_binary/1, update_c_binary/2.
482 c_bitstr(Value::cerl(), Type::cerl(), Flags::cerl()) -> cerl()
484 Equivalent to c_bitstr(Value, abstract(all), abstract(1), Type,
486 Flags).
487 c_bitstr(Value::cerl(), Size::cerl(), Type::cerl(), Flags::cerl()) ->
489 cerl()
490 Equivalent to c_bitstr(Value, Size, abstract(1), Type, Flags).
492 c_bitstr(Value::cerl(), Size::cerl(), Unit::cerl(), Type::cerl(),
494 Flags::cerl()) -> cerl()
495 Creates an abstract bit-string template. These can only occur as
497 components of an abstract binary-template (see c_binary/1). The
498 result represents "#<Value>(Size, Unit, Type, Flags)", where
499 Unit must represent a positive integer constant, Type must rep‐
500 resent a constant atom (one of 'integer', 'float', or 'binary'),
501 and Flags must represent a constant list "[F1, ..., Fn]" where
502 all the Fi are atoms.
503 See also: ann_c_bitstr/6, bitstr_flags/1, bitstr_size/1, bit‐
505 str_type/1, bitstr_unit/1, bitstr_val/1, c_binary/1, is_c_bit‐
506 str/1, update_c_bitstr/6.
507 c_call(Module::cerl(), Name::cerl(), Arguments::[cerl()]) -> cerl()
509 Creates an abstract inter-module call. If Arguments is [A1, ...,
511 An], the result represents "call Module:Name(A1, ..., An)".
512 See also: ann_c_call/4, c_apply/2, c_primop/2, call_args/1,
514 call_arity/1, call_module/1, call_name/1, is_c_call/1, up‐
515 date_c_call/4.
516 c_case(Argument::cerl(), Clauses::[cerl()]) -> cerl()
518 Creates an abstract case-expression. If Clauses is [C1, ...,
520 Cn], the result represents "case Argument of C1 ... Cn end".
521 Clauses must not be empty.
522 See also: ann_c_case/3, c_clause/3, case_arg/1, case_arity/1,
524 case_clauses/1, is_c_case/1, update_c_case/3.
525 c_catch(Body::cerl()) -> cerl()
527 Creates an abstract catch-expression. The result represents
529 "catch Body".
530 Note: catch-expressions can be rewritten as try-expressions, and
532 will eventually be removed from Core Erlang.
533 See also: ann_c_catch/2, c_try/5, catch_body/1, is_c_catch/1,
535 update_c_catch/2.
536 c_char(Value) -> cerl()
538 Types:
540 Value = char() | integer()
542 Creates an abstract character literal. If the local implementa‐
544 tion of Erlang defines char() as a subset of integer(), this
545 function is equivalent to c_int/1. Otherwise, if the given value
546 is an integer, it will be converted to the character with the
547 corresponding code. The lexical representation of a character is
548 "$Char", where Char is a single printing character or an escape
549 sequence.
550 See also: ann_c_char/2, c_int/1, c_string/1, char_lit/1,
552 char_val/1, is_c_char/1, is_print_char/1.
553 c_clause(Patterns::[cerl()], Body::cerl()) -> cerl()
555 Equivalent to c_clause(Patterns, c_atom(true), Body).
557 See also: c_atom/1.
559 c_clause(Patterns::[cerl()], Guard::cerl(), Body::cerl()) -> cerl()
561 Creates an an abstract clause. If Patterns is [P1, ..., Pn], the
563 result represents "<P1, ..., Pn> when Guard -> Body".
564 See also: ann_c_clause/4, c_case/2, c_clause/2, c_receive/3,
566 clause_arity/1, clause_body/1, clause_guard/1, clause_pats/1,
567 clause_vars/1, is_c_clause/1, update_c_clause/4.
568 c_cons(Head::cerl(), Tail::cerl()) -> cerl()
570 Creates an abstract list constructor. The result represents
572 "[Head | Tail]". Note that if both Head and Tail have type lit‐
573 eral, then the result will also have type literal, and annota‐
574 tions on Head and Tail are lost.
575 Recall that in Erlang, the tail element of a list constructor is
577 not necessarily a list.
578 See also: ann_c_cons/3, c_cons_skel/2, c_nil/0, cons_hd/1,
580 cons_tl/1, is_c_cons/1, is_c_list/1, list_elements/1,
581 list_length/1, make_list/2, update_c_cons/3.
582 c_cons_skel(Head::cerl(), Tail::cerl()) -> cerl()
584 Creates an abstract list constructor skeleton. Does not fold
586 constant literals, i.e., the result always has type cons, repre‐
587 senting "[Head | Tail]".
588 This function is occasionally useful when it is necessary to
590 have annotations on the subnodes of a list constructor node,
591 even when the subnodes are constant literals. Note however that
592 is_literal/1 will yield false and concrete/1 will fail if passed
593 the result from this function.
594 fold_literal/1 can be used to revert a node to the normal-form
596 representation.
597 See also: ann_c_cons_skel/3, c_cons/2, c_nil/0, concrete/1,
599 fold_literal/1, is_c_cons/1, is_c_list/1, is_literal/1, up‐
600 date_c_cons_skel/3.
601 c_float(Value::float()) -> cerl()
603 Creates an abstract floating-point literal. The lexical repre‐
605 sentation is the decimal floating-point numeral of Value.
606 See also: ann_c_float/2, float_lit/1, float_val/1, is_c_float/1.
608 c_fname(Name::atom(), Arity::arity()) -> cerl()
610 Equivalent to c_var({Name, Arity}).
612 See also: ann_c_fname/3, fname_arity/1, fname_id/1,
614 is_c_fname/1, update_c_fname/3.
615 c_fun(Variables::[cerl()], Body::cerl()) -> cerl()
617 Creates an abstract fun-expression. If Variables is [V1, ...,
619 Vn], the result represents "fun (V1, ..., Vn) -> Body". All the
620 Vi must have type var.
621 See also: ann_c_fun/3, fun_arity/1, fun_body/1, fun_vars/1,
623 is_c_fun/1, update_c_fun/3.
624 c_int(Value::integer()) -> cerl()
626 Creates an abstract integer literal. The lexical representation
628 is the canonical decimal numeral of Value.
629 See also: ann_c_int/2, c_char/1, int_lit/1, int_val/1,
631 is_c_int/1.
632 c_let(Variables::[cerl()], Argument::cerl(), Body::cerl()) -> cerl()
634 Creates an abstract let-expression. If Variables is [V1, ...,
636 Vn], the result represents "let <V1, ..., Vn> = Argument in
637 Body". All the Vi must have type var.
638 See also: ann_c_let/4, is_c_let/1, let_arg/1, let_arity/1,
640 let_body/1, let_vars/1, update_c_let/4.
641 c_letrec(Definitions::[{cerl(), cerl()}], Body::cerl()) -> cerl()
643 Creates an abstract letrec-expression. If Definitions is [{V1,
645 F1}, ..., {Vn, Fn}], the result represents "letrec V1 = F1 ...
646 Vn = Fn in Body. All the Vi must have type var and represent
647 function names. All the Fi must have type 'fun'.
648 See also: ann_c_letrec/3, is_c_letrec/1, letrec_body/1, le‐
650 trec_defs/1, letrec_vars/1, update_c_letrec/3.
651 c_map(Pairs::[c_map_pair()]) -> c_map()
653 c_map_pair(Key::cerl(), Val::cerl()) -> c_map_pair()
655 c_map_pair_exact(Key::cerl(), Val::cerl()) -> c_map_pair()
657 c_map_pattern(Pairs::[c_map_pair()]) -> c_map()
659 c_module(Name::cerl(), Exports, Es::Definitions) -> cerl()
661 Types:
663 Exports = [cerl()]
665 Definitions = [{cerl(), cerl()}]
666 Equivalent to c_module(Name, Exports, [], Definitions).
668 c_module(Name::cerl(), Exports, Attrs::Attributes, Es::Definitions) ->
670 cerl()
671 Types:
673 Exports = [cerl()]
675 Attributes = [{cerl(), cerl()}]
676 Definitions = [{cerl(), cerl()}]
677 Creates an abstract module definition. The result represents
679 module Name [E1, ..., Ek]
681 attributes [K1 = T1, ...,
682 Km = Tm]
683 V1 = F1
684 ...
685 Vn = Fn
686 end
687 if Exports = [E1, ..., Ek], Attributes = [{K1, T1}, ..., {Km,
689 Tm}], and Definitions = [{V1, F1}, ..., {Vn, Fn}].
690 Name and all the Ki must be atom literals, and all the Ti must
692 be constant literals. All the Vi and Ei must have type var and
693 represent function names. All the Fi must have type 'fun'.
694 See also: ann_c_module/4, ann_c_module/5, c_atom/1, c_fun/2,
696 c_module/3, c_var/1, is_literal/1, module_attrs/1, mod‐
697 ule_defs/1, module_exports/1, module_name/1, module_vars/1, up‐
698 date_c_module/5.
699 c_nil() -> cerl()
701 Creates an abstract empty list. The result represents "[]". The
703 empty list is traditionally called "nil".
704 See also: ann_c_nil/1, c_cons/2, is_c_list/1.
706 c_primop(Name::cerl(), Arguments::[cerl()]) -> cerl()
708 Creates an abstract primitive operation call. If Arguments is
710 [A1, ..., An], the result represents "primop Name(A1, ..., An)".
711 Name must be an atom literal.
712 See also: ann_c_primop/3, c_apply/2, c_call/3, is_c_primop/1,
714 primop_args/1, primop_arity/1, primop_name/1, update_c_primop/3.
715 c_receive(Clauses::[cerl()]) -> cerl()
717 Equivalent to c_receive(Clauses, c_atom(infinity),
719 c_atom(true)).
720 See also: c_atom/1.
722 c_receive(Clauses::[cerl()], Timeout::cerl(), Action::cerl()) -> cerl()
724 Creates an abstract receive-expression. If Clauses is [C1, ...,
726 Cn], the result represents "receive C1 ... Cn after Timeout ->
727 Action end".
728 See also: ann_c_receive/4, c_receive/1, is_c_receive/1, re‐
730 ceive_action/1, receive_clauses/1, receive_timeout/1, up‐
731 date_c_receive/4.
732 c_seq(Argument::cerl(), Body::cerl()) -> cerl()
734 Creates an abstract sequencing expression. The result represents
736 "do Argument Body".
737 See also: ann_c_seq/3, is_c_seq/1, seq_arg/1, seq_body/1, up‐
739 date_c_seq/3.
740 c_string(Value::string()) -> cerl()
742 Creates an abstract string literal. Equivalent to creating an
744 abstract list of the corresponding character literals (cf.
745 is_c_string/1), but is typically more efficient. The lexical
746 representation of a string is ""Chars"", where Chars is a se‐
747 quence of printing characters or spaces.
748 See also: ann_c_string/2, c_char/1, is_c_string/1,
750 is_print_string/1, string_lit/1, string_val/1.
751 c_try(Argument::cerl(), Variables::[cerl()], Body::cerl(), Exception‐
753 Vars::[cerl()], Handler::cerl()) -> cerl()
754 Creates an abstract try-expression. If Variables is [V1, ...,
756 Vn] and ExceptionVars is [X1, ..., Xm], the result represents
757 "try Argument of <V1, ..., Vn> -> Body catch <X1, ..., Xm> ->
758 Handler". All the Vi and Xi must have type var.
759 See also: ann_c_try/6, c_catch/1, is_c_try/1, try_arg/1,
761 try_body/1, try_vars/1, update_c_try/6.
762 c_tuple(Elements::[cerl()]) -> cerl()
764 Creates an abstract tuple. If Elements is [E1, ..., En], the re‐
766 sult represents "{E1, ..., En}". Note that if all nodes in Ele‐
767 ments have type literal, or if Elements is empty, then the re‐
768 sult will also have type literal and annotations on nodes in El‐
769 ements are lost.
770 Recall that Erlang has distinct 1-tuples, i.e., {X} is always
772 distinct from X itself.
773 See also: ann_c_tuple/2, c_tuple_skel/1, is_c_tuple/1, tuple_ar‐
775 ity/1, tuple_es/1, update_c_tuple/2.
776 c_tuple_skel(Elements::[cerl()]) -> cerl()
778 Creates an abstract tuple skeleton. Does not fold constant lit‐
780 erals, i.e., the result always has type tuple, representing
781 "{E1, ..., En}", if Elements is [E1, ..., En].
782 This function is occasionally useful when it is necessary to
784 have annotations on the subnodes of a tuple node, even when all
785 the subnodes are constant literals. Note however that is_lit‐
786 eral/1 will yield false and concrete/1 will fail if passed the
787 result from this function.
788 fold_literal/1 can be used to revert a node to the normal-form
790 representation.
791 See also: ann_c_tuple_skel/2, c_tuple/1, concrete/1, fold_lit‐
793 eral/1, is_c_tuple/1, is_literal/1, tuple_es/1, update_c_tu‐
794 ple_skel/2.
795 c_values(Elements::[cerl()]) -> cerl()
797 Creates an abstract value list. If Elements is [E1, ..., En],
799 the result represents "<E1, ..., En>".
800 See also: ann_c_values/2, is_c_values/1, update_c_values/2, val‐
802 ues_arity/1, values_es/1.
803 c_var(Name::var_name()) -> cerl()
805 Types:
807 var_name() = integer() | atom() | {atom(), integer()}
809 Creates an abstract variable. A variable is identified by its
811 name, given by the Name parameter.
812 If a name is given by a single atom, it should either be a "sim‐
814 ple" atom which does not need to be single-quoted in Erlang, or
815 otherwise its print name should correspond to a proper Erlang
816 variable, i.e., begin with an uppercase character or an under‐
817 score. Names on the form {A, N} represent function name vari‐
818 ables "A/N"; these are special variables which may be bound only
819 in the function definitions of a module or a letrec. They may
820 not be bound in let expressions and cannot occur in clause pat‐
821 terns. The atom A in a function name may be any atom; the inte‐
822 ger N must be nonnegative. The functions c_fname/2 etc. are
823 utilities for handling function name variables.
824 When printing variable names, they must have the form of proper
826 Core Erlang variables and function names. E.g., a name repre‐
827 sented by an integer such as 42 could be formatted as "_42", an
828 atom 'Xxx' simply as "Xxx", and an atom foo as "_foo". However,
829 one must assure that any two valid distinct names are never
830 mapped to the same strings. Tuples such as {foo, 2} representing
831 function names can simply by formatted as "'foo'/2", with no
832 risk of conflicts.
833 See also: ann_c_var/2, c_fname/2, c_letrec/2, c_module/4,
835 is_c_var/1, update_c_var/2, var_name/1.
836 call_args(Node::cerl()) -> [cerl()]
838 Returns the list of argument subtrees of an abstract inter-mod‐
840 ule call.
841 See also: c_call/3, call_arity/1.
843 call_arity(Node::cerl()) -> arity()
845 Returns the number of argument subtrees of an abstract inter-
847 module call.
848 Note: this is equivalent to length(call_args(Node)), but poten‐
850 tially more efficient.
851 See also: c_call/3, call_args/1.
853 call_module(Node::cerl()) -> cerl()
855 Returns the module subtree of an abstract inter-module call.
857 See also: c_call/3.
859 call_name(Node::cerl()) -> cerl()
861 Returns the name subtree of an abstract inter-module call.
863 See also: c_call/3.
865 case_arg(Node::cerl()) -> cerl()
867 Returns the argument subtree of an abstract case-expression.
869 See also: c_case/2.
871 case_arity(Node::cerl()) -> integer()
873 Equivalent to clause_arity(hd(case_clauses(Node))), but poten‐
875 tially more efficient.
876 See also: c_case/2, case_clauses/1, clause_arity/1.
878 case_clauses(Node::cerl()) -> [cerl()]
880 Returns the list of clause subtrees of an abstract case-expres‐
882 sion.
883 See also: c_case/2, case_arity/1.
885 catch_body(Node::cerl()) -> cerl()
887 Returns the body subtree of an abstract catch-expression.
889 See also: c_catch/1.
891 char_lit(Node::cerl()) -> string()
893 Returns the literal string represented by an abstract character.
895 This includes a leading $ character. Currently, all characters
896 that are not in the set of ISO 8859-1 (Latin-1) "printing" char‐
897 acters will be escaped.
898 See also: c_char/1.
900 char_val(Node::cerl()) -> char()
902 Returns the value represented by an abstract character literal.
904 See also: c_char/1.
906 clause_arity(Node::cerl()) -> integer()
908 Returns the number of pattern subtrees of an abstract clause.
910 Note: this is equivalent to length(clause_pats(Node)), but po‐
912 tentially more efficient.
913 See also: c_clause/3, clause_pats/1.
915 clause_body(Node::cerl()) -> cerl()
917 Returns the body subtree of an abstract clause.
919 See also: c_clause/3.
921 clause_guard(Node::cerl()) -> cerl()
923 Returns the guard subtree of an abstract clause.
925 See also: c_clause/3.
927 clause_pats(Node::cerl()) -> [cerl()]
929 Returns the list of pattern subtrees of an abstract clause.
931 See also: c_clause/3, clause_arity/1.
933 clause_vars(Clause::cerl()) -> [cerl()]
935 Returns the list of all abstract variables in the patterns of an
937 abstract clause. The order of listing is not defined.
938 See also: c_clause/3, pat_list_vars/1.
940 concrete(Node::cerl()) -> term()
942 Returns the Erlang term represented by a syntax tree. An excep‐
944 tion is thrown if Node does not represent a literal term.
945 Note: This is a constant time operation.
947 See also: abstract/1, is_literal/1.
949 cons_hd(C_cons::cerl()) -> cerl()
951 Returns the head subtree of an abstract list constructor.
953 See also: c_cons/2.
955 cons_tl(C_cons::cerl()) -> cerl()
957 Returns the tail subtree of an abstract list constructor.
959 Recall that the tail does not necessarily represent a proper
961 list.
962 See also: c_cons/2.
964 copy_ann(Source::cerl(), Target::cerl()) -> cerl()
966 Copies the list of user annotations from Source to Target.
968 Note: this is equivalent to set_ann(Target, get_ann(Source)),
970 but potentially more efficient.
971 See also: get_ann/1, set_ann/2.
973 data_arity(Node::cerl()) -> integer()
975 Returns the number of subtrees of a data constructor node. This
977 is equivalent to length(data_es(Node)), but potentially more ef‐
978 ficient.
979 See also: data_es/1, is_data/1.
981 data_es(Node::cerl()) -> [cerl()]
983 Returns the list of subtrees of a data constructor node. If the
985 arity of the constructor is zero, the result is the empty list.
986 Note: if data_type(Node) is cons, the number of subtrees is ex‐
988 actly two. If data_type(Node) is {atomic, Value}, the number of
989 subtrees is zero.
990 See also: data_arity/1, data_type/1, is_data/1, make_data/2.
992 data_type(Node::cerl()) -> dtype()
994 Types:
996 dtype() = cons | tuple | {atomic, Value}
998 Value = integer() | float() | atom() | []
999 Returns a type descriptor for a data constructor node. (Cf.
1001 is_data/1.) This is mainly useful for comparing types and for
1002 constructing new nodes of the same type (cf. make_data/2). If
1003 Node represents an integer, floating-point number, atom or empty
1004 list, the result is {atomic, Value}, where Value is the value of
1005 concrete(Node), otherwise the result is either cons or tuple.
1006 Type descriptors can be compared for equality or order (in the
1008 Erlang term order), but remember that floating-point values
1009 should in general never be tested for equality.
1010 See also: concrete/1, is_data/1, make_data/2, type/1.
1012 float_lit(Node::cerl()) -> string()
1014 Returns the numeral string represented by a floating-point lit‐
1016 eral node.
1017 See also: c_float/1.
1019 float_val(Node::cerl()) -> float()
1021 Returns the value represented by a floating-point literal node.
1023 See also: c_float/1.
1025 fname_arity(C_var::cerl()) -> arity()
1027 Returns the arity part of an abstract function name variable.
1029 See also: c_fname/2, fname_id/1.
1031 fname_id(C_var::cerl()) -> atom()
1033 Returns the identifier part of an abstract function name vari‐
1035 able.
1036 See also: c_fname/2, fname_arity/1.
1038 fold_literal(Node::cerl()) -> cerl()
1040 Assures that literals have a compact representation. This is oc‐
1042 casionally useful if c_cons_skel/2, c_tuple_skel/1 or un‐
1043 fold_literal/1 were used in the construction of Node, and you
1044 want to revert to the normal "folded" representation of liter‐
1045 als. If Node represents a tuple or list constructor, its ele‐
1046 ments are rewritten recursively, and the node is reconstructed
1047 using c_cons/2 or c_tuple/1, respectively; otherwise, Node is
1048 not changed.
1049 See also: c_cons/2, c_cons_skel/2, c_tuple/1, c_tuple_skel/1,
1051 is_literal/1, unfold_literal/1.
1052 from_records(Tree::record(record_types())) -> cerl()
1054 Types:
1056 record_types() = c_alias | c_apply | c_call | c_case |
1058 c_catch | c_clause | c_cons | c_fun | c_let | c_letrec |
1059 c_lit | c_module | c_primop | c_receive | c_seq | c_try |
1060 c_tuple | c_values | c_var
1061 Translates an explicit record representation to a corresponding
1063 abstract syntax tree. The records are defined in the file
1064 "core_parse.hrl".
1065 See also: to_records/1, type/1.
1067 fun_arity(Node::cerl()) -> arity()
1069 Returns the number of parameter subtrees of an abstract fun-ex‐
1071 pression.
1072 Note: this is equivalent to length(fun_vars(Node)), but poten‐
1074 tially more efficient.
1075 See also: c_fun/2, fun_vars/1.
1077 fun_body(Node::cerl()) -> cerl()
1079 Returns the body subtree of an abstract fun-expression.
1081 See also: c_fun/2.
1083 fun_vars(Node::cerl()) -> [cerl()]
1085 Returns the list of parameter subtrees of an abstract fun-ex‐
1087 pression.
1088 See also: c_fun/2, fun_arity/1.
1090 get_ann(Node::cerl()) -> [term()]
1092 Returns the list of user annotations associated with a syntax
1094 tree node. For a newly created node, this is the empty list. The
1095 annotations may be any terms.
1096 See also: set_ann/2.
1098 int_lit(Node::cerl()) -> string()
1100 Returns the numeral string represented by an integer literal
1102 node.
1103 See also: c_int/1.
1105 int_val(Node::cerl()) -> integer()
1107 Returns the value represented by an integer literal node.
1109 See also: c_int/1.
1111 is_c_alias(Node::cerl()) -> boolean()
1113 Returns true if Node is an abstract pattern alias, otherwise
1115 false.
1116 See also: c_alias/2.
1118 is_c_apply(Node::cerl()) -> boolean()
1120 Returns true if Node is an abstract function application, other‐
1122 wise false.
1123 See also: c_apply/2.
1125 is_c_atom(Node::cerl()) -> boolean()
1127 Returns true if Node represents an atom literal, otherwise
1129 false.
1130 See also: c_atom/1.
1132 is_c_binary(Node::cerl()) -> boolean()
1134 Returns true if Node is an abstract binary-template; otherwise
1136 false.
1137 See also: c_binary/1.
1139 is_c_bitstr(Node::cerl()) -> boolean()
1141 Returns true if Node is an abstract bit-string template; other‐
1143 wise false.
1144 See also: c_bitstr/5.
1146 is_c_call(Node::cerl()) -> boolean()
1148 Returns true if Node is an abstract inter-module call expres‐
1150 sion; otherwise false.
1151 See also: c_call/3.
1153 is_c_case(C_case::cerl()) -> boolean()
1155 Returns true if Node is an abstract case-expression; otherwise
1157 false.
1158 See also: c_case/2.
1160 is_c_catch(Node::cerl()) -> boolean()
1162 Returns true if Node is an abstract catch-expression, otherwise
1164 false.
1165 See also: c_catch/1.
1167 is_c_char(Node::cerl()) -> boolean()
1169 Returns true if Node may represent a character literal, other‐
1171 wise false.
1172 If the local implementation of Erlang defines char() as a subset
1174 of integer(), then is_c_int(Node) will also yield true.
1175 See also: c_char/1, is_print_char/1.
1177 is_c_clause(Node::cerl()) -> boolean()
1179 Returns true if Node is an abstract clause, otherwise false.
1181 See also: c_clause/3.
1183 is_c_cons(Node::cerl()) -> boolean()
1185 Returns true if Node is an abstract list constructor, otherwise
1187 false.
1188 is_c_float(Node::cerl()) -> boolean()
1190 Returns true if Node represents a floating-point literal, other‐
1192 wise false.
1193 See also: c_float/1.
1195 is_c_fname(Node::cerl()) -> boolean()
1197 Returns true if Node is an abstract function name variable, oth‐
1199 erwise false.
1200 See also: c_fname/2, c_var/1, var_name/1.
1202 is_c_fun(Node::cerl()) -> boolean()
1204 Returns true if Node is an abstract fun-expression, otherwise
1206 false.
1207 See also: c_fun/2.
1209 is_c_int(Node::cerl()) -> boolean()
1211 Returns true if Node represents an integer literal, otherwise
1213 false.
1214 See also: c_int/1.
1216 is_c_let(Node::cerl()) -> boolean()
1218 Returns true if Node is an abstract let-expression, otherwise
1220 false.
1221 See also: c_let/3.
1223 is_c_letrec(Node::cerl()) -> boolean()
1225 Returns true if Node is an abstract letrec-expression, otherwise
1227 false.
1228 See also: c_letrec/2.
1230 is_c_list(Node::cerl()) -> boolean()
1232 Returns true if Node represents a proper list, otherwise false.
1234 A proper list is either the empty list [], or a cons cell [Head
1235 | Tail], where recursively Tail is a proper list.
1236 Note: Because Node is a syntax tree, the actual run-time values
1238 corresponding to its subtrees may often be partially or com‐
1239 pletely unknown. Thus, if Node represents e.g. "[... | Ns]"
1240 (where Ns is a variable), then the function will return false,
1241 because it is not known whether Ns will be bound to a list at
1242 run-time. If Node instead represents e.g. "[1, 2, 3]" or "[A |
1243 []]", then the function will return true.
1244 See also: c_cons/2, c_nil/0, list_elements/1, list_length/1.
1246 is_c_map(Node::cerl()) -> boolean()
1248 Returns true if Node is an abstract map constructor, otherwise
1250 false.
1251 is_c_map_empty(C_map::c_map() | c_literal()) -> boolean()
1253 is_c_map_pattern(C_map::c_map()) -> boolean()
1255 is_c_module(Node::cerl()) -> boolean()
1257 Returns true if Node is an abstract module definition, otherwise
1259 false.
1260 See also: type/1.
1262 is_c_nil(Node::cerl()) -> boolean()
1264 Returns true if Node is an abstract empty list, otherwise false.
1266 is_c_primop(Node::cerl()) -> boolean()
1268 Returns true if Node is an abstract primitive operation call,
1270 otherwise false.
1271 See also: c_primop/2.
1273 is_c_receive(Node::cerl()) -> boolean()
1275 Returns true if Node is an abstract receive-expression, other‐
1277 wise false.
1278 See also: c_receive/3.
1280 is_c_seq(Node::cerl()) -> boolean()
1282 Returns true if Node is an abstract sequencing expression, oth‐
1284 erwise false.
1285 See also: c_seq/2.
1287 is_c_string(Node::cerl()) -> boolean()
1289 Returns true if Node may represent a string literal, otherwise
1291 false. Strings are defined as lists of characters; see
1292 is_c_char/1 for details.
1293 See also: c_string/1, is_c_char/1, is_print_string/1.
1295 is_c_try(Node::cerl()) -> boolean()
1297 Returns true if Node is an abstract try-expression, otherwise
1299 false.
1300 See also: c_try/5.
1302 is_c_tuple(Node::cerl()) -> boolean()
1304 Returns true if Node is an abstract tuple, otherwise false.
1306 See also: c_tuple/1.
1308 is_c_values(Node::cerl()) -> boolean()
1310 Returns true if Node is an abstract value list; otherwise false.
1312 See also: c_values/1.
1314 is_c_var(Node::cerl()) -> boolean()
1316 Returns true if Node is an abstract variable, otherwise false.
1318 See also: c_var/1.
1320 is_data(Node::cerl()) -> boolean()
1322 Returns true if Node represents a data constructor, otherwise
1324 false. Data constructors are cons cells, tuples, and atomic lit‐
1325 erals.
1326 See also: data_arity/1, data_es/1, data_type/1.
1328 is_leaf(Node::cerl()) -> boolean()
1330 Returns true if Node is a leaf node, otherwise false. The cur‐
1332 rent leaf node types are literal and var.
1333 Note: all literals (cf. is_literal/1) are leaf nodes, even if
1335 they represent structured (constant) values such as {foo, [bar,
1336 baz]}. Also note that variables are leaf nodes but not literals.
1337 See also: is_literal/1, type/1.
1339 is_literal(Node::cerl()) -> boolean()
1341 Returns true if Node represents a literal term, otherwise false.
1343 This function returns true if and only if the value of con‐
1344 crete(Node) is defined.
1345 Note: This is a constant time operation.
1347 See also: abstract/1, concrete/1, fold_literal/1.
1349 is_literal_term(Term::term()) -> boolean()
1351 Returns true if Term can be represented as a literal, otherwise
1353 false. This function takes time proportional to the size of
1354 Term.
1355 See also: abstract/1.
1357 is_print_char(Node::cerl()) -> boolean()
1359 Returns true if Node may represent a "printing" character, oth‐
1361 erwise false. (Cf. is_c_char/1.) A "printing" character has ei‐
1362 ther a given graphical representation, or a "named" escape se‐
1363 quence such as "\n". Currently, only ISO 8859-1 (Latin-1) char‐
1364 acter values are recognized.
1365 See also: c_char/1, is_c_char/1.
1367 is_print_string(Node::cerl()) -> boolean()
1369 Returns true if Node may represent a string literal containing
1371 only "printing" characters, otherwise false. See is_c_string/1
1372 and is_print_char/1 for details. Currently, only ISO 8859-1
1373 (Latin-1) character values are recognized.
1374 See also: c_string/1, is_c_string/1, is_print_char/1.
1376 let_arg(Node::cerl()) -> cerl()
1378 Returns the argument subtree of an abstract let-expression.
1380 See also: c_let/3.
1382 let_arity(Node::cerl()) -> integer()
1384 Returns the number of left-hand side variables of an abstract
1386 let-expression.
1387 Note: this is equivalent to length(let_vars(Node)), but poten‐
1389 tially more efficient.
1390 See also: c_let/3, let_vars/1.
1392 let_body(Node::cerl()) -> cerl()
1394 Returns the body subtree of an abstract let-expression.
1396 See also: c_let/3.
1398 let_vars(Node::cerl()) -> [cerl()]
1400 Returns the list of left-hand side variables of an abstract let-
1402 expression.
1403 See also: c_let/3, let_arity/1.
1405 letrec_body(Node::cerl()) -> cerl()
1407 Returns the body subtree of an abstract letrec-expression.
1409 See also: c_letrec/2.
1411 letrec_defs(Node::cerl()) -> [{cerl(), cerl()}]
1413 Returns the list of definitions of an abstract letrec-expres‐
1415 sion. If Node represents "letrec V1 = F1 ... Vn = Fn in Body",
1416 the returned value is [{V1, F1}, ..., {Vn, Fn}].
1417 See also: c_letrec/2.
1419 letrec_vars(Node::cerl()) -> [cerl()]
1421 Returns the list of left-hand side function variable subtrees of
1423 a letrec-expression. If Node represents "letrec V1 = F1 ... Vn =
1424 Fn in Body", the returned value is [V1, ..., Vn].
1425 See also: c_letrec/2.
1427 list_elements(C_cons::cerl()) -> [cerl()]
1429 Returns the list of element subtrees of an abstract list. Node
1431 must represent a proper list. E.g., if Node represents "[X1, X2
1432 | [X3, X4 | []]", then list_elements(Node) yields the list [X1,
1433 X2, X3, X4].
1434 See also: c_cons/2, c_nil/0, is_c_list/1, list_length/1,
1436 make_list/2.
1437 list_length(Node::cerl()) -> integer()
1439 Returns the number of element subtrees of an abstract list. Node
1441 must represent a proper list. E.g., if Node represents "[X1 |
1442 [X2, X3 | [X4, X5, X6]]]", then list_length(Node) returns the
1443 integer 6.
1444 Note: this is equivalent to length(list_elements(Node)), but po‐
1446 tentially more efficient.
1447 See also: c_cons/2, c_nil/0, is_c_list/1, list_elements/1.
1449 make_data(Type::dtype(), Elements::[cerl()]) -> cerl()
1451 Creates a data constructor node with the specified type and sub‐
1453 trees. (Cf. data_type/1.) An exception is thrown if the length
1454 of Elements is invalid for the given Type; see data_es/1 for ar‐
1455 ity constraints on constructor types.
1456 See also: ann_make_data/3, data_es/1, data_type/1,
1458 make_data_skel/2, update_data/3.
1459 make_data_skel(Type::dtype(), Elements::[cerl()]) -> cerl()
1461 Like make_data/2, but analogous to c_tuple_skel/1 and
1463 c_cons_skel/2.
1464 See also: ann_make_data_skel/3, c_cons_skel/2, c_tuple_skel/1,
1466 make_data/2, update_data_skel/3.
1467 make_list(List) -> Node
1469 Equivalent to make_list(List, none).
1471 make_list(List::[cerl()], Tail) -> cerl()
1473 Types:
1475 Tail = cerl() | none
1477 Creates an abstract list from the elements in List and the op‐
1479 tional Tail. If Tail is none, the result will represent a nil-
1480 terminated list, otherwise it represents "[... | Tail]".
1481 See also: ann_make_list/3, c_cons/2, c_nil/0, list_elements/1,
1483 update_list/3.
1484 make_tree(Type::ctype(), Groups::[[cerl()]]) -> cerl()
1486 Creates a syntax tree with the given type and subtrees. Type
1488 must be a node type name (cf. type/1) that does not denote a
1489 leaf node type (cf. is_leaf/1). Groups must be a nonempty list
1490 of groups of syntax trees, representing the subtrees of a node
1491 of the given type, in left-to-right order as they would occur in
1492 the printed program text, grouped by category as done by sub‐
1493 trees/1.
1494 The result of ann_make_tree(get_ann(Node), type(Node), sub‐
1496 trees(Node)) (cf. update_tree/2) represents the same source code
1497 text as the original Node, assuming that subtrees(Node) yields a
1498 nonempty list. However, it does not necessarily have the exact
1499 same data representation as Node.
1500 See also: ann_make_tree/3, is_leaf/1, subtrees/1, type/1, up‐
1502 date_tree/2.
1503 map_arg(C_literal::c_map() | c_literal()) -> c_map() | c_literal()
1505 map_es(C_literal::c_map() | c_literal()) -> [c_map_pair()]
1507 map_pair_key(C_map_pair::c_map_pair()) -> cerl()
1509 map_pair_op(C_map_pair::c_map_pair()) -> map_op()
1511 map_pair_val(C_map_pair::c_map_pair()) -> cerl()
1513 meta(Tree::cerl()) -> cerl()
1515 Creates a meta-representation of a syntax tree. The result rep‐
1517 resents an Erlang expression "MetaTree" which, if evaluated,
1518 will yield a new syntax tree representing the same source code
1519 text as Tree (although the actual data representation may be
1520 different). The expression represented by MetaTree is implemen‐
1521 tation independent with regard to the data structures used by
1522 the abstract syntax tree implementation.
1523 Any node in Tree whose node type is var (cf. type/1), and whose
1525 list of annotations (cf. get_ann/1) contains the atom meta_var,
1526 will remain unchanged in the resulting tree, except that exactly
1527 one occurrence of meta_var is removed from its annotation list.
1528 The main use of the function meta/1 is to transform a data
1530 structure Tree, which represents a piece of program code, into a
1531 form that is representation independent when printed. E.g., sup‐
1532 pose Tree represents a variable named "V". Then (assuming a
1533 function print/1 for printing syntax trees), evaluating
1534 print(abstract(Tree)) - simply using abstract/1 to map the ac‐
1535 tual data structure onto a syntax tree representation - would
1536 output a string that might look something like "{var, ...,
1537 'V'}", which is obviously dependent on the implementation of the
1538 abstract syntax trees. This could e.g. be useful for caching a
1539 syntax tree in a file. However, in some situations like in a
1540 program generator generator (with two "generator"), it may be
1541 unacceptable. Using print(meta(Tree)) instead would output a
1542 representation independent syntax tree generating expression; in
1543 the above case, something like "cerl:c_var('V')".
1544 The implementation tries to generate compact code with respect
1546 to literals and lists.
1547 See also: abstract/1, get_ann/1, type/1.
1549 module_attrs(Node::cerl()) -> [{cerl(), cerl()}]
1551 Returns the list of pairs of attribute key/value subtrees of an
1553 abstract module definition.
1554 See also: c_module/4.
1556 module_defs(Node::cerl()) -> [{cerl(), cerl()}]
1558 Returns the list of function definitions of an abstract module
1560 definition.
1561 See also: c_module/4.
1563 module_exports(Node::cerl()) -> [cerl()]
1565 Returns the list of exports subtrees of an abstract module defi‐
1567 nition.
1568 See also: c_module/4.
1570 module_name(Node::cerl()) -> cerl()
1572 Returns the name subtree of an abstract module definition.
1574 See also: c_module/4.
1576 module_vars(Node::cerl()) -> [cerl()]
1578 Returns the list of left-hand side function variable subtrees of
1580 an abstract module definition.
1581 See also: c_module/4.
1583 pat_list_vars(Patterns::[cerl()]) -> [cerl()]
1585 Returns the list of all abstract variables in the given pat‐
1587 terns. An exception is thrown if some element in Patterns does
1588 not represent a well-formed Core Erlang clause pattern. The or‐
1589 der of listing is not defined.
1590 See also: clause_vars/1, pat_vars/1.
1592 pat_vars(Pattern::cerl()) -> [cerl()]
1594 Returns the list of all abstract variables in a pattern. An ex‐
1596 ception is thrown if Node does not represent a well-formed Core
1597 Erlang clause pattern. The order of listing is not defined.
1598 See also: clause_vars/1, pat_list_vars/1.
1600 primop_args(Node::cerl()) -> [cerl()]
1602 Returns the list of argument subtrees of an abstract primitive
1604 operation call.
1605 See also: c_primop/2, primop_arity/1.
1607 primop_arity(Node::cerl()) -> arity()
1609 Returns the number of argument subtrees of an abstract primitive
1611 operation call.
1612 Note: this is equivalent to length(primop_args(Node)), but po‐
1614 tentially more efficient.
1615 See also: c_primop/2, primop_args/1.
1617 primop_name(Node::cerl()) -> cerl()
1619 Returns the name subtree of an abstract primitive operation
1621 call.
1622 See also: c_primop/2.
1624 receive_action(Node::cerl()) -> cerl()
1626 Returns the action subtree of an abstract receive-expression.
1628 See also: c_receive/3.
1630 receive_clauses(Node::cerl()) -> [cerl()]
1632 Returns the list of clause subtrees of an abstract receive-ex‐
1634 pression.
1635 See also: c_receive/3.
1637 receive_timeout(Node::cerl()) -> cerl()
1639 Returns the timeout subtree of an abstract receive-expression.
1641 See also: c_receive/3.
1643 seq_arg(Node::cerl()) -> cerl()
1645 Returns the argument subtree of an abstract sequencing expres‐
1647 sion.
1648 See also: c_seq/2.
1650 seq_body(Node::cerl()) -> cerl()
1652 Returns the body subtree of an abstract sequencing expression.
1654 See also: c_seq/2.
1656 set_ann(Node::cerl(), Annotations::[term()]) -> cerl()
1658 Sets the list of user annotations of Node to Annotations.
1660 See also: add_ann/2, copy_ann/2, get_ann/1.
1662 string_lit(Node::cerl()) -> string()
1664 Returns the literal string represented by an abstract string.
1666 This includes surrounding double-quote characters "...". Cur‐
1667 rently, characters that are not in the set of ISO 8859-1
1668 (Latin-1) "printing" characters will be escaped, except for spa‐
1669 ces.
1670 See also: c_string/1.
1672 string_val(Node::cerl()) -> string()
1674 Returns the value represented by an abstract string literal.
1676 See also: c_string/1.
1678 subtrees(Node::cerl()) -> [[cerl()]]
1680 Returns the grouped list of all subtrees of a node. If Node is a
1682 leaf node (cf. is_leaf/1), this is the empty list, otherwise the
1683 result is always a nonempty list, containing the lists of sub‐
1684 trees of Node, in left-to-right order as they occur in the
1685 printed program text, and grouped by category. Often, each group
1686 contains only a single subtree.
1687 Depending on the type of Node, the size of some groups may be
1689 variable (e.g., the group consisting of all the elements of a
1690 tuple), while others always contain the same number of elements
1691 - usually exactly one (e.g., the group containing the argument
1692 expression of a case-expression). Note, however, that the exact
1693 structure of the returned list (for a given node type) should in
1694 general not be depended upon, since it might be subject to
1695 change without notice.
1696 The function subtrees/1 and the constructor functions
1698 make_tree/2 and update_tree/2 can be a great help if one wants
1699 to traverse a syntax tree, visiting all its subtrees, but treat
1700 nodes of the tree in a uniform way in most or all cases. Using
1701 these functions makes this simple, and also assures that your
1702 code is not overly sensitive to extensions of the syntax tree
1703 data type, because any node types not explicitly handled by your
1704 code can be left to a default case.
1705 For example:
1707 postorder(F, Tree) ->
1709 F(case subtrees(Tree) of
1710 [] -> Tree;
1711 List -> update_tree(Tree,
1712 [[postorder(F, Subtree)
1713 || Subtree <- Group]
1714 || Group <- List])
1715 end).
1716 maps the function F on Tree and all its subtrees, doing a post-
1719 order traversal of the syntax tree. (Note the use of up‐
1720 date_tree/2 to preserve annotations.) For a simple function
1721 like:
1722 f(Node) ->
1724 case type(Node) of
1725 atom -> atom("a_" ++ atom_name(Node));
1726 _ -> Node
1727 end.
1728 the call postorder(fun f/1, Tree) will yield a new representa‐
1731 tion of Tree in which all atom names have been extended with the
1732 prefix "a_", but nothing else (including annotations) has been
1733 changed.
1734 See also: is_leaf/1, make_tree/2, update_tree/2.
1736 to_records(Tree::cerl()) -> record(record_types())
1738 Translates an abstract syntax tree to a corresponding explicit
1740 record representation. The records are defined in the file
1741 "cerl.hrl".
1742 See also: from_records/1, type/1.
1744 try_arg(Node::cerl()) -> cerl()
1746 Returns the expression subtree of an abstract try-expression.
1748 See also: c_try/5.
1750 try_body(Node::cerl()) -> cerl()
1752 Returns the success body subtree of an abstract try-expression.
1754 See also: c_try/5.
1756 try_evars(Node::cerl()) -> [cerl()]
1758 Returns the list of exception variable subtrees of an abstract
1760 try-expression.
1761 See also: c_try/5.
1763 try_handler(Node::cerl()) -> cerl()
1765 Returns the exception body subtree of an abstract try-expres‐
1767 sion.
1768 See also: c_try/5.
1770 try_vars(Node::cerl()) -> [cerl()]
1772 Returns the list of success variable subtrees of an abstract
1774 try-expression.
1775 See also: c_try/5.
1777 tuple_arity(Node::cerl()) -> integer()
1779 Returns the number of element subtrees of an abstract tuple.
1781 Note: this is equivalent to length(tuple_es(Node)), but poten‐
1783 tially more efficient.
1784 See also: c_tuple/1, tuple_es/1.
1786 tuple_es(C_tuple::cerl()) -> [cerl()]
1788 Returns the list of element subtrees of an abstract tuple.
1790 See also: c_tuple/1.
1792 type(Node::cerl()) -> atom()
1794 Returns the type tag of Node. Current node types are:
1796 alias apply binary bitstr call case catch clause
1798 cons fun let letrec literal map map_pair module
1799 primop receive seq try tuple values var
1800 Note: The name of the primary constructor function for a node
1803 type is always the name of the type itself, prefixed by "c_";
1804 recognizer predicates are correspondingly prefixed by "is_c_".
1805 Furthermore, to simplify preservation of annotations (cf.
1806 get_ann/1), there are analogous constructor functions prefixed
1807 by "ann_c_" and "update_c_", for setting the annotation list of
1808 the new node to either a specific value or to the annotations of
1809 an existing node, respectively.
1810 See also: abstract/1, c_alias/2, c_apply/2, c_binary/1, c_bit‐
1812 str/5, c_call/3, c_case/2, c_catch/1, c_clause/3, c_cons/2,
1813 c_fun/2, c_let/3, c_letrec/2, c_module/3, c_primop/2, c_re‐
1814 ceive/1, c_seq/2, c_try/5, c_tuple/1, c_values/1, c_var/1,
1815 data_type/1, from_records/1, get_ann/1, meta/1, subtrees/1,
1816 to_records/1.
1817 unfold_literal(Node::cerl()) -> cerl()
1819 Assures that literals have a fully expanded representation. If
1821 Node represents a literal tuple or list constructor, its ele‐
1822 ments are rewritten recursively, and the node is reconstructed
1823 using c_cons_skel/2 or c_tuple_skel/1, respectively; otherwise,
1824 Node is not changed. The fold_literal/1 can be used to revert to
1825 the normal compact representation.
1826 See also: c_cons/2, c_cons_skel/2, c_tuple/1, c_tuple_skel/1,
1828 fold_literal/1, is_literal/1.
1829 update_c_alias(Old::cerl(), Variable::cerl(), Pattern::cerl()) ->
1831 cerl()
1832 See also: c_alias/2.
1834 update_c_apply(Old::cerl(), Operator::cerl(), Arguments::[cerl()]) ->
1836 cerl()
1837 See also: c_apply/2.
1839 update_c_binary(Old::cerl(), Segments::[cerl()]) -> cerl()
1841 See also: c_binary/1.
1843 update_c_bitstr(Old::cerl(), Value::cerl(), Size::cerl(), Type::cerl(),
1845 Flags::cerl()) -> cerl()
1846 Equivalent to update_c_bitstr(Node, Value, Size, abstract(1),
1848 Type, Flags).
1849 update_c_bitstr(Old::cerl(), Value::cerl(), Size::cerl(), Unit::cerl(),
1851 Type::cerl(), Flags::cerl()) -> cerl()
1852 See also: c_bitstr/5, update_c_bitstr/5.
1854 update_c_call(Old::cerl(), Module::cerl(), Name::cerl(), Argu‐
1856 ments::[cerl()]) -> cerl()
1857 See also: c_call/3.
1859 update_c_case(Old::cerl(), Argument::cerl(), Clauses::[cerl()]) ->
1861 cerl()
1862 See also: c_case/2.
1864 update_c_catch(Old::cerl(), Body::cerl()) -> cerl()
1866 See also: c_catch/1.
1868 update_c_clause(Old::cerl(), Patterns::[cerl()], Guard::cerl(),
1870 Body::cerl()) -> cerl()
1871 See also: c_clause/3.
1873 update_c_cons(Old::cerl(), Head::cerl(), Tail::cerl()) -> cerl()
1875 See also: c_cons/2.
1877 update_c_cons_skel(Old::cerl(), Head::cerl(), Tail::cerl()) -> cerl()
1879 See also: c_cons_skel/2.
1881 update_c_fname(Old::cerl(), Name::atom()) -> cerl()
1883 Like update_c_fname/3, but takes the arity from Node.
1885 See also: c_fname/2, update_c_fname/3.
1887 update_c_fname(Old::cerl(), Name::atom(), Arity::arity()) -> cerl()
1889 Equivalent to update_c_var(Old, {Atom, Arity}).
1891 See also: c_fname/2, update_c_fname/2.
1893 update_c_fun(Old::cerl(), Variables::[cerl()], Body::cerl()) -> cerl()
1895 See also: c_fun/2.
1897 update_c_let(Node::c_let(), Variables::[cerl()], Argument::cerl(),
1899 Body::cerl()) -> c_let()
1900 See also: c_let/3.
1902 update_c_letrec(Old::cerl(), Definitions::[{cerl(), cerl()}],
1904 Body::cerl()) -> cerl()
1905 See also: c_letrec/2.
1907 update_c_map(C_map::c_map(), M::cerl(), Es::[cerl()]) -> c_map() |
1909 c_literal()
1910 update_c_map_pair(Old::c_map_pair(), Op::map_op(), K::cerl(),
1912 V::cerl()) -> c_map_pair()
1913 update_c_module(Old::cerl(), Name::cerl(), Exports, Attrs::Attributes,
1915 Es::Definitions) -> cerl()
1916 Types:
1918 Exports = [cerl()]
1920 Attributes = [{cerl(), cerl()}]
1921 Definitions = [{cerl(), cerl()}]
1922 See also: c_module/4.
1924 update_c_primop(Old::cerl(), Name::cerl(), Arguments::[cerl()]) ->
1926 cerl()
1927 See also: c_primop/2.
1929 update_c_receive(Old::cerl(), Clauses::[cerl()], Timeout::cerl(), Ac‐
1931 tion::cerl()) -> cerl()
1932 See also: c_receive/3.
1934 update_c_seq(Old::cerl(), Argument::cerl(), Body::cerl()) -> cerl()
1936 See also: c_seq/2.
1938 update_c_try(Old::cerl(), Expression::cerl(), Variables::[cerl()],
1940 Body::cerl(), EVars::[cerl()], Handler::cerl()) -> cerl()
1941 See also: c_try/5.
1943 update_c_tuple(Old::cerl(), Elements::[cerl()]) -> cerl()
1945 See also: c_tuple/1.
1947 update_c_tuple_skel(Old::cerl(), Elements::[cerl()]) -> cerl()
1949 See also: c_tuple_skel/1.
1951 update_c_values(Old::cerl(), Elements::[cerl()]) -> cerl()
1953 See also: c_values/1.
1955 update_c_var(Old::cerl(), Name::var_name()) -> cerl()
1957 See also: c_var/1.
1959 update_data(Old::cerl(), Type::dtype(), Elements::[cerl()]) -> cerl()
1961 See also: make_data/2.
1963 update_data_skel(Old::cerl(), Type::dtype(), Elements::[cerl()]) ->
1965 cerl()
1966 See also: make_data_skel/2.
1968 update_list(Old::cerl(), List::[cerl()]) -> cerl()
1970 Equivalent to update_list(Old, List, none).
1972 update_list(Old::cerl(), List::[cerl()], Tail) -> cerl()
1974 Types:
1976 Tail = cerl() | none
1978 See also: make_list/2, update_list/2.
1980 update_tree(Old::cerl(), Groups::[[cerl()]]) -> cerl()
1982 Creates a syntax tree with the given subtrees, and the same type
1984 and annotations as the Old node. This is equivalent to
1985 ann_make_tree(get_ann(Node), type(Node), Groups), but poten‐
1986 tially more efficient.
1987 See also: ann_make_tree/3, get_ann/1, type/1, update_tree/3.
1989 update_tree(Old::cerl(), Type::ctype(), Groups::[[cerl()]]) -> cerl()
1991 Creates a syntax tree with the given type and subtrees, and the
1993 same annotations as the Old node. This is equivalent to
1994 ann_make_tree(get_ann(Node), Type, Groups), but potentially more
1995 efficient.
1996 See also: ann_make_tree/3, get_ann/1, update_tree/2.
1998 values_arity(Node::cerl()) -> integer()
2000 Returns the number of element subtrees of an abstract value
2002 list.
2003 Note: This is equivalent to length(values_es(Node)), but poten‐
2005 tially more efficient.
2006 See also: c_values/1, values_es/1.
2008 values_es(Node::cerl()) -> [cerl()]
2010 Returns the list of element subtrees of an abstract value list.
2012 See also: c_values/1, values_arity/1.
2014 var_name(Node::cerl()) -> var_name()
2016 Returns the name of an abstract variable.
2018 See also: c_var/1.
2020
2022 Richard Carlsson <carlsson.richard@gmail.com>
2023 compiler 7.6.9.1 cerl(3)