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

Merge pull request #330 from schungx/master

Browse Source 
Update playground link.
This commit is contained in:
Stephen Chung 2021-01-12 10:34:31 +08:00 committed by GitHub
commit bbd83ba201
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 161 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -78,7 +78,7 @@ Running `mdbook build` builds it.
Playground
----------
An [Online Playground](https://alvinhochun.github.io/rhai-demo/) is available with syntax-highlighting editor.
An [Online Playground](https://rhaiscript.github.io/playground) is available with syntax-highlighting editor.
Scripts can be evaluated directly from the editor.

8
RELEASES.md
View File

@ -4,6 +4,11 @@ Rhai Release Notes
Version 0.19.10
===============
Bug fixes
---------
* Bug in `FileModuleResolver::clear_cache_for_path` path mapping fixed.
Breaking changes
----------------
@ -15,7 +20,7 @@ Breaking changes
New features
------------
* `Engine::compile_to_self_contained` compiles a script into an `AST` and _eagerly_ resolves all `import` statements with string literal paths. The resolved modules are directly embedded into the `AST`. When the `AST` is later evaluated, `import` statements directly yield the pre-resolved modules without going through the resolution process once again.
* `Engine::compile_into_self_contained` compiles a script into an `AST` and _eagerly_ resolves all `import` statements with string literal paths. The resolved modules are directly embedded into the `AST`. When the `AST` is later evaluated, `import` statements directly yield the pre-resolved modules without going through the resolution process once again.
* `AST::walk`, `Stmt::walk` and `Expr::walk` internal API's to recursively walk an `AST`.
Enhancements
@ -24,6 +29,7 @@ Enhancements
* Source information is provided when there is an error within a call to a function defined in another module.
* Source information is provided to the `NativeCallContext` for native Rust functions.
* `EvalAltResult::clear_position` to clear the position information of an error - useful when only the message is needed and the position doesn't need to be printed out.
* A new optional function `resolve_ast` is added to the `ModuleResolver` trait for advanced usage.
Version 0.19.9

10
codegen/src/lib.rs
View File

@ -1,4 +1,4 @@
//! This crate contains procedural macros to make creating Rhai plugin-modules much easier.
//! This crate contains procedural macros to make creating Rhai plugin modules much easier.
//!
//! # Export an Entire Rust Module to a Rhai `Module`
//!
@ -184,7 +184,7 @@ pub fn export_module(
proc_macro::TokenStream::from(tokens)
}
/// Macro to generate a Rhai `Module` from a _plugin module_ defined via `#[export_module]`.
/// Macro to generate a Rhai `Module` from a _plugin module_ defined via [`#[export_module]`][export_module].
///
/// # Usage
///
@ -223,8 +223,8 @@ pub fn exported_module(module_path: proc_macro::TokenStream) -> proc_macro::Toke
/// Functions and variables in the plugin module overrides any existing similarly-named
/// functions and variables in the target module.
///
/// This call is intended to be used within the `def_package!` macro to define a custom
/// package based on a plugin module.
/// This call is intended to be used within the [`def_package!`][crate::def_package] macro to define
/// a custom package based on a plugin module.
///
/// All sub-modules, if any, in the plugin module are _flattened_ and their functions/variables
/// registered at the top level because packages require so.
@ -269,7 +269,7 @@ pub fn combine_with_exported_module(args: proc_macro::TokenStream) -> proc_macro
proc_macro::TokenStream::from(tokens)
}
/// Macro to register a _plugin function_ (defined via `#[export_fn]`) into an `Engine`.
/// Macro to register a _plugin function_ (defined via [`#[export_fn]`][export_fn]) into an `Engine`.
///
/// # Usage
///

12
src/ast.rs
View File

@ -295,7 +295,7 @@ impl AST {
) -> Option<Shared<crate::module::resolvers::StaticModuleResolver>> {
self.resolver.clone()
}
/// _(INTERNALS)_ Get the embedded [module resolver][`ModuleResolver`].
/// _(INTERNALS)_ Get the embedded [module resolver][crate::ModuleResolver].
/// Exported under the `internals` feature only.
#[cfg(not(feature = "no_module"))]
#[cfg(feature = "internals")]
@ -318,7 +318,7 @@ impl AST {
///
/// This operation is cheap because functions are shared.
///
/// Not available under [`no_function`].
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn clone_functions_only(&self) -> Self {
@ -329,7 +329,7 @@ impl AST {
///
/// This operation is cheap because functions are shared.
///
/// Not available under [`no_function`].
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn clone_functions_only_filtered(
@ -614,7 +614,7 @@ impl AST {
}
/// Filter out the functions, retaining only some based on a filter predicate.
///
/// Not available under [`no_function`].
/// Not available under `no_function`.
///
/// # Example
///
@ -661,7 +661,7 @@ impl AST {
}
/// Iterate through all function definitions.
///
/// Not available under [`no_function`].
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn iter_functions<'a>(&'a self) -> impl Iterator<Item = ScriptFnMetadata> + 'a {
@ -671,7 +671,7 @@ impl AST {
}
/// Clear all function definitions in the [`AST`].
///
/// Not available under [`no_function`].
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn clear_functions(&mut self) {

2
src/dynamic.rs
View File

@ -266,6 +266,8 @@ impl Dynamic {
}
}
/// Is the value held by this [`Dynamic`] shared?
///
/// Always [`false`] under the `no_closure` feature.
#[inline(always)]
pub fn is_shared(&self) -> bool {
match self.0 {

12
src/engine_api.rs
View File

@ -936,11 +936,15 @@ impl Engine {
while let Some(path) = imports.iter().next() {
let path = path.clone();
if let Some(module_ast) =
self.module_resolver
.resolve_ast(self, &path, Position::NONE)?
match self
.module_resolver
.resolve_ast(self, &path, Position::NONE)
{
collect_imports(&module_ast, &mut resolver, &mut imports);
Some(Ok(module_ast)) => {
collect_imports(&module_ast, &mut resolver, &mut imports)
}
Some(err @ Err(_)) => return err,
None => (),
}
let module = shared_take_or_clone(self.module_resolver.resolve(

104
src/module/mod.rs
View File

@ -168,27 +168,48 @@ impl fmt::Debug for Module {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"Module({}\n modules: {}\n vars: {}\n functions: {}\n)",
"Module({}\n{}{}{})",
if let Some(ref id) = self.id {
format!("id: {:?}", id)
format!("id: {:?},", id)
} else {
"".to_string()
},
if !self.modules.is_empty() {
format!(
" modules: {}\n",
self.modules
.keys()
.map(|m| m.as_str())
.collect::<Vec<_>>()
.join(", "),
.join(", ")
)
} else {
"".to_string()
},
if !self.variables.is_empty() {
format!(
" vars: {}\n",
self.variables
.iter()
.map(|(k, v)| format!("{}={:?}", k, v))
.collect::<Vec<_>>()
.join(", "),
.join(", ")
)
} else {
"".to_string()
},
if !self.functions.is_empty() {
format!(
" functions: {}\n",
self.functions
.values()
.map(|FuncInfo { func, .. }| func.to_string())
.collect::<Vec<_>>()
.join(", "),
.join(", ")
)
} else {
"".to_string()
}
)
}
}
@ -200,6 +221,31 @@ impl AsRef<Module> for Module {
}
}
impl<M: AsRef<Module>> Add<M> for &Module {
type Output = Module;
fn add(self, rhs: M) -> Self::Output {
let mut module = self.clone();
module.merge(rhs.as_ref());
module
}
}
impl<M: AsRef<Module>> Add<M> for Module {
type Output = Self;
fn add(mut self, rhs: M) -> Self::Output {
self.merge(rhs.as_ref());
self
}
}
impl<M: Into<Module>> AddAssign<M> for Module {
fn add_assign(&mut self, rhs: M) {
self.combine(rhs.into());
}
}
impl Module {
/// Create a new [`Module`].
///
@ -1962,13 +2008,16 @@ impl Module {
///
/// This type is volatile and may change.
#[derive(Clone, Eq, PartialEq, Default, Hash)]
pub struct NamespaceRef(Option<NonZeroUsize>, StaticVec<Ident>);
pub struct NamespaceRef {
index: Option<NonZeroUsize>,
path: StaticVec<Ident>,
}
impl fmt::Debug for NamespaceRef {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Debug::fmt(&self.1, f)?;
fmt::Debug::fmt(&self.path, f)?;
if let Some(index) = self.0 {
if let Some(index) = self.index {
write!(f, " -> {}", index)
} else {
Ok(())
@ -1980,19 +2029,19 @@ impl Deref for NamespaceRef {
type Target = StaticVec<Ident>;
fn deref(&self) -> &Self::Target {
&self.1
&self.path
}
}
impl DerefMut for NamespaceRef {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.1
&mut self.path
}
}
impl fmt::Display for NamespaceRef {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
for Ident { name, .. } in self.1.iter() {
for Ident { name, .. } in self.path.iter() {
write!(f, "{}{}", name, Token::DoubleColon.syntax())?;
}
Ok(())
@ -2000,45 +2049,20 @@ impl fmt::Display for NamespaceRef {
}
impl From<StaticVec<Ident>> for NamespaceRef {
fn from(modules: StaticVec<Ident>) -> Self {
Self(None, modules)
}
}
impl<M: AsRef<Module>> Add<M> for &Module {
type Output = Module;
fn add(self, rhs: M) -> Self::Output {
let mut module = self.clone();
module.merge(rhs.as_ref());
module
}
}
impl<M: AsRef<Module>> Add<M> for Module {
type Output = Self;
fn add(mut self, rhs: M) -> Self::Output {
self.merge(rhs.as_ref());
self
}
}
impl<M: Into<Module>> AddAssign<M> for Module {
fn add_assign(&mut self, rhs: M) {
self.combine(rhs.into());
fn from(path: StaticVec<Ident>) -> Self {
Self { index: None, path }
}
}
impl NamespaceRef {
/// Get the [`Scope`][crate::Scope] index offset.
pub(crate) fn index(&self) -> Option<NonZeroUsize> {
self.0
self.index
}
/// Set the [`Scope`][crate::Scope] index offset.
#[cfg(not(feature = "no_module"))]
pub(crate) fn set_index(&mut self, index: Option<NonZeroUsize>) {
self.0 = index
self.index = index
}
}

2
src/module/resolvers/collection.rs
View File

@ -1,7 +1,7 @@
use crate::stdlib::{boxed::Box, ops::AddAssign, vec::Vec};
use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
/// [Module] resolution service that holds a collection of [module][Module] resolves,
/// [Module] resolution service that holds a collection of module resolvers,
/// to be searched in sequential order.
///
/// # Example

69
src/module/resolvers/file.rs
View File

@ -7,15 +7,21 @@ use crate::stdlib::{
};
use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
/// [Module] resolution service that loads [module][Module] script files from the file system.
/// A [module][Module] resolution service that loads [module][Module] script files from the file system.
///
/// Script files are cached so they are are not reloaded and recompiled in subsequent requests.
/// ## Caching
///
/// # Function Namespace
/// Resolved [Modules][Module] are cached internally so script files are not reloaded and recompiled
/// for subsequent requests.
///
/// When a function within a script file module is called, all functions in the _global_ namespace
/// plus all those defined within the same module are _merged_ into a _unified_ namespace before
/// the call. Therefore, functions in a module script can always cross-call each other.
/// Use [`clear_cache`][FileModuleResolver::clear_cache] or
/// [`clear_cache_for_path`][FileModuleResolver::clear_cache_for_path] to clear the internal cache.
///
/// ## Namespace
///
/// When a function within a script file module is called, all functions defined within the same
/// script are available, evan `private` ones. In other words, functions defined in a module script
/// can always cross-call each other.
///
/// # Example
///
@ -146,6 +152,16 @@ impl FileModuleResolver {
self
}
/// Is a particular path cached?
#[inline(always)]
pub fn is_cached(&self, path: &str) -> bool {
let file_path = self.get_file_path(path);
#[cfg(not(feature = "sync"))]
return self.cache.borrow_mut().contains_key(&file_path);
#[cfg(feature = "sync")]
return self.cache.write().unwrap().contains_key(&file_path);
}
/// Empty the internal cache.
#[inline(always)]
pub fn clear_cache(&mut self) {
@ -154,26 +170,34 @@ impl FileModuleResolver {
#[cfg(feature = "sync")]
self.cache.write().unwrap().clear();
}
/// Remove the specified path from internal cache.
///
/// The next time this path is resolved, the script file will be loaded once again.
#[inline(always)]
pub fn clear_cache_for_path(&mut self, path: impl AsRef<Path>) -> Option<Shared<Module>> {
pub fn clear_cache_for_path(&mut self, path: &str) -> Option<Shared<Module>> {
let file_path = self.get_file_path(path);
#[cfg(not(feature = "sync"))]
return self
.cache
.borrow_mut()
.remove_entry(path.as_ref())
.remove_entry(&file_path)
.map(|(_, v)| v);
#[cfg(feature = "sync")]
return self
.cache
.write()
.unwrap()
.remove_entry(path.as_ref())
.remove_entry(&file_path)
.map(|(_, v)| v);
}
/// Construct a full file path.
fn get_file_path(&self, path: &str) -> PathBuf {
let mut file_path = self.base_path.clone();
file_path.push(path);
file_path.set_extension(&self.extension); // Force extension
file_path
}
}
impl ModuleResolver for FileModuleResolver {
@ -184,9 +208,7 @@ impl ModuleResolver for FileModuleResolver {
pos: Position,
) -> Result<Shared<Module>, Box<EvalAltResult>> {
// Construct the script file path
let mut file_path = self.base_path.clone();
file_path.push(path);
file_path.set_extension(&self.extension); // Force extension
let file_path = self.get_file_path(path);
// See if it is cached
{
@ -228,27 +250,30 @@ impl ModuleResolver for FileModuleResolver {
Ok(m)
}
/// Resolve an `AST` based on a path string.
///
/// The file system is accessed during each call; the internal cache is by-passed.
fn resolve_ast(
&self,
engine: &Engine,
path: &str,
pos: Position,
) -> Result<Option<crate::AST>, Box<EvalAltResult>> {
) -> Option<Result<crate::AST, Box<EvalAltResult>>> {
// Construct the script file path
let mut file_path = self.base_path.clone();
file_path.push(path);
file_path.set_extension(&self.extension); // Force extension
let file_path = self.get_file_path(path);
// Load the script file and compile it
let mut ast = engine.compile_file(file_path).map_err(|err| match *err {
match engine.compile_file(file_path).map_err(|err| match *err {
EvalAltResult::ErrorSystem(_, err) if err.is::<IoError>() => {
Box::new(EvalAltResult::ErrorModuleNotFound(path.to_string(), pos))
}
_ => Box::new(EvalAltResult::ErrorInModule(path.to_string(), err, pos)),
})?;
}) {
Ok(mut ast) => {
ast.set_source(path);
Ok(Some(ast))
Some(Ok(ast))
}
err @ Err(_) => Some(err),
}
}
}

6
src/module/resolvers/mod.rs
View File

@ -29,7 +29,7 @@ pub trait ModuleResolver: SendSync {
pos: Position,
) -> Result<Shared<Module>, Box<EvalAltResult>>;
/// Resolve a module into an `AST` based on a path string.
/// Resolve an `AST` based on a path string.
///
/// Returns [`None`] (default) if such resolution is not supported
/// (e.g. if the module is Rust-based).
@ -44,7 +44,7 @@ pub trait ModuleResolver: SendSync {
engine: &Engine,
path: &str,
pos: Position,
) -> Result<Option<AST>, Box<EvalAltResult>> {
Ok(None)
) -> Option<Result<AST, Box<EvalAltResult>>> {
None
}
}

2
src/module/resolvers/stat.rs
View File

@ -1,7 +1,7 @@
use crate::stdlib::{boxed::Box, collections::HashMap, ops::AddAssign, string::String};
use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
/// [Module] resolution service that serves [modules][Module] added into it.
/// A static [module][Module] resolution service that serves [modules][Module] added into it.
///
/// # Example
///

6
src/packages/mod.rs
View File

@ -50,7 +50,7 @@ pub trait Package {
}
}
/// Macro that makes it easy to define a _package_ (which is basically a shared module)
/// Macro that makes it easy to define a _package_ (which is basically a shared [module][Module])
/// and register functions into it.
///
/// Functions can be added to the package using the standard module methods such as
@ -58,6 +58,8 @@ pub trait Package {
///
/// # Example
///
/// Define a package named `MyPackage` with a single function named `my_add`:
///
/// ```
/// use rhai::{Dynamic, EvalAltResult};
/// use rhai::def_package;
@ -70,8 +72,6 @@ pub trait Package {
/// lib.set_fn_2("my_add", add);
/// });
/// ```
///
/// The above defines a package named 'MyPackage' with a single function named 'my_add'.
#[macro_export]
macro_rules! def_package {
($root:ident : $package:ident : $comment:expr , $lib:ident , $block:stmt) => {