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         cerl() = cerl:cerl():
15
16

EXPORTS

18       any_catchall(Clauses::[cerl()]) -> boolean()
19
20              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
23              Note: each node in Clauses must have type clause.
24
25              See also: is_catchall/1.
26
27       eval_guard(Expr::cerl()) -> none | {value, term()}
28
29              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
34              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
40              See also: is_catchall/1.
41
42       is_catchall(Clause::cerl()) -> boolean()
43
44              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
49              Note: Clause must have type clause.
50
51              See also: any_catchall/1, eval_guard/1.
52
53       match(Pattern::cerl(), E::Expr) -> none | {true,  Bindings}  |  {false,
54       Bindings}
55
56              Types:
57
58                 Expr = any | cerl()
59                 Bindings = [{cerl(), Expr}]
60
61              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
74              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
81              Note:  Binary-syntax  patterns  are  never  structurally matched
82              against binary-syntax expressions by this function.
83
84              Examples:
85
86                * 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
90                * 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
96                * 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
100                * 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
104                * Matching a pattern "{X, Y}" against any yields {false, Bind‐
105                  ings} where Bindings associates both "X" and "Y" with any.
106
107       match_list(Patterns::[cerl()],  Exprs::[Expr])  ->  none | {true, Bind‐
108       ings} | {false, Bindings}
109
110              Types:
111
112                 Expr = any | cerl()
113                 Bindings = [{cerl(), cerl()}]
114
115              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
120              See also: match/2.
121
122       reduce(Cs::Clauses) -> {true, {Clause, Bindings}} | {false, Clauses}
123
124              Equivalent to reduce(Cs, []).
125
126       reduce(Clauses::[Clause],  Exprs::[Expr]) -> {true, {Clause, Bindings}}
127       | {false, [Clause]}
128
129              Types:
130
131                 Clause = cerl()
132                 Expr = any | cerl()
133                 Bindings = [{cerl(), cerl()}]
134
135              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
145              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
150              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
157              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
162              See also: eval_guard/1, match/2, match_list/2.
163

AUTHORS

165       Richard Carlsson <carlsson.richard@gmail.com>
166
167
168
169                               compiler 7.6.9.1                cerl_clauses(3)
Impressum