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

Refine API for contexts.

Browse Source
This commit is contained in:
Stephen Chung 2021-01-01 17:05:06 +08:00
parent 70f79d5402
commit 0a69caaf6d
8 changed files with 100 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/src/engine/custom-syntax.md
View File

@ -116,18 +116,20 @@ The function signature of an implementation is:
where:
| Parameter | Type | Description |
| -------------------------- | :-----------------------------: | ------------------------------------------------------------------------------------- |
| `context` | `&mut EvalContext` | mutable reference to the current evaluation _context_ |
| • `scope()` | `&Scope` | reference to the current [`Scope`] |
| • `scope_mut()` | `&mut Scope` | mutable reference to the current [`Scope`]; variables can be added to/removed from it |
| • `engine()` | `&Engine` | reference to the current [`Engine`] |
| &bull; `source()` | `Option<&str>` | reference to the current source, if any |
| &bull; `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements |
| &bull; `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| &bull; `this_ptr()` | `Option<&Dynamic>` | reference to the current bound [`this`] pointer, if any |
| &bull; `call_level()` | `usize` | the current nesting level of function calls |
| `inputs` | `&[Expression]` | a list of input expression trees |
| Parameter | Type | Description |
| -------------------------- | :-------------------------------------: | ---------------------------------------------------------------------------------------------------------------------- |
| `context` | `&mut EvalContext` | mutable reference to the current evaluation _context_ |
| &bull; `scope()` | `&Scope` | reference to the current [`Scope`] |
| &bull; `scope_mut()` | `&mut &mut Scope` | mutable reference to the current [`Scope`]; variables can be added to/removed from it |
| &bull; `engine()` | `&Engine` | reference to the current [`Engine`] |
| &bull; `source()` | `Option<&str>` | reference to the current source, if any |
| &bull; `iter_imports()` | `impl Iterator<Item = (&str, &Module)>` | iterator of the current stack of [modules] imported via `import` statements |
| &bull; `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements; requires the [`internals`] feature |
| &bull; `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| &bull; `namespaces()` | `&[&Module]` | reference to the namespaces (as [modules]) containing all script-defined functions; requires the [`internals`] feature |
| &bull; `this_ptr()` | `Option<&Dynamic>` | reference to the current bound [`this`] pointer, if any |
| &bull; `call_level()` | `usize` | the current nesting level of function calls |
| `inputs` | `&[Expression]` | a list of input expression trees |
### Return Value

26
doc/src/engine/var.md
View File

@ -67,18 +67,20 @@ The function signature passed to `Engine::on_var` takes the following form:
where:
| Parameter | Type | Description |
| -------------------------- | :-----------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `&str` | variable name |
| `index` | `usize` | an offset from the bottom of the current [`Scope`] that the variable is supposed to reside.<br/>Offsets start from 1, with 1 meaning the last variable in the current [`Scope`]. Essentially the correct variable is at position `scope.len() - index`.<br/>If `index` is zero, then there is no pre-calculated offset position and a search through the current [`Scope`] must be performed. |
| `context` | `&EvalContext` | reference to the current evaluation _context_ |
| &bull; `scope()` | `&Scope` | reference to the current [`Scope`] |
| &bull; `engine()` | `&Engine` | reference to the current [`Engine`] |
| &bull; `source()` | `Option<&str>` | reference to the current source, if any |
| &bull; `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements |
| &bull; `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| &bull; `this_ptr()` | `Option<&Dynamic>` | reference to the current bound [`this`] pointer, if any |
| &bull; `call_level()` | `usize` | the current nesting level of function calls |
| Parameter | Type | Description |
| -------------------------- | :-------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `&str` | variable name |
| `index` | `usize` | an offset from the bottom of the current [`Scope`] that the variable is supposed to reside.<br/>Offsets start from 1, with 1 meaning the last variable in the current [`Scope`]. Essentially the correct variable is at position `scope.len() - index`.<br/>If `index` is zero, then there is no pre-calculated offset position and a search through the current [`Scope`] must be performed. |
| `context` | `&EvalContext` | reference to the current evaluation _context_ |
| &bull; `scope()` | `&Scope` | reference to the current [`Scope`] |
| &bull; `engine()` | `&Engine` | reference to the current [`Engine`] |
| &bull; `source()` | `Option<&str>` | reference to the current source, if any |
| &bull; `iter_imports()` | `impl Iterator<Item = (&str, &Module)>` | iterator of the current stack of [modules] imported via `import` statements |
| &bull; `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements; requires the [`internals`] feature |
| &bull; `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| &bull; `namespaces()` | `&[&Module]` | reference to the namespaces (as [modules]) containing all script-defined functions; requires the [`internals`] feature |
| &bull; `this_ptr()` | `Option<&Dynamic>` | reference to the current bound [`this`] pointer, if any |
| &bull; `call_level()` | `usize` | the current nesting level of function calls |
### Return Value

14
doc/src/language/fn-ptr.md
View File

@ -225,12 +225,14 @@ engine.register_raw_fn("super_call",
`FnPtr::call_dynamic` takes a parameter of type `NativeCallContext` which holds the _native call context_
of the particular call to a registered Rust function. It is a type that exposes the following:
| Field | Type | Description |
| ------------------- | :-----------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| `source()` | `Option<&str>` | reference to the current source, if any |
| `imports()` | `Option<&Imports>` | reference to the current stack of [modules] imported via `import` statements (if any) |
| `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| Field | Type | Description |
| ------------------- | :-------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| `source()` | `Option<&str>` | reference to the current source, if any |
| `iter_imports()` | `impl Iterator<Item = (&str, &Module)>` | iterator of the current stack of [modules] imported via `import` statements |
| `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements; requires the [`internals`] feature |
| `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| `namespaces()` | `&[&Module]` | reference to the namespaces (as [modules]) containing all script-defined functions; requires the [`internals`] feature |
This type is normally provided by the [`Engine`] (e.g. when using [`Engine::register_fn_raw`](../rust/register-raw.md)).

14
doc/src/plugins/function.md
View File

@ -86,12 +86,14 @@ specially by the plugins system.
`NativeCallContext` is a type that encapsulates the current _native call context_ and exposes the following:
| Field | Type | Description |
| ------------------- | :-----------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| `source()` | `Option<&str>` | reference to the current source, if any |
| `imports()` | `Option<&Imports>` | reference to the current stack of [modules] imported via `import` statements (if any) |
| `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| Field | Type | Description |
| ------------------- | :-------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| `source()` | `Option<&str>` | reference to the current source, if any |
| `iter_imports()` | `impl Iterator<Item = (&str, &Module)>` | iterator of the current stack of [modules] imported via `import` statements |
| `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements; requires the [`internals`] feature |
| `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| `namespaces()` | `&[&Module]` | reference to the namespaces (as [modules]) containing all script-defined functions; requires the [`internals`] feature |
This first parameter, if exists, will be stripped before all other processing. It is _virtual_.
Most importantly, it does _not_ count as a parameter to the function and there is no need to provide

14
doc/src/plugins/module.md
View File

@ -399,12 +399,14 @@ specially by the plugins system.
`NativeCallContext` is a type that encapsulates the current _native call context_ and exposes the following:
| Field | Type | Description |
| ------------------- | :-----------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| `source()` | `Option<&str>` | reference to the current source, if any |
| `imports()` | `Option<&Imports>` | reference to the current stack of [modules] imported via `import` statements (if any) |
| `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| Field | Type | Description |
| ------------------- | :-------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| `source()` | `Option<&str>` | reference to the current source, if any |
| `iter_imports()` | `impl Iterator<Item = (&str, &Module)>` | iterator of the current stack of [modules] imported via `import` statements |
| `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements; requires the [`internals`] feature |
| `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| `namespaces()` | `&[&Module]` | reference to the namespaces (as [modules]) containing all script-defined functions; requires the [`internals`] feature |
This first parameter, if exists, will be stripped before all other processing. It is _virtual_.
Most importantly, it does _not_ count as a parameter to the function and there is no need to provide

20
doc/src/rust/register-raw.md
View File

@ -65,15 +65,17 @@ The function signature passed to `Engine::register_raw_fn` takes the following f
where:
| Parameter | Type | Description |
| -------------------------- | :-----------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `T` | `impl Clone` | return type of the function |
| `context` | `NativeCallContext` | the current _native call context_ |
| &bull; `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| &bull; `source()` | `Option<&str>` | reference to the current source, if any |
| &bull; `imports()` | `Option<&Imports>` | reference to the current stack of [modules] imported via `import` statements (if any) |
| &bull; `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| `args` | `&mut [&mut Dynamic]` | a slice containing `&mut` references to [`Dynamic`] values.<br/>The slice is guaranteed to contain enough arguments _of the correct types_. |
| Parameter | Type | Description |
| -------------------------- | :-------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `T` | `impl Clone` | return type of the function |
| `context` | `NativeCallContext` | the current _native call context_ |
| &bull; `engine()` | `&Engine` | the current [`Engine`], with all configurations and settings.<br/>This is sometimes useful for calling a script-defined function within the same evaluation context using [`Engine::call_fn`][`call_fn`], or calling a [function pointer]. |
| &bull; `source()` | `Option<&str>` | reference to the current source, if any |
| &bull; `iter_imports()` | `impl Iterator<Item = (&str, &Module)>` | iterator of the current stack of [modules] imported via `import` statements |
| &bull; `imports()` | `&Imports` | reference to the current stack of [modules] imported via `import` statements; requires the [`internals`] feature |
| &bull; `iter_namespaces()` | `impl Iterator<Item = &Module>` | iterator of the namespaces (as [modules]) containing all script-defined functions |
| &bull; `namespaces()` | `&[&Module]` | reference to the namespaces (as [modules]) containing all script-defined functions; requires the [`internals`] feature |
| `args` | `&mut [&mut Dynamic]` | a slice containing `&mut` references to [`Dynamic`] values.<br/>The slice is guaranteed to contain enough arguments _of the correct types_. |
### Return value

29
src/engine.rs
View File

@ -96,7 +96,7 @@ impl Imports {
/// Get an iterator to this stack of imported [modules][Module] in reverse order.
#[allow(dead_code)]
#[inline(always)]
pub fn iter<'a>(&'a self) -> impl Iterator<Item = (&'a str, &'a Module)> + 'a {
pub fn iter(&self) -> impl Iterator<Item = (&str, &Module)> {
self.0
.iter()
.rev()
@ -105,9 +105,7 @@ impl Imports {
/// Get an iterator to this stack of imported [modules][Module] in reverse order.
#[allow(dead_code)]
#[inline(always)]
pub(crate) fn iter_raw<'a>(
&'a self,
) -> impl Iterator<Item = (&'a ImmutableString, &'a Shared<Module>)> + 'a {
pub(crate) fn iter_raw(&self) -> impl Iterator<Item = (&ImmutableString, &Shared<Module>)> {
self.0.iter().rev().map(|(n, m)| (n, m))
}
/// Get a consuming iterator to this stack of imported [modules][Module] in reverse order.
@ -575,17 +573,17 @@ pub struct EvalContext<'e, 'x, 'px: 'x, 'a, 's, 'm, 'pm: 'm, 't, 'pt: 't> {
impl<'e, 'x, 'px, 'a, 's, 'm, 'pm, 't, 'pt> EvalContext<'e, 'x, 'px, 'a, 's, 'm, 'pm, 't, 'pt> {
/// The current [`Engine`].
#[inline(always)]
pub fn engine(&self) -> &'e Engine {
pub fn engine(&self) -> &Engine {
self.engine
}
/// The current source.
#[inline(always)]
pub fn source<'z: 's>(&'z self) -> Option<&'s str> {
pub fn source(&self) -> Option<&str> {
self.state.source.as_ref().map(|s| s.as_str())
}
/// The current [`Scope`].
#[inline(always)]
pub fn scope(&self) -> &Scope<'px> {
pub fn scope(&self) -> &Scope {
self.scope
}
/// Mutable reference to the current [`Scope`].
@ -593,19 +591,32 @@ impl<'e, 'x, 'px, 'a, 's, 'm, 'pm, 't, 'pt> EvalContext<'e, 'x, 'px, 'a, 's, 'm,
pub fn scope_mut(&mut self) -> &mut &'x mut Scope<'px> {
&mut self.scope
}
/// Get an iterator over the current set of modules imported via `import` statements.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub fn iter_imports(&self) -> impl Iterator<Item = (&str, &Module)> {
self.mods.iter()
}
/// _(INTERNALS)_ The current set of modules imported via `import` statements.
/// Available under the `internals` feature only.
#[cfg(feature = "internals")]
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub fn imports(&'a self) -> &'a Imports {
pub fn imports(&self) -> &Imports {
self.mods
}
/// Get an iterator over the namespaces containing definition of all script-defined functions.
#[inline(always)]
pub fn iter_namespaces(&self) -> impl Iterator<Item = &'pm Module> + 'm {
pub fn iter_namespaces(&self) -> impl Iterator<Item = &Module> {
self.lib.iter().cloned()
}
/// _(INTERNALS)_ The current set of namespaces containing definitions of all script-defined functions.
/// Available under the `internals` feature only.
#[cfg(feature = "internals")]
#[inline(always)]
pub fn namespaces(&self) -> &[&Module] {
self.lib
}
/// The current bound `this` pointer, if any.
#[inline(always)]
pub fn this_ptr(&self) -> Option<&Dynamic> {

21
src/fn_native.rs
View File

@ -121,14 +121,20 @@ impl<'e, 's, 'a, 'm, 'pm> NativeCallContext<'e, 's, 'a, 'm, 'pm> {
}
/// The current [`Engine`].
#[inline(always)]
pub fn engine(&self) -> &'e Engine {
pub fn engine(&self) -> &Engine {
self.engine
}
/// The current source.
#[inline(always)]
pub fn source<'z: 's>(&'z self) -> Option<&'s str> {
pub fn source(&self) -> Option<&str> {
self.source
}
/// Get an iterator over the current set of modules imported via `import` statements.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub fn iter_imports(&self) -> impl Iterator<Item = (&str, &Module)> {
self.mods.iter().flat_map(|m| m.iter())
}
/// _(INTERNALS)_ The current set of modules imported via `import` statements.
/// Available under the `internals` feature only.
#[cfg(feature = "internals")]
@ -137,11 +143,18 @@ impl<'e, 's, 'a, 'm, 'pm> NativeCallContext<'e, 's, 'a, 'm, 'pm> {
pub fn imports(&self) -> Option<&Imports> {
self.mods
}
/// Get an iterator over the namespaces containing definition of all script-defined functions.
/// Get an iterator over the namespaces containing definitions of all script-defined functions.
#[inline(always)]
pub fn iter_namespaces(&self) -> impl Iterator<Item = &'pm Module> + 'm {
pub fn iter_namespaces(&self) -> impl Iterator<Item = &Module> {
self.lib.iter().cloned()
}
/// _(INTERNALS)_ The current set of namespaces containing definitions of all script-defined functions.
/// Available under the `internals` feature only.
#[cfg(feature = "internals")]
#[inline(always)]
pub fn namespaces(&self) -> &[&Module] {
self.lib
}
/// Call a function inside the call context.
///
/// ## WARNING