FIXED - method calls inside dot chain.

doc/src/SUMMARY.md

@@ -105,9 +105,11 @@ The Rhai Scripting Language
       5. [Volatility Considerations](engine/optimize/volatility.md)
       6. [Subtle Semantic Changes](engine/optimize/semantics.md)
    4. [Low-Level API](rust/register-raw.md)
-   5. [Disable Keywords and/or Operators](engine/disable.md)
-   6. [Custom Operators](engine/custom-op.md)
-   7. [Eval Statement](language/eval.md)
+   5. [Use as DSL](engine/dsl.md)
+      1. [Disable Keywords and/or Operators](engine/disable.md)
+      2. [Custom Operators](engine/custom-op.md)
+      3. [Custom Syntax](engine/custom-syntax.md)
+   6. [Eval Statement](language/eval.md)
 9. [Appendix](appendix/index.md)
    1. [Keywords](appendix/keywords.md)
    2. [Operators and Symbols](appendix/operators.md)

doc/src/about/features.md

@@ -67,4 +67,4 @@ Flexible
 
 * Surgically [disable keywords and operators] to restrict the language.
 
-* [Custom operators].
+* Use as a [DSL] by [disabling keywords/operators][disable keywords and operators], [custom operators] and defining [custom syntax].

doc/src/appendix/operators.md

@@ -41,6 +41,7 @@ Symbols
 | ------------ | ------------------------ |
 | `:`          | Property value separator |
 | `::`         | Module path separator    |
+| `#`          | _Reserved_               |
 | `=>`         | _Reserved_               |
 | `->`         | _Reserved_               |
 | `<-`         | _Reserved_               |

doc/src/engine/custom-syntax.md

@@ -0,0 +1,5 @@
+Custom Syntax
+=============
+
+{{#include ../links.md}}
+

doc/src/engine/dsl.md

@@ -0,0 +1,80 @@
+Use Rhai as a Domain-Specific Language (DSL)
+===========================================
+
+{{#include ../links.md}}
+
+Rhai can be successfully used as a domain-specific language (DSL).
+
+
+Expressions Only
+----------------
+
+In many DSL scenarios, only evaluation of expressions is needed.
+
+The `Engine::eval_expression_XXX`[`eval_expression`] API can be used to restrict
+a script to expressions only.
+
+
+Disable Keywords and/or Operators
+--------------------------------
+
+In some DSL scenarios, it is necessary to further restrict the language to exclude certain
+language features that are not necessary or dangerous to the application.
+
+For example, a DSL may disable the `while` loop altogether while keeping all other statement
+types intact.
+
+It is possible, in Rhai, to surgically [disable keywords and operators].
+
+
+Custom Operators
+----------------
+
+On the other hand, some DSL scenarios require special operators that make sense only for
+that specific environment.  In such cases, it is possible to define [custom operators] in Rhai.
+
+For example:
+
+```rust
+let animal = "rabbit";
+let food = "carrot";
+
+animal eats food            // custom operator - 'eats'
+
+eats(animal, food)          // <- the above really de-sugars to this
+```
+
+Although a [custom operator] always de-sugars to a simple function call,
+nevertheless it makes the DSL syntax much simpler and expressive.
+
+
+Custom Syntax
+-------------
+
+For advanced DSL scenarios, it is possible to define entire expression [_syntax_][custom syntax] -
+essentially custom statement types.
+
+The [`internals`] feature is needed to be able to define [custom syntax] in Rhai.
+
+For example:
+
+```rust
+let table = [..., ..., ..., ...];
+
+// Syntax = "select" $ident$ $ident$ "from" $expr$ "->" $ident$ ":" $expr$
+let total = select sum price from table -> row : row.weight > 50;
+```
+
+After registering this custom syntax with Rhai, it can be used anywhere inside a script as
+a normal expression.
+
+For its evaluation, the callback function will receive the following list of parameters:
+
+`exprs[0] = "sum"` - math operator  
+`exprs[1] = "price"` - field name  
+`exprs[2] = Expr(table)` - data source  
+`exprs[3] = "row"` - loop variable name  
+`exprs[4] = Expr(row.wright > 50)` - expression  
+
+The other identified, such as `"select"`, `"from"`, as as as symbols `->` and `:` are
+parsed in the order defined within the custom syntax.

doc/src/links.md

@@ -89,6 +89,7 @@
 [`eval`]: {{rootUrl}}/language/eval.md
 
 [OOP]: {{rootUrl}}/language/oop.md
+[DSL]: {{rootUrl}}/engine/dsl.md
 
 [maximum statement depth]: {{rootUrl}}/safety/max-stmt-depth.md
 [maximum call stack depth]: {{rootUrl}}/safety/max-call-stack.md
@@ -107,3 +108,4 @@
 [disable keywords and operators]: {{rootUrl}}/engine/disable.md
 [custom operator]: {{rootUrl}}/engine/custom-op.md
 [custom operators]: {{rootUrl}}/engine/custom-op.md
+[custom syntax]: {{rootUrl}}/engine/custom-syntax.md

doc/src/start/features.md

@@ -25,7 +25,7 @@ more control over what a script can (or cannot) do.
 | `no_module`   | Disable loading external [modules].                                                                                                                                                                        |
 | `no_std`      | Build for `no-std`. Notice that additional dependencies will be pulled in to replace `std` features.                                                                                                       |
 | `serde`       | Enable serialization/deserialization via [`serde`]. Notice that the [`serde`](https://crates.io/crates/serde) crate will be pulled in together with its dependencies.                                      |
-| `internals`   | Expose internal data structures (e.g. [`AST`] nodes). Beware that Rhai internals are volatile and may change from version to version.                                                                      |
+| `internals`   | Expose internal data structures (e.g. [`AST`] nodes) and enable defining [custom syntax]. Beware that Rhai internals are volatile and may change from version to version.                                  |
 
 
 Example