From 284e58e8a1e1ad35b5887046761b86c4808f63cf Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Sat, 25 Jul 2020 15:52:27 +0800 Subject: [PATCH] Improve documentation on internal types. --- Cargo.toml | 3 ++ src/engine.rs | 10 ++++ src/error.rs | 7 ++- src/fn_native.rs | 4 +- src/lib.rs | 2 +- src/module.rs | 8 +++- src/parser.rs | 41 ++++++++++++++-- src/syntax.rs | 3 +- src/token.rs | 118 +++++++++++++++++++++++++++++++++++++++++++++-- src/utils.rs | 9 +++- 10 files changed, 191 insertions(+), 14 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index bf4e0dc2..2f2ab525 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -75,3 +75,6 @@ optional = true [target.'cfg(target_arch = "wasm32")'.dependencies] instant= { version = "0.1.4", features = ["wasm-bindgen"] } # WASM implementation of std::time::Instant + +[package.metadata.docs.rs] +features = [ "serde", "internals" ] diff --git a/src/engine.rs b/src/engine.rs index dccc308f..cb0a3000 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -39,6 +39,11 @@ pub type Array = Vec; pub type Map = HashMap; /// A stack of imported modules. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. pub type Imports<'a> = Vec<(Cow<'a, str>, Module)>; #[cfg(not(feature = "unchecked"))] @@ -190,11 +195,16 @@ impl> From for Target<'_> { } /// A type that holds all the current states of the Engine. +/// Exported under the `internals` feature only. /// /// # Safety /// /// This type uses some unsafe code, mainly for avoiding cloning of local variable names via /// direct lifetime casting. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, Clone, Eq, PartialEq, Hash, Default)] pub struct State { /// Normally, access to variables are parsed with a relative offset into the scope to avoid a lookup. diff --git a/src/error.rs b/src/error.rs index 86c49091..736c9df8 100644 --- a/src/error.rs +++ b/src/error.rs @@ -10,7 +10,12 @@ use crate::stdlib::{ string::{String, ToString}, }; -/// Error when tokenizing the script text. +/// Error encountered when tokenizing the script text. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, Eq, PartialEq, Clone, Hash)] #[non_exhaustive] pub enum LexError { diff --git a/src/fn_native.rs b/src/fn_native.rs index f4de5982..2833729a 100644 --- a/src/fn_native.rs +++ b/src/fn_native.rs @@ -9,7 +9,9 @@ use crate::token::{is_valid_identifier, Position}; use crate::utils::{ImmutableString, StaticVec}; use crate::Scope; -use crate::stdlib::{boxed::Box, convert::TryFrom, fmt, mem, rc::Rc, string::String, sync::Arc}; +use crate::stdlib::{ + boxed::Box, convert::TryFrom, fmt, mem, rc::Rc, string::String, sync::Arc, vec::Vec, +}; /// Trait that maps to `Send + Sync` only under the `sync` feature. #[cfg(feature = "sync")] diff --git a/src/lib.rs b/src/lib.rs index 87f60cf3..240d87d1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -166,7 +166,7 @@ pub use token::{get_next_token, parse_string_literal, InputStream, Token, Tokeni #[cfg(feature = "internals")] #[deprecated(note = "this type is volatile and may change")] -pub use parser::{CustomExpr, Expr, ReturnType, ScriptFnDef, Stmt}; +pub use parser::{CustomExpr, Expr, FloatWrapper, ReturnType, ScriptFnDef, Stmt}; #[cfg(feature = "internals")] #[deprecated(note = "this type is volatile and may change")] diff --git a/src/module.rs b/src/module.rs index 11787e1c..2a590cb8 100644 --- a/src/module.rs +++ b/src/module.rs @@ -1129,10 +1129,16 @@ impl Module { } /// A chain of module names to qualify a variable or function call. -/// A `u64` hash key is kept for quick search purposes. +/// Exported under the `internals` feature only. +/// +/// A `u64` hash key is cached for quick search purposes. /// /// A `StaticVec` is used because most module-level access contains only one level, /// and it is wasteful to always allocate a `Vec` with one element. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Clone, Eq, PartialEq, Default, Hash)] pub struct ModuleRef(StaticVec<(String, Position)>, Option); diff --git a/src/parser.rs b/src/parser.rs index 0655c903..786f7d85 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -342,7 +342,12 @@ impl fmt::Display for FnAccess { } } -/// A scripted function definition. +/// A type containing information on a scripted function. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, Clone, Hash)] pub struct ScriptFnDef { /// Function name. @@ -376,7 +381,12 @@ impl fmt::Display for ScriptFnDef { } } -/// `return`/`throw` statement. +/// A type encapsulating the mode of a `return`/`throw` statement. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, Eq, PartialEq, Clone, Copy, Hash)] pub enum ReturnType { /// `return` statement. @@ -477,7 +487,8 @@ impl ParseSettings { } } -/// A statement. +/// A Rhai statement. +/// Exported under the `internals` feature only. /// /// Each variant is at most one pointer in size (for speed), /// with everything being allocated together in one single tuple. @@ -582,6 +593,12 @@ impl Stmt { } } +/// A type wrapping a custom syntax definition. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Clone)] pub struct CustomExpr(pub StaticVec, pub Shared); @@ -592,11 +609,20 @@ impl fmt::Debug for CustomExpr { } impl Hash for CustomExpr { - fn hash(&self, state: &mut H) { + fn hash(&self, state: &mut H) { self.0.hash(state); } } +/// A type wrapping a floating-point number. +/// Exported under the `internals` feature only. +/// +/// This type is mainly used to provide a standard `Hash` implementation +/// to floating-point numbers, allowing `Expr` to derive `Hash` automatically. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[cfg(not(feature = "no_float"))] #[derive(Debug, PartialEq, PartialOrd, Clone)] pub struct FloatWrapper(pub FLOAT, pub Position); @@ -609,10 +635,15 @@ impl Hash for FloatWrapper { } } -/// An expression. +/// An expression sub-tree. +/// Exported under the `internals` feature only. /// /// Each variant is at most one pointer in size (for speed), /// with everything being allocated together in one single tuple. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, Clone, Hash)] pub enum Expr { /// Integer constant. diff --git a/src/syntax.rs b/src/syntax.rs index 485e99ea..616833c1 100644 --- a/src/syntax.rs +++ b/src/syntax.rs @@ -12,7 +12,8 @@ use crate::token::{is_valid_identifier, Position, Token}; use crate::utils::StaticVec; use crate::stdlib::{ - fmt, + boxed::Box, + fmt, format, rc::Rc, string::{String, ToString}, sync::Arc, diff --git a/src/token.rs b/src/token.rs index f2719a7a..82e850d5 100644 --- a/src/token.rs +++ b/src/token.rs @@ -136,89 +136,181 @@ impl fmt::Debug for Position { } } -/// Tokens. +/// A language token. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, PartialEq, Clone)] pub enum Token { + /// An `INT` constant. IntegerConstant(INT), + /// A `FLOAT` constaint. + /// + /// Never appears under the `no_float` feature. #[cfg(not(feature = "no_float"))] FloatConstant(FLOAT), + /// An identifier. Identifier(String), + /// A character constant. CharConstant(char), + /// A string constant. StringConstant(String), + /// `{` LeftBrace, + /// `}` RightBrace, + /// `(` LeftParen, + /// `)` RightParen, + /// `[` LeftBracket, + /// `]` RightBracket, + /// `+` Plus, + /// `+` (unary) UnaryPlus, + /// `-` Minus, + /// `-` (unary) UnaryMinus, + /// `*` Multiply, + /// `/` Divide, + /// `%` Modulo, + /// `~` PowerOf, + /// `<<` LeftShift, + /// `>>` RightShift, + /// `;` SemiColon, + /// `:` Colon, + /// `::` DoubleColon, + /// `,` Comma, + /// `.` Period, + /// `#{` MapStart, + /// `=` Equals, + /// `true` True, + /// `false` False, + /// `let` Let, + /// `const` Const, + /// `if` If, + /// `else` Else, + /// `while` While, + /// `loop` Loop, + /// `for` For, + /// `in` In, + /// `<` LessThan, + /// `>` GreaterThan, + /// `<=` LessThanEqualsTo, + /// `>=` GreaterThanEqualsTo, + /// `==` EqualsTo, + /// `!=` NotEqualsTo, + /// `!` Bang, + /// `|` Pipe, + /// `||` Or, + /// `^` XOr, + /// `&` Ampersand, + /// `&&` And, + /// `fn` + /// + /// Never appears under the `no_function` feature. #[cfg(not(feature = "no_function"))] Fn, + /// `continue` Continue, + /// `break` Break, + /// `return` Return, + /// `throw` Throw, + /// `+=` PlusAssign, + /// `-=` MinusAssign, + /// `*=` MultiplyAssign, + /// `/=` DivideAssign, + /// `<<=` LeftShiftAssign, + /// `>>=` RightShiftAssign, + /// `&=` AndAssign, + /// `|=` OrAssign, + /// `^=` XOrAssign, + /// `%=` ModuloAssign, + /// `~=` PowerOfAssign, + /// `private` + /// + /// Never appears under the `no_function` feature. #[cfg(not(feature = "no_function"))] Private, + /// `import` + /// + /// Never appears under the `no_module` feature. #[cfg(not(feature = "no_module"))] Import, + /// `export` + /// + /// Never appears under the `no_module` feature. #[cfg(not(feature = "no_module"))] Export, + /// `as` + /// + /// Never appears under the `no_module` feature. #[cfg(not(feature = "no_module"))] As, + /// A lexer error. LexError(Box), + /// A comment block. Comment(String), + /// A reserved symbol. Reserved(String), + /// A custom keyword. Custom(String), + /// End of the input stream. EOF, } @@ -566,7 +658,7 @@ impl Token { } } - /// Is this token a reserved keyword? + /// Is this token a reserved symbol? pub fn is_reserved(&self) -> bool { match self { Self::Reserved(_) => true, @@ -590,6 +682,11 @@ impl From for String { } /// State of the tokenizer. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. #[derive(Debug, Clone, Eq, PartialEq, Default)] pub struct TokenizeState { /// Maximum length of a string (0 = unlimited). @@ -605,6 +702,11 @@ pub struct TokenizeState { } /// Trait that encapsulates a peekable character input stream. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This trait is volatile and may change. pub trait InputStream { /// Get the next character fn get_next(&mut self) -> Option; @@ -629,6 +731,11 @@ pub fn is_valid_identifier(name: impl Iterator) -> bool { } /// Parse a string literal wrapped by `enclosing_char`. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. pub fn parse_string_literal( stream: &mut impl InputStream, state: &mut TokenizeState, @@ -794,7 +901,12 @@ fn scan_comment( } } -/// Get the next token. +/// Get the next token from the `InputStream`. +/// Exported under the `internals` feature only. +/// +/// ## WARNING +/// +/// This type is volatile and may change. pub fn get_next_token( stream: &mut impl InputStream, state: &mut TokenizeState, diff --git a/src/utils.rs b/src/utils.rs index a6eff859..603f8b81 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -92,9 +92,12 @@ pub fn calc_fn_spec<'a>( s.finish() } -/// A type to hold a number of values in static storage for no-allocation, quick access. +/// An array-like type that holds a number of values in static storage for no-allocation, quick access. +/// Exported under the `internals` feature only. +/// /// If too many items are stored, it converts into using a `Vec`. /// +/// /// This is essentially a knock-off of the [`staticvec`](https://crates.io/crates/staticvec) crate. /// This simplified implementation here is to avoid pulling in another crate. /// @@ -130,6 +133,10 @@ pub fn calc_fn_spec<'a>( /// # Safety /// /// This type uses some unsafe code (mainly for uninitialized/unused array slots) for efficiency. +/// +/// ## WARNING +/// +/// This type is volatile and may change. // // TODO - remove unsafe code pub struct StaticVec {