kjuulh/rhai
1
0
Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity

Refine docs.

Browse Source
This commit is contained in:
Stephen Chung 2020-12-26 23:21:16 +08:00
parent 66d3af256e
commit 88f63fa24b
16 changed files with 116 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/src/SUMMARY.md
View File

@ -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)

10
doc/src/about/related.md
View File

@ -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
-------------------

4
doc/src/engine/call-fn.md
View File

@ -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

17
doc/src/engine/custom-op.md
View File

@ -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
```

16
doc/src/rust/modules/ast.md
View File

@ -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

13
doc/src/rust/override.md
View File

@ -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

6
doc/src/tools/index.md Normal file
View File

@ -0,0 +1,6 @@
External Tools
==============
{{#include ../links.md}}
External tools available to work with Rhai.

15
doc/src/tools/playground.md Normal file
View File

@ -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]

6
doc/src/tools/rhai-doc.md Normal file
View File

@ -0,0 +1,6 @@
Rhai Script Documentation Tool
=============================
{{#include ../links.md}}
<< TODO >>

2
examples/arrays_and_structs.rs
View File

@ -1,4 +1,4 @@
use rhai::{Engine, RegisterFn, INT};
use rhai::{Engine, EvalAltResult, RegisterFn, INT};
#[derive(Debug, Clone)]
struct TestStruct {

2
examples/rhai-repl.rs
View File

@ -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!();

10
src/ast.rs
View File

@ -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<StaticVec<Stmt>>, Position),
/// Wrapped [expression][`Expr`] - should not be optimized away.
/// Wrapped [expression][Expr] - should not be optimized away.
Expr(Box<Expr>),
/// func `(` expr `,` ... `)`
FnCall(Box<FnCallExpr>, 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) => {

7
src/engine.rs
View File

@ -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<String>,
/// A hashmap containing custom keywords and precedence to recognize.
pub(crate) custom_keywords: HashMap<String, Option<u8>>,
pub(crate) custom_keywords: HashMap<String, Option<NonZeroU8>>,
/// Custom syntax.
pub(crate) custom_syntax: HashMap<ImmutableString, CustomSyntax>,
/// Callback closure for resolving variable access.
@ -989,7 +988,7 @@ impl Engine {
new_val: Option<(Dynamic, Position)>,
) -> Result<(Dynamic, bool), Box<EvalAltResult>> {
if chain_type == ChainType::None {
panic!();
unreachable!();
}
let is_ref = target.is_ref();

21
src/engine_api.rs
View File

@ -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<Module>) -> &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<Shared<Module>>) -> &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]

14
src/module/mod.rs
View File

@ -356,7 +356,7 @@ impl Module {
self.get_var(name).and_then(Dynamic::try_cast::<T>)
}
/// 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<ImmutableString, Shared<Module>> {
// 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.

8
src/optimize.rs
View File

@ -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<Stmt>,
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<Stmt>,
engine: &Engine,