diff --git a/doc/src/language/functions.md b/doc/src/language/functions.md index 980c4799..d7f9917d 100644 --- a/doc/src/language/functions.md +++ b/doc/src/language/functions.md @@ -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; ``` diff --git a/src/ast.rs b/src/ast.rs index 65667c80..743ba661 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -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 + '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 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() => { diff --git a/src/dynamic.rs b/src/dynamic.rs index 08e473ae..47507ff6 100644 --- a/src/dynamic.rs +++ b/src/dynamic.rs @@ -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(&self) -> bool { let mut target_type_id = TypeId::of::(); @@ -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::() == TypeId::of::<&str>() { return ::downcast_ref::<&str>(&value) .unwrap() - .to_string() + .deref() .into(); } if TypeId::of::() == TypeId::of::<()>() { diff --git a/src/engine.rs b/src/engine.rs index bdf95ba2..00bce1c7 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -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 here because `eval` may load a [module][Module] and +// We cannot use Cow 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), - 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` 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 { 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> for IndexChainValue { +impl From> for ChainArgument { #[inline(always)] fn from(value: StaticVec) -> Self { Self::FnCallArgs(value) @@ -270,10 +277,10 @@ impl From> for IndexChainValue { } #[cfg(any(not(feature = "no_index"), not(feature = "no_object")))] -impl From for IndexChainValue { +impl From for ChainArgument { #[inline(always)] fn from(value: Dynamic) -> Self { - Self::Value(value) + Self::IndexValue(value) } } @@ -487,7 +494,7 @@ impl> From 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, + idx_values: &mut StaticVec, chain_type: ChainType, level: usize, new_val: Option<(Dynamic, Position)>, ) -> Result<(Dynamic, bool), Box> { - 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, + idx_values: &mut StaticVec, size: usize, level: usize, ) -> Result<(), Box> { @@ -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, diff --git a/src/engine_api.rs b/src/engine_api.rs index ff07e9e8..5f5b4b21 100644 --- a/src/engine_api.rs +++ b/src/engine_api.rs @@ -35,7 +35,7 @@ fn calc_hash_for_scripts<'a>(scripts: impl IntoIterator) -> 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::(); - /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Use `register_fn` to register methods on the type. - /// engine.register_fn("update", TestStruct::update); + /// // Register API for the custom type. + /// engine + /// .register_type::() + /// .register_fn("new_ts", TestStruct::new) + /// // Use `register_fn` to register methods on the type. + /// .register_fn("update", TestStruct::update); /// /// assert_eq!( /// engine.eval::("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::(); - /// - /// engine.register_fn("new_ts", TestStruct::new); + /// // Register API for the custom type. + /// engine + /// .register_type::() + /// .register_fn("new_ts", TestStruct::new); /// /// assert_eq!( /// engine.eval::("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::("Hello"); /// - /// // Register methods on the type. - /// engine.register_fn("new_ts", TestStruct::new); - /// /// assert_eq!( /// engine.eval::("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::(); - /// - /// engine.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 API for the custom type. + /// engine + /// .register_type::() + /// .register_fn("new_ts", TestStruct::new) + /// // Register a getter on a property (notice it doesn't have to be the same name). + /// .register_get("xyz", TestStruct::get_field); /// /// assert_eq!(engine.eval::("let a = new_ts(); a.xyz")?, 1); /// # Ok(()) @@ -239,13 +234,12 @@ impl Engine { /// # fn main() -> Result<(), Box> { /// let mut engine = Engine::new(); /// - /// // Register the custom type. - /// engine.register_type::(); - /// - /// engine.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 API for the custom type. + /// engine + /// .register_type::() + /// .register_fn("new_ts", TestStruct::new) + /// // Register a getter on a property (notice it doesn't have to be the same name). + /// .register_get_result("xyz", TestStruct::get_field); /// /// assert_eq!(engine.eval::("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::(); - /// - /// engine.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 API for the custom type. + /// engine + /// .register_type::() + /// .register_fn("new_ts", TestStruct::new) + /// // Register a setter on a property (notice it doesn't have to be the same name) + /// .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> { /// let mut engine = Engine::new(); /// - /// // Register the custom type. - /// engine.register_type::(); - /// - /// engine.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 API for the custom type. + /// engine + /// .register_type::() + /// .register_fn("new_ts", TestStruct::new) + /// // Register a setter on a property (notice it doesn't have to be the same name) + /// .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::(); - /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Register 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 API for the custom type. + /// engine + /// .register_type::() + /// .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) + /// .register_get_set("xyz", TestStruct::get_field, TestStruct::set_field); /// /// assert_eq!(engine.eval::("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::(); /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Register an indexer. - /// engine.register_indexer_get(TestStruct::get_field); + /// engine + /// .register_fn("new_ts", TestStruct::new) + /// // Register an indexer. + /// .register_indexer_get(TestStruct::get_field); /// /// assert_eq!(engine.eval::("let a = new_ts(); a[2]")?, 3); /// # Ok(()) @@ -500,14 +491,14 @@ impl Engine { /// # fn main() -> Result<(), Box> { /// let mut engine = Engine::new(); /// - /// // Register the custom type. + /// // Register API for the custom type. /// # #[cfg(not(feature = "no_object"))] /// engine.register_type::(); /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Register an indexer. - /// engine.register_indexer_get_result(TestStruct::get_field); + /// engine + /// .register_fn("new_ts", TestStruct::new) + /// // Register an indexer. + /// .register_indexer_get_result(TestStruct::get_field); /// /// assert_eq!(engine.eval::("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::(); /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Register an indexer. - /// engine.register_indexer_set(TestStruct::set_field); + /// engine + /// .register_fn("new_ts", TestStruct::new) + /// // Register an indexer. + /// .register_indexer_set(TestStruct::set_field); /// /// assert_eq!( /// engine.eval::("let a = new_ts(); a[2] = 42; a")?.fields[2], @@ -628,14 +619,14 @@ impl Engine { /// # fn main() -> Result<(), Box> { /// let mut engine = Engine::new(); /// - /// // Register the custom type. + /// // Register API for the custom type. /// # #[cfg(not(feature = "no_object"))] /// engine.register_type::(); /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Register an indexer. - /// engine.register_indexer_set_result(TestStruct::set_field); + /// engine + /// .register_fn("new_ts", TestStruct::new) + /// // Register an indexer. + /// .register_indexer_set_result(TestStruct::set_field); /// /// assert_eq!( /// engine.eval::("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::(); /// - /// engine.register_fn("new_ts", TestStruct::new); - /// - /// // Register an indexer. - /// engine.register_indexer_get_set(TestStruct::get_field, TestStruct::set_field); + /// engine + /// .register_fn("new_ts", TestStruct::new) + /// // Register an indexer. + /// .register_indexer_get_set(TestStruct::get_field, TestStruct::set_field); /// /// assert_eq!(engine.eval::("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>) -> &mut Self { @@ -768,13 +759,12 @@ impl Engine { /// /// let module: Shared = module.into(); /// - /// // Register the module as a fixed sub-module - /// engine.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); + /// engine + /// // Register the module as a fixed sub-module + /// .register_static_module("foo::bar::baz", module.clone()) + /// // Multiple registrations to the same partial path is also OK! + /// .register_static_module("foo::bar::hello", module.clone()) + /// .register_static_module("CalcService", module); /// /// assert_eq!(engine.eval::("foo::bar::baz::calc(41)")?, 42); /// assert_eq!(engine.eval::("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> { 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. /// diff --git a/src/engine_settings.rs b/src/engine_settings.rs index cb60a6d0..7d99c1fa 100644 --- a/src/engine_settings.rs +++ b/src/engine_settings.rs @@ -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( diff --git a/src/fn_call.rs b/src/fn_call.rs index 0788dde7..85da3fcb 100644 --- a/src/fn_call.rs +++ b/src/fn_call.rs @@ -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> { 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 { diff --git a/src/fn_func.rs b/src/fn_func.rs index 1791c0ba..e4b2d4ed 100644 --- a/src/fn_func.rs +++ b/src/fn_func.rs @@ -12,6 +12,7 @@ pub trait Func { 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 { 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 diff --git a/src/fn_native.rs b/src/fn_native.rs index 324ff54a..261a3935 100644 --- a/src/fn_native.rs +++ b/src/fn_native.rs @@ -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 { - 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. diff --git a/src/lib.rs b/src/lib.rs index 9f7a8773..a618879d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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; /// 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; diff --git a/src/module/mod.rs b/src/module/mod.rs index 7413b1ac..97a3fada 100644 --- a/src/module/mod.rs +++ b/src/module/mod.rs @@ -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, /// Sub-modules. modules: HashMap>, - /// Module variables. + /// [`Module`] variables. variables: HashMap, - /// 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, /// External Rust functions. functions: HashMap, @@ -146,7 +144,7 @@ pub struct Module { type_iterators: HashMap, /// Flattened collection of iterator functions, including those in sub-modules. all_type_iterators: HashMap, - /// Is the module indexed? + /// Is the [`Module`] indexed? indexed: bool, } @@ -203,7 +201,7 @@ impl AsRef 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 { &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 + '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::) } - /// 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> { @@ -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)> { 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 { 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(&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(&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; diff --git a/src/module/resolvers/collection.rs b/src/module/resolvers/collection.rs index 30039234..6a6009c3 100644 --- a/src/module/resolvers/collection.rs +++ b/src/module/resolvers/collection.rs @@ -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> { 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 { 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 { 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> { 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() diff --git a/src/module/resolvers/dummy.rs b/src/module/resolvers/dummy.rs index 8ed3b3f0..d238b448 100644 --- a/src/module/resolvers/dummy.rs +++ b/src/module/resolvers/dummy.rs @@ -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 /// diff --git a/src/module/resolvers/file.rs b/src/module/resolvers/file.rs index c35c347d..fb2ee5e8 100644 --- a/src/module/resolvers/file.rs +++ b/src/module/resolvers/file.rs @@ -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) -> Option> { #[cfg(not(feature = "sync"))] diff --git a/src/module/resolvers/stat.rs b/src/module/resolvers/stat.rs index 311d92d0..f4705108 100644 --- a/src/module/resolvers/stat.rs +++ b/src/module/resolvers/stat.rs @@ -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, 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> { 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)> { 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)> { self.0.iter_mut().map(|(k, v)| (k.as_str(), v)) @@ -73,17 +73,17 @@ impl StaticModuleResolver { pub fn into_iter(self) -> impl Iterator)> { 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 { 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> { 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() diff --git a/src/optimize.rs b/src/optimize.rs index 5ba290e0..729d43e8 100644 --- a/src/optimize.rs +++ b/src/optimize.rs @@ -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. diff --git a/src/packages/mod.rs b/src/packages/mod.rs index 9b7112bb..a2f41ada 100644 --- a/src/packages/mod.rs +++ b/src/packages/mod.rs @@ -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 { self.as_shared_module() diff --git a/src/parse_error.rs b/src/parse_error.rs index 376631fe..0a03726c 100644 --- a/src/parse_error.rs +++ b/src/parse_error.rs @@ -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)] diff --git a/src/parser.rs b/src/parser.rs index ca546ac9..7f43e9c9 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -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() } diff --git a/src/scope.rs b/src/scope.rs index 4386bae7..d60aab40 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -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(); /// diff --git a/src/syntax.rs b/src/syntax.rs index 8ce578fa..65b6513c 100644 --- a/src/syntax.rs +++ b/src/syntax.rs @@ -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. /// diff --git a/src/token.rs b/src/token.rs index c4f8d74f..7ae8ba8a 100644 --- a/src/token.rs +++ b/src/token.rs @@ -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 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]