rhai/src/engine_settings.rs

273 lines
9.5 KiB
Rust
Raw Normal View History

2020-11-20 09:52:28 +01:00
//! Configuration settings for [`Engine`].
2020-07-05 09:23:51 +02:00
use crate::packages::PackageLibrary;
2020-07-26 09:53:22 +02:00
use crate::stdlib::{format, string::String};
2020-11-16 16:10:14 +01:00
use crate::token::{is_valid_identifier, Token};
use crate::Engine;
2020-07-26 09:53:22 +02:00
#[cfg(not(feature = "no_module"))]
use crate::stdlib::boxed::Box;
2020-07-13 13:38:50 +02:00
2020-07-05 09:23:51 +02:00
impl Engine {
2020-11-20 09:52:28 +01:00
/// Load a new package into the [`Engine`].
/// A simple [`Module`][crate::Module] is automatically converted into a package.
2020-07-05 09:23:51 +02:00
///
/// When searching for functions, packages loaded later are preferred.
/// In other words, loaded packages are searched in reverse order.
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-08-02 12:55:22 +02:00
pub fn load_package(&mut self, package: impl Into<PackageLibrary>) -> &mut Self {
2020-11-15 05:07:35 +01:00
self.packages.add(package.into());
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
2020-11-20 09:52:28 +01:00
/// Control whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
2020-07-05 09:23:51 +02:00
///
/// Not available under the `no_optimize` feature.
#[cfg(not(feature = "no_optimize"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-11-16 09:28:04 +01:00
pub fn set_optimization_level(
&mut self,
optimization_level: crate::OptimizationLevel,
) -> &mut Self {
2020-07-12 05:46:53 +02:00
self.optimization_level = optimization_level;
self
2020-07-05 09:23:51 +02:00
}
/// The current optimization level.
2020-11-20 09:52:28 +01:00
/// It controls whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
2020-07-05 09:23:51 +02:00
///
/// Not available under the `no_optimize` feature.
#[cfg(not(feature = "no_optimize"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-11-16 09:28:04 +01:00
pub fn optimization_level(&self) -> crate::OptimizationLevel {
2020-07-05 09:23:51 +02:00
self.optimization_level
}
/// Set the maximum levels of function calls allowed for a script in order to avoid
/// infinite recursion and stack overflows.
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_call_levels(&mut self, levels: usize) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_call_stack_depth = levels;
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The maximum levels of function calls allowed for a script.
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_call_levels(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_call_stack_depth
2020-07-05 09:23:51 +02:00
}
/// Set the maximum number of operations allowed for a script to run to avoid
/// consuming too much resources (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_operations(&mut self, operations: u64) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_operations = if operations == u64::MAX {
2020-07-05 09:23:51 +02:00
0
} else {
operations
};
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The maximum number of operations allowed for a script to run (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_operations(&self) -> u64 {
2020-11-10 16:26:50 +01:00
self.limits.max_operations
2020-07-05 09:23:51 +02:00
}
/// Set the maximum number of imported modules allowed for a script.
#[cfg(not(feature = "unchecked"))]
2020-10-18 16:10:08 +02:00
#[cfg(not(feature = "no_module"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_modules(&mut self, modules: usize) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_modules = modules;
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The maximum number of imported modules allowed for a script.
#[cfg(not(feature = "unchecked"))]
2020-10-18 16:10:08 +02:00
#[cfg(not(feature = "no_module"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_modules(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_modules
2020-07-05 09:23:51 +02:00
}
/// Set the depth limits for expressions (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_expr_depths(
&mut self,
max_expr_depth: usize,
#[cfg(not(feature = "no_function"))] max_function_expr_depth: usize,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_expr_depth = if max_expr_depth == usize::MAX {
2020-07-05 09:23:51 +02:00
0
} else {
max_expr_depth
};
#[cfg(not(feature = "no_function"))]
{
2020-11-10 16:26:50 +01:00
self.limits.max_function_expr_depth = if max_function_expr_depth == usize::MAX {
0
} else {
max_function_expr_depth
};
}
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The depth limit for expressions (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_expr_depth(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_expr_depth
2020-07-05 09:23:51 +02:00
}
/// The depth limit for expressions in functions (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_function"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_function_expr_depth(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_function_expr_depth
2020-07-05 09:23:51 +02:00
}
/// Set the maximum length of strings (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_string_size(&mut self, max_size: usize) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_string_size = if max_size == usize::MAX { 0 } else { max_size };
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The maximum length of strings (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_string_size(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_string_size
2020-07-05 09:23:51 +02:00
}
/// Set the maximum length of arrays (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_index"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_array_size(&mut self, max_size: usize) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_array_size = if max_size == usize::MAX { 0 } else { max_size };
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The maximum length of arrays (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_index"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_array_size(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_array_size
2020-07-05 09:23:51 +02:00
}
/// Set the maximum length of object maps (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_object"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_max_map_size(&mut self, max_size: usize) -> &mut Self {
2020-11-10 16:26:50 +01:00
self.limits.max_map_size = if max_size == usize::MAX { 0 } else { max_size };
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// The maximum length of object maps (0 for unlimited).
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_object"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-05 09:23:51 +02:00
pub fn max_map_size(&self) -> usize {
2020-11-10 16:26:50 +01:00
self.limits.max_map_size
2020-07-05 09:23:51 +02:00
}
2020-11-20 09:52:28 +01:00
/// Set the module resolution service used by the [`Engine`].
2020-07-05 09:23:51 +02:00
///
/// Not available under the `no_module` feature.
#[cfg(not(feature = "no_module"))]
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn set_module_resolver(
&mut self,
2020-11-16 09:28:04 +01:00
resolver: Option<impl crate::ModuleResolver + 'static>,
2020-07-12 05:46:53 +02:00
) -> &mut Self {
2020-11-16 09:28:04 +01:00
self.module_resolver = resolver.map(|f| Box::new(f) as Box<dyn crate::ModuleResolver>);
2020-07-12 05:46:53 +02:00
self
2020-07-05 09:23:51 +02:00
}
/// Disable a particular keyword or operator in the language.
///
/// # Examples
///
/// The following will raise an error during parsing because the `if` keyword is disabled
/// and is recognized as a variable name!
///
/// ```rust,should_panic
/// # fn main() -> Result<(), rhai::ParseError> {
/// use rhai::Engine;
///
/// let mut engine = Engine::new();
///
/// engine.disable_symbol("if"); // disable the 'if' keyword
///
/// engine.compile("let x = if true { 42 } else { 0 };")?;
/// // ^ 'if' is rejected as a reserved keyword
2020-07-05 09:23:51 +02:00
/// # Ok(())
/// # }
/// ```
///
/// The following will raise an error during parsing because the `+=` operator is disabled.
///
/// ```rust,should_panic
/// # fn main() -> Result<(), rhai::ParseError> {
/// use rhai::Engine;
///
/// let mut engine = Engine::new();
///
/// engine.disable_symbol("+="); // disable the '+=' operator
///
/// engine.compile("let x = 42; x += 1;")?;
/// // ^ unknown operator
/// # Ok(())
/// # }
/// ```
2020-10-08 16:25:50 +02:00
#[inline(always)]
2020-07-12 05:46:53 +02:00
pub fn disable_symbol(&mut self, symbol: &str) -> &mut Self {
2020-10-25 14:57:18 +01:00
self.disabled_symbols.insert(symbol.into());
2020-07-12 05:46:53 +02:00
self
2020-07-05 11:41:45 +02:00
}
/// Register a custom operator into the language.
///
/// The operator must be a valid identifier (i.e. it cannot be a symbol).
///
2020-10-27 04:30:38 +01:00
/// # Example
2020-07-05 11:41:45 +02:00
///
/// ```rust
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// use rhai::{Engine, RegisterFn};
///
/// let mut engine = Engine::new();
///
/// // Register a custom operator called 'foo' and give it
2020-07-06 07:01:57 +02:00
/// // a precedence of 160 (i.e. between +|- and *|/).
/// engine.register_custom_operator("foo", 160).unwrap();
2020-07-05 11:41:45 +02:00
///
/// // Register a binary function named 'foo'
/// engine.register_fn("foo", |x: i64, y: i64| (x * y) - (x + y));
///
/// assert_eq!(
/// engine.eval_expression::<i64>("1 + 2 * 3 foo 4 - 5 / 6")?,
/// 15
/// );
/// # Ok(())
/// # }
/// ```
pub fn register_custom_operator(
&mut self,
keyword: &str,
precedence: u8,
2020-07-12 05:46:53 +02:00
) -> Result<&mut Self, String> {
2020-07-05 11:41:45 +02:00
if !is_valid_identifier(keyword.chars()) {
return Err(format!("not a valid identifier: '{}'", keyword).into());
}
match Token::lookup_from_syntax(keyword) {
// Standard identifiers, reserved keywords and custom keywords are OK
None | Some(Token::Reserved(_)) | Some(Token::Custom(_)) => (),
// Disabled keywords are also OK
2020-10-25 14:57:18 +01:00
Some(token) if !self.disabled_symbols.contains(token.syntax().as_ref()) => (),
// Active standard keywords cannot be made custom
Some(_) => return Err(format!("'{}' is a reserved keyword", keyword).into()),
}
// Add to custom keywords
2020-07-05 11:41:45 +02:00
self.custom_keywords
2020-10-25 14:57:18 +01:00
.insert(keyword.into(), Some(precedence));
2020-07-05 11:41:45 +02:00
2020-07-12 05:46:53 +02:00
Ok(self)
2020-07-05 09:23:51 +02:00
}
}