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

Refine doc comments.

Browse Source
This commit is contained in:
Stephen Chung 2022-03-01 15:34:15 +08:00
parent 99ca6de822
commit 83755bf936
7 changed files with 81 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
src/api/mod.rs
View File

@ -16,6 +16,8 @@ pub mod call_fn;
pub mod options;
pub mod optimize;
pub mod limits;
pub mod events;
@ -59,83 +61,6 @@ pub mod default_limits {
pub const MAX_DYNAMIC_PARAMETERS: usize = 16;
}
/// Script optimization API.
#[cfg(not(feature = "no_optimize"))]
impl Engine {
/// Control whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
///
/// Not available under `no_optimize`.
#[inline(always)]
pub fn set_optimization_level(
&mut self,
optimization_level: crate::OptimizationLevel,
) -> &mut Self {
self.optimization_level = optimization_level;
self
}
/// The current optimization level.
/// It controls whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
///
/// Not available under `no_optimize`.
#[inline(always)]
#[must_use]
pub const fn optimization_level(&self) -> crate::OptimizationLevel {
self.optimization_level
}
/// Optimize the [`AST`][crate::AST] with constants defined in an external Scope.
/// An optimized copy of the [`AST`][crate::AST] is returned while the original [`AST`][crate::AST]
/// is consumed.
///
/// Not available under `no_optimize`.
///
/// Although optimization is performed by default during compilation, sometimes it is necessary
/// to _re_-optimize an [`AST`][crate::AST].
///
/// For example, when working with constants that are passed in via an external scope, it will
/// be more efficient to optimize the [`AST`][crate::AST] once again to take advantage of the
/// new constants.
///
/// With this method, it is no longer necessary to recompile a large script. The script
/// [`AST`][crate::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]).
///
/// Then, the [`AST`][crate::AST] is cloned and the copy re-optimized before running.
#[inline]
#[must_use]
pub fn optimize_ast(
&self,
scope: &crate::Scope,
ast: crate::AST,
optimization_level: crate::OptimizationLevel,
) -> crate::AST {
let mut ast = ast;
#[cfg(not(feature = "no_function"))]
let lib = ast
.shared_lib()
.iter_fn()
.filter(|f| f.func.is_script())
.map(|f| {
f.func
.get_script_fn_def()
.expect("script-defined function")
.clone()
})
.collect();
crate::optimizer::optimize_into_ast(
self,
scope,
ast.take_statements(),
#[cfg(not(feature = "no_function"))]
lib,
optimization_level,
)
}
}
impl Engine {
/// Set the module resolution service used by the [`Engine`].
///
@ -149,6 +74,7 @@ impl Engine {
self.module_resolver = Some(Box::new(resolver));
self
}
/// Disable a particular keyword or operator in the language.
///
/// # Examples
@ -190,6 +116,7 @@ impl Engine {
self.disabled_symbols.insert(symbol.into());
self
}
/// Register a custom operator with a precedence into the language.
///
/// The operator can be a valid identifier, a reserved symbol, a disabled operator or a disabled keyword.

76
src/api/optimize.rs Normal file
View File

@ -0,0 +1,76 @@
//! Module that defines the script optimization API of [`Engine`].
#![cfg(not(feature = "no_optimize"))]
use crate::{Engine, OptimizationLevel, Scope, AST};
impl Engine {
/// Control whether and how the [`Engine`] will optimize an [`AST`] after compilation.
///
/// Not available under `no_optimize`.
#[inline(always)]
pub fn set_optimization_level(&mut self, optimization_level: OptimizationLevel) -> &mut Self {
self.optimization_level = optimization_level;
self
}
/// The current optimization level.
/// It controls whether and how the [`Engine`] will optimize an [`AST`] after compilation.
///
/// Not available under `no_optimize`.
#[inline(always)]
#[must_use]
pub const fn optimization_level(&self) -> OptimizationLevel {
self.optimization_level
}
/// Optimize the [`AST`] with constants defined in an external Scope.
/// An optimized copy of the [`AST`] is returned while the original [`AST`] is consumed.
///
/// Not available under `no_optimize`.
///
/// Although optimization is performed by default during compilation, sometimes it is necessary
/// to _re_-optimize an [`AST`].
///
/// For example, when working with constants that are passed in via an external scope,
/// it will be more efficient to optimize the [`AST`] once again to take advantage of the new constants.
///
/// 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`][Scope::push_constant]).
///
/// Then, the [`AST`] is cloned and the copy re-optimized before running.
#[inline]
#[must_use]
pub fn optimize_ast(
&self,
scope: &Scope,
ast: AST,
optimization_level: OptimizationLevel,
) -> AST {
let mut ast = ast;
#[cfg(not(feature = "no_function"))]
let lib = ast
.shared_lib()
.iter_fn()
.filter(|f| f.func.is_script())
.map(|f| {
f.func
.get_script_fn_def()
.expect("script-defined function")
.clone()
})
.collect();
crate::optimizer::optimize_into_ast(
self,
scope,
ast.take_statements(),
#[cfg(not(feature = "no_function"))]
lib,
optimization_level,
)
}
}

10
src/ast/expr.rs
View File

@ -168,8 +168,6 @@ impl FnCallHashes {
#[derive(Clone, Default, Hash)]
pub struct FnCallExpr {
/// Namespace of the function, if any.
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
pub namespace: Option<crate::module::Namespace>,
/// Function name.
@ -369,8 +367,6 @@ pub enum Expr {
/// Integer constant.
IntegerConstant(INT, Position),
/// Floating-point constant.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
FloatConstant(FloatWrapper<crate::FLOAT>, Position),
/// Character constant.
@ -575,11 +571,7 @@ impl Expr {
if !x.is_qualified() && x.args.len() == 1 && x.name == KEYWORD_FN_PTR =>
{
if let Expr::StringConstant(ref s, ..) = x.args[0] {
if let Ok(fn_ptr) = FnPtr::new(s) {
fn_ptr.into()
} else {
return None;
}
FnPtr::new(s).ok()?.into()
} else {
return None;
}

2
src/ast/script_fn.rs
View File

@ -34,8 +34,6 @@ pub struct ScriptFnDef {
/// Function body.
pub body: StmtBlock,
/// Encapsulated AST environment, if any.
///
/// Not available under `no_module` or `no_function`.
#[cfg(not(feature = "no_module"))]
#[cfg(not(feature = "no_function"))]
pub environ: Option<EncapsulatedEnviron>,

4
src/eval/global_state.rs
View File

@ -24,13 +24,9 @@ pub type GlobalConstants =
#[derive(Clone)]
pub struct GlobalRuntimeState<'a> {
/// Stack of module names.
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
keys: crate::StaticVec<Identifier>,
/// Stack of imported [modules][crate::Module].
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
modules: crate::StaticVec<crate::Shared<crate::Module>>,
/// Source of the current context.

2
src/func/callable_function.rs
View File

@ -21,8 +21,6 @@ pub enum CallableFunction {
/// A plugin function,
Plugin(Shared<FnPlugin>),
/// A script-defined function.
///
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
Script(Shared<crate::ast::ScriptFnDef>),
}

14
src/types/dynamic.rs
View File

@ -162,8 +162,6 @@ pub enum Union {
/// An integer value.
Int(INT, Tag, AccessMode),
/// A floating-point value.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
Float(crate::ast::FloatWrapper<crate::FLOAT>, Tag, AccessMode),
/// _(decimal)_ A fixed-precision decimal value.
@ -171,25 +169,17 @@ pub enum Union {
#[cfg(feature = "decimal")]
Decimal(Box<rust_decimal::Decimal>, Tag, AccessMode),
/// An array value.
///
/// Not available under `no_index`.
#[cfg(not(feature = "no_index"))]
Array(Box<crate::Array>, Tag, AccessMode),
/// An blob (byte array).
///
/// Not available under `no_index`.
#[cfg(not(feature = "no_index"))]
Blob(Box<crate::Blob>, Tag, AccessMode),
/// An object map value.
///
/// Not available under `no_object`.
#[cfg(not(feature = "no_object"))]
Map(Box<crate::Map>, Tag, AccessMode),
/// A function pointer.
FnPtr(Box<FnPtr>, Tag, AccessMode),
/// A timestamp value.
///
/// Not available under `no-std`.
#[cfg(not(feature = "no_std"))]
TimeStamp(Box<Instant>, Tag, AccessMode),
@ -198,8 +188,6 @@ pub enum Union {
Variant(Box<Box<dyn Variant>>, Tag, AccessMode),
/// A _shared_ value of any type.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
Shared(crate::Shared<crate::Locked<Dynamic>>, Tag, AccessMode),
}
@ -256,8 +244,6 @@ enum DynamicWriteLockInner<'d, T: Clone> {
Reference(&'d mut T),
/// A write guard to a shared value.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
Guard(crate::func::native::LockGuard<'d, Dynamic>),
}