reorganize module

_archive/rhai_engine/rhaibook/language/object-maps-missing-prop.md

@@ -0,0 +1,78 @@
+Non-Existent Property Handling for Object Maps
+==============================================
+
+{{#include ../links.md}}
+
+[`Engine::on_map_missing_property`]: https://docs.rs/rhai/{{version}}/rhai/struct.Engine.html#method.on_map_missing_property
+[`Target`]: https://docs.rs/rhai/latest/rhai/enum.Target.html
+
+
+~~~admonish warning.small "Requires `internals`"
+
+This is an advanced feature that requires the [`internals`] feature to be enabled.
+~~~
+
+Normally, when a property is accessed from an [object map] that does not exist, [`()`] is returned.
+Via [`Engine:: set_fail_on_invalid_map_property`][options], it is possible to make this an error
+instead.
+
+Other than that, it is possible to completely control this behavior via a special callback function
+registered into an [`Engine`] via `on_map_missing_property`.
+
+Using this callback, for instance, it is simple to instruct Rhai to create a new property in the
+[object map] on the fly, possibly with a default value, when a non-existent property is accessed.
+
+
+Function Signature
+------------------
+
+The function signature passed to [`Engine::on_map_missing_property`] takes the following form.
+
+> ```rust
+> Fn(map: &mut Map, prop: &str, context: EvalContext) -> Result<Target, Box<EvalAltResult>>
+> ```
+
+where:
+
+| Parameter |           Type           | Description                         |
+| --------- | :----------------------: | ----------------------------------- |
+| `map`     | [`&mut Map`][object map] | the [object map] being accessed     |
+| `prop`    |          `&str`          | name of the property being accessed |
+| `context` |     [`EvalContext`]      | the current _evaluation context_    |
+
+### Return value
+
+The return value is `Result<Target, Box<EvalAltResult>>`.
+
+[`Target`] is an advanced type, available only under the [`internals`] feature, that represents a
+_reference_ to a [`Dynamic`] value.
+
+It can be used to point to a particular value within the [object map].
+
+
+Example
+-------
+
+```rust
+engine.on_map_missing_property(|map, prop, context| {
+    match prop {
+        "x" => {
+            // The object-map can be modified in place
+            map.insert("y".into(), (42_i64).into());
+
+            // Return a mutable reference to an element
+            let value_ref = map.get_mut("y").unwrap();
+            Ok(value_ref.into())
+        }
+        "z" => {
+            // Return a temporary value (not a reference)
+            let value = Dynamic::from(100_i64);
+            Ok(value.into())
+        }
+        // Return the standard property-not-found error
+        _ => Err(EvalAltResult::ErrorPropertyNotFound(
+                prop.to_string(), Position::NONE
+             ).into()),
+    }
+});
+```