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

Fix doc comment links.

Browse Source
This commit is contained in:
Stephen Chung 2021-11-20 21:29:36 +08:00
parent fa41f4faf0
commit 90200e607c
11 changed files with 100 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
src/api/compile.rs
View File

@ -36,9 +36,9 @@ impl Engine {
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
///
/// # Example
///
@ -81,7 +81,7 @@ impl Engine {
/// Modules referred by `import` statements containing literal string paths are eagerly resolved
/// via the current [module resolver][crate::ModuleResolver] and embedded into the resultant
/// [`AST`]. When it is evaluated later, `import` statement directly recall pre-resolved
/// [modules][Module] and the resolution process is not performed again.
/// [modules][crate::Module] and the resolution process is not performed again.
#[cfg(not(feature = "no_module"))]
pub fn compile_into_self_contained(
&self,
@ -146,22 +146,22 @@ impl Engine {
Ok(ast)
}
/// When passed a list of strings, first join the strings into one large script,
/// and then compile them into an [`AST`] using own scope, which can be used later for evaluation.
/// When passed a list of strings, first join the strings into one large script, and then
/// compile them into an [`AST`] using own scope, which can be used later for evaluation.
///
/// The scope is useful for passing constants into the script for optimization
/// when using [`OptimizationLevel::Full`].
/// The scope is useful for passing constants into the script for optimization when using
/// [`OptimizationLevel::Full`][crate::OptimizationLevel::Full].
///
/// ## Note
///
/// All strings are simply parsed one after another with nothing inserted in between, not even
/// a newline or space.
/// All strings are simply parsed one after another with nothing inserted in between, not even a
/// newline or space.
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
///
/// # Example
///

2
src/api/deprecated.rs
View File

@ -80,7 +80,7 @@ impl Engine {
self.run_with_scope(scope, script)
}
/// Evaluate an AST, but throw away the result and only return error (if any).
/// Evaluate an [`AST`], but throw away the result and only return error (if any).
/// Useful for when you don't need the result, but still need to keep track of possible errors.
///
/// # Deprecated

6
src/api/eval.rs
View File

@ -31,9 +31,9 @@ impl Engine {
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
///
/// # Example
///

10
src/api/events.rs
View File

@ -17,11 +17,11 @@ impl Engine {
/// > ` -> Result<Option<Dynamic>, Box<EvalAltResult>> + 'static`
///
/// where:
/// * `index`: an offset from the bottom of the current [`Scope`] that the variable is supposed
/// to reside. Offsets start from 1, with 1 meaning the last variable in the current
/// [`Scope`]. Essentially the correct variable is at position `scope.len() - index`.
/// If `index` is zero, then there is no pre-calculated offset position and a search through the
/// current [`Scope`] must be performed.
/// * `index`: an offset from the bottom of the current [`Scope`][crate::Scope] that the
/// variable is supposed to reside. Offsets start from 1, with 1 meaning the last variable in
/// the current [`Scope`][crate::Scope]. Essentially the correct variable is at position
/// `scope.len() - index`. If `index` is zero, then there is no pre-calculated offset position
/// and a search through the current [`Scope`][crate::Scope] must be performed.
///
/// * `context`: the current [evaluation context][`EvalContext`].
///

18
src/api/files.rs
View File

@ -71,9 +71,9 @@ impl Engine {
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
///
/// # Example
///
@ -136,9 +136,9 @@ impl Engine {
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
///
/// # Example
///
@ -180,9 +180,9 @@ impl Engine {
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
#[cfg(not(feature = "no_std"))]
#[cfg(not(any(target_arch = "wasm32", target_arch = "wasm64")))]
#[inline]

42
src/api/mod.rs
View File

@ -1,17 +1,25 @@
//! Module defining the public API of the Rhai engine.
pub mod call_fn;
pub mod compile;
pub mod deprecated;
pub mod eval;
pub mod events;
pub mod run;
pub mod compile;
#[cfg(not(feature = "no_std"))]
#[cfg(not(any(target_arch = "wasm32", target_arch = "wasm64")))]
pub mod files;
pub mod register;
pub mod call_fn;
#[cfg(not(feature = "unchecked"))]
pub mod limits;
pub mod register;
pub mod run;
pub mod events;
pub mod deprecated;
use crate::engine::Precedence;
use crate::tokenizer::Token;
@ -43,21 +51,21 @@ impl Engine {
pub const fn optimization_level(&self) -> crate::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.
/// 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`]. 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.
/// 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`] can be compiled just once. Before evaluation,
/// constants are passed into the [`Engine`] via an external scope
/// (i.e. with [`Scope::push_constant`]).
/// Then, the [`AST`] is cloned and the copy re-optimized before running.
/// 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(

2
src/api/register.rs
View File

@ -154,7 +154,7 @@ impl Engine {
///
/// This function is very low level. It takes a list of [`TypeId`][std::any::TypeId]'s indicating the actual types of the parameters.
///
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][Dynamic],
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][crate::Dynamic],
/// The arguments are guaranteed to be of the correct types matching the [`TypeId`][std::any::TypeId]'s.
///
/// To access a primary argument value (i.e. cloning is cheap), use: `args[n].as_xxx().unwrap()`

8
src/api/run.rs
View File

@ -16,9 +16,9 @@ impl Engine {
///
/// ## Constants Propagation
///
/// If not [`OptimizationLevel::None`], constants defined within the scope are propagated
/// throughout the script _including_ functions. This allows functions to be optimized based on
/// dynamic global constants.
/// If not [`OptimizationLevel::None`][crate::OptimizationLevel::None], constants defined within
/// the scope are propagated throughout the script _including_ functions. This allows functions
/// to be optimized based on dynamic global constants.
#[inline]
pub fn run_with_scope(
&self,
@ -40,7 +40,7 @@ impl Engine {
self.run_ast_with_scope(scope, &ast)
}
/// Evaluate an AST, returning any error (if any).
/// Evaluate an [`AST`], returning any error (if any).
#[inline(always)]
pub fn run_ast(&self, ast: &AST) -> Result<(), Box<EvalAltResult>> {
self.run_ast_with_scope(&mut Scope::new(), ast)

2
src/engine.rs
View File

@ -1011,7 +1011,7 @@ pub struct Engine {
#[cfg(not(feature = "unchecked"))]
pub(crate) progress: Option<crate::func::native::OnProgressCallback>,
/// Optimize the AST after compilation.
/// Optimize the [`AST`][crate::AST] after compilation.
#[cfg(not(feature = "no_optimize"))]
pub(crate) optimization_level: crate::OptimizationLevel,

52
src/func/builtin.rs
View File

@ -10,6 +10,10 @@ use std::prelude::v1::*;
#[cfg(not(feature = "no_float"))]
use crate::FLOAT;
#[cfg(not(feature = "no_float"))]
#[cfg(feature = "no_std")]
use num_traits::Float;
#[cfg(feature = "decimal")]
use rust_decimal::Decimal;
@ -48,10 +52,6 @@ pub fn get_builtin_binary_op_fn(
x: &Dynamic,
y: &Dynamic,
) -> Option<fn(NativeCallContext, &mut FnCallArgs) -> RhaiResult> {
#[cfg(feature = "no_std")]
#[cfg(not(feature = "no_float"))]
use num_traits::Float;
let type1 = x.type_id();
let type2 = y.type_id();
@ -127,9 +127,9 @@ pub fn get_builtin_binary_op_fn(
} };
}
#[cfg(not(feature = "no_float"))]
macro_rules! impl_float {
($x:ty, $xx:ident, $y:ty, $yy:ident) => {
#[cfg(not(feature = "no_float"))]
if types_pair == (TypeId::of::<$x>(), TypeId::of::<$y>()) {
return match op {
"+" => Some(impl_op!(FLOAT => $xx + $yy)),
@ -150,13 +150,16 @@ pub fn get_builtin_binary_op_fn(
};
}
impl_float!(FLOAT, as_float, FLOAT, as_float);
impl_float!(FLOAT, as_float, INT, as_int);
impl_float!(INT, as_int, FLOAT, as_float);
#[cfg(not(feature = "no_float"))]
{
impl_float!(FLOAT, as_float, FLOAT, as_float);
impl_float!(FLOAT, as_float, INT, as_int);
impl_float!(INT, as_int, FLOAT, as_float);
}
#[cfg(feature = "decimal")]
macro_rules! impl_decimal {
($x:ty, $xx:ident, $y:ty, $yy:ident) => {
#[cfg(feature = "decimal")]
if types_pair == (TypeId::of::<$x>(), TypeId::of::<$y>()) {
#[cfg(not(feature = "unchecked"))]
use crate::packages::arithmetic::decimal_functions::*;
@ -199,9 +202,12 @@ pub fn get_builtin_binary_op_fn(
};
}
impl_decimal!(Decimal, as_decimal, Decimal, as_decimal);
impl_decimal!(Decimal, as_decimal, INT, as_int);
impl_decimal!(INT, as_int, Decimal, as_decimal);
#[cfg(feature = "decimal")]
{
impl_decimal!(Decimal, as_decimal, Decimal, as_decimal);
impl_decimal!(Decimal, as_decimal, INT, as_int);
impl_decimal!(INT, as_int, Decimal, as_decimal);
}
// char op string
if types_pair == (TypeId::of::<char>(), TypeId::of::<ImmutableString>()) {
@ -419,10 +425,6 @@ pub fn get_builtin_op_assignment_fn(
x: &Dynamic,
y: &Dynamic,
) -> Option<fn(NativeCallContext, &mut FnCallArgs) -> RhaiResult> {
#[cfg(feature = "no_std")]
#[cfg(not(feature = "no_float"))]
use num_traits::Float;
let type1 = x.type_id();
let type2 = y.type_id();
@ -468,9 +470,9 @@ pub fn get_builtin_op_assignment_fn(
} };
}
#[cfg(not(feature = "no_float"))]
macro_rules! impl_float {
($x:ident, $xx:ident, $y:ty, $yy:ident) => {
#[cfg(not(feature = "no_float"))]
if types_pair == (TypeId::of::<$x>(), TypeId::of::<$y>()) {
return match op {
"+=" => Some(impl_op!($x += $yy)),
@ -485,12 +487,15 @@ pub fn get_builtin_op_assignment_fn(
}
}
impl_float!(FLOAT, as_float, FLOAT, as_float);
impl_float!(FLOAT, as_float, INT, as_int);
#[cfg(not(feature = "no_float"))]
{
impl_float!(FLOAT, as_float, FLOAT, as_float);
impl_float!(FLOAT, as_float, INT, as_int);
}
#[cfg(feature = "decimal")]
macro_rules! impl_decimal {
($x:ident, $xx:ident, $y:ty, $yy:ident) => {
#[cfg(feature = "decimal")]
if types_pair == (TypeId::of::<$x>(), TypeId::of::<$y>()) {
#[cfg(not(feature = "unchecked"))]
use crate::packages::arithmetic::decimal_functions::*;
@ -523,8 +528,11 @@ pub fn get_builtin_op_assignment_fn(
};
}
impl_decimal!(Decimal, as_decimal, Decimal, as_decimal);
impl_decimal!(Decimal, as_decimal, INT, as_int);
#[cfg(feature = "decimal")]
{
impl_decimal!(Decimal, as_decimal, Decimal, as_decimal);
impl_decimal!(Decimal, as_decimal, INT, as_int);
}
// string op= char
if types_pair == (TypeId::of::<ImmutableString>(), TypeId::of::<char>()) {

22
src/packages/arithmetic.rs
View File

@ -329,13 +329,10 @@ mod f32_functions {
}
#[rhai_fn(return_raw)]
pub fn sign(x: f32) -> Result<INT, Box<EvalAltResult>> {
if x == 0.0 {
Ok(0)
} else {
match x.signum() {
x if x.is_nan() => Err(make_err("Sign of NaN is undefined")),
x => Ok(x as INT),
}
match x.signum() {
_ if x == 0.0 => Ok(0),
x if x.is_nan() => Err(make_err("Sign of NaN is undefined")),
x => Ok(x as INT),
}
}
pub fn is_zero(x: f32) -> bool {
@ -439,13 +436,10 @@ mod f64_functions {
}
#[rhai_fn(return_raw)]
pub fn sign(x: f64) -> Result<INT, Box<EvalAltResult>> {
if x == 0.0 {
Ok(0)
} else {
match x.signum() {
x if x.is_nan() => Err(make_err("Sign of NaN is undefined")),
x => Ok(x as INT),
}
match x.signum() {
_ if x == 0.0 => Ok(0),
x if x.is_nan() => Err(make_err("Sign of NaN is undefined")),
x => Ok(x as INT),
}
}
pub fn is_zero(x: f64) -> bool {