reorganize module

_archive/rhai_engine/rhaibook/patterns/config.md

@@ -0,0 +1,171 @@
+Loadable Configuration
+======================
+
+{{#include ../links.md}}
+
+
+```admonish info "Usage scenario"
+
+* A system where settings and configurations are complex and logic-driven.
+
+* Where said system is too complex to configure via standard configuration file formats such as
+  `JSON`, `TOML` or `YAML`.
+
+* The system is complex enough to require a full programming language to configure.
+  Essentially _configuration by code_.
+
+* Yet the configuration must be flexible, late-bound and dynamically loadable, just like a
+  configuration file.
+```
+
+```admonish abstract "Key concepts"
+
+* Leverage the loadable [modules] of Rhai.  The [`no_module`] feature must not be on.
+
+* Expose the configuration API.  Use separate scripts to configure that API.
+  Dynamically load scripts via the `import` statement.
+
+* Leverage [function overloading] to simplify the API design.
+
+* Since Rhai is _sand-boxed_, it cannot mutate the environment.  To modify the external
+  configuration object via an API, it must be wrapped in a `RefCell` (or `RwLock`/`Mutex` for
+  [`sync`]) and shared to the [`Engine`].
+```
+
+
+Implementation
+--------------
+
+### Configuration type
+
+```rust
+#[derive(Debug, Clone, Default)]
+struct Config {
+    id: String,
+    some_field: i64,
+    some_list: Vec<String>,
+    some_map: HashMap<String, bool>,
+}
+```
+
+### Make shared object
+
+```rust
+type SharedConfig = Rc<RefCell<Config>>;
+
+let config = SharedConfig::default();
+```
+
+or in multi-threaded environments with the [`sync`] feature, use one of the following:
+
+```rust
+type SharedConfig = Arc<RwLock<Config>>;
+
+type SharedConfig = Arc<Mutex<Config>>;
+```
+
+### Register config API
+
+The trick to building a Config API is to clone the shared configuration object and move it into each
+function registration via a closure.
+
+Therefore, it is not possible to use a [plugin module] to achieve this, and each function must be
+registered one after another.
+
+```rust
+// Notice 'move' is used to move the shared configuration object into the closure.
+let cfg = config.clone();
+engine.register_fn("config_set_id", move |id: String| cfg.borrow_mut().id = id);
+
+let cfg = config.clone();
+engine.register_fn("config_get_id", move || cfg.borrow().id.clone());
+
+let cfg = config.clone();
+engine.register_fn("config_set", move |value: i64| cfg.borrow_mut().some_field = value);
+
+// Remember Rhai functions can be overloaded when designing the API.
+
+let cfg = config.clone();
+engine.register_fn("config_add", move |value: String|
+    cfg.borrow_mut().some_list.push(value)
+);
+
+let cfg = config.clone();
+engine.register_fn("config_add", move |values: &mut Array|
+    cfg.borrow_mut().some_list.extend(values.into_iter().map(|v| v.to_string()))
+);
+
+let cfg = config.clone();
+engine.register_fn("config_add", move |key: String, value: bool|
+    cfg.borrow_mut().some_map.insert(key, value)
+);
+
+let cfg = config.clone();
+engine.register_fn("config_contains", move |value: String|
+    cfg.borrow().some_list.contains(&value)
+);
+
+let cfg = config.clone();
+engine.register_fn("config_is_set", move |value: String|
+    cfg.borrow().some_map.get(&value).cloned().unwrap_or(false)
+);
+```
+
+### Configuration script
+
+```rust
+┌────────────────┐
+│ my_config.rhai │
+└────────────────┘
+
+config_set_id("hello");
+
+config_add("foo");          // add to list
+config_add("bar", true);    // add to map
+
+if config_contains("hey") || config_is_set("hey") {
+    config_add("baz", false);   // add to map
+}
+```
+
+### Load the configuration
+
+```rust
+import "my_config";         // run configuration script without creating a module
+
+let id = config_get_id();
+
+id == "hello";
+```
+
+
+Consider a Custom Syntax
+------------------------
+
+This is probably one of the few scenarios where a [custom syntax] can be recommended.
+
+A properly-designed [custom syntax] can make the configuration file clean, simple to write,
+easy to understand and quick to modify.
+
+For example, the above configuration example may be expressed by this custom syntax:
+
+```rust
+┌────────────────┐
+│ my_config.rhai │
+└────────────────┘
+
+// Configure ID
+id "hello";
+
+// Add to list
+list + "foo";
+
+// Add to map
+map "bar" => true;
+
+if config contains "hey" || config is_set "hey" {
+    map "baz" => false;
+}
+```
+
+Notice that `contains` and `is_set` may also be implemented as a [custom operator].