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

NAME

6       cerl_clauses - Utility functions for Core Erlang case/receive clauses.
7

DESCRIPTION

9       Utility functions for Core Erlang case/receive clauses.
10
11       Syntax trees are defined in the module cerl.
12

DATA TYPES

14         bindings() = [{cerl:cerl(), cerl:cerl()}]:
15
16
17         cerl() = cerl:cerl():
18
19
20         expr() = any | cerl:cerl():
21
22
23         match_ret() = none | {true, bindings()} | {false, bindings()}:
24
25

EXPORTS

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

AUTHORS

157       Richard Carlsson <carlsson.richard@gmail.com>
158
159
160
161                                compiler 8.1.1                 cerl_clauses(3)
Impressum