Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang:24
erlang
3511-Document-maybe-.-end-in-the-reference-manu...
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File 3511-Document-maybe-.-end-in-the-reference-manual.patch of Package erlang
From c83478d45b76b34dd5804f358fa95070dfbd99e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org> Date: Tue, 16 Nov 2021 07:05:20 +0100 Subject: [PATCH 11/12] Document maybe ... end in the reference manual --- system/doc/reference_manual/expressions.xml | 132 ++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 956775d7e8..b3259ec630 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -394,6 +394,134 @@ is_valid_signal(Signal) -> end.</pre> </section> + <section> + <marker id="maybe"></marker> + <title>Maybe</title> + <note><p><c>maybe</c> is an experimental new feature introduced in + OTP 25. By default, it is disabled. To enable <c>maybe</c>, use + compiler option <c>{enable_feature,maybe_expr}</c>.</p></note> + + <code type="erl"><![CDATA[ +maybe + Expr1, + ..., + ExprN +end]]></code> + + <p>The expressions in a <c>maybe</c> block are evaluated sequentially. If all + expressions are evaluated successfully, the return value of the <c>maybe</c> + block is <c>ExprN</c>. However, execution can be short-circuited by a + conditional match expression:</p> + + <code type="erl"><![CDATA[ +Expr1 ?= Expr2]]></code> + + <p><c>?=</c> is called the conditional match operator. It is only + allowed to be used at the top-level of a <c>maybe</c> block. It + matches the pattern <c>Expr1</c> against <c>Expr2</c>. If the + matching succeeds, any unbound variable in the pattern becomes + bound. If the expression is the last expression in the + <c>maybe</c> block, it also returns the value of <c>Expr2</c>. If the + matching is unsuccessful, the rest of the expressions in the <c>maybe</c> + block are skipped and the return value of the <c>maybe</c> + block is <c>Expr2</c>.</p> + + <p>None of the variables bound in a <c>maybe</c> block must be + used in the code that follows the block.</p> + + <p>Here is an example:</p> + + <code type="erl"><![CDATA[ +maybe + {ok, A} ?= a(), + true = A >= 0, + {ok, B} ?= b(), + A + B +end]]></code> + + <p>Let us first assume that <c>a()</c> returns <c>{ok,42}</c> and + <c>b()</c> returns <c>{ok,58}</c>. With those return values, all + of the match operators will succeed, and the return value of the + <c>maybe</c> block is <c>A + B</c>, which is equal to <c>42 + + 58 = 100</c>.</p> + + <p>Now let us assume that <c>a()</c> returns <c>error</c>. The + conditional match operator in <c>{ok, A} ?= a()</c> fails to + match, and the return value of the <c>maybe</c> block is the + value of the expression that failed to match, namely <c>error</c>. + Similarly, if <c>b()</c> returns <c>wrong</c>, the return value of + the <c>maybe</c> block is <c>wrong</c>.</p> + + <p>Finally, let us assume that <c>a()</c> returns + <c>-1</c>. Because <c>true = A >= 0</c> uses the match operator + `=`, a <c>{badmatch,false}</c> run-time error occurs when the + expression fails to match the pattern.</p> + + <p>The example can be written in a less succient way using nested + case expressions:</p> + + <code type="erl"><![CDATA[ +case a() of + {ok, A} -> + true = A >= 0, + case b() of + {ok, B} -> + A + B; + Other1 -> + Other1 + end; + Other2 -> + Other2 +end]]></code> + + <p>The <c>maybe</c> block can be augmented with <c>else</c> clauses:</p> + + <code type="erl"><![CDATA[ +maybe + Expr1, + ..., + ExprN +else + Pattern1 [when GuardSeq1] -> + Body1; + ...; + PatternN [when GuardSeqN] -> + BodyN +end]]></code> + + <p>If a conditional match operator fails, the failed expression is + matched against the patterns in all clauses between the + <c>else</c> and <c>end</c> keywords. If a match succeeds and the + optional guard sequence <c>GuardSeq</c> is true, the corresponding + <c>Body</c> is evaluated. The value returned from the body is the + return value of the <c>maybe</c> block.</p> + + <p>If there is no matching pattern with a true guard sequence, + an <c>else_clause</c> run-time error occurs.</p> + + <p>None of the variables bound in a <c>maybe</c> block must be used in + the <c>else</c> clauses. None of the variables bound in the <c>else</c> clauses + must be used in the code that follows the <c>maybe</c> block.</p> + + <p>Here is the previous example augmented with a <c>else</c> clauses:</p> + + <code type="erl"><![CDATA[ +maybe + {ok, A} ?= a(), + true = A >= 0, + {ok, B} ?= b(), + A + B +else + error -> error; + wrong -> error +end]]></code> + + <p>The <c>else</c> clauses translate the failing value from + the conditional match operators to the value <c>error</c>. If the + failing value is not one of the recognized values, a + <c>else_clause</c> run-time error occurs.</p> + </section> + <section> <marker id="send"></marker> <title>Send</title> @@ -1865,6 +1865,10 @@ end</pre> <cell align="left" valign="middle">= !</cell> <cell align="left" valign="middle">Right-associative</cell> </row> + <row> + <cell align="left" valign="middle">?=</cell> + <cell align="left" valign="middle"> </cell> + </row> <tcaption>Operator Precedence</tcaption> </table> <p>Before Erlang/OTP 24, the <c>catch</c> operator had the lowest -- 2.34.1
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor