From 762072685d33c6f28b30e48f2c0752c26c1d0733 Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Tue, 6 Oct 2020 22:35:27 +0800 Subject: [PATCH] Move script optimization into separate section. --- doc/src/SUMMARY.md | 43 +++++++++++++++--------------- doc/src/advanced.md | 2 -- doc/src/language/modules/export.md | 10 +++++++ doc/src/language/modules/import.md | 6 +++++ doc/src/language/modules/index.md | 12 +++------ doc/src/links.md | 6 ++--- doc/src/rust/modules/ast.md | 5 +++- doc/src/rust/modules/index.md | 14 ++++++++++ doc/src/rust/modules/resolvers.md | 2 ++ 9 files changed, 65 insertions(+), 35 deletions(-) create mode 100644 doc/src/rust/modules/index.md diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index f8e279cc..9b6f1fc5 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -45,7 +45,12 @@ The Rhai Scripting Language 1. [Built-in Packages](rust/packages/builtin.md) 2. [Load a Plugin Module as a Package](rust/packages/plugin.md) 3. [Manually Create a Custom Package](rust/packages/create.md) - 10. [Plugins](plugins/index.md) + 10. [Modules](rust/modules/index.md) + 1. [Create from Rust](rust/modules/create.md) + 2. [Create from AST](rust/modules/ast.md) + 3. [Module Resolvers](rust/modules/resolvers.md) + 1. [Custom Implementation](rust/modules/imp-resolver.md) + 11. [Plugins](plugins/index.md) 1. [Export a Rust Module](plugins/module.md) 2. [Export a Rust Function](plugins/function.md) 5. [Rhai Language Reference](language/index.md) @@ -89,10 +94,6 @@ The Rhai Scripting Language 17. [Modules](language/modules/index.md) 1. [Export Variables, Functions and Sub-Modules](language/modules/export.md) 2. [Import Modules](language/modules/import.md) - 3. [Create from Rust](rust/modules/create.md) - 4. [Create from AST](rust/modules/ast.md) - 5. [Module Resolvers](rust/modules/resolvers.md) - 1. [Custom Implementation](rust/modules/imp-resolver.md) 18. [Eval Statement](language/eval.md) 6. [Safety and Protection](safety/index.md) 1. [Checked Arithmetic](safety/checked.md) @@ -105,29 +106,29 @@ The Rhai Scripting Language 7. [Maximum Number of Modules](safety/max-modules.md) 8. [Maximum Call Stack Depth](safety/max-call-stack.md) 9. [Maximum Statement Depth](safety/max-stmt-depth.md) -7. [Usage Patterns](patterns/index.md) +7. [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) +8. [Usage Patterns](patterns/index.md) 1. [Object-Oriented Programming (OOP)](patterns/oop.md) 2. [Loadable Configuration](patterns/config.md) 3. [Control Layer](patterns/control.md) 4. [Singleton Command](patterns/singleton.md) 5. [One Engine Instance Per Call](patterns/parallel.md) 6. [Scriptable Event Handler with State](patterns/events.md) -8. [Advanced Topics](advanced.md) +9. [Advanced Topics](advanced.md) 1. [Capture Scope for Function Call](language/fn-capture.md) - 2. [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. [Low-Level API](rust/register-raw.md) - 4. [Use as DSL](engine/dsl.md) + 2. [Low-Level API](rust/register-raw.md) + 3. [Use as DSL](engine/dsl.md) 1. [Disable Keywords and/or Operators](engine/disable.md) 2. [Custom Operators](engine/custom-op.md) 3. [Extending with Custom Syntax](engine/custom-syntax.md) - 5. [Multiple Instantiation](patterns/multiple.md) -9. [Appendix](appendix/index.md) - 1. [Keywords](appendix/keywords.md) - 2. [Operators and Symbols](appendix/operators.md) - 3. [Literals](appendix/literals.md) + 4. [Multiple Instantiation](patterns/multiple.md) +10. [Appendix](appendix/index.md) + 1. [Keywords](appendix/keywords.md) + 2. [Operators and Symbols](appendix/operators.md) + 3. [Literals](appendix/literals.md) diff --git a/doc/src/advanced.md b/doc/src/advanced.md index 482ae621..7ed51620 100644 --- a/doc/src/advanced.md +++ b/doc/src/advanced.md @@ -11,8 +11,6 @@ This section covers advanced features such as: * [`serde`] integration. -* [Script optimization]. - * Low-level [function registration API]({{rootUrl}}/rust/register-raw.md) * [Domain-Specific Languages][DSL]. diff --git a/doc/src/language/modules/export.md b/doc/src/language/modules/export.md index aaa8eb2d..70977290 100644 --- a/doc/src/language/modules/export.md +++ b/doc/src/language/modules/export.md @@ -4,6 +4,16 @@ Export Variables, Functions and Sub-Modules in Module {{#include ../../links.md}} +The easiest way to expose a package of functions as a self-contained [module] is to do it via a Rhai script itself. + +See the section on [_Creating a Module from AST_]({{rootUrl}}/rust/modules/ast.md) for more details. + +The script text is evaluated, variables are then selectively exposed via the [`export`] statement. +Functions defined by the script are automatically exported. + +Modules loaded within this module at the global level become _sub-modules_ and are also automatically exported. + + Export Global Variables ---------------------- diff --git a/doc/src/language/modules/import.md b/doc/src/language/modules/import.md index b592ff74..44ee5412 100644 --- a/doc/src/language/modules/import.md +++ b/doc/src/language/modules/import.md @@ -4,6 +4,12 @@ Import a Module {{#include ../../links.md}} +Before a module can be used (via an `import` statement) in a script, there must be a [module resolver] +registered into the [`Engine`], the default being the `FileModuleResolver`. + +See the section on [_Module Resolvers_][module resolver] for more details. + + `import` Statement ----------------- diff --git a/doc/src/language/modules/index.md b/doc/src/language/modules/index.md index cac54f3d..9df73faf 100644 --- a/doc/src/language/modules/index.md +++ b/doc/src/language/modules/index.md @@ -6,13 +6,9 @@ Modules Rhai allows organizing code (functions, both Rust-based or script-based, and variables) into _modules_. Modules can be disabled via the [`no_module`] feature. -A module is of the type `Module` and encapsulates a Rhai script together with the functions defined -by that script. +A module is of the type `Module` and holds a collection of functions, variables, iterators and sub-modules. +It may be created entirely from Rust functions, or it may encapsulate a Rhai script together with the functions +and variables defined by that script. -The script text is run, variables are then selectively exposed via the [`export`] statement. -Functions defined by the script are automatically exported. - -Modules loaded within this module at the global level become _sub-modules_ and are also automatically exported. - -Other scripts can then load this module and use the variables and functions exported +Other scripts can then load this module and use the functions and variables exported as if they were defined inside the same script. diff --git a/doc/src/links.md b/doc/src/links.md index ac7f1f4a..54826c66 100644 --- a/doc/src/links.md +++ b/doc/src/links.md @@ -102,9 +102,9 @@ [anonymous functions]: {{rootUrl}}/language/fn-anon.md [operator overloading]: {{rootUrl}}/rust/operators.md -[`Module`]: {{rootUrl}}/language/modules/index.md -[module]: {{rootUrl}}/language/modules/index.md -[modules]: {{rootUrl}}/language/modules/index.md +[`Module`]: {{rootUrl}}/rust/modules/index.md +[module]: {{rootUrl}}/rust/modules/index.md +[modules]: {{rootUrl}}/rust/modules/index.md [module resolver]: {{rootUrl}}/rust/modules/resolvers.md [`export`]: {{rootUrl}}/language/modules/export.md [`import`]: {{rootUrl}}/language/modules/import.md diff --git a/doc/src/rust/modules/ast.md b/doc/src/rust/modules/ast.md index 51f1b187..1410fa20 100644 --- a/doc/src/rust/modules/ast.md +++ b/doc/src/rust/modules/ast.md @@ -10,9 +10,12 @@ Create a Module from an AST A _module_ can be created from a single script (or pre-compiled [`AST`]) containing global variables, functions and sub-modules via the `Module::eval_ast_as_new` method. +See the section on [_Exporting Variables, Functions and Sub-Modules_][`export`] for details on how to prepare +a Rhai script for this purpose as well as to control which functions/variables to export. + When given an [`AST`], it is first evaluated, then the following items are exposed as members of the new module: -* Global variables - essentially all variables that remain in the [`Scope`] at the end of a script run - that are exported. Variables not exported (via the `export` statement) remain hidden. +* Global variables - all variables exported via the `export` statement (those not exported remain hidden). * Functions not specifically marked `private`. diff --git a/doc/src/rust/modules/index.md b/doc/src/rust/modules/index.md new file mode 100644 index 00000000..9df73faf --- /dev/null +++ b/doc/src/rust/modules/index.md @@ -0,0 +1,14 @@ +Modules +======= + +{{#include ../../links.md}} + +Rhai allows organizing code (functions, both Rust-based or script-based, and variables) into _modules_. +Modules can be disabled via the [`no_module`] feature. + +A module is of the type `Module` and holds a collection of functions, variables, iterators and sub-modules. +It may be created entirely from Rust functions, or it may encapsulate a Rhai script together with the functions +and variables defined by that script. + +Other scripts can then load this module and use the functions and variables exported +as if they were defined inside the same script. diff --git a/doc/src/rust/modules/resolvers.md b/doc/src/rust/modules/resolvers.md index abca9c27..961110cd 100644 --- a/doc/src/rust/modules/resolvers.md +++ b/doc/src/rust/modules/resolvers.md @@ -5,6 +5,8 @@ Module Resolvers When encountering an [`import`] statement, Rhai attempts to _resolve_ the module based on the path string. +See the section on [_Importing Modules_][`import`] for more details. + _Module Resolvers_ are service types that implement the [`ModuleResolver`][traits] trait.