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

Refine docs and comments etc.

Browse Source
This commit is contained in:
Stephen Chung 2021-01-02 23:30:10 +08:00
parent 5a3bbaa322
commit ef48f47b74
22 changed files with 352 additions and 296 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/language/functions.md
View File

@ -149,14 +149,18 @@ change(); // <- error: `this` is unbound
`is_def_fn`
-----------
Use `is_def_fn` to detect if a Rhai function is defined (and therefore callable), based on its name
and the number of parameters.
Use `is_def_fn` to detect if a Rhai function is defined (and therefore callable),
based on its name and the number of parameters.
```rust
fn foo(x) { x + 1 }
is_def_fn("foo", 1) == true;
is_def_fn("foo", 0) == false;
is_def_fn("foo", 2) == false;
is_def_fn("bar", 1) == false;
```

28
src/ast.rs
View File

@ -62,7 +62,7 @@ impl FnAccess {
/// _(INTERNALS)_ A type containing information on a scripted function.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone)]
@ -271,6 +271,8 @@ impl AST {
/// No statements are cloned.
///
/// This operation is cheap because functions are shared.
///
/// Not available under [`no_function`].
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn clone_functions_only(&self) -> Self {
@ -280,6 +282,8 @@ impl AST {
/// No statements are cloned.
///
/// This operation is cheap because functions are shared.
///
/// Not available under [`no_function`].
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn clone_functions_only_filtered(
@ -564,6 +568,8 @@ impl AST {
}
/// Filter out the functions, retaining only some based on a filter predicate.
///
/// Not available under [`no_function`].
///
/// # Example
///
/// ```
@ -597,6 +603,8 @@ impl AST {
self
}
/// Iterate through all function definitions.
///
/// Not available under [`no_function`].
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn iter_functions<'a>(&'a self) -> impl Iterator<Item = ScriptFnMetadata> + 'a {
@ -605,6 +613,8 @@ impl AST {
.map(|(_, _, _, _, fn_def)| fn_def.into())
}
/// Clear all function definitions in the [`AST`].
///
/// Not available under [`no_function`].
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn clear_functions(&mut self) {
@ -650,7 +660,7 @@ impl AsRef<Module> for AST {
/// _(INTERNALS)_ An identifier containing an [immutable string][ImmutableString] name and a [position][Position].
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Clone, Eq, PartialEq, Hash)]
@ -671,7 +681,7 @@ impl fmt::Debug for Ident {
/// _(INTERNALS)_ A type encapsulating the mode of a `return`/`throw` statement.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Eq, PartialEq, Clone, Copy, Hash)]
@ -685,7 +695,7 @@ pub enum ReturnType {
/// _(INTERNALS)_ A statement.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone)]
@ -882,7 +892,7 @@ impl Stmt {
/// _(INTERNALS)_ A custom syntax definition.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Clone)]
@ -909,7 +919,7 @@ impl fmt::Debug for CustomExpr {
/// _(INTERNALS)_ A binary expression.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone)]
@ -923,7 +933,7 @@ pub struct BinaryExpr {
/// _(INTERNALS)_ A function call.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone, Default)]
@ -948,7 +958,7 @@ pub struct FnCallExpr {
/// _(INTERNALS)_ An expression sub-tree.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone)]
@ -1028,7 +1038,7 @@ impl Expr {
AccessMode::ReadOnly,
)),
Self::BoolConstant(x, _) => (*x).into(),
Self::Unit(_) => ().into(),
Self::Unit(_) => Dynamic::UNIT,
#[cfg(not(feature = "no_index"))]
Self::Array(x, _) if self.is_constant() => {

21
src/dynamic.rs
View File

@ -9,7 +9,7 @@ use crate::stdlib::{
hash::{Hash, Hasher},
mem,
ops::{Deref, DerefMut},
string::{String, ToString},
string::String,
};
use crate::{FnPtr, ImmutableString, INT};
@ -132,7 +132,7 @@ pub enum AccessMode {
}
impl AccessMode {
/// Is the access type [`ReadOnly`]?
/// Is the access type `ReadOnly`?
#[inline(always)]
pub fn is_read_only(self) -> bool {
match self {
@ -183,7 +183,7 @@ enum DynamicReadLockInner<'d, T: Variant + Clone> {
/// A simple reference to a non-shared value.
Reference(&'d T),
/// A read guard to a shared `RefCell`.
/// A read guard to a shared [`RefCell`][std::cell::RefCell].
#[cfg(not(feature = "no_closure"))]
#[cfg(not(feature = "sync"))]
Guard(crate::stdlib::cell::Ref<'d, Dynamic>),
@ -220,7 +220,7 @@ enum DynamicWriteLockInner<'d, T: Variant + Clone> {
/// A simple mutable reference to a non-shared value.
Reference(&'d mut T),
/// A write guard to a shared `RefCell`.
/// A write guard to a shared [`RefCell`][std::cell::RefCell].
#[cfg(not(feature = "no_closure"))]
#[cfg(not(feature = "sync"))]
Guard(crate::stdlib::cell::RefMut<'d, Dynamic>),
@ -258,7 +258,7 @@ impl<'d, T: Variant + Clone> DerefMut for DynamicWriteLock<'d, T> {
impl Dynamic {
/// Does this [`Dynamic`] hold a variant data type
/// instead of one of the support system primitive types?
/// instead of one of the supported system primitive types?
#[inline(always)]
pub fn is_variant(&self) -> bool {
match self.0 {
@ -266,8 +266,7 @@ impl Dynamic {
_ => false,
}
}
/// Does this [`Dynamic`] hold a shared data type
/// instead of one of the supported system primitive types?
/// Is the value held by this [`Dynamic`] shared?
#[inline(always)]
pub fn is_shared(&self) -> bool {
match self.0 {
@ -279,7 +278,7 @@ impl Dynamic {
/// Is the value held by this [`Dynamic`] a particular type?
///
/// If the [`Dynamic`] is a shared variant checking is performed on
/// top of it's internal value.
/// top of its internal value.
#[inline(always)]
pub fn is<T: Variant + Clone>(&self) -> bool {
let mut target_type_id = TypeId::of::<T>();
@ -508,7 +507,7 @@ impl fmt::Debug for Dynamic {
impl Clone for Dynamic {
/// Clone the [`Dynamic`] value.
///
/// ## WARNING
/// # WARNING
///
/// The cloned copy is marked read-write even if the original is read-only.
fn clone(&self) -> Self {
@ -618,7 +617,7 @@ impl Dynamic {
///
/// Constant [`Dynamic`] values are read-only. If a [`&mut Dynamic`][Dynamic] to such a constant
/// is passed to a Rust function, the function can use this information to return an error of
/// [`EvalAltResult::ErrorAssignmentToConstant`][crate::EvalAltResult::ErrorAssignmentToConstant]
/// [`ErrorAssignmentToConstant`][crate::EvalAltResult::ErrorAssignmentToConstant]
/// if its value is going to be modified. This safe-guards constant values from being modified
/// from within Rust functions.
pub fn is_read_only(&self) -> bool {
@ -707,7 +706,7 @@ impl Dynamic {
if TypeId::of::<T>() == TypeId::of::<&str>() {
return <dyn Any>::downcast_ref::<&str>(&value)
.unwrap()
.to_string()
.deref()
.into();
}
if TypeId::of::<T>() == TypeId::of::<()>() {

77
src/engine.rs
View File

@ -45,13 +45,13 @@ pub const TYPICAL_MAP_SIZE: usize = 8; // Small maps are typical
/// _(INTERNALS)_ A stack of imported [modules][Module].
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
//
// # Implementation Notes
//
// We cannot use &str or Cow<str> here because `eval` may load a [module][Module] and
// We cannot use Cow<str> here because `eval` may load a [module][Module] and
// the module name will live beyond the AST of the eval script text.
// The best we can do is a shared reference.
#[derive(Debug, Clone, Default)]
@ -214,55 +214,62 @@ pub const FN_ANONYMOUS: &str = "anon$";
#[cfg(any(not(feature = "no_index"), not(feature = "no_object")))]
pub const OP_EQUALS: &str = "==";
/// A type specifying the method of chaining.
/// Method of chaining.
#[cfg(any(not(feature = "no_index"), not(feature = "no_object")))]
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
pub enum ChainType {
None,
/// Not a chaining type.
NonChaining,
/// Indexing.
Index,
/// Dotting.
Dot,
}
/// Value of a chaining argument.
#[cfg(any(not(feature = "no_index"), not(feature = "no_object")))]
#[derive(Debug, Clone)]
pub enum IndexChainValue {
None,
#[derive(Debug, Clone, Hash)]
pub enum ChainArgument {
/// Dot-property access.
Property,
/// Arguments to a dot-function call.
FnCallArgs(StaticVec<Dynamic>),
Value(Dynamic),
/// Index value.
IndexValue(Dynamic),
}
#[cfg(any(not(feature = "no_index"), not(feature = "no_object")))]
impl IndexChainValue {
impl ChainArgument {
/// Return the `Dynamic` value.
///
/// # Panics
///
/// Panics if not `IndexChainValue::Value`.
/// Panics if not `ChainArgument::IndexValue`.
#[inline(always)]
#[cfg(not(feature = "no_index"))]
pub fn as_value(self) -> Dynamic {
pub fn as_index_value(self) -> Dynamic {
match self {
Self::None | Self::FnCallArgs(_) => panic!("expecting IndexChainValue::Value"),
Self::Value(value) => value,
Self::Property | Self::FnCallArgs(_) => panic!("expecting ChainArgument::IndexValue"),
Self::IndexValue(value) => value,
}
}
/// Return the `StaticVec<Dynamic>` value.
///
/// # Panics
///
/// Panics if not `IndexChainValue::FnCallArgs`.
/// Panics if not `ChainArgument::FnCallArgs`.
#[inline(always)]
#[cfg(not(feature = "no_object"))]
pub fn as_fn_call_args(self) -> StaticVec<Dynamic> {
match self {
Self::None | Self::Value(_) => panic!("expecting IndexChainValue::FnCallArgs"),
Self::Property | Self::IndexValue(_) => panic!("expecting ChainArgument::FnCallArgs"),
Self::FnCallArgs(value) => value,
}
}
}
#[cfg(any(not(feature = "no_index"), not(feature = "no_object")))]
impl From<StaticVec<Dynamic>> for IndexChainValue {
impl From<StaticVec<Dynamic>> for ChainArgument {
#[inline(always)]
fn from(value: StaticVec<Dynamic>) -> Self {
Self::FnCallArgs(value)
@ -270,10 +277,10 @@ impl From<StaticVec<Dynamic>> for IndexChainValue {
}
#[cfg(any(not(feature = "no_index"), not(feature = "no_object")))]
impl From<Dynamic> for IndexChainValue {
impl From<Dynamic> for ChainArgument {
#[inline(always)]
fn from(value: Dynamic) -> Self {
Self::Value(value)
Self::IndexValue(value)
}
}
@ -487,7 +494,7 @@ impl<T: Into<Dynamic>> From<T> for Target<'_> {
/// _(INTERNALS)_ A type that holds all the current states of the [`Engine`].
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone, Default)]
@ -524,7 +531,7 @@ impl State {
/// _(INTERNALS)_ A type containing all the limits imposed by the [`Engine`].
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[cfg(not(feature = "unchecked"))]
@ -850,7 +857,8 @@ impl Engine {
}
/// Create a new [`Engine`] with minimal built-in functions.
/// Use the [`register_global_module`][Engine::register_global_module] method to load additional packages of functions.
///
/// Use [`register_global_module`][Engine::register_global_module] to add packages of functions.
#[inline]
pub fn new_raw() -> Self {
Self {
@ -1021,13 +1029,13 @@ impl Engine {
this_ptr: &mut Option<&mut Dynamic>,
target: &mut Target,
rhs: &Expr,
idx_values: &mut StaticVec<IndexChainValue>,
idx_values: &mut StaticVec<ChainArgument>,
chain_type: ChainType,
level: usize,
new_val: Option<(Dynamic, Position)>,
) -> Result<(Dynamic, bool), Box<EvalAltResult>> {
if chain_type == ChainType::None {
unreachable!("should not be ChainType::None");
if chain_type == ChainType::NonChaining {
unreachable!("should not be ChainType::NonChaining");
}
let is_ref = target.is_ref();
@ -1035,7 +1043,7 @@ impl Engine {
let next_chain = match rhs {
Expr::Index(_, _) => ChainType::Index,
Expr::Dot(_, _) => ChainType::Dot,
_ => ChainType::None,
_ => ChainType::NonChaining,
};
// Pop the last index value
@ -1052,7 +1060,7 @@ impl Engine {
// xxx[idx].expr... | xxx[idx][expr]...
Expr::Dot(x, x_pos) | Expr::Index(x, x_pos) => {
let idx_pos = x.lhs.position();
let idx_val = idx_val.as_value();
let idx_val = idx_val.as_index_value();
let obj_ptr = &mut self.get_indexed_mut(
mods, state, lib, target_val, idx_val, idx_pos, false, is_ref, true,
level,
@ -1066,7 +1074,7 @@ impl Engine {
}
// xxx[rhs] = new_val
_ if new_val.is_some() => {
let idx_val = idx_val.as_value();
let idx_val = idx_val.as_index_value();
let mut idx_val2 = idx_val.clone();
// `call_setter` is introduced to bypass double mutable borrowing of target
@ -1114,7 +1122,7 @@ impl Engine {
}
// xxx[rhs]
_ => {
let idx_val = idx_val.as_value();
let idx_val = idx_val.as_index_value();
self.get_indexed_mut(
mods, state, lib, target_val, idx_val, pos, false, is_ref, true, level,
)
@ -1405,7 +1413,7 @@ impl Engine {
this_ptr: &mut Option<&mut Dynamic>,
expr: &Expr,
parent_chain_type: ChainType,
idx_values: &mut StaticVec<IndexChainValue>,
idx_values: &mut StaticVec<ChainArgument>,
size: usize,
level: usize,
) -> Result<(), Box<EvalAltResult>> {
@ -1428,7 +1436,7 @@ impl Engine {
}
Expr::Property(_) if parent_chain_type == ChainType::Dot => {
idx_values.push(IndexChainValue::None)
idx_values.push(ChainArgument::Property)
}
Expr::Property(_) => unreachable!("unexpected Expr::Property for indexing"),
@ -1438,7 +1446,7 @@ impl Engine {
// Evaluate in left-to-right order
let lhs_val = match lhs {
Expr::Property(_) if parent_chain_type == ChainType::Dot => {
IndexChainValue::None
ChainArgument::Property
}
Expr::Property(_) => unreachable!("unexpected Expr::Property for indexing"),
Expr::FnCall(x, _)
@ -2312,7 +2320,7 @@ impl Engine {
let result = self
.eval_stmt(scope, mods, state, lib, this_ptr, try_body, level)
.map(|_| ().into());
.map(|_| Dynamic::UNIT);
match result {
Ok(_) => result,
@ -2374,7 +2382,7 @@ impl Engine {
// Empty throw
Stmt::Return((ReturnType::Exception, pos), None, _) => {
EvalAltResult::ErrorRuntime(().into(), *pos).into()
EvalAltResult::ErrorRuntime(Dynamic::UNIT, *pos).into()
}
// Let/const statement
@ -2389,7 +2397,7 @@ impl Engine {
self.eval_expr(scope, mods, state, lib, this_ptr, expr, level)?
.flatten()
} else {
().into()
Dynamic::UNIT
};
let (var_name, _alias): (Cow<'_, str>, _) = if state.is_global() {
(
@ -2607,6 +2615,7 @@ impl Engine {
}
/// Check if the number of operations stay within limit.
#[inline]
pub(crate) fn inc_operations(
&self,
state: &mut State,

169
src/engine_api.rs
View File

@ -35,7 +35,7 @@ fn calc_hash_for_scripts<'a>(scripts: impl IntoIterator<Item = &'a &'a str>) ->
impl Engine {
/// Register a function of the [`Engine`].
///
/// ## WARNING - Low Level API
/// # WARNING - Low Level API
///
/// This function is very low level. It takes a list of [`TypeId`][std::any::TypeId]'s indicating the actual types of the parameters.
///
@ -88,13 +88,12 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new)
/// // Use `register_fn` to register methods on the type.
/// engine.register_fn("update", TestStruct::update);
/// .register_fn("update", TestStruct::update);
///
/// assert_eq!(
/// engine.eval::<TestStruct>("let x = new_ts(); x.update(41); x")?,
@ -128,22 +127,19 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new);
///
/// assert_eq!(
/// engine.eval::<String>("let x = new_ts(); type_of(x)")?,
/// "rust_out::TestStruct"
/// );
///
/// // Register the custom type with a name.
/// // Re-register the custom type with a name.
/// engine.register_type_with_name::<TestStruct>("Hello");
///
/// // Register methods on the type.
/// engine.register_fn("new_ts", TestStruct::new);
///
/// assert_eq!(
/// engine.eval::<String>("let x = new_ts(); type_of(x)")?,
/// "Hello"
@ -192,13 +188,12 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new)
/// // Register a getter on a property (notice it doesn't have to be the same name).
/// engine.register_get("xyz", TestStruct::get_field);
/// .register_get("xyz", TestStruct::get_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a.xyz")?, 1);
/// # Ok(())
@ -239,13 +234,12 @@ impl Engine {
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new)
/// // Register a getter on a property (notice it doesn't have to be the same name).
/// engine.register_get_result("xyz", TestStruct::get_field);
/// .register_get_result("xyz", TestStruct::get_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a.xyz")?, 1);
/// # Ok(())
@ -281,13 +275,12 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new)
/// // Register a setter on a property (notice it doesn't have to be the same name)
/// engine.register_set("xyz", TestStruct::set_field);
/// .register_set("xyz", TestStruct::set_field);
///
/// // Notice that, with a getter, there is no way to get the property value
/// assert_eq!(
@ -330,13 +323,12 @@ impl Engine {
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new)
/// // Register a setter on a property (notice it doesn't have to be the same name)
/// engine.register_set_result("xyz", TestStruct::set_field);
/// .register_set_result("xyz", TestStruct::set_field);
///
/// // Notice that, with a getter, there is no way to get the property value
/// assert_eq!(
@ -383,14 +375,13 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// // Register a getter and a setter on a property
/// // Register API for the custom type.
/// engine
/// .register_type::<TestStruct>()
/// .register_fn("new_ts", TestStruct::new)
/// // Register both a getter and a setter on a property
/// // (notice it doesn't have to be the same name)
/// engine.register_get_set("xyz", TestStruct::get_field, TestStruct::set_field);
/// .register_get_set("xyz", TestStruct::get_field, TestStruct::set_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a.xyz = 42; a.xyz")?, 42);
/// # Ok(())
@ -434,14 +425,14 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// // Register API for the custom type.
/// # #[cfg(not(feature = "no_object"))]
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// engine
/// .register_fn("new_ts", TestStruct::new)
/// // Register an indexer.
/// engine.register_indexer_get(TestStruct::get_field);
/// .register_indexer_get(TestStruct::get_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a[2]")?, 3);
/// # Ok(())
@ -500,14 +491,14 @@ impl Engine {
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// // Register API for the custom type.
/// # #[cfg(not(feature = "no_object"))]
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// engine
/// .register_fn("new_ts", TestStruct::new)
/// // Register an indexer.
/// engine.register_indexer_get_result(TestStruct::get_field);
/// .register_indexer_get_result(TestStruct::get_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a[2]")?, 3);
/// # Ok(())
@ -561,14 +552,14 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// // Register API for the custom type.
/// # #[cfg(not(feature = "no_object"))]
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// engine
/// .register_fn("new_ts", TestStruct::new)
/// // Register an indexer.
/// engine.register_indexer_set(TestStruct::set_field);
/// .register_indexer_set(TestStruct::set_field);
///
/// assert_eq!(
/// engine.eval::<TestStruct>("let a = new_ts(); a[2] = 42; a")?.fields[2],
@ -628,14 +619,14 @@ impl Engine {
/// # fn main() -> Result<(), Box<rhai::EvalAltResult>> {
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// // Register API for the custom type.
/// # #[cfg(not(feature = "no_object"))]
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// engine
/// .register_fn("new_ts", TestStruct::new)
/// // Register an indexer.
/// engine.register_indexer_set_result(TestStruct::set_field);
/// .register_indexer_set_result(TestStruct::set_field);
///
/// assert_eq!(
/// engine.eval::<TestStruct>("let a = new_ts(); a[2] = 42; a")?.fields[2],
@ -700,14 +691,14 @@ impl Engine {
///
/// let mut engine = Engine::new();
///
/// // Register the custom type.
/// // Register API for the custom type.
/// # #[cfg(not(feature = "no_object"))]
/// engine.register_type::<TestStruct>();
///
/// engine.register_fn("new_ts", TestStruct::new);
///
/// engine
/// .register_fn("new_ts", TestStruct::new)
/// // Register an indexer.
/// engine.register_indexer_get_set(TestStruct::get_field, TestStruct::set_field);
/// .register_indexer_get_set(TestStruct::get_field, TestStruct::set_field);
///
/// assert_eq!(engine.eval::<i64>("let a = new_ts(); a[2] = 42; a[2]")?, 42);
/// # Ok(())
@ -740,9 +731,9 @@ impl Engine {
}
/// Register a shared [`Module`] into the global namespace of [`Engine`].
///
/// ## Deprecated
/// # Deprecated
///
/// Use `register_global_module` instead.
/// Use [`register_global_module`][Engine::register_global_module] instead.
#[inline(always)]
#[deprecated = "use `register_global_module` instead"]
pub fn load_package(&mut self, module: impl Into<Shared<Module>>) -> &mut Self {
@ -768,13 +759,12 @@ impl Engine {
///
/// let module: Shared<Module> = module.into();
///
/// engine
/// // Register the module as a fixed sub-module
/// engine.register_static_module("foo::bar::baz", module.clone());
///
/// .register_static_module("foo::bar::baz", module.clone())
/// // Multiple registrations to the same partial path is also OK!
/// engine.register_static_module("foo::bar::hello", module.clone());
///
/// engine.register_static_module("CalcService", module);
/// .register_static_module("foo::bar::hello", module.clone())
/// .register_static_module("CalcService", module);
///
/// assert_eq!(engine.eval::<i64>("foo::bar::baz::calc(41)")?, 42);
/// assert_eq!(engine.eval::<i64>("foo::bar::hello::calc(41)")?, 42);
@ -830,9 +820,9 @@ impl Engine {
/// Register a shared [`Module`] as a static module namespace with the [`Engine`].
///
/// ## Deprecated
/// # Deprecated
///
/// Use `register_static_module` instead.
/// Use [`register_static_module`][Engine::register_static_module] instead.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
#[deprecated = "use `register_static_module` instead"]
@ -1001,6 +991,8 @@ impl Engine {
}
/// Compile a script file into an [`AST`], which can be used later for evaluation.
///
/// Not available under `no_std` or `WASM`.
///
/// # Example
///
/// ```no_run
@ -1030,6 +1022,8 @@ impl Engine {
}
/// Compile a script file into an [`AST`] using own scope, which can be used later for evaluation.
///
/// Not available under `no_std` or `WASM`.
///
/// The scope is useful for passing constants into the script for optimization
/// when using [`OptimizationLevel::Full`].
///
@ -1069,12 +1063,13 @@ impl Engine {
) -> Result<AST, Box<EvalAltResult>> {
Self::read_file(path).and_then(|contents| Ok(self.compile_with_scope(scope, &contents)?))
}
/// Parse a JSON string into a map.
/// Parse a JSON string into an [object map][`Map`].
/// This is a light-weight alternative to using, say, [`serde_json`][https://crates.io/crates/serde_json] to deserialize the JSON.
///
/// The JSON string must be an object hash. It cannot be a simple JavaScript primitive.
/// The JSON string must be an object hash. It cannot be a simple scalar value.
///
/// Set `has_null` to `true` in order to map `null` values to `()`.
/// Setting it to `false` will cause a _variable not found_ error during parsing.
/// Setting it to `false` will cause an [`ErrorVariableNotFound`][EvalAltResult::ErrorVariableNotFound] error during parsing.
///
/// # JSON With Sub-Objects
///
@ -1083,7 +1078,7 @@ impl Engine {
/// Parsing a JSON string with sub-objects will cause a syntax error.
///
/// If it is certain that the character `{` never appears in any text string within the JSON object,
/// then globally replace `{` with `#{` before calling this method.
/// which is a valid assumption for many use cases, then globally replace `{` with `#{` before calling this method.
///
/// # Example
///
@ -1235,6 +1230,8 @@ impl Engine {
}
/// Evaluate a script file.
///
/// Not available under `no_std` or `WASM`.
///
/// # Example
///
/// ```no_run
@ -1259,6 +1256,8 @@ impl Engine {
}
/// Evaluate a script file with own scope.
///
/// Not available under `no_std` or `WASM`.
///
/// # Example
///
/// ```no_run
@ -1483,6 +1482,8 @@ impl Engine {
}
/// Evaluate a file, 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.
///
/// Not available under `no_std` or `WASM`.
#[cfg(not(feature = "no_std"))]
#[cfg(not(target_arch = "wasm32"))]
#[inline(always)]
@ -1494,6 +1495,8 @@ impl Engine {
}
/// Evaluate a file with own scope, 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.
///
/// Not available under `no_std` or `WASM`.
#[cfg(not(feature = "no_std"))]
#[cfg(not(target_arch = "wasm32"))]
#[inline(always)]
@ -1611,7 +1614,7 @@ impl Engine {
/// Call a script function defined in an [`AST`] with multiple [`Dynamic`] arguments
/// and optionally a value for binding to the `this` pointer.
///
/// ## WARNING
/// # WARNING
///
/// All the arguments are _consumed_, meaning that they're replaced by `()`.
/// This is to avoid unnecessarily cloning the arguments.
@ -1673,7 +1676,7 @@ impl Engine {
}
/// Call a script function defined in an [`AST`] with multiple [`Dynamic`] arguments.
///
/// ## WARNING
/// # WARNING
///
/// All the arguments are _consumed_, meaning that they're replaced by `()`.
/// This is to avoid unnecessarily cloning the arguments.
@ -1776,12 +1779,12 @@ impl Engine {
}
/// Provide a callback that will be invoked before each variable access.
///
/// ## Return Value of Callback
/// # Return Value of Callback
///
/// Return `Ok(None)` to continue with normal variable access.
/// Return `Ok(Some(Dynamic))` as the variable's value.
///
/// ## Errors in Callback
/// # Errors in Callback
///
/// Return `Err(...)` if there is an error.
///

40
src/engine_settings.rs
View File

@ -10,7 +10,7 @@ use crate::stdlib::boxed::Box;
impl Engine {
/// Control whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
///
/// Not available under the `no_optimize` feature.
/// Not available under `no_optimize`.
#[cfg(not(feature = "no_optimize"))]
#[inline(always)]
pub fn set_optimization_level(
@ -23,7 +23,7 @@ impl Engine {
/// The current optimization level.
/// It controls whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
///
/// Not available under the `no_optimize` feature.
/// Not available under `no_optimize`.
#[cfg(not(feature = "no_optimize"))]
#[inline(always)]
pub fn optimization_level(&self) -> crate::OptimizationLevel {
@ -37,6 +37,8 @@ impl Engine {
}
/// Set the maximum levels of function calls allowed for a script in order to avoid
/// infinite recursion and stack overflows.
///
/// Not available under `unchecked` or `no_function`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_function"))]
#[inline(always)]
@ -45,6 +47,8 @@ impl Engine {
self
}
/// The maximum levels of function calls allowed for a script.
///
/// Not available under `unchecked` or `no_function`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_function"))]
#[inline(always)]
@ -53,6 +57,8 @@ impl Engine {
}
/// Set the maximum number of operations allowed for a script to run to avoid
/// consuming too much resources (0 for unlimited).
///
/// Not available under `unchecked`.
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn set_max_operations(&mut self, operations: u64) -> &mut Self {
@ -64,12 +70,16 @@ impl Engine {
self
}
/// The maximum number of operations allowed for a script to run (0 for unlimited).
///
/// Not available under `unchecked`.
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn max_operations(&self) -> u64 {
self.limits.max_operations
}
/// Set the maximum number of imported [modules][crate::Module] allowed for a script.
///
/// Not available under `unchecked` or `no_module`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_module"))]
#[inline(always)]
@ -78,6 +88,8 @@ impl Engine {
self
}
/// The maximum number of imported [modules][crate::Module] allowed for a script.
///
/// Not available under `unchecked` or `no_module`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_module"))]
#[inline(always)]
@ -85,6 +97,8 @@ impl Engine {
self.limits.max_modules
}
/// Set the depth limits for expressions (0 for unlimited).
///
/// Not available under `unchecked`.
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn set_max_expr_depths(
@ -108,12 +122,16 @@ impl Engine {
self
}
/// The depth limit for expressions (0 for unlimited).
///
/// Not available under `unchecked`.
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn max_expr_depth(&self) -> usize {
self.limits.max_expr_depth
}
/// The depth limit for expressions in functions (0 for unlimited).
///
/// Not available under `unchecked` or `no_function`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_function"))]
#[inline(always)]
@ -121,6 +139,8 @@ impl Engine {
self.limits.max_function_expr_depth
}
/// Set the maximum length of [strings][crate::ImmutableString] (0 for unlimited).
///
/// Not available under `unchecked`.
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn set_max_string_size(&mut self, max_size: usize) -> &mut Self {
@ -128,12 +148,16 @@ impl Engine {
self
}
/// The maximum length of [strings][crate::ImmutableString] (0 for unlimited).
///
/// Not available under `unchecked`.
#[cfg(not(feature = "unchecked"))]
#[inline(always)]
pub fn max_string_size(&self) -> usize {
self.limits.max_string_size
}
/// Set the maximum length of [arrays][crate::Array] (0 for unlimited).
///
/// Not available under `unchecked` or `no_index`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_index"))]
#[inline(always)]
@ -142,13 +166,17 @@ impl Engine {
self
}
/// The maximum length of [arrays][crate::Array] (0 for unlimited).
///
/// Not available under `unchecked` or `no_index`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_index"))]
#[inline(always)]
pub fn max_array_size(&self) -> usize {
self.limits.max_array_size
}
/// Set the maximum length of [object maps][crate::Map] (0 for unlimited).
/// Set the maximum size of [object maps][crate::Map] (0 for unlimited).
///
/// Not available under `unchecked` or `no_object`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_object"))]
#[inline(always)]
@ -156,7 +184,9 @@ impl Engine {
self.limits.max_map_size = if max_size == usize::MAX { 0 } else { max_size };
self
}
/// The maximum length of [object maps][crate::Map] (0 for unlimited).
/// The maximum size of [object maps][crate::Map] (0 for unlimited).
///
/// Not available under `unchecked` or `no_object`.
#[cfg(not(feature = "unchecked"))]
#[cfg(not(feature = "no_object"))]
#[inline(always)]
@ -165,7 +195,7 @@ impl Engine {
}
/// Set the module resolution service used by the [`Engine`].
///
/// Not available under the `no_module` feature.
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub fn set_module_resolver(

8
src/fn_call.rs
View File

@ -155,7 +155,7 @@ pub fn ensure_no_data_race(
impl Engine {
/// Call a native Rust function registered with the [`Engine`].
///
/// ## WARNING
/// # WARNING
///
/// Function call arguments be _consumed_ when the function requires them to be passed by value.
/// All function arguments not in the first position are always passed by value and thus consumed.
@ -346,7 +346,7 @@ impl Engine {
/// Call a script-defined function.
///
/// ## WARNING
/// # WARNING
///
/// Function call arguments may be _consumed_ when the function requires them to be passed by value.
/// All function arguments not in the first position are always passed by value and thus consumed.
@ -516,7 +516,7 @@ impl Engine {
/// Perform an actual function call, native Rust or scripted, taking care of special functions.
///
/// ## WARNING
/// # WARNING
///
/// Function call arguments may be _consumed_ when the function requires them to be passed by value.
/// All function arguments not in the first position are always passed by value and thus consumed.
@ -698,7 +698,7 @@ impl Engine {
) -> Result<Dynamic, Box<EvalAltResult>> {
statements
.into_iter()
.try_fold(().into(), |_, stmt| {
.try_fold(Dynamic::UNIT, |_, stmt| {
self.eval_stmt(scope, mods, state, lib, &mut None, stmt, level)
})
.or_else(|err| match *err {

2
src/fn_func.rs
View File

@ -12,6 +12,7 @@ pub trait Func<ARGS, RET> {
type Output;
/// Create a Rust closure from an [`AST`].
///
/// The [`Engine`] and [`AST`] are consumed and basically embedded into the closure.
///
/// # Example
@ -43,6 +44,7 @@ pub trait Func<ARGS, RET> {
fn create_from_ast(self, ast: AST, entry_point: &str) -> Self::Output;
/// Create a Rust closure from a script.
///
/// The [`Engine`] is consumed and basically embedded into the closure.
///
/// # Example

6
src/fn_native.rs
View File

@ -134,7 +134,7 @@ impl<'e, 's, 'a, 'm, 'pm> NativeCallContext<'e, 's, 'a, 'm, 'pm> {
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub fn iter_imports(&self) -> impl Iterator<Item = (&str, &Module)> {
self.mods.iter().flat_map(|m| m.iter())
self.mods.iter().flat_map(|&m| m.iter())
}
/// _(INTERNALS)_ The current set of modules imported via `import` statements.
/// Available under the `internals` feature only.
@ -158,7 +158,7 @@ impl<'e, 's, 'a, 'm, 'pm> NativeCallContext<'e, 's, 'a, 'm, 'pm> {
}
/// Call a function inside the call context.
///
/// ## WARNING
/// # WARNING
///
/// All arguments may be _consumed_, meaning that they may be replaced by `()`.
/// This is to avoid unnecessarily cloning the arguments.
@ -298,7 +298,7 @@ impl FnPtr {
///
/// If this function is a script-defined function, it must not be marked private.
///
/// ## WARNING
/// # WARNING
///
/// All the arguments are _consumed_, meaning that they're replaced by `()`.
/// This is to avoid unnecessarily cloning the arguments.

8
src/lib.rs
View File

@ -104,7 +104,7 @@ pub type INT = i32;
///
/// If the `f32_float` feature is enabled, this will be [`i32`] instead.
///
/// Not available under the `no_float` feature.
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
#[cfg(not(feature = "f32_float"))]
pub type FLOAT = f64;
@ -114,7 +114,7 @@ pub type FLOAT = f64;
///
/// If the `f32_float` feature is not used, this will be `f64` instead.
///
/// Not available under the `no_float` feature.
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
#[cfg(feature = "f32_float")]
pub type FLOAT = f32;
@ -148,13 +148,13 @@ pub use fn_func::Func;
/// Variable-sized array of [`Dynamic`] values.
///
/// Not available under the `no_index` feature.
/// Not available under `no_index`.
#[cfg(not(feature = "no_index"))]
pub type Array = stdlib::vec::Vec<Dynamic>;
/// Hash map of [`Dynamic`] values with [`ImmutableString`] keys.
///
/// Not available under the `no_object` feature.
/// Not available under `no_object`.
#[cfg(not(feature = "no_object"))]
pub type Map = stdlib::collections::HashMap<ImmutableString, Dynamic>;

163
src/module/mod.rs
View File

@ -125,17 +125,15 @@ impl FuncInfo {
/// A module which may contain variables, sub-modules, external Rust functions,
/// and/or script-defined functions.
///
/// Not available under the `no_module` feature.
#[derive(Clone)]
pub struct Module {
/// ID identifying the module.
id: Option<ImmutableString>,
/// Sub-modules.
modules: HashMap<ImmutableString, Shared<Module>>,
/// Module variables.
/// [`Module`] variables.
variables: HashMap<ImmutableString, Dynamic>,
/// Flattened collection of all module variables, including those in sub-modules.
/// Flattened collection of all [`Module`] variables, including those in sub-modules.
all_variables: HashMap<NonZeroU64, Dynamic, StraightHasherBuilder>,
/// External Rust functions.
functions: HashMap<NonZeroU64, FuncInfo, StraightHasherBuilder>,
@ -146,7 +144,7 @@ pub struct Module {
type_iterators: HashMap<TypeId, IteratorFn>,
/// Flattened collection of iterator functions, including those in sub-modules.
all_type_iterators: HashMap<TypeId, IteratorFn>,
/// Is the module indexed?
/// Is the [`Module`] indexed?
indexed: bool,
}
@ -203,7 +201,7 @@ impl AsRef<Module> for Module {
}
impl Module {
/// Create a new module.
/// Create a new [`Module`].
///
/// # Example
///
@ -219,7 +217,7 @@ impl Module {
Default::default()
}
/// Create a new module with a specified capacity for native Rust functions.
/// Create a new [`Module`] with a specified capacity for native Rust functions.
///
/// # Example
///
@ -238,7 +236,7 @@ impl Module {
}
}
/// Get the ID of the module, if any.
/// Get the ID of the [`Module`], if any.
///
/// # Example
///
@ -253,12 +251,12 @@ impl Module {
self.id.as_ref().map(|s| s.as_str())
}
/// Get the ID of the module, if any.
/// Get the ID of the [`Module`], if any.
pub(crate) fn id_raw(&self) -> &Option<ImmutableString> {
&self.id
}
/// Set the ID of the module.
/// Set the ID of the [`Module`].
///
/// # Example
///
@ -273,7 +271,7 @@ impl Module {
self.id = id.map(|s| s.into());
}
/// Is the module empty?
/// Is the [`Module`] empty?
///
/// # Example
///
@ -294,7 +292,7 @@ impl Module {
&& self.all_type_iterators.is_empty()
}
/// Is the module indexed?
/// Is the [`Module`] indexed?
///
/// # Example
///
@ -314,7 +312,7 @@ impl Module {
self.indexed
}
/// Generate signatures for all the functions in the module.
/// Generate signatures for all the functions in the [`Module`].
pub fn gen_fn_signatures<'a>(&'a self) -> impl Iterator<Item = String> + 'a {
self.functions
.values()
@ -322,7 +320,7 @@ impl Module {
.map(FuncInfo::gen_signature)
}
/// Does a variable exist in the module?
/// Does a variable exist in the [`Module`]?
///
/// # Example
///
@ -338,7 +336,7 @@ impl Module {
self.variables.contains_key(name)
}
/// Get the value of a module variable.
/// Get the value of a [`Module`] variable.
///
/// # Example
///
@ -354,7 +352,7 @@ impl Module {
self.get_var(name).and_then(Dynamic::try_cast::<T>)
}
/// Get a module variable as a [`Dynamic`].
/// Get a [`Module`] variable as a [`Dynamic`].
///
/// # Example
///
@ -370,7 +368,7 @@ impl Module {
self.variables.get(name).cloned()
}
/// Set a variable into the module.
/// Set a variable into the [`Module`].
///
/// If there is an existing variable of the same name, it is replaced.
///
@ -397,7 +395,7 @@ impl Module {
/// Get a reference to a namespace-qualified variable.
/// Name and Position in [`EvalAltResult`] are [`None`] and [`NONE`][Position::NONE] and must be set afterwards.
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`].
/// The [`NonZeroU64`] hash is calculated by the function [`calc_native_fn_hash`][crate::calc_native_fn_hash].
#[inline(always)]
pub(crate) fn get_qualified_var(
&self,
@ -408,7 +406,7 @@ impl Module {
})
}
/// Set a script-defined function into the module.
/// Set a script-defined function into the [`Module`].
///
/// If there is an existing function of the same name and number of arguments, it is replaced.
#[cfg(not(feature = "no_function"))]
@ -437,7 +435,7 @@ impl Module {
hash_script
}
/// Get a script-defined function in the module based on name and number of parameters.
/// Get a script-defined function in the [`Module`] based on name and number of parameters.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn get_script_fn(
@ -465,10 +463,10 @@ impl Module {
/// Get a mutable reference to the underlying [`HashMap`] of sub-modules.
///
/// ## Warning
/// # WARNING
///
/// By taking a mutable reference, it is assumed that some sub-modules will be modified.
/// Thus the module is automatically set to be non-indexed.
/// Thus the [`Module`] is automatically set to be non-indexed.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub(crate) fn sub_modules_mut(&mut self) -> &mut HashMap<ImmutableString, Shared<Module>> {
@ -482,7 +480,7 @@ impl Module {
&mut self.modules
}
/// Does a sub-module exist in the module?
/// Does a sub-module exist in the [`Module`]?
///
/// # Example
///
@ -499,7 +497,7 @@ impl Module {
self.modules.contains_key(name)
}
/// Get a sub-module.
/// Get a sub-module in the [`Module`].
///
/// # Example
///
@ -516,7 +514,7 @@ impl Module {
self.modules.get(name).map(|m| m.as_ref())
}
/// Set a sub-module into the module.
/// Set a sub-module into the [`Module`].
///
/// If there is an existing sub-module of the same name, it is replaced.
///
@ -541,9 +539,9 @@ impl Module {
self
}
/// Does the particular Rust function exist in the module?
/// Does the particular Rust function exist in the [`Module`]?
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`].
/// The [`NonZeroU64`] hash is calculated by the function [`calc_native_fn_hash`][crate::calc_native_fn_hash].
/// It is also returned by the `set_fn_XXX` calls.
///
/// # Example
@ -569,12 +567,17 @@ impl Module {
/// Update the metadata (parameter names/types and return type) of a registered function.
///
/// The [`NonZeroU64`] hash is calculated either by the function [`crate::calc_native_fn_hash`] or
/// the function [`crate::calc_script_fn_hash`].
/// The [`NonZeroU64`] hash is calculated either by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] or the function
/// [`calc_script_fn_hash`][crate::calc_script_fn_hash].
///
/// ## Parameter Names and Types
///
/// Each parameter name/type pair should be a single string of the format: `var_name: type`.
///
/// The last entry in the list should be the return type of the function.
/// ## Return Type
///
/// The _last entry_ in the list should be the _return type_ of the function.
/// In other words, the number of entries should be one larger than the number of parameters.
pub fn update_fn_metadata<'a>(
&mut self,
@ -589,8 +592,9 @@ impl Module {
/// Update the namespace of a registered function.
///
/// The [`NonZeroU64`] hash is calculated either by the function [`crate::calc_native_fn_hash`] or
/// the function [`crate::calc_script_fn_hash`].
/// The [`NonZeroU64`] hash is calculated either by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] or the function
/// [`calc_script_fn_hash`][crate::calc_script_fn_hash].
pub fn update_fn_namespace(
&mut self,
hash_fn: NonZeroU64,
@ -603,11 +607,11 @@ impl Module {
self
}
/// Set a Rust function into the module, returning a hash key.
/// Set a Rust function into the [`Module`], returning a hash key.
///
/// If there is an existing Rust function of the same hash, it is replaced.
///
/// ## WARNING - Low Level API
/// # WARNING - Low Level API
///
/// This function is very low level.
pub fn set_fn(
@ -660,7 +664,7 @@ impl Module {
/// Set a Rust function taking a reference to the scripting [`Engine`][crate::Engine],
/// the current set of functions, plus a list of mutable [`Dynamic`] references
/// into the module, returning a hash key.
/// into the [`Module`], returning a hash key.
///
/// Use this to register a built-in function which must reference settings on the scripting
/// [`Engine`][crate::Engine] (e.g. to prevent growing an array beyond the allowed maximum size),
@ -668,13 +672,13 @@ impl Module {
///
/// If there is a similar existing Rust function, it is replaced.
///
/// ## WARNING - Low Level API
/// # WARNING - Low Level API
///
/// This function is very low level.
///
/// A list of [`TypeId`]'s is taken as the argument types.
///
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`],
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][Dynamic],
/// which is guaranteed to contain enough arguments of the correct types.
///
/// The function is assumed to be a _method_, meaning that the first argument should not be consumed.
@ -746,7 +750,7 @@ impl Module {
)
}
/// Set a Rust function taking no parameters into the module, returning a hash key.
/// Set a Rust function taking no parameters into the [`Module`], returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
///
@ -781,7 +785,7 @@ impl Module {
)
}
/// Set a Rust function taking one parameter into the module, returning a hash key.
/// Set a Rust function taking one parameter into the [`Module`], returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
///
@ -818,7 +822,7 @@ impl Module {
)
}
/// Set a Rust function taking one mutable parameter into the module, returning a hash key.
/// Set a Rust function taking one mutable parameter into the [`Module`], returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
///
@ -890,7 +894,7 @@ impl Module {
)
}
/// Set a Rust function taking two parameters into the module, returning a hash key.
/// Set a Rust function taking two parameters into the [`Module`], returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
///
@ -932,7 +936,7 @@ impl Module {
)
}
/// Set a Rust function taking two parameters (the first one mutable) into the module,
/// Set a Rust function taking two parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
@ -979,7 +983,7 @@ impl Module {
)
}
/// Set a Rust setter function taking two parameters (the first one mutable) into the module,
/// Set a Rust setter function taking two parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
/// This function is automatically exposed to the global namespace.
///
@ -1015,7 +1019,7 @@ impl Module {
)
}
/// Set a Rust index getter taking two parameters (the first one mutable) into the module,
/// Set a Rust index getter taking two parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
/// This function is automatically exposed to the global namespace.
///
@ -1064,7 +1068,7 @@ impl Module {
self.set_fn_2_mut(crate::engine::FN_IDX_GET, FnNamespace::Global, func)
}
/// Set a Rust function taking three parameters into the module, returning a hash key.
/// Set a Rust function taking three parameters into the [`Module`], returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
///
@ -1112,7 +1116,7 @@ impl Module {
)
}
/// Set a Rust function taking three parameters (the first one mutable) into the module,
/// Set a Rust function taking three parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
@ -1165,7 +1169,7 @@ impl Module {
)
}
/// Set a Rust index setter taking three parameters (the first one mutable) into the module,
/// Set a Rust index setter taking three parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
/// This function is automatically exposed to the global namespace.
///
@ -1276,7 +1280,7 @@ impl Module {
)
}
/// Set a Rust function taking four parameters into the module, returning a hash key.
/// Set a Rust function taking four parameters into the [`Module`], returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
///
@ -1331,7 +1335,7 @@ impl Module {
)
}
/// Set a Rust function taking four parameters (the first one mutable) into the module,
/// Set a Rust function taking four parameters (the first one mutable) into the [`Module`],
/// returning a hash key.
///
/// If there is a similar existing Rust function, it is replaced.
@ -1393,7 +1397,7 @@ impl Module {
/// Get a Rust function.
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`].
/// The [`NonZeroU64`] hash is calculated by the function [`calc_native_fn_hash`][crate::calc_native_fn_hash].
/// It is also returned by the `set_fn_XXX` calls.
#[inline(always)]
pub(crate) fn get_fn(
@ -1410,9 +1414,10 @@ impl Module {
})
}
/// Does the particular namespace-qualified function exist in the module?
/// Does the particular namespace-qualified function exist in the [`Module`]?
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`] and must match
/// The [`NonZeroU64`] hash is calculated by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] and must match
/// the hash calculated by [`build_index`][Module::build_index].
#[inline(always)]
pub fn contains_qualified_fn(&self, hash_fn: NonZeroU64) -> bool {
@ -1421,7 +1426,8 @@ impl Module {
/// Get a namespace-qualified function.
///
/// The [`NonZeroU64`] hash is calculated by the function [`crate::calc_native_fn_hash`] and must match
/// The [`NonZeroU64`] hash is calculated by the function
/// [`calc_native_fn_hash`][crate::calc_native_fn_hash] and must match
/// the hash calculated by [`build_index`][Module::build_index].
#[inline(always)]
pub(crate) fn get_qualified_fn(
@ -1431,8 +1437,8 @@ impl Module {
self.all_functions.get(&hash_qualified_fn)
}
/// Combine another module into this module.
/// The other module is consumed to merge into this module.
/// Combine another [`Module`] into this [`Module`].
/// The other [`Module`] is _consumed_ to merge into this [`Module`].
#[inline]
pub fn combine(&mut self, other: Self) -> &mut Self {
self.modules.extend(other.modules.into_iter());
@ -1446,9 +1452,9 @@ impl Module {
self
}
/// Combine another module into this module.
/// The other module is consumed to merge into this module.
/// Sub-modules are flattened onto the root module, with higher level overriding lower level.
/// Combine another [`Module`] into this [`Module`].
/// The other [`Module`] is _consumed_ to merge into this [`Module`].
/// Sub-modules are flattened onto the root [`Module`], with higher level overriding lower level.
#[inline]
pub fn combine_flatten(&mut self, other: Self) -> &mut Self {
other.modules.into_iter().for_each(|(_, m)| {
@ -1464,8 +1470,8 @@ impl Module {
self
}
/// Poly-fill this module with another module.
/// Only items not existing in this module are added.
/// Polyfill this [`Module`] with another [`Module`].
/// Only items not existing in this [`Module`] are added.
#[inline]
pub fn fill_with(&mut self, other: &Self) -> &mut Self {
other.modules.iter().for_each(|(k, v)| {
@ -1491,13 +1497,13 @@ impl Module {
self
}
/// Merge another module into this module.
/// Merge another [`Module`] into this [`Module`].
#[inline(always)]
pub fn merge(&mut self, other: &Self) -> &mut Self {
self.merge_filtered(other, &mut |_, _, _, _, _| true)
}
/// Merge another module into this module based on a filter predicate.
/// Merge another [`Module`] into this [`Module`] based on a filter predicate.
pub(crate) fn merge_filtered(
&mut self,
other: &Self,
@ -1583,7 +1589,7 @@ impl Module {
self
}
/// Get the number of variables, functions and type iterators in the module.
/// Get the number of variables, functions and type iterators in the [`Module`].
#[inline(always)]
pub fn count(&self) -> (usize, usize, usize) {
(
@ -1593,19 +1599,19 @@ impl Module {
)
}
/// Get an iterator to the sub-modules in the module.
/// Get an iterator to the sub-modules in the [`Module`].
#[inline(always)]
pub fn iter_sub_modules(&self) -> impl Iterator<Item = (&str, Shared<Module>)> {
self.modules.iter().map(|(k, m)| (k.as_str(), m.clone()))
}
/// Get an iterator to the variables in the module.
/// Get an iterator to the variables in the [`Module`].
#[inline(always)]
pub fn iter_var(&self) -> impl Iterator<Item = (&str, &Dynamic)> {
self.variables.iter().map(|(k, v)| (k.as_str(), v))
}
/// Get an iterator to the functions in the module.
/// Get an iterator to the functions in the [`Module`].
#[cfg(not(feature = "no_optimize"))]
#[cfg(not(feature = "no_function"))]
#[inline(always)]
@ -1613,7 +1619,7 @@ impl Module {
self.functions.values()
}
/// Get an iterator over all script-defined functions in the module.
/// Get an iterator over all script-defined functions in the [`Module`].
///
/// Function metadata includes:
/// 1) Namespace ([`FnNamespace::Global`] or [`FnNamespace::Internal`]).
@ -1646,7 +1652,7 @@ impl Module {
)
}
/// Get an iterator over all script-defined functions in the module.
/// Get an iterator over all script-defined functions in the [`Module`].
///
/// Function metadata includes:
/// 1) Namespace ([`FnNamespace::Global`] or [`FnNamespace::Internal`]).
@ -1670,7 +1676,7 @@ impl Module {
)
}
/// Get an iterator over all script-defined functions in the module.
/// Get an iterator over all script-defined functions in the [`Module`].
///
/// Function metadata includes:
/// 1) Namespace ([`FnNamespace::Global`] or [`FnNamespace::Internal`]).
@ -1688,11 +1694,11 @@ impl Module {
self.iter_script_fn()
}
/// Create a new module by evaluating an [`AST`][crate::AST].
/// Create a new [`Module`] by evaluating an [`AST`][crate::AST].
///
/// The entire [`AST`][crate::AST] is encapsulated into each function, allowing functions
/// to cross-call each other. Functions in the global namespace, plus all functions
/// defined in the module, are _merged_ into a _unified_ namespace before each call.
/// defined in the [`Module`], are _merged_ into a _unified_ namespace before each call.
/// Therefore, all functions will be found.
///
/// # Example
@ -1765,10 +1771,10 @@ impl Module {
Ok(module)
}
/// Scan through all the sub-modules in the module and build a hash index of all
/// Scan through all the sub-modules in the [`Module`] and build a hash index of all
/// variables and functions as one flattened namespace.
///
/// If the module is already indexed, this method has no effect.
/// If the [`Module`] is already indexed, this method has no effect.
pub fn build_index(&mut self) -> &mut Self {
// Collect a particular module.
fn index_module<'a>(
@ -1886,14 +1892,14 @@ impl Module {
self.type_iterators.contains_key(&id)
}
/// Set a type iterator into the module.
/// Set a type iterator into the [`Module`].
pub fn set_iter(&mut self, typ: TypeId, func: IteratorFn) -> &mut Self {
self.type_iterators.insert(typ, func);
self.indexed = false;
self
}
/// Set a type iterator into the module.
/// Set a type iterator into the [`Module`].
pub fn set_iterable<T>(&mut self) -> &mut Self
where
T: Variant + Clone + IntoIterator,
@ -1904,7 +1910,7 @@ impl Module {
})
}
/// Set an iterator type into the module as a type iterator.
/// Set an iterator type into the [`Module`] as a type iterator.
pub fn set_iterator<T>(&mut self) -> &mut Self
where
T: Variant + Clone + Iterator,
@ -1934,7 +1940,7 @@ impl Module {
/// A [`StaticVec`] is used because most namespace-qualified access contains only one level,
/// and it is wasteful to always allocate a [`Vec`] with one element.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Clone, Eq, PartialEq, Default, Hash)]
@ -2018,10 +2024,9 @@ impl NamespaceRef {
}
}
/// Re-export module resolver trait.
#[cfg(not(feature = "no_module"))]
pub use resolvers::ModuleResolver;
/// Re-export module resolvers.
/// Module containing all built-in [module resolvers][ModuleResolver].
#[cfg(not(feature = "no_module"))]
pub mod resolvers;

18
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 resolves,
/// [Module] resolution service that holds a collection of [module][Module] resolves,
/// to be searched in sequential order.
///
/// # Example
@ -42,13 +42,13 @@ impl ModuleResolversCollection {
pub fn new() -> Self {
Default::default()
}
/// Append a module resolver to the end.
/// Append a [module resolver][ModuleResolver] to the end.
#[inline(always)]
pub fn push(&mut self, resolver: impl ModuleResolver + 'static) -> &mut Self {
self.0.push(Box::new(resolver));
self
}
/// Insert a module resolver to an offset index.
/// Insert a [module resolver][ModuleResolver] to an offset index.
///
/// # Panics
///
@ -58,12 +58,12 @@ impl ModuleResolversCollection {
self.0.insert(index, Box::new(resolver));
self
}
/// Remove the last module resolver from the end, if any.
/// Remove the last [module resolver][ModuleResolver] from the end, if any.
#[inline(always)]
pub fn pop(&mut self) -> Option<Box<dyn ModuleResolver>> {
self.0.pop()
}
/// Remove a module resolver at an offset index.
/// Remove a [module resolver][ModuleResolver] at an offset index.
///
/// # Panics
///
@ -72,17 +72,17 @@ impl ModuleResolversCollection {
pub fn remove(&mut self, index: usize) -> Box<dyn ModuleResolver> {
self.0.remove(index)
}
/// Get an iterator of all the module resolvers.
/// Get an iterator of all the [module resolvers][ModuleResolver].
#[inline(always)]
pub fn iter(&self) -> impl Iterator<Item = &dyn ModuleResolver> {
self.0.iter().map(|v| v.as_ref())
}
/// Get a mutable iterator of all the modules.
/// Get a mutable iterator of all the [module resolvers][ModuleResolver].
#[inline(always)]
pub fn into_iter(self) -> impl Iterator<Item = Box<dyn ModuleResolver>> {
self.0.into_iter()
}
/// Remove all module resolvers.
/// Remove all [module resolvers][ModuleResolver].
#[inline(always)]
pub fn clear(&mut self) -> &mut Self {
self.0.clear();
@ -93,7 +93,7 @@ impl ModuleResolversCollection {
pub fn is_empty(&self) -> bool {
self.0.is_empty()
}
/// Get the number of module resolvers in this [`ModuleResolversCollection`].
/// Get the number of [module resolvers][ModuleResolver] in this [`ModuleResolversCollection`].
#[inline(always)]
pub fn len(&self) -> usize {
self.0.len()

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

@ -1,7 +1,7 @@
use crate::stdlib::boxed::Box;
use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
/// Empty/disabled module resolution service that acts as a dummy.
/// Empty/disabled [module][Module] resolution service that acts as a dummy.
///
/// # Example
///

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

@ -7,21 +7,15 @@ use crate::stdlib::{
};
use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
/// Module resolution service that loads module script files from the file system.
/// [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.
///
/// The [`new_with_path`][FileModuleResolver::new_with_path] and
/// [`new_with_path_and_extension`][FileModuleResolver::new_with_path_and_extension] constructor functions
/// allow specification of a base directory with module path used as a relative path offset
/// to the base directory. The script file is then forced to be in a specified extension
/// (default `.rhai`).
///
/// # Function Namespace
///
/// When a function within a script file module is loaded, all functions in the _global_ namespace
/// 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 cross-call each other.
/// the call. Therefore, functions in a module script can always cross-call each other.
///
/// # Example
///
@ -58,6 +52,8 @@ impl Default for FileModuleResolver {
impl FileModuleResolver {
/// Create a new [`FileModuleResolver`] with a specific base path.
///
/// The default extension is `.rhai`.
///
/// # Example
///
/// ```
@ -78,8 +74,6 @@ impl FileModuleResolver {
/// Create a new [`FileModuleResolver`] with a specific base path and file extension.
///
/// The default extension is `.rhai`.
///
/// # Example
///
/// ```
@ -107,6 +101,8 @@ impl FileModuleResolver {
/// Create a new [`FileModuleResolver`] with the current directory as base path.
///
/// The default extension is `.rhai`.
///
/// # Example
///
/// ```
@ -159,7 +155,9 @@ impl FileModuleResolver {
self.cache.write().unwrap().clear();
}
/// Empty the internal cache.
/// 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>> {
#[cfg(not(feature = "sync"))]

18
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 added into it.
/// [Module] resolution service that serves [modules][Module] added into it.
///
/// # Example
///
@ -42,13 +42,13 @@ impl StaticModuleResolver {
pub fn new() -> Self {
Default::default()
}
/// Add a module keyed by its path.
/// Add a [module][Module] keyed by its path.
#[inline(always)]
pub fn insert(&mut self, path: impl Into<String>, mut module: Module) {
module.build_index();
self.0.insert(path.into(), module.into());
}
/// Remove a module given its path.
/// Remove a [module][Module] given its path.
#[inline(always)]
pub fn remove(&mut self, path: &str) -> Option<Shared<Module>> {
self.0.remove(path)
@ -58,12 +58,12 @@ impl StaticModuleResolver {
pub fn contains_path(&self, path: &str) -> bool {
self.0.contains_key(path)
}
/// Get an iterator of all the modules.
/// Get an iterator of all the [modules][Module].
#[inline(always)]
pub fn iter(&self) -> impl Iterator<Item = (&str, &Shared<Module>)> {
self.0.iter().map(|(k, v)| (k.as_str(), v))
}
/// Get a mutable iterator of all the modules.
/// Get a mutable iterator of all the [modules][Module].
#[inline(always)]
pub fn iter_mut(&mut self) -> impl Iterator<Item = (&str, &mut Shared<Module>)> {
self.0.iter_mut().map(|(k, v)| (k.as_str(), v))
@ -73,17 +73,17 @@ impl StaticModuleResolver {
pub fn into_iter(self) -> impl Iterator<Item = (String, Shared<Module>)> {
self.0.into_iter()
}
/// Get an iterator of all the module paths.
/// Get an iterator of all the [module][Module] paths.
#[inline(always)]
pub fn paths(&self) -> impl Iterator<Item = &str> {
self.0.keys().map(String::as_str)
}
/// Get an iterator of all the modules.
/// Get an iterator of all the [modules][Module].
#[inline(always)]
pub fn values(&self) -> impl Iterator<Item = &Shared<Module>> {
self.0.values().map(|m| m)
}
/// Remove all modules.
/// Remove all [modules][Module].
#[inline(always)]
pub fn clear(&mut self) {
self.0.clear();
@ -93,7 +93,7 @@ impl StaticModuleResolver {
pub fn is_empty(&self) -> bool {
self.0.is_empty()
}
/// Get the number of modules in this [`StaticModuleResolver`].
/// Get the number of [modules][Module] in this [`StaticModuleResolver`].
#[inline(always)]
pub fn len(&self) -> usize {
self.0.len()

2
src/optimize.rs
View File

@ -19,8 +19,6 @@ use crate::utils::get_hasher;
use crate::{calc_native_fn_hash, Dynamic, Engine, Module, Position, Scope, StaticVec, AST};
/// Level of optimization performed.
///
/// Not available under the `no_optimize` feature.
#[derive(Debug, Eq, PartialEq, Hash, Clone, Copy)]
pub enum OptimizationLevel {
/// No optimization performed.

4
src/packages/mod.rs
View File

@ -41,9 +41,9 @@ pub trait Package {
/// Retrieve the generic package library from this package.
///
/// ## Deprecated
/// # Deprecated
///
/// Use `as_shared_module` instead.
/// Use [`as_shared_module`][Package::as_shared_module] instead.
#[deprecated = "use `as_shared_module` instead"]
fn get(&self) -> Shared<Module> {
self.as_shared_module()

2
src/parse_error.rs
View File

@ -11,7 +11,7 @@ use crate::{EvalAltResult, Position};
/// _(INTERNALS)_ Error encountered when tokenizing the script text.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Eq, PartialEq, Clone, Hash)]

8
src/parser.rs
View File

@ -173,11 +173,9 @@ impl<'e> ParseState<'e> {
) -> ImmutableString {
#[allow(clippy::map_entry)]
if !self.strings.contains_key(text.as_ref()) {
let value: ImmutableString = text.into();
let result = value.clone();
let key = value.to_string();
self.strings.insert(key, value);
result
let value = text.into();
self.strings.insert(value.clone().into(), value.clone());
value
} else {
self.strings.get(text.as_ref()).unwrap().clone()
}

2
src/scope.rs
View File

@ -445,7 +445,7 @@ impl<'a> Scope<'a> {
/// let mut my_scope = Scope::new();
///
/// my_scope.push("x", 42_i64);
/// my_scope.push_constant("foo", "hello".to_string());
/// my_scope.push_constant("foo", "hello");
///
/// let mut iter = my_scope.iter();
///

4
src/syntax.rs
View File

@ -64,7 +64,7 @@ impl Expression<'_> {
impl EvalContext<'_, '_, '_, '_, '_, '_, '_, '_, '_> {
/// Evaluate an [expression tree][Expression].
///
/// ## WARNING - Low Level API
/// # WARNING - Low Level API
///
/// This function is very low level. It evaluates an expression from an [`AST`][crate::AST].
#[inline(always)]
@ -210,7 +210,7 @@ impl Engine {
}
/// Register a custom syntax with the [`Engine`].
///
/// ## WARNING - Low Level API
/// # WARNING - Low Level API
///
/// This function is very low level.
///

10
src/token.rs
View File

@ -149,7 +149,7 @@ impl fmt::Debug for Position {
/// _(INTERNALS)_ A Rhai language token.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, PartialEq, Clone)]
@ -741,7 +741,7 @@ impl From<Token> for String {
/// _(INTERNALS)_ State of the tokenizer.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[derive(Debug, Clone, Eq, PartialEq, Default)]
@ -763,7 +763,7 @@ pub struct TokenizeState {
/// _(INTERNALS)_ Trait that encapsulates a peekable character input stream.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This trait is volatile and may change.
pub trait InputStream {
@ -777,7 +777,7 @@ pub trait InputStream {
/// _(INTERNALS)_ Parse a string literal wrapped by `enclosing_char`.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
pub fn parse_string_literal(
@ -968,7 +968,7 @@ fn scan_block_comment(
/// _(INTERNALS)_ Get the next token from the `stream`.
/// Exported under the `internals` feature only.
///
/// ## WARNING
/// # WARNING
///
/// This type is volatile and may change.
#[inline]