reorganize module

_archive/rhai_engine/rhaibook/engine/raw.md

@@ -0,0 +1,76 @@
+Raw `Engine`
+============
+
+{{#include ../links.md}}
+
+`Engine::new` creates a scripting [`Engine`] with common functionalities (e.g. printing to `stdout`
+via [`print`] or [`debug`]).
+
+In many controlled embedded environments, however, these may not be needed and unnecessarily occupy
+application code storage space.
+
+```admonish info.side.wide "Built-in operators"
+
+Even with a raw [`Engine`], some operators are built-in and always available.
+
+See [_Built-in Operators_][built-in operators] for a full list.
+```
+
+Use `Engine::new_raw` to create a _raw_ [`Engine`], in which only a minimal set of
+[built-in][built-in operators] basic arithmetic and logical operators are supported.
+
+To add more functionalities to a _raw_ [`Engine`], load [packages] into it.
+
+Since [packages] can be _shared_, this is an extremely efficient way to create multiple instances of
+the same [`Engine`] with the same set of functions.
+
+|                       |    `Engine::new`     | `Engine::new_raw` |
+| --------------------- | :------------------: | :---------------: |
+| [Built-in operators]  |         yes          |        yes        |
+| [Package] loaded      |  `StandardPackage`   |      _none_       |
+| [Module resolver]     | `FileModuleResolver` |      _none_       |
+| [Strings interner]    |         yes          |       _no_        |
+| [`on_print`][`print`] |         yes          |      _none_       |
+| [`on_debug`][`debug`] |         yes          |      _none_       |
+
+
+```admonish warning.small "Warning: No strings interner"
+
+A _raw_ [`Engine`] disables the _[strings interner]_ by default.
+
+This may lead to a significant increase in memory usage if many strings are created in scripts.
+
+Turn the _[strings interner]_ back on via [`Engine::set_max_strings_interned`][options].
+```
+
+~~~admonish example "`Engine::new` is equivalent to..."
+```rust
+use rhai::module_resolvers::FileModuleResolver;
+use rhai::packages::StandardPackage;
+
+// Create a raw scripting Engine
+let mut engine = Engine::new_raw();
+
+// Use the file-based module resolver
+engine.set_module_resolver(FileModuleResolver::new());
+
+// Enable the strings interner
+engine.set_max_strings_interned(1024);
+
+// Default print/debug implementations
+engine.on_print(|text| println!("{text}"));
+
+engine.on_debug(|text, source, pos| match (source, pos) {
+    (Some(source), Position::NONE) => println!("{source} | {text}"),
+    (Some(source), pos) => println!("{source} @ {pos:?} | {text}"),
+    (None, Position::NONE) => println!("{text}"),
+    (None, pos) => println!("{pos:?} | {text}"),
+});
+
+// Register the Standard Package
+let package = StandardPackage::new();
+
+// Load the package into the [`Engine`]
+package.register_into_engine(&mut engine);
+```
+~~~