1cerl_clauses(3) Erlang Module Definition cerl_clauses(3)
2
6 cerl_clauses - Utility functions for Core Erlang case/receive clauses.
7
9 Utility functions for Core Erlang case/receive clauses.
10 Syntax trees are defined in the module cerl.
12
14 cerl() = cerl:cerl():
15
18 any_catchall(Clauses::[cerl()]) -> boolean()
19 Returns true if any of the abstract clauses in the list is a
21 catch-all, otherwise false. See is_catchall/1 for details.
22 Note: each node in Clauses must have type clause.
24 See also: is_catchall/1.
26 eval_guard(Expr::cerl()) -> none | {value, term()}
28 Tries to reduce a guard expression to a single constant value,
30 if possible. The returned value is {value, Term} if the guard
31 expression Expr always yields the constant value Term, and is
32 otherwise none.
33 Note that although guard expressions should only yield boolean
35 values, this function does not guarantee that Term is either
36 true or false. Also note that only simple constructs like let-
37 expressions are examined recursively; general constant folding
38 is not performed.
39 See also: is_catchall/1.
41 is_catchall(Clause::cerl()) -> boolean()
43 Returns true if an abstract clause is a catch-all, otherwise
45 false. A clause is a catch-all if all its patterns are vari‐
46 ables, and its guard expression always evaluates to true; cf.
47 eval_guard/1.
48 Note: Clause must have type clause.
50 See also: any_catchall/1, eval_guard/1.
52 match(Pattern::cerl(), E::Expr) -> none | {true, Bindings} | {false,
54 Bindings}
55 Types:
57 Expr = any | cerl()
59 Bindings = [{cerl(), Expr}]
60 Matches a pattern against an expression. The returned value is
62 none if a match is impossible, {true, Bindings} if Pattern defi‐
63 nitely matches Expr, and {false, Bindings} if a match is not
64 definite, but cannot be excluded. Bindings is then a list of
65 pairs {Var, SubExpr}, associating each variable in the pattern
66 with either the corresponding subexpression of Expr, or with the
67 atom any if no matching subexpression exists. (Recall that vari‐
68 ables may not be repeated in a Core Erlang pattern.) The list of
69 bindings is given in innermost-first order; this should only be
70 of interest if Pattern contains one or more alias patterns. If
71 the returned value is {true, []}, it implies that the pattern
72 and the expression are syntactically identical.
73 Instead of a syntax tree, the atom any can be passed for Expr
75 (or, more generally, be used for any subtree of Expr, in as much
76 the abstract syntax tree implementation allows it); this means
77 that it cannot be decided whether the pattern will match or not,
78 and the corresponding variable bindings will all map to any. The
79 typical use is for producing bindings for receive clauses.
80 Note: Binary-syntax patterns are never structurally matched
82 against binary-syntax expressions by this function.
83 Examples:
85 * Matching a pattern "{X, Y}" against the expression "{foo,
87 f(Z)}" yields {true, Bindings} where Bindings associates "X"
88 with the subtree "foo" and "Y" with the subtree "f(Z)".
89 * Matching pattern "{X, {bar, Y}}" against expression "{foo,
91 f(Z)}" yields {false, Bindings} where Bindings associates
92 "X" with the subtree "foo" and "Y" with any (because it is
93 not known if "{foo, Y}" might match the run-time value of
94 "f(Z)" or not).
95 * Matching pattern "{foo, bar}" against expression "{foo,
97 f()}" yields {false, []}, telling us that there might be a
98 match, but we cannot deduce any bindings.
99 * Matching {foo, X = {bar, Y}} against expression "{foo, {bar,
101 baz}}" yields {true, Bindings} where Bindings associates "Y"
102 with "baz", and "X" with "{bar, baz}".
103 * Matching a pattern "{X, Y}" against any yields {false, Bind‐
105 ings} where Bindings associates both "X" and "Y" with any.
106 match_list(Patterns::[cerl()], Exprs::[Expr]) -> none | {true, Bind‐
108 ings} | {false, Bindings}
109 Types:
111 Expr = any | cerl()
113 Bindings = [{cerl(), cerl()}]
114 Like match/2, but matching a sequence of patterns against a se‐
116 quence of expressions. Passing an empty list for Exprs is equiv‐
117 alent to passing a list of any atoms of the same length as Pat‐
118 terns.
119 See also: match/2.
121 reduce(Cs::Clauses) -> {true, {Clause, Bindings}} | {false, Clauses}
123 Equivalent to reduce(Cs, []).
125 reduce(Clauses::[Clause], Exprs::[Expr]) -> {true, {Clause, Bindings}}
127 | {false, [Clause]}
128 Types:
130 Clause = cerl()
132 Expr = any | cerl()
133 Bindings = [{cerl(), cerl()}]
134 Selects a single clause, if possible, or otherwise reduces the
136 list of selectable clauses. The input is a list Clauses of ab‐
137 stract clauses (i.e., syntax trees of type clause), and a list
138 of switch expressions Exprs. The function tries to uniquely se‐
139 lect a single clause or discard unselectable clauses, with re‐
140 spect to the switch expressions. All abstract clauses in the
141 list must have the same number of patterns. If Exprs is not the
142 empty list, it must have the same length as the number of pat‐
143 terns in each clause; see match_list/2 for details.
144 A clause can only be selected if its guard expression always
146 yields the atom true, and a clause whose guard expression always
147 yields the atom false can never be selected. Other guard expres‐
148 sions are considered to have unknown value; cf. eval_guard/1.
149 If a particular clause can be selected, the function returns
151 {true, {Clause, Bindings}}, where Clause is the selected clause
152 and Bindings is a list of pairs {Var, SubExpr} associating the
153 variables occurring in the patterns of Clause with the corre‐
154 sponding subexpressions in Exprs. The list of bindings is given
155 in innermost-first order; see the match/2 function for details.
156 If no clause could be definitely selected, the function returns
158 {false, NewClauses}, where NewClauses is the list of entries in
159 Clauses that remain after eliminating unselectable clauses, pre‐
160 serving the relative order.
161 See also: eval_guard/1, match/2, match_list/2.
163
165 Richard Carlsson <carlsson.richard@gmail.com>
166 compiler 7.6.9.1 cerl_clauses(3)