From fc54fdc907047c155e459784a8d2a761d757b632 Mon Sep 17 00:00:00 2001
From: Stephen Chung <schungx@live.com>
Date: Thu, 17 Dec 2020 10:42:20 +0800
Subject: [PATCH] Emphasize custom syntax are expressions.

---
 doc/src/engine/custom-syntax.md | 16 +++++++++++++++-
 tests/syntax.rs                 | 15 ++++++++++++++-
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/src/engine/custom-syntax.md b/doc/src/engine/custom-syntax.md
index 876e18a3..856392b0 100644
--- a/doc/src/engine/custom-syntax.md
+++ b/doc/src/engine/custom-syntax.md
@@ -220,7 +220,7 @@ fn implementation_func(
     Ok(Dynamic::UNIT)
 }
 
-// Register the custom syntax (sample): exec |x| -> { x += 1 } while x < 0;
+// Register the custom syntax (sample): exec |x| -> { x += 1 } while x < 0
 engine.register_custom_syntax(
     &[ "exec", "|", "$ident$", "|", "->", "$block$", "while", "$expr$" ], // the custom syntax
     1,  // the number of new variables declared within this custom syntax
@@ -228,6 +228,20 @@ engine.register_custom_syntax(
 )?;
 ```
 
+Remember that a custom syntax acts as an _expression_, so it can show up practically anywhere:
+
+```rust
+// Use as an expression:
+let foo = (exec |x| -> { x += 1 } while x < 0) * 100;
+
+// Use as a function call argument:
+do_something(exec |x| -> { x += 1 } while x < 0, 24, true);
+
+// Use as a statement:
+exec |x| -> { x += 1 } while x < 0;
+//                                ^ terminate statement with ';'
+```
+
 
 Step Four - Disable Unneeded Statement Types
 -------------------------------------------
diff --git a/tests/syntax.rs b/tests/syntax.rs
index f2049e86..55272f54 100644
--- a/tests/syntax.rs
+++ b/tests/syntax.rs
@@ -29,8 +29,11 @@ fn test_custom_syntax() -> Result<(), Box<EvalAltResult>> {
 
             context.scope_mut().push(var_name, 0 as INT);
 
+            let mut count: INT = 0;
+
             loop {
                 context.eval_expression_tree(stmt)?;
+                count += 1;
 
                 let stop = !context
                     .eval_expression_tree(condition)?
@@ -48,10 +51,20 @@ fn test_custom_syntax() -> Result<(), Box<EvalAltResult>> {
                 }
             }
 
-            Ok(Dynamic::UNIT)
+            Ok(count.into())
         },
     )?;
 
+    assert_eq!(
+        engine.eval::<INT>(
+            r"
+                let x = 0;
+                let foo = (exec |x| -> { x += 2 } while x < 42) * 10;
+                foo
+            "
+        )?,
+        210
+    );
     assert_eq!(
         engine.eval::<INT>(
             r"