Provided by: erlang-manpages_25.3.2.8+dfsg-1ubuntu4_all 
NAME
cerl_clauses - Utility functions for Core Erlang case/receive clauses.
DESCRIPTION
Utility functions for Core Erlang case/receive clauses.
Syntax trees are defined in the module cerl.
DATA TYPES
bindings() = [{cerl:cerl(), cerl:cerl()}]:
cerl() = cerl:cerl():
expr() = any | cerl:cerl():
match_ret() = none | {true, bindings()} | {false, bindings()}:
EXPORTS
any_catchall(Cs::[cerl:cerl()]) -> boolean()
Returns true if any of the abstract clauses in the list is a catch-all, otherwise
false. See is_catchall/1 for details.
Note: each node in Clauses must have type clause.
See also: is_catchall/1.
eval_guard(E::cerl:cerl()) -> none | {value, term()}
Tries to reduce a guard expression to a single constant value, if possible. The
returned value is {value, Term} if the guard expression Expr always yields the
constant value Term, and is otherwise none.
Note that although guard expressions should only yield boolean values, this
function does not guarantee that Term is either true or false. Also note that only
simple constructs like let-expressions are examined recursively; general constant
folding is not performed.
See also: is_catchall/1.
is_catchall(C::cerl:c_clause()) -> boolean()
Returns true if an abstract clause is a catch-all, otherwise false. A clause is a
catch-all if all its patterns are variables, and its guard expression always
evaluates to true; cf. eval_guard/1.
Note: Clause must have type clause.
See also: any_catchall/1, eval_guard/1.
match(P::cerl:cerl(), E::expr()) -> match_ret()
Matches a pattern against an expression. The returned value is none if a match is
impossible, {true, Bindings} if Pattern definitely matches Expr, and {false,
Bindings} if a match is not definite, but cannot be excluded. Bindings is then a
list of pairs {Var, SubExpr}, associating each variable in the pattern with either
the corresponding subexpression of Expr, or with the atom any if no matching
subexpression exists. (Recall that variables may not be repeated in a Core Erlang
pattern.) The list of bindings is given in innermost-first order; this should only
be of interest if Pattern contains one or more alias patterns. If the returned
value is {true, []}, it implies that the pattern and the expression are
syntactically identical.
Instead of a syntax tree, the atom any can be passed for Expr (or, more generally,
be used for any subtree of Expr, in as much the abstract syntax tree implementation
allows it); this means that it cannot be decided whether the pattern will match or
not, and the corresponding variable bindings will all map to any. The typical use
is for producing bindings for receive clauses.
Note: Binary-syntax patterns are never structurally matched against binary-syntax
expressions by this function.
Examples:
* Matching a pattern "{X, Y}" against the expression "{foo, f(Z)}" yields {true,
Bindings} where Bindings associates "X" with the subtree "foo" and "Y" with the
subtree "f(Z)".
* Matching pattern "{X, {bar, Y}}" against expression "{foo, f(Z)}" yields
{false, Bindings} where Bindings associates "X" with the subtree "foo" and "Y"
with any (because it is not known if "{foo, Y}" might match the run-time value
of "f(Z)" or not).
* Matching pattern "{foo, bar}" against expression "{foo, f()}" yields {false,
[]}, telling us that there might be a match, but we cannot deduce any bindings.
* Matching {foo, X = {bar, Y}} against expression "{foo, {bar, baz}}" yields
{true, Bindings} where Bindings associates "Y" with "baz", and "X" with "{bar,
baz}".
* Matching a pattern "{X, Y}" against any yields {false, Bindings} where Bindings
associates both "X" and "Y" with any.
match_list(Ps::[cerl:cerl()], Es::[expr()]) -> match_ret()
Like match/2, but matching a sequence of patterns against a sequence of
expressions. Passing an empty list for Exprs is equivalent to passing a list of any
atoms of the same length as Patterns.
See also: match/2.
reduce(Cs::[cerl:c_clause()]) -> {true, {cerl:c_clause(), bindings()}} | {false,
[cerl:c_clause()]}
Equivalent to reduce(Cs, []).
reduce(Cs::[cerl:c_clause()], Es::[expr()]) -> {true, {cerl:c_clause(), bindings()}} |
{false, [cerl:c_clause()]}
Selects a single clause, if possible, or otherwise reduces the list of selectable
clauses. The input is a list Clauses of abstract clauses (i.e., syntax trees of
type clause), and a list of switch expressions Exprs. The function tries to
uniquely select a single clause or discard unselectable clauses, with respect to
the switch expressions. All abstract clauses in the list must have the same number
of patterns. If Exprs is not the empty list, it must have the same length as the
number of patterns in each clause; see match_list/2 for details.
A clause can only be selected if its guard expression always yields the atom true,
and a clause whose guard expression always yields the atom false can never be
selected. Other guard expressions are considered to have unknown value; cf.
eval_guard/1.
If a particular clause can be selected, the function returns {true, {Clause,
Bindings}}, where Clause is the selected clause and Bindings is a list of pairs
{Var, SubExpr} associating the variables occurring in the patterns of Clause with
the corresponding subexpressions in Exprs. The list of bindings is given in
innermost-first order; see the match/2 function for details.
If no clause could be definitely selected, the function returns {false,
NewClauses}, where NewClauses is the list of entries in Clauses that remain after
eliminating unselectable clauses, preserving the relative order.
See also: eval_guard/1, match/2, match_list/2.
AUTHORS
Richard Carlsson <carlsson.richard@gmail.com>
compiler 8.2.6.3 cerl_clauses(3erl)