---

yaml
---
r: 35895
b: refs/heads/try2
c: fd85a00
h: refs/heads/master
i:
  35893: 107077a
  35891: e0ac8e2
  35887: 83903ca
v: v3

Author: graydon

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: eb8fd119c65c67f3b1b8268cc7341c22d39b7b61
 refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 693866d75e25425053c61dc16adcc12b977d86f0
+refs/heads/try2: fd85a0000a542a52f0fda3bd2f941fba452e0698
 refs/heads/incoming: d9317a174e434d4c99fc1a37fd7dc0d2f5328d37
 refs/heads/dist-snap: 22efa39382d41b084fde1719df7ae8ce5697d8c9
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596

branches/try2/doc/rust.md

@@ -2071,6 +2071,52 @@ the loop.
 A `loop` expression is only permitted in the body of a loop.
 
 
+### Do expressions
+
+~~~~~~~~{.ebnf .gram}
+do_expr : "do" expr [ '|' ident_list '|' ] ? '{' block '}' ;
+~~~~~~~~
+
+A _do expression_ provides a more-familiar block-syntax for a [lambda expression](#lambda-expressions),
+including a special translation of [return expressions](#return-expressions) inside the supplied block.
+
+The optional `ident_list` and `block` provided in a `do` expression are parsed as though they constitute a lambda expression;
+if the `ident_list` is missing, an empty `ident_list` is implied.
+
+The lambda expression is then provided as a _trailing argument_
+to the outermost [call](#call-expressions) or [method call](#method-call-expressions) expression
+in the `expr` following `do`.
+If the `expr` is a [path expression](#path-expressions), it is parsed as though it is a call expression.
+If the `expr` is a [field expression](#field-expressions), it is parsed as though it is a method call expression.
+
+Additionally, any occurrence of a [return expression](#return-expressions)
+inside the `block` of a `do` expression is rewritten
+as a reference to an (anonymous) flag set in the caller's environment,
+which is checked on return from the `expr` and, if set,
+causes a corresponding return from the caller.
+In this way, the meaning of `return` statements in language built-in control blocks is preserved,
+if they are rewritten using lambda functions and `do` expressions as abstractions.
+
+Therefore the two calls to `f` in this example are equivalent.
+Both cause an early return from the caller's frame:
+
+~~~~
+# fn f(f: fn(int)) { }
+# fn g(i: int) { }
+
+{
+  let mut _early_ret = false;
+  f(|j| { g(j); _early_ret = true; });
+  if early_ret { return; }
+}
+
+do f |j| {
+    g(j);
+    return;
+}
+~~~~
+
+
 ### For expressions
 
 ~~~~~~~~{.ebnf .gram}