Add serde deserialization.

doc/src/SUMMARY.md

@@ -96,14 +96,15 @@ The Rhai Scripting Language
    9. [Maximum Statement Depth](safety/max-stmt-depth.md)
 8. [Advanced Topics](advanced.md)
    1. [Object-Oriented Programming (OOP)](language/oop.md)
-   2. [Script Optimization](engine/optimize/index.md)
+   2. [Serialization/Deserialization of `Dynamic` with `serde`](rust/serde.md)
+   3. [Script Optimization](engine/optimize/index.md)
       1. [Optimization Levels](engine/optimize/optimize-levels.md)
       2. [Re-Optimize an AST](engine/optimize/reoptimize.md)
       3. [Eager Function Evaluation](engine/optimize/eager.md)
       4. [Side-Effect Considerations](engine/optimize/side-effects.md)
       5. [Volatility Considerations](engine/optimize/volatility.md)
       6. [Subtle Semantic Changes](engine/optimize/semantics.md)
-   3. [Eval Statement](language/eval.md)
+   4. [Eval Statement](language/eval.md)
 9. [Appendix](appendix/index.md)
    1. [Keywords](appendix/keywords.md)
    2. [Operators](appendix/operators.md)

doc/src/about/features.md

@@ -39,6 +39,8 @@ Dynamic
 
 * Some support for [object-oriented programming (OOP)][OOP].
 
+* Serialization/deserialization support via [`serde`].
+
 Safe
 ----
 

doc/src/links.md

@@ -29,6 +29,7 @@
 [package]: {{rootUrl}}/rust/packages/index.md
 [packages]: {{rootUrl}}/rust/packages/index.md
 [`Scope`]: {{rootUrl}}/rust/scope.md
+[`serde`]: {{rootUrl}}/rust/serde.md
 
 [`type_of()`]: {{rootUrl}}/language/type-of.md
 [`to_string()`]: {{rootUrl}}/language/values-and-types.md

doc/src/rust/serde.md

@@ -0,0 +1,63 @@
+Serialization and Deserialization of `Dynamic` with `serde`
+=========================================================
+
+{{#include ../links.md}}
+
+Rhai's [`Dynamic`] type supports serialization and deserialization by [`serde`](https://crates.io/crates/serde)
+via the [`serde`][features] feature.
+
+A [`Dynamic`] can be seamlessly converted to and from a type that implements `serde::Serialize` and/or
+`serde::Deserialize`.
+
+
+Serialization
+-------------
+
+Serialization by [`serde`](https://crates.io/crates/serde) is not yet implemented.
+
+It is simple to serialize a Rust type to `JSON` via `serde`, then use [`Engine::parse_json`]({{rootUrl}}/language/json.md) to convert
+it into an [object map].
+
+
+Deserialization
+---------------
+
+The function `rhai::de::from_dynamic` automatically converts a [`Dynamic`] value into any Rust type
+that implements `serde::Deserialize`.
+
+In particular, [object maps] are converted into Rust `struct`'s (or any type that is marked as
+a `serde` map) while [arrays] are converted into Rust `Vec`'s (or any type that is marked
+as a `serde` sequence).
+
+```rust
+use rhai::{Engine, Dynamic};
+use rhai::de::from_dynamic;
+
+#[derive(Debug, serde::Deserialize)]
+struct Point {
+    x: f64,
+    y: f64
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct MyStruct {
+    a: i64,
+    b: Vec<String>,
+    c: bool,
+    d: Point
+}
+
+let engine = Engine::new();
+
+let result: Dynamic = engine.eval(r#"
+            #{
+                a: 42,
+                b: [ "hello", "world" ],
+                c: true,
+                d: #{ x: 123.456, y: 999.0 }
+            }
+        "#)?;
+
+// Convert the 'Dynamic' object map into 'MyStruct'
+let x: MyStruct = from_dynamic(&result)?;
+```

doc/src/start/features.md

@@ -24,6 +24,7 @@ more control over what a script can (or cannot) do.
 | `no_function` | Disable script-defined [functions].                                                                                                                                                                        |
 | `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.                                                                      |