diff --git a/src/any.rs b/src/any.rs index 3599f972..814e369a 100644 --- a/src/any.rs +++ b/src/any.rs @@ -7,9 +7,15 @@ use crate::stdlib::{ }; /// An raw value of any type. +/// +/// Currently, `Variant` is not `Send` nor `Sync`, so it can practically be any type. +/// Turn on the `sync` feature to restrict it to only types that implement `Send + Sync`. pub type Variant = dyn Any; /// A boxed dynamic type containing any value. +/// +/// Currently, `Dynamic` is not `Send` nor `Sync`, so it can practically be any type. +/// Turn on the `sync` feature to restrict it to only types that implement `Send + Sync`. pub type Dynamic = Box; /// A trait covering any type. @@ -48,6 +54,7 @@ impl Any for T { } } +/// A trait covering any type. #[cfg(not(feature = "sync"))] pub trait Any: crate::stdlib::any::Any { /// Get the `TypeId` of this type. diff --git a/src/engine.rs b/src/engine.rs index 235068a2..c60bf0d4 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -23,10 +23,14 @@ use crate::stdlib::{ }; /// An dynamic array of `Dynamic` values. +/// +/// Not available under the `no_index` feature. #[cfg(not(feature = "no_index"))] pub type Array = Vec; -/// An dynamic hash map of `Dynamic` values. +/// An dynamic hash map of `Dynamic` values with `String` keys. +/// +/// Not available under the `no_object` feature. #[cfg(not(feature = "no_object"))] pub type Map = HashMap; @@ -188,6 +192,8 @@ impl FunctionsLib { /// # Ok(()) /// # } /// ``` +/// +/// Currently, `Engine` is neither `Send` nor `Sync`. Turn on the `sync` feature to make it `Send + Sync`. pub struct Engine<'e> { /// A hashmap containing all compiled functions known to the engine. pub(crate) functions: HashMap, Box>, @@ -302,6 +308,8 @@ impl Engine<'_> { } /// Control whether and how the `Engine` will optimize an AST after compilation + /// + /// Not available under the `no_optimize` feature. #[cfg(not(feature = "no_optimize"))] pub fn set_optimization_level(&mut self, optimization_level: OptimizationLevel) { self.optimization_level = optimization_level diff --git a/src/error.rs b/src/error.rs index 2a2986b8..5fa654a5 100644 --- a/src/error.rs +++ b/src/error.rs @@ -30,9 +30,7 @@ impl fmt::Display for LexError { Self::MalformedEscapeSequence(s) => write!(f, "Invalid escape sequence: '{}'", s), Self::MalformedNumber(s) => write!(f, "Invalid number: '{}'", s), Self::MalformedChar(s) => write!(f, "Invalid character: '{}'", s), - Self::MalformedIdentifier(s) => { - write!(f, "Variable name is not in a legal format: '{}'", s) - } + Self::MalformedIdentifier(s) => write!(f, "Variable name is not proper: '{}'", s), Self::UnterminatedString => write!(f, "Open string is not terminated"), } } @@ -47,37 +45,51 @@ pub enum ParseErrorType { UnexpectedEOF, /// An unknown operator is encountered. Wrapped value is the operator. UnknownOperator(String), - /// Expecting a particular token but not finding one. Wrapped values are the token and usage. + /// Expecting a particular token but not finding one. Wrapped values are the token and description. MissingToken(String, String), - /// An expression in function call arguments `()` has syntax error. + /// An expression in function call arguments `()` has syntax error. Wrapped value is the error description (if any). MalformedCallExpr(String), - /// An expression in indexing brackets `[]` has syntax error. + /// An expression in indexing brackets `[]` has syntax error. Wrapped value is the error description (if any). + /// + /// Not available under the `no_index` feature. #[cfg(not(feature = "no_index"))] MalformedIndexExpr(String), - /// A map definition has duplicated property names. Wrapped is the property name. + /// A map definition has duplicated property names. Wrapped value is the property name. + /// + /// Not available under the `no_object` feature. #[cfg(not(feature = "no_object"))] DuplicatedProperty(String), - /// Invalid expression assigned to constant. + /// Invalid expression assigned to constant. Wrapped value is the name of the constant. ForbiddenConstantExpr(String), /// Missing a property name for custom types and maps. PropertyExpected, /// Missing a variable name after the `let`, `const` or `for` keywords. VariableExpected, - /// Missing an expression. + /// Missing an expression. Wrapped value is the expression type. ExprExpected(String), /// Defining a function `fn` in an appropriate place (e.g. inside another function). + /// + /// Not available under the `no_function` feature. #[cfg(not(feature = "no_function"))] WrongFnDefinition, /// Missing a function name after the `fn` keyword. + /// + /// Not available under the `no_function` feature. #[cfg(not(feature = "no_function"))] FnMissingName, /// A function definition is missing the parameters list. Wrapped value is the function name. + /// + /// Not available under the `no_function` feature. #[cfg(not(feature = "no_function"))] FnMissingParams(String), /// A function definition has duplicated parameters. Wrapped values are the function name and parameter name. + /// + /// Not available under the `no_function` feature. #[cfg(not(feature = "no_function"))] FnDuplicatedParam(String, String), /// A function definition is missing the body. Wrapped value is the function name. + /// + /// Not available under the `no_function` feature. #[cfg(not(feature = "no_function"))] FnMissingBody(String), /// Assignment to an inappropriate LHS (left-hand-side) expression. diff --git a/src/lib.rs b/src/lib.rs index a553a3a2..3321fccc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -36,7 +36,23 @@ //! } //! ``` //! -//! [Check out the README on GitHub for more information!](https://github.com/jonathandturner/rhai) +//! ## Optional features +//! +//! | Feature | Description | +//! | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +//! | `no_stdlib` | Exclude the standard library of utility functions in the build, and only include the minimum necessary functionalities. Standard types are not affected. | +//! | `unchecked` | Exclude arithmetic checking (such as overflows and division by zero). Beware that a bad script may panic the entire system! | +//! | `no_function` | Disable script-defined functions if not needed. | +//! | `no_index` | Disable arrays and indexing features if not needed. | +//! | `no_object` | Disable support for custom types and objects. | +//! | `no_float` | Disable floating-point numbers and math if not needed. | +//! | `no_optimize` | Disable the script optimizer. | +//! | `only_i32` | Set the system integer type to `i32` and disable all other integer types. `INT` is set to `i32`. | +//! | `only_i64` | Set the system integer type to `i64` and disable all other integer types. `INT` is set to `i64`. | +//! | `no_std` | Build for `no-std`. Notice that additional dependencies will be pulled in to replace `std` features. | +//! | `sync` | Restrict all values types to those that are `Send + Sync`. Under this feature, `Engine`, `Scope` and `AST` are all `Send + Sync`. | +//! +//! [Check out the README on GitHub for details on the Rhai language!](https://github.com/jonathandturner/rhai) #![cfg_attr(feature = "no_std", no_std)] diff --git a/src/optimize.rs b/src/optimize.rs index 0651536c..f0e915bf 100644 --- a/src/optimize.rs +++ b/src/optimize.rs @@ -16,6 +16,8 @@ use crate::stdlib::{ }; /// 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/parser.rs b/src/parser.rs index d164d35e..0ec77e86 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -37,6 +37,8 @@ pub type INT = i64; pub type INT = i32; /// The system floating-point type. +/// +/// Not available under the `no_float` feature. #[cfg(not(feature = "no_float"))] pub type FLOAT = f64; @@ -160,6 +162,8 @@ impl fmt::Debug for Position { } /// Compiled AST (abstract syntax tree) of a Rhai script. +/// +/// Currently, `AST` is neither `Send` nor `Sync`. Turn on the `sync` feature to make it `Send + Sync`. #[derive(Debug, Clone)] pub struct AST(pub(crate) Vec, pub(crate) Vec>); diff --git a/src/result.rs b/src/result.rs index 474ae8b9..dcbade53 100644 --- a/src/result.rs +++ b/src/result.rs @@ -22,6 +22,8 @@ pub enum EvalAltResult { ErrorParsing(ParseError), /// Error reading from a script file. Wrapped value is the path of the script file. + /// + /// Not available under the `no_std` feature. #[cfg(not(feature = "no_std"))] ErrorReadingScriptFile(PathBuf, std::io::Error), diff --git a/src/scope.rs b/src/scope.rs index bf66564d..b76e3904 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -61,6 +61,8 @@ pub(crate) struct EntryRef<'a> { /// /// When searching for entries, newly-added entries are found before similarly-named but older entries, /// allowing for automatic _shadowing_. +/// +/// Currently, `Scope` is neither `Send` nor `Sync`. Turn on the `sync` feature to make it `Send + Sync`. pub struct Scope<'a>(Vec>); impl<'a> Scope<'a> {