Restructure book chapters.

doc/src/engine/options.md

@@ -0,0 +1,18 @@
+Engine Configuration Options
+===========================
+
+{{#include ../links.md}}
+
+A number of other configuration options are available from the `Engine` to fine-tune behavior and safeguards.
+
+| Method                   | Not available under          | Description                                                                                                              |
+| ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `set_optimization_level` | [`no_optimize`]              | Set the amount of script _optimizations_ performed. See [script optimization].                                           |
+| `set_max_expr_depths`    | [`unchecked`]                | Set the maximum nesting levels of an expression/statement. See [maximum statement depth].                                |
+| `set_max_call_levels`    | [`unchecked`]                | Set the maximum number of function call levels (default 50) to avoid infinite recursion. See [maximum call stack depth]. |
+| `set_max_operations`     | [`unchecked`]                | Set the maximum number of _operations_ that a script is allowed to consume. See [maximum number of operations].          |
+| `set_max_modules`        | [`unchecked`]                | Set the maximum number of [modules] that a script is allowed to load. See [maximum number of modules].                   |
+| `set_max_string_size`    | [`unchecked`]                | Set the maximum length (in UTF-8 bytes) for [strings]. See [maximum length of strings].                                  |
+| `set_max_array_size`     | [`unchecked`], [`no_index`]  | Set the maximum size for [arrays]. See [maximum size of arrays].                                                         |
+| `set_max_map_size`       | [`unchecked`], [`no_object`] | Set the maximum number of properties for [object maps]. See [maximum size of object maps].                               |
+| `disable_symbol`         |                              | Disable a certain keyword or operator. See [disable keywords and operators].                                             |

doc/src/engine/scope.md

@@ -0,0 +1,54 @@
+`Scope` - Initializing and Maintaining State
+===========================================
+
+{{#include ../links.md}}
+
+By default, Rhai treats each [`Engine`] invocation as a fresh one, persisting only the functions that have been defined
+but no global state. This gives each evaluation a clean starting slate.
+
+In order to continue using the same global state from one invocation to the next,
+such a state must be manually created and passed in.
+
+All `Scope` variables are [`Dynamic`], meaning they can store values of any type.
+
+Under [`sync`], however, only types that are `Send + Sync` are supported, and the entire `Scope` itself
+will also be `Send + Sync`. This is extremely useful in multi-threaded applications.
+
+In this example, a global state object (a `Scope`) is created with a few initialized variables,
+then the same state is threaded through multiple invocations:
+
+```rust
+use rhai::{Engine, Scope, EvalAltResult};
+
+let engine = Engine::new();
+
+// First create the state
+let mut scope = Scope::new();
+
+// Then push (i.e. add) some initialized variables into the state.
+// Remember the system number types in Rhai are i64 (i32 if 'only_i32') ond f64.
+// Better stick to them or it gets hard working with the script.
+scope
+    .push("y", 42_i64)
+    .push("z", 999_i64)
+    .set_value("s", "hello, world!".to_string());   //'set_value' adds a variable when one doesn't exist
+                                                    // remember to use 'String', not '&str'
+
+// First invocation
+engine.eval_with_scope::<()>(&mut scope, r"
+    let x = 4 + 5 - y + z + s.len;
+    y = 1;
+")?;
+
+// Second invocation using the same state
+let result = engine.eval_with_scope::<i64>(&mut scope, "x")?;
+
+println!("result: {}", result);                     // prints 979
+
+// Variable y is changed in the script - read it with 'get_value'
+assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 1);
+
+// We can modify scope variables directly with 'set_value'
+scope.set_value("y", 42_i64);
+assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 42);
+```