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

Refine doc comments.

Browse Source
This commit is contained in:
Stephen Chung 2021-05-10 11:07:19 +08:00
parent 2cf59e9954
commit fd19d625b0
7 changed files with 131 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -14,6 +14,7 @@ New features
* Each `Dynamic` value can now contain arbitrary data (type `i16`) in the form of a _tag_. This is to use up otherwise wasted space in the `Dynamic` type.
* A new internal feature `no_smartstring` to turn off `SmartString` for those rare cases that it is needed.
* `DynamicReadLock` and `DynamicWriteLoc` are exposed under `internals`.
Version 0.20.1

30
src/ast.rs
View File

@ -53,6 +53,8 @@ pub struct ScriptFnDef {
/// Encapsulated running environment, if any.
pub lib: Option<Shared<Module>>,
/// Encapsulated imported modules.
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
pub mods: crate::engine::Imports,
/// Function name.
@ -62,9 +64,14 @@ pub struct ScriptFnDef {
/// Names of function parameters.
pub params: StaticVec<Identifier>,
/// Access to external variables.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
pub externals: std::collections::BTreeSet<Identifier>,
/// Function doc-comments (if any).
/// _(METADATA)_ Function doc-comments (if any).
/// Exported under the `metadata` feature only.
///
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
#[cfg(feature = "metadata")]
pub comments: StaticVec<String>,
@ -98,7 +105,10 @@ impl fmt::Display for ScriptFnDef {
#[cfg(not(feature = "no_function"))]
#[derive(Debug, Eq, PartialEq, Clone, Hash)]
pub struct ScriptFnMetadata<'a> {
/// Function doc-comments (if any).
/// _(METADATA)_ Function doc-comments (if any).
/// Exported under the `metadata` feature only.
///
/// Not available under `no_function`.
///
/// Block doc-comments are kept in a single string slice with line-breaks within.
///
@ -180,6 +190,8 @@ pub struct AST {
/// Script-defined functions.
functions: Shared<Module>,
/// Embedded module resolver, if any.
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
resolver: Option<Shared<crate::module::resolvers::StaticModuleResolver>>,
}
@ -287,7 +299,7 @@ impl AST {
/// _(INTERNALS)_ Get the internal shared [`Module`] containing all script-defined functions.
/// Exported under the `internals` feature only.
///
/// Not available under `no_function`.
/// Not available under `no_function` or `no_module`.
#[cfg(feature = "internals")]
#[deprecated = "this method is volatile and may change"]
#[cfg(not(feature = "no_module"))]
@ -323,6 +335,8 @@ impl AST {
}
/// _(INTERNALS)_ Get the embedded [module resolver][crate::ModuleResolver].
/// Exported under the `internals` feature only.
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
#[cfg(feature = "internals")]
#[inline(always)]
@ -960,12 +974,18 @@ pub enum Stmt {
/// `return`/`throw`
Return(ReturnType, Option<Expr>, Position),
/// `import` expr `as` var
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
Import(Expr, Option<Box<Ident>>, Position),
/// `export` var `as` var `,` ...
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
Export(Box<[(Ident, Option<Ident>)]>, Position),
/// Convert a variable to shared.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
Share(Identifier),
}
@ -1529,6 +1549,8 @@ impl FnCallExpr {
}
/// A type that wraps a floating-point number and implements [`Hash`].
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
#[derive(Clone, Copy, PartialEq, PartialOrd)]
pub struct FloatWrapper<F>(F);
@ -1659,6 +1681,8 @@ pub enum Expr {
/// Integer constant.
IntegerConstant(INT, Position),
/// Floating-point constant.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
FloatConstant(FloatWrapper<FLOAT>, Position),
/// Character constant.

51
src/dynamic.rs
View File

@ -164,20 +164,29 @@ pub enum Union {
/// An integer value.
Int(INT, Tag, AccessMode),
/// A floating-point value.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
Float(FloatWrapper<FLOAT>, Tag, AccessMode),
/// A fixed-precision decimal value.
/// _(DECIMAL)_ A fixed-precision decimal value.
/// Exported under the `decimal` feature only.
#[cfg(feature = "decimal")]
Decimal(Box<Decimal>, Tag, AccessMode),
/// An array value.
///
/// Not available under `no_index`.
#[cfg(not(feature = "no_index"))]
Array(Box<Array>, Tag, AccessMode),
/// An object map value.
///
/// Not available under `no_object`.
#[cfg(not(feature = "no_object"))]
Map(Box<Map>, Tag, AccessMode),
/// A function pointer.
FnPtr(Box<FnPtr>, Tag, AccessMode),
/// A timestamp value.
///
/// Not available under `no-std`.
#[cfg(not(feature = "no_std"))]
TimeStamp(Box<Instant>, Tag, AccessMode),
@ -185,14 +194,21 @@ pub enum Union {
Variant(Box<Box<dyn Variant>>, Tag, AccessMode),
/// A _shared_ value of any type.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
Shared(crate::Shared<crate::Locked<Dynamic>>, Tag, AccessMode),
}
/// Underlying [`Variant`] read guard for [`Dynamic`].
/// _(INTERNALS)_ Lock guard for reading a [`Dynamic`].
/// Exported under the `internals` feature only.
///
/// This data structure provides transparent interoperability between
/// normal [`Dynamic`] and shared [`Dynamic`] values.
/// This type provides transparent interoperability between normal [`Dynamic`] and shared
/// [`Dynamic`] values.
///
/// # Volatile Data Structure
///
/// This type is volatile and may change.
#[derive(Debug)]
pub struct DynamicReadLock<'d, T: Clone>(DynamicReadLockInner<'d, T>);
@ -226,10 +242,15 @@ impl<'d, T: Any + Clone> Deref for DynamicReadLock<'d, T> {
}
}
/// Underlying [`Variant`] write guard for [`Dynamic`].
/// _(INTERNALS)_ Lock guard for writing a [`Dynamic`].
/// Exported under the `internals` feature only.
///
/// This data structure provides transparent interoperability between
/// normal [`Dynamic`] and shared [`Dynamic`] values.
/// This type provides transparent interoperability between normal [`Dynamic`] and shared
/// [`Dynamic`] values.
///
/// # Volatile Data Structure
///
/// This type is volatile and may change.
#[derive(Debug)]
pub struct DynamicWriteLock<'d, T: Clone>(DynamicWriteLockInner<'d, T>);
@ -758,21 +779,27 @@ impl Dynamic {
pub const ONE: Dynamic = Self(Union::Int(1, DEFAULT_TAG, AccessMode::ReadWrite));
/// A [`Dynamic`] containing the integer negative one.
pub const NEGATIVE_ONE: Dynamic = Self(Union::Int(-1, DEFAULT_TAG, AccessMode::ReadWrite));
/// A [`Dynamic`] containing the floating-point zero.
/// A [`Dynamic`] containing `0.0`.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
pub const FLOAT_ZERO: Dynamic = Self(Union::Float(
FloatWrapper::const_new(0.0),
DEFAULT_TAG,
AccessMode::ReadWrite,
));
/// A [`Dynamic`] containing the floating-point one.
/// A [`Dynamic`] containing `1.0`.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
pub const FLOAT_ONE: Dynamic = Self(Union::Float(
FloatWrapper::const_new(1.0),
DEFAULT_TAG,
AccessMode::ReadWrite,
));
/// A [`Dynamic`] containing the floating-point negative one.
/// A [`Dynamic`] containing the `-1.0`.
///
/// Not available under `no_float`.
#[cfg(not(feature = "no_float"))]
pub const FLOAT_NEGATIVE_ONE: Dynamic = Self(Union::Float(
FloatWrapper::const_new(-1.0),
@ -1806,7 +1833,7 @@ impl From<&crate::Identifier> for Dynamic {
}
#[cfg(not(feature = "no_index"))]
impl Dynamic {
/// Create a [`Dynamc`] from an [`Array`].
/// Create a [`Dynamic`] from an [`Array`].
#[inline(always)]
pub(crate) fn from_array(array: Array) -> Self {
Self(Union::Array(
@ -1851,7 +1878,7 @@ impl<T: Variant + Clone> std::iter::FromIterator<T> for Dynamic {
}
#[cfg(not(feature = "no_object"))]
impl Dynamic {
/// Create a [`Dynamc`] from a [`Map`].
/// Create a [`Dynamic`] from a [`Map`].
#[inline(always)]
pub(crate) fn from_map(map: Map) -> Self {
Self(Union::Map(

40
src/engine_api.rs
View File

@ -183,6 +183,8 @@ impl Engine {
/// Register a custom type for use with the [`Engine`].
/// The type must implement [`Clone`].
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -224,6 +226,8 @@ impl Engine {
/// Register a custom type for use with the [`Engine`], with a pretty-print name
/// for the `type_of` function. The type must implement [`Clone`].
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -284,6 +288,8 @@ impl Engine {
///
/// The function signature must start with `&mut self` and not `&self`.
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -329,6 +335,8 @@ impl Engine {
///
/// The function signature must start with `&mut self` and not `&self`.
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -374,6 +382,8 @@ impl Engine {
}
/// Register a setter function for a member of a registered type with the [`Engine`].
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -420,6 +430,8 @@ impl Engine {
}
/// Register a setter function for a member of a registered type with the [`Engine`].
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -474,6 +486,8 @@ impl Engine {
///
/// All function signatures must start with `&mut self` and not `&self`.
///
/// Not available under `no_object`.
///
/// # Example
///
/// ```
@ -522,6 +536,8 @@ impl Engine {
///
/// The function signature must start with `&mut self` and not `&self`.
///
/// Not available under `no_index`.
///
/// # Panics
///
/// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@ -586,6 +602,8 @@ impl Engine {
///
/// The function signature must start with `&mut self` and not `&self`.
///
/// Not available under `no_index`.
///
/// # Panics
///
/// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@ -654,6 +672,8 @@ impl Engine {
}
/// Register an index setter for a custom type with the [`Engine`].
///
/// Not available under `no_index`.
///
/// # Panics
///
/// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@ -718,6 +738,8 @@ impl Engine {
}
/// Register an index setter for a custom type with the [`Engine`].
///
/// Not available under `no_index`.
///
/// # Panics
///
/// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@ -792,6 +814,8 @@ impl Engine {
}
/// Short-hand for register both index getter and setter functions for a custom type with the [`Engine`].
///
/// Not available under `no_index`.
///
/// # Panics
///
/// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@ -870,6 +894,8 @@ impl Engine {
/// Functions marked [`FnNamespace::Global`] and type iterators are exposed to scripts without
/// namespace qualifications.
///
/// Not available under `no_module`.
///
/// # Example
///
/// ```
@ -1024,6 +1050,8 @@ impl Engine {
/// Compile a string into an [`AST`] using own scope, which can be used later for evaluation,
/// embedding all imported modules.
///
/// Not available under `no_module`.
///
/// Modules referred by `import` statements containing literal string paths are eagerly resolved
/// via the current [module resolver][crate::ModuleResolver] and embedded into the resultant
/// [`AST`]. When it is evaluated later, `import` statement directly recall pre-resolved
@ -1272,6 +1300,8 @@ impl Engine {
/// Parse a JSON string into an [object map][`Map`].
/// This is a light-weight alternative to using, say, [`serde_json`] to deserialize the JSON.
///
/// Not available under `no_object`.
///
/// 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 `()`.
@ -1788,6 +1818,8 @@ impl Engine {
/// Call a script function defined in an [`AST`] with multiple arguments.
/// Arguments are passed as a tuple.
///
/// Not available under `no_function`.
///
/// The [`AST`] is evaluated before calling the function.
/// This allows a script to load the necessary modules.
/// This is usually desired. If not, a specialized [`AST`] can be prepared that contains only
@ -1855,6 +1887,8 @@ impl Engine {
/// Call a script function defined in an [`AST`] with multiple [`Dynamic`] arguments
/// and optionally a value for binding to the `this` pointer.
///
/// Not available under `no_function`.
///
/// There is an option to evaluate the [`AST`] to load necessary modules before calling the function.
///
/// # WARNING
@ -1971,6 +2005,8 @@ impl Engine {
/// Optimize the [`AST`] with constants defined in an external Scope.
/// An optimized copy of the [`AST`] is returned while the original [`AST`] is consumed.
///
/// Not available under `no_optimize`.
///
/// Although optimization is performed by default during compilation, sometimes it is necessary to
/// _re_-optimize an [`AST`]. For example, when working with constants that are passed in via an
/// external scope, it will be more efficient to optimize the [`AST`] once again to take advantage
@ -2003,7 +2039,7 @@ impl Engine {
let stmt = std::mem::take(ast.statements_mut());
crate::optimize::optimize_into_ast(self, scope, stmt.into_vec(), lib, optimization_level)
}
/// Generate a list of all registered functions.
/// _(METADATA)_ Generate a list of all registered functions.
/// Exported under the `metadata` feature only.
///
/// Functions from the following sources are included, in order:
@ -2074,6 +2110,8 @@ impl Engine {
}
/// Register a callback for script evaluation progress.
///
/// Not available under `unchecked`.
///
/// # Example
///
/// ```

16
src/fn_native.rs
View File

@ -39,10 +39,14 @@ pub use std::rc::Rc as Shared;
pub use std::sync::Arc as Shared;
/// Synchronized shared object.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
#[cfg(not(feature = "sync"))]
pub use std::cell::RefCell as Locked;
/// Synchronized shared object.
///
/// Not available under `no_closure`.
#[cfg(not(feature = "no_closure"))]
#[cfg(feature = "sync")]
pub use std::sync::RwLock as Locked;
@ -101,6 +105,8 @@ impl<'a> NativeCallContext<'a> {
}
/// _(INTERNALS)_ Create a new [`NativeCallContext`].
/// Exported under the `internals` feature only.
///
/// Not available under `no_module`.
#[cfg(feature = "internals")]
#[cfg(not(feature = "no_module"))]
#[inline(always)]
@ -135,6 +141,8 @@ impl<'a> NativeCallContext<'a> {
self.source
}
/// Get an iterator over the current set of modules imported via `import` statements.
///
/// Not available under `no_module`.
#[cfg(not(feature = "no_module"))]
#[inline(always)]
pub fn iter_imports(&self) -> impl Iterator<Item = (&str, &Module)> {
@ -151,6 +159,8 @@ impl<'a> NativeCallContext<'a> {
}
/// _(INTERNALS)_ The current set of modules imported via `import` statements.
/// Exported under the `internals` feature only.
///
/// Not available under `no_module`.
#[cfg(feature = "internals")]
#[cfg(not(feature = "no_module"))]
#[inline(always)]
@ -303,6 +313,8 @@ impl FnPtr {
!self.1.is_empty()
}
/// Does the function pointer refer to an anonymous function?
///
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
#[inline(always)]
pub fn is_anonymous(&self) -> bool {
@ -467,6 +479,8 @@ pub enum CallableFunction {
/// A plugin function,
Plugin(Shared<FnPlugin>),
/// A script-defined function.
///
/// Not available under `no_function`.
#[cfg(not(feature = "no_function"))]
Script(Shared<crate::ast::ScriptFnDef>),
}
@ -601,6 +615,8 @@ impl CallableFunction {
}
/// Get a shared reference to a script-defined function definition.
///
/// Not available under `no_function`.
///
/// # Panics
///
/// Panics if the [`CallableFunction`] is not [`Script`][CallableFunction::Script].

6
src/fn_register.rs
View File

@ -61,15 +61,15 @@ pub trait RegisterNativeFunction<Args, Result> {
fn into_callable_function(self) -> CallableFunction;
/// Get the type ID's of this function's parameters.
fn param_types() -> Box<[TypeId]>;
/// Get the type names of this function's parameters.
/// _(METADATA)_ Get the type names of this function's parameters.
/// Exported under the `metadata` feature only.
#[cfg(feature = "metadata")]
fn param_names() -> Box<[&'static str]>;
/// Get the type ID of this function's return value.
/// _(METADATA)_ Get the type ID of this function's return value.
/// Exported under the `metadata` feature only.
#[cfg(feature = "metadata")]
fn return_type() -> TypeId;
/// Get the type name of this function's return value.
/// _(METADATA)_ Get the type name of this function's return value.
/// Exported under the `metadata` feature only.
#[cfg(feature = "metadata")]
fn return_type_name() -> &'static str;

10
src/lib.rs
View File

@ -209,13 +209,15 @@ pub use optimize::OptimizationLevel;
#[deprecated = "this type is volatile and may change"]
pub use dynamic::{DynamicReadLock, DynamicWriteLock, Variant};
// Expose internal data structures.
#[cfg(feature = "internals")]
#[deprecated = "this function is volatile and may change"]
pub use token::{get_next_token, parse_string_literal};
// Expose internal data structures.
#[cfg(feature = "internals")]
#[deprecated = "this type is volatile and may change"]
pub use token::{
get_next_token, parse_string_literal, InputStream, Token, TokenizeState, TokenizerControl,
TokenizerControlBlock,
};
pub use token::{InputStream, Token, TokenizeState, TokenizerControl, TokenizerControlBlock};
#[cfg(feature = "internals")]
#[deprecated = "this type is volatile and may change"]