reorganize module

_archive/rhai_engine/rhaibook/start/bin.md

@@ -0,0 +1,121 @@
+Packaged Utilities
+==================
+
+{{#include ../links.md}}
+
+A number of Rhai-driven tools can be found in the `src/bin` directory:
+
+```admonish tip.side "Tip: Domain-specific tools"
+
+It is possible to turn these tools into [_Domain-Specific Tools_](../patterns/domain-tools.md).
+```
+
+|                       Tool                       | Required feature(s) | Description            |
+| :----------------------------------------------: | :-----------------: | ---------------------- |
+|  [`rhai-run`]({{repoHome}}/src/bin/rhai-run.rs)  |                     | runs Rhai script files |
+| [`rhai-repl`]({{repoHome}}/src/bin/rhai-repl.rs) |     `rustyline`     | a simple REPL tool     |
+|  [`rhai-dbg`]({{repoHome}}/src/bin/rhai-dbg.rs)  |    [`debugging`]    | the _Rhai Debugger_    |
+
+~~~admonish tip "Tip: `bin-features`"
+Some bin tools require certain [features] and will not be built by default without those [features] set.
+
+For convenience, a feature named [`bin-features`][features] is available which is a combination of
+the following:
+
+|    Feature    | Description                                 |
+| :-----------: | ------------------------------------------- |
+|  [`decimal`]  | support for [decimal][rust_decimal] numbers |
+| [`metadata`]  | access [functions metadata]                 |
+|   [`serde`]   | export [functions metadata] to JSON         |
+| [`debugging`] | required by `rhai-dbg`                      |
+|  `rustyline`  | required by `rhai-repl`                     |
+~~~
+
+
+Install Tools
+-------------
+
+To install all these tools (with full features), use the following command:
+
+```sh
+cargo install --path . --bins  --features bin-features
+```
+
+or specifically:
+
+```sh
+cargo install --path . --bin sample_app_to_run  --features bin-features
+```
+
+
+Run a Tool from Cargo
+---------------------
+
+Tools can also be run with the following `cargo` command:
+
+```sh
+cargo run --features bin-features --bin sample_app_to_run
+```
+
+
+Tools List
+----------
+
+~~~admonish example "`rhai-repl` – The Rhai REPL Tool"
+
+`rhai-repl` is a particularly useful tool – it allows one to interactively try out
+Rhai's language features in a standard REPL (**R**ead-**E**val-**P**rint **L**oop).
+
+Filenames passed to it as command line arguments are run and loaded as Rhai scripts before the REPL starts.
+
+### Test functions
+
+The following test functions are pre-registered, via `Engine::register_fn`, into `rhai-repl`.
+They are intended for testing purposes.
+
+| Function                             | Description                                |
+| ------------------------------------ | ------------------------------------------ |
+| `test(x: i64, y: i64)`               | returns a string with both numbers         |
+| `test(x: &mut i64, y: i64, z: &str)` | displays the parameters and add `y` to `x` |
+
+### Example
+
+The following command first runs three scripts – `init1.rhai`, `init2.rhai` and `init3.rhai` –
+loading the functions defined in each script into the _global_ namespace.
+
+Then it enters an REPL, which can call the above functions freely.
+
+```sh
+rhai-repl init1.rhai init2.rhai init3.rhai
+```
+~~~
+
+~~~admonish danger "`rhai-run` – The Rhai Runner"
+
+Use `rhai-run` to run Rhai scripts.
+
+Filenames passed to it as command line arguments are run in sequence as Rhai scripts.
+
+### Example
+
+The following command runs the scripts `script1.rhai`, `script2.rhai` and `script3.rhai` in order.
+
+```sh
+rhai-run script1.rhai script2.rhai script3.rhai
+```
+~~~
+
+~~~admonish bug "`rhai-dbg` – The Rhai Debugger"
+
+Use `rhai-dbg` to debug a Rhai script.
+
+Filename passed to it will be loaded as a Rhai script for debugging.
+
+### Example
+
+The following command debugs the script `my_script.rhai`.
+
+```sh
+rhai-dbg my_script.rhai
+```
+~~~