From 83755bf936d25129d280112543207b8062d596dc Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Tue, 1 Mar 2022 15:34:15 +0800 Subject: [PATCH] Refine doc comments. --- src/api/mod.rs | 81 ++--------------------------------- src/api/optimize.rs | 76 ++++++++++++++++++++++++++++++++ src/ast/expr.rs | 10 +---- src/ast/script_fn.rs | 2 - src/eval/global_state.rs | 4 -- src/func/callable_function.rs | 2 - src/types/dynamic.rs | 14 ------ 7 files changed, 81 insertions(+), 108 deletions(-) create mode 100644 src/api/optimize.rs diff --git a/src/api/mod.rs b/src/api/mod.rs index 17730cce..85e2d0f0 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -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. diff --git a/src/api/optimize.rs b/src/api/optimize.rs new file mode 100644 index 00000000..7589c2fd --- /dev/null +++ b/src/api/optimize.rs @@ -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, + ) + } +} diff --git a/src/ast/expr.rs b/src/ast/expr.rs index 9e90f8b1..07fc028c 100644 --- a/src/ast/expr.rs +++ b/src/ast/expr.rs @@ -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, /// 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, 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; } diff --git a/src/ast/script_fn.rs b/src/ast/script_fn.rs index 4c103cf7..3d810492 100644 --- a/src/ast/script_fn.rs +++ b/src/ast/script_fn.rs @@ -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, diff --git a/src/eval/global_state.rs b/src/eval/global_state.rs index b15fa6ab..1363f108 100644 --- a/src/eval/global_state.rs +++ b/src/eval/global_state.rs @@ -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, /// Stack of imported [modules][crate::Module]. - /// - /// Not available under `no_module`. #[cfg(not(feature = "no_module"))] modules: crate::StaticVec>, /// Source of the current context. diff --git a/src/func/callable_function.rs b/src/func/callable_function.rs index 86e4d4f3..1480840d 100644 --- a/src/func/callable_function.rs +++ b/src/func/callable_function.rs @@ -21,8 +21,6 @@ pub enum CallableFunction { /// A plugin function, Plugin(Shared), /// A script-defined function. - /// - /// Not available under `no_function`. #[cfg(not(feature = "no_function"))] Script(Shared), } diff --git a/src/types/dynamic.rs b/src/types/dynamic.rs index abf7f346..d50d530e 100644 --- a/src/types/dynamic.rs +++ b/src/types/dynamic.rs @@ -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, Tag, AccessMode), /// _(decimal)_ A fixed-precision decimal value. @@ -171,25 +169,17 @@ pub enum Union { #[cfg(feature = "decimal")] Decimal(Box, Tag, AccessMode), /// An array value. - /// - /// Not available under `no_index`. #[cfg(not(feature = "no_index"))] Array(Box, Tag, AccessMode), /// An blob (byte array). - /// - /// Not available under `no_index`. #[cfg(not(feature = "no_index"))] Blob(Box, Tag, AccessMode), /// An object map value. - /// - /// Not available under `no_object`. #[cfg(not(feature = "no_object"))] Map(Box, Tag, AccessMode), /// A function pointer. FnPtr(Box, Tag, AccessMode), /// A timestamp value. - /// - /// Not available under `no-std`. #[cfg(not(feature = "no_std"))] TimeStamp(Box, Tag, AccessMode), @@ -198,8 +188,6 @@ pub enum Union { Variant(Box>, Tag, AccessMode), /// A _shared_ value of any type. - /// - /// Not available under `no_closure`. #[cfg(not(feature = "no_closure"))] Shared(crate::Shared>, 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>), }