From 88f63fa24b9776e84a1fb03595c48c4b93e09c2c Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Sat, 26 Dec 2020 23:21:16 +0800 Subject: [PATCH] Refine docs. --- doc/src/SUMMARY.md | 23 +++++++++++++---------- doc/src/about/related.md | 10 ++++++++-- doc/src/engine/call-fn.md | 4 ++-- doc/src/engine/custom-op.md | 17 +++++++++++++---- doc/src/rust/modules/ast.md | 16 +++++++++------- doc/src/rust/override.md | 13 +++++++------ doc/src/tools/index.md | 6 ++++++ doc/src/tools/playground.md | 15 +++++++++++++++ doc/src/tools/rhai-doc.md | 6 ++++++ examples/arrays_and_structs.rs | 2 +- examples/rhai-repl.rs | 2 +- src/ast.rs | 10 +++++----- src/engine.rs | 7 +++---- src/engine_api.rs | 21 ++++++++++++--------- src/module/mod.rs | 14 +++++++++++--- src/optimize.rs | 8 ++++---- 16 files changed, 116 insertions(+), 58 deletions(-) create mode 100644 doc/src/tools/index.md create mode 100644 doc/src/tools/playground.md create mode 100644 doc/src/tools/rhai-doc.md diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 45c199df..4b3e7e30 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -127,19 +127,22 @@ The Rhai Scripting Language 7. [One Engine Instance Per Call](patterns/parallel.md) 8. [Scriptable Event Handler with State](patterns/events.md) 9. [Dynamic Constants Provider](patterns/dynamic-const.md) -9. [Advanced Topics](advanced.md) - 10. [Capture Scope for Function Call](language/fn-capture.md) - 11. [Low-Level API](rust/register-raw.md) - 12. [Variable Resolver](engine/var.md) - 13. [Use as DSL](engine/dsl.md) +9. [Advanced Topics](advanced.md) + 1. [Capture Scope for Function Call](language/fn-capture.md) + 2. [Low-Level API](rust/register-raw.md) + 3. [Variable Resolver](engine/var.md) + 4. [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) - 14. [Multiple Instantiation](patterns/multiple.md) - 15. [Functions Metadata](engine/metadata/index.md) - 4. [Generate Function Signatures](engine/metadata/gen_fn_sig.md) - 5. [Export Metadata to JSON](engine/metadata/export_to_json.md) -10. [Appendix](appendix/index.md) + 5. [Multiple Instantiation](patterns/multiple.md) + 6. [Functions Metadata](engine/metadata/index.md) + 1. [Generate Function Signatures](engine/metadata/gen_fn_sig.md) + 2. [Export Metadata to JSON](engine/metadata/export_to_json.md) +10. [External Tools](tools/index.md) + 1. [Online Playground](tools/playground.md) + 2. [`rhai-doc`](tools/rhai-doc.md) +11. [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/about/related.md b/doc/src/about/related.md index 9b55003b..0f29cb16 100644 --- a/doc/src/about/related.md +++ b/doc/src/about/related.md @@ -15,13 +15,19 @@ Online Resources for Rhai * [`LIB.RS`](https://lib.rs/crates/rhai) - Rhai library info -* [Online Playground][playground] - Run scripts directly from editor - * [Discord Chat](https://discord.gg/HquqbYFcZ9) - Rhai channel * [Reddit](https://www.reddit.com/r/Rhai) - Rhai community +External Tools +-------------- + +* [Online Playground][playground] - Run Rhai scripts directly from an editor in the browser + +* [`rhai-doc`] - Rhai script documentation tool + + Other Cool Projects ------------------- diff --git a/doc/src/engine/call-fn.md b/doc/src/engine/call-fn.md index a68925ac..466ec1ee 100644 --- a/doc/src/engine/call-fn.md +++ b/doc/src/engine/call-fn.md @@ -41,8 +41,8 @@ let mut scope = Scope::new(); // If arguments of the wrong types are passed, the Engine will not find the function. let result: i64 = engine.call_fn(&mut scope, &ast, "hello", ( String::from("abc"), 123_i64 ) )?; -// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -// put arguments in a tuple +// ^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +// return type must be specified put arguments in a tuple let result: i64 = engine.call_fn(&mut scope, &ast, "hello", (123_i64,) )?; // ^^^^^^^^^^ tuple of one diff --git a/doc/src/engine/custom-op.md b/doc/src/engine/custom-op.md index e2a118e9..3dacfa9d 100644 --- a/doc/src/engine/custom-op.md +++ b/doc/src/engine/custom-op.md @@ -6,7 +6,8 @@ Custom Operators For use as a DSL (Domain-Specific Languages), it is sometimes more convenient to augment Rhai with customized operators performing specific logic. -`Engine::register_custom_operator` registers a keyword as a custom operator. +`Engine::register_custom_operator` registers a keyword as a custom operator, giving it a particular +_precedence_ (which cannot be zero). Example @@ -52,15 +53,23 @@ into a syntax that uses the corresponding function calls. Using `Engine::register_custom_operator` merely enables a convenient shortcut. -Must Follow Variable Naming --------------------------- +Must be a Valid Identifier or Reserved Symbol +-------------------------------------------- All custom operators must be _identifiers_ that follow the same naming rules as [variables]. +Alternatively, they can also be [reserved symbols]({{rootUrl}}/appendix/operators.md#symbols), +[disabled operators or keywords][disable keywords and operators]. + ```rust engine.register_custom_operator("foo", 20); // 'foo' is a valid custom operator -engine.register_custom_operator("=>", 30); // <- error: '=>' is not a valid custom operator +engine.register_custom_operator("#", 20); // the reserved symbol '#' is also + // a valid custom operator + +engine.register_custom_operator("+", 30); // <- error: '+' is an active operator + +engine.register_custom_operator("=>", 30); // <- error: '=>' is an active symbol ``` diff --git a/doc/src/rust/modules/ast.md b/doc/src/rust/modules/ast.md index 1410fa20..80dd7c5a 100644 --- a/doc/src/rust/modules/ast.md +++ b/doc/src/rust/modules/ast.md @@ -7,22 +7,24 @@ Create a Module from an AST `Module::eval_ast_as_new` ------------------------ -A _module_ can be created from a single script (or pre-compiled [`AST`]) containing global variables, +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. +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: +When given an [`AST`], it is first evaluated, then the following items are exposed as members of the +new [module]: * Global variables - all variables exported via the `export` statement (those not exported remain hidden). * Functions not specifically marked `private`. -* Global modules that remain in the [`Scope`] at the end of a script run. +* Global modules that remain in the [`Scope`] at the end of a script run (become sub-modules). -`Module::eval_ast_as_new` encapsulates the entire `AST` into each function call, merging the module namespace -with the global namespace. Therefore, functions defined within the same module script can cross-call each other. +`Module::eval_ast_as_new` encapsulates the entire `AST` into each function call, merging the +module namespace with the global namespace. Therefore, functions defined within the same module +script can cross-call each other. Examples diff --git a/doc/src/rust/override.md b/doc/src/rust/override.md index f6d4d656..7620bfd5 100644 --- a/doc/src/rust/override.md +++ b/doc/src/rust/override.md @@ -3,18 +3,19 @@ Override a Built-in Function {{#include ../links.md}} -Any similarly-named function defined in a script overrides any built-in or registered +Any similarly-named function defined in a script _overrides_ any built-in or registered native Rust function of the same name and number of parameters. ```rust -// Override the built-in function 'to_int' -fn to_int(num) { - print("Ha! Gotcha! " + num); +// Override the built-in function 'to_float' when called as a method +fn to_float() { + print("Ha! Gotcha! " + this); + 42.0 } -let x = (123).to_int(); +let x = 123.to_float(); -print(x); // what happens? +print(x); // what happens? ``` A registered native Rust function, in turn, overrides any built-in function of the diff --git a/doc/src/tools/index.md b/doc/src/tools/index.md new file mode 100644 index 00000000..9b9eff01 --- /dev/null +++ b/doc/src/tools/index.md @@ -0,0 +1,6 @@ +External Tools +============== + +{{#include ../links.md}} + +External tools available to work with Rhai. diff --git a/doc/src/tools/playground.md b/doc/src/tools/playground.md new file mode 100644 index 00000000..91507a3d --- /dev/null +++ b/doc/src/tools/playground.md @@ -0,0 +1,15 @@ +Online Playground +================= + +{{#include ../links.md}} + + +The Online Playground runs off a [WASM] build of Rhai and allows evaluating +Rhai scripts directly within a browser editor window. + + +Author : [`@alvinhochun`](https://github.com/alvinhochun) + +Repo : [On GitHub](https://github.com/alvinhochun/rhai-playground) + +URL : [Link to Online Playground][playground] diff --git a/doc/src/tools/rhai-doc.md b/doc/src/tools/rhai-doc.md new file mode 100644 index 00000000..fd32be6a --- /dev/null +++ b/doc/src/tools/rhai-doc.md @@ -0,0 +1,6 @@ +Rhai Script Documentation Tool +============================= + +{{#include ../links.md}} + +<< TODO >> \ No newline at end of file diff --git a/examples/arrays_and_structs.rs b/examples/arrays_and_structs.rs index 75137dac..094a7d08 100644 --- a/examples/arrays_and_structs.rs +++ b/examples/arrays_and_structs.rs @@ -1,4 +1,4 @@ -use rhai::{Engine, RegisterFn, INT}; +use rhai::{Engine, EvalAltResult, RegisterFn, INT}; #[derive(Debug, Clone)] struct TestStruct { diff --git a/examples/rhai-repl.rs b/examples/rhai-repl.rs index 6e4d2719..f60a0a81 100644 --- a/examples/rhai-repl.rs +++ b/examples/rhai-repl.rs @@ -43,7 +43,7 @@ fn print_help() { println!("quit, exit => quit"); println!("scope => print all variables in the scope"); println!("functions => print all functions defined"); - println!("ast => print the last AST"); + println!("ast => print the last AST (optimized)"); println!("astu => print the last raw, un-optimized AST"); println!(r"end a line with '\' to continue to the next line."); println!(); diff --git a/src/ast.rs b/src/ast.rs index 702a1ad5..21e36b56 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -736,7 +736,7 @@ impl Stmt { _ => false, } } - /// Get the [position][`Position`] of this statement. + /// Get the [position][Position] of this statement. pub fn position(&self) -> Position { match self { Self::Noop(pos) @@ -765,7 +765,7 @@ impl Stmt { Self::Share(x) => x.pos, } } - /// Override the [position][`Position`] of this statement. + /// Override the [position][Position] of this statement. pub fn set_position(&mut self, new_pos: Position) -> &mut Self { match self { Self::Noop(pos) @@ -973,7 +973,7 @@ pub enum Expr { Property(Box<(ImmutableString, ImmutableString, Ident)>), /// { [statement][Stmt] } Stmt(Box>, Position), - /// Wrapped [expression][`Expr`] - should not be optimized away. + /// Wrapped [expression][Expr] - should not be optimized away. Expr(Box), /// func `(` expr `,` ... `)` FnCall(Box, Position), @@ -1052,7 +1052,7 @@ impl Expr { _ => None, } } - /// Get the [position][`Position`] of the expression. + /// Get the [position][Position] of the expression. pub fn position(&self) -> Position { match self { Self::Expr(x) => x.position(), @@ -1082,7 +1082,7 @@ impl Expr { Self::Custom(_, pos) => *pos, } } - /// Override the [position][`Position`] of the expression. + /// Override the [position][Position] of the expression. pub fn set_position(&mut self, new_pos: Position) -> &mut Self { match self { Self::Expr(x) => { diff --git a/src/engine.rs b/src/engine.rs index c3396a83..012578c9 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -19,8 +19,7 @@ use crate::stdlib::{ fmt, format, hash::{Hash, Hasher}, iter::{empty, once, FromIterator}, - num::NonZeroU64, - num::NonZeroUsize, + num::{NonZeroU64, NonZeroU8, NonZeroUsize}, ops::DerefMut, string::{String, ToString}, }; @@ -637,7 +636,7 @@ pub struct Engine { /// A hashset containing symbols to disable. pub(crate) disabled_symbols: HashSet, /// A hashmap containing custom keywords and precedence to recognize. - pub(crate) custom_keywords: HashMap>, + pub(crate) custom_keywords: HashMap>, /// Custom syntax. pub(crate) custom_syntax: HashMap, /// Callback closure for resolving variable access. @@ -989,7 +988,7 @@ impl Engine { new_val: Option<(Dynamic, Position)>, ) -> Result<(Dynamic, bool), Box> { if chain_type == ChainType::None { - panic!(); + unreachable!(); } let is_ref = target.is_ref(); diff --git a/src/engine_api.rs b/src/engine_api.rs index a5720708..026e0df8 100644 --- a/src/engine_api.rs +++ b/src/engine_api.rs @@ -723,21 +723,22 @@ impl Engine { self.register_indexer_get(getter) .register_indexer_set(setter) } - /// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`]. + /// Register a shared [`Module`] into the global namespace of [`Engine`]. /// - /// All functions and type iterators are automatically available to scripts without namespace qualifications. + /// All functions and type iterators are automatically available to scripts without namespace + /// qualifications. /// /// Sub-modules and variables are **ignored**. /// - /// When searching for functions, modules loaded later are preferred. - /// In other words, loaded modules are searched in reverse order. + /// When searching for functions, modules loaded later are preferred. In other words, loaded + /// modules are searched in reverse order. #[inline(always)] pub fn register_global_module(&mut self, module: Shared) -> &mut Self { // Insert the module into the front self.global_modules.insert(0, module); self } - /// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`]. + /// Register a shared [`Module`] into the global namespace of [`Engine`]. /// /// ## Deprecated /// @@ -747,9 +748,11 @@ impl Engine { pub fn load_package(&mut self, module: impl Into>) -> &mut Self { self.register_global_module(module.into()) } - /// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`]. + /// Register a shared [`Module`] as a static module namespace with the + /// [`Engine`]. /// - /// Functions marked `FnNamespace::Global` and type iterators are exposed to scripts without namespace qualifications. + /// Functions marked [`FnNamespace::Global`] and type iterators are exposed to scripts without + /// namespace qualifications. /// /// # Example /// @@ -825,7 +828,7 @@ impl Engine { self } - /// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`]. + /// Register a shared [`Module`] as a static module namespace with the [`Engine`]. /// /// ## Deprecated /// @@ -1719,7 +1722,7 @@ impl Engine { /// With this method, it is no longer necessary to recompile a large script. /// The script [`AST`] can be compiled just once. Before evaluation, /// constants are passed into the [`Engine`] via an external scope - /// (i.e. with [`scope.push_constant(...)`][crate::Scope::push_constant]). + /// (i.e. with [`Scope::push_constant`]). /// Then, the [`AST`] is cloned and the copy re-optimized before running. #[cfg(not(feature = "no_optimize"))] #[inline] diff --git a/src/module/mod.rs b/src/module/mod.rs index 95b079ae..92c7b8fb 100644 --- a/src/module/mod.rs +++ b/src/module/mod.rs @@ -356,7 +356,7 @@ impl Module { self.get_var(name).and_then(Dynamic::try_cast::) } - /// Get a module variable as a [`Dynamic`][crate::Dynamic]. + /// Get a module variable as a [`Dynamic`]. /// /// # Example /// @@ -466,10 +466,18 @@ impl Module { } /// Get a mutable reference to the underlying [`HashMap`] of sub-modules. + /// + /// ## Warning + /// + /// By taking a mutable reference, it is assumed that some sub-modules will be modified. + /// Thus the module is automatically set to be non-indexed. #[inline(always)] pub(crate) fn sub_modules_mut(&mut self) -> &mut HashMap> { // We must assume that the user has changed the sub-modules // (otherwise why take a mutable reference?) + self.all_functions.clear(); + self.all_variables.clear(); + self.all_type_iterators.clear(); self.indexed = false; &mut self.modules @@ -652,7 +660,7 @@ impl Module { } /// Set a Rust function taking a reference to the scripting [`Engine`][crate::Engine], - /// the current set of functions, plus a list of mutable [`Dynamic`][crate::Dynamic] references + /// the current set of functions, plus a list of mutable [`Dynamic`] references /// into the module, returning a hash key. /// /// Use this to register a built-in function which must reference settings on the scripting @@ -667,7 +675,7 @@ impl Module { /// /// A list of [`TypeId`]'s is taken as the argument types. /// - /// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][crate::Dynamic], + /// Arguments are simply passed in as a mutable array of [`&mut Dynamic`], /// which is guaranteed to contain enough arguments of the correct types. /// /// The function is assumed to be a _method_, meaning that the first argument should not be consumed. diff --git a/src/optimize.rs b/src/optimize.rs index d6e3099f..07d16642 100644 --- a/src/optimize.rs +++ b/src/optimize.rs @@ -152,7 +152,7 @@ fn call_fn_with_constant_arguments( .map(|(v, _)| v) } -/// Optimize a block of [statements][crate::ast::Stmt]. +/// Optimize a block of [statements][Stmt]. fn optimize_stmt_block( mut statements: Vec, pos: Position, @@ -277,7 +277,7 @@ fn optimize_stmt_block( } } -/// Optimize a [statement][crate::ast::Stmt]. +/// Optimize a [statement][Stmt]. fn optimize_stmt(stmt: &mut Stmt, state: &mut State, preserve_result: bool) { match stmt { // expr op= expr @@ -473,7 +473,7 @@ fn optimize_stmt(stmt: &mut Stmt, state: &mut State, preserve_result: bool) { } } -/// Optimize an [expression][crate::ast::Expr]. +/// Optimize an [expression][Expr]. fn optimize_expr(expr: &mut Expr, state: &mut State) { // These keywords are handled specially const DONT_EVAL_KEYWORDS: &[&str] = &[ @@ -737,7 +737,7 @@ fn optimize_expr(expr: &mut Expr, state: &mut State) { } } -/// Optimize a block of [statements][crate::ast::Stmt] at top level. +/// Optimize a block of [statements][Stmt] at top level. fn optimize_top_level( mut statements: Vec, engine: &Engine,