diff --git a/doc/src/about/features.md b/doc/src/about/features.md index a079873f..c5292a42 100644 --- a/doc/src/about/features.md +++ b/doc/src/about/features.md @@ -8,7 +8,7 @@ Easy * Easy-to-use language similar to JavaScript+Rust with dynamic typing. -* Tight integration with native Rust [functions]({{rootUrl}}/rust/functions.md) and [types]({{rootUrl}}/rust/custom.md), including [getters/setters]({{rootUrl}}/rust/getters-setters.md), [methods]({{rootUrl}}/rust/custom.md) and [indexers]({{rootUrl}}/rust/indexers.md). +* Tight integration with native Rust [functions] and [types][custom types], including [getters/setters]({{rootUrl}}/rust/getters-setters.md), [methods][custom type] and [indexers]({{rootUrl}}/rust/indexers.md). * Freely pass Rust variables/constants into a script via an external [`Scope`]. @@ -24,7 +24,7 @@ Fast * Fairly efficient evaluation (1 million iterations in 0.25 sec on a single core, 2.3 GHz Linux VM). -* Scripts are [optimized]({{rootUrl}}/engine/optimize.md) (useful for template-based machine-generated scripts) for repeated evaluations. +* Scripts are [optimized][script optimization] (useful for template-based machine-generated scripts) for repeated evaluations. Dynamic ------- @@ -50,7 +50,7 @@ Rugged * Sand-boxed - the scripting [`Engine`], if declared immutable, cannot mutate the containing environment unless explicitly permitted (e.g. via a `RefCell`). -* Protected against malicious attacks (such as [stack-overflow]({{rootUrl}}/safety/max-call-stack.md), [over-sized data]({{rootUrl}}/safety/max-string-size.md), and [runaway scripts]({{rootUrl}}/safety/max-operations.md) etc.) that may come from untrusted third-party user-land scripts. +* Protected against malicious attacks (such as [stack-overflow][maximum call stack depth], [over-sized data][maximum length of strings], and [runaway scripts][maximum number of operations] etc.) that may come from untrusted third-party user-land scripts. * Track script evaluation [progress] and manually terminate a script run. diff --git a/doc/src/language/arrays.md b/doc/src/language/arrays.md index 89870f5f..3afc09b6 100644 --- a/doc/src/language/arrays.md +++ b/doc/src/language/arrays.md @@ -22,7 +22,7 @@ The maximum allowed size of an array can be controlled via `Engine::set_max_arra Built-in Functions ----------------- -The following methods (mostly defined in the [`BasicArrayPackage`]({{rootUrl}}/rust/packages.md) but excluded if using a [raw `Engine`]) operate on arrays: +The following methods (mostly defined in the [`BasicArrayPackage`][packages] but excluded if using a [raw `Engine`]) operate on arrays: | Function | Parameter(s) | Description | | ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | diff --git a/doc/src/language/eval.md b/doc/src/language/eval.md index a624403f..a7e5b979 100644 --- a/doc/src/language/eval.md +++ b/doc/src/language/eval.md @@ -82,7 +82,7 @@ engine.register_result_fn("eval", alt_eval); `EvalPackage` ------------- -There is even a package named [`EvalPackage`]({{rootUrl}}/rust/packages.md) which implements the disabling override: +There is even a package named [`EvalPackage`][packages] which implements the disabling override: ```rust use rhai::Engine; diff --git a/doc/src/language/fn-ptr.md b/doc/src/language/fn-ptr.md index a2f7f83f..a9f2e64a 100644 --- a/doc/src/language/fn-ptr.md +++ b/doc/src/language/fn-ptr.md @@ -12,7 +12,7 @@ Call a function pointer using the `call` method, which needs to be called in met Built-in methods ---------------- -The following standard methods (mostly defined in the [`BasicFnPackage`]({{rootUrl}}/rust/packages.md) but excluded if +The following standard methods (mostly defined in the [`BasicFnPackage`][packages] but excluded if using a [raw `Engine`]) operate on [strings]: | Function | Parameter(s) | Description | diff --git a/doc/src/language/modules/imp-resolver.md b/doc/src/language/modules/imp-resolver.md index 9634f633..415abf72 100644 --- a/doc/src/language/modules/imp-resolver.md +++ b/doc/src/language/modules/imp-resolver.md @@ -7,7 +7,7 @@ For many applications in which Rhai is embedded, it is necessary to customize th are resolved. For instance, modules may need to be loaded from script texts stored in a database, not in the file system. -A module resolver must implement the trait [`rhai::ModuleResolver`]({{rootUrl}}/rust/traits.md), +A module resolver must implement the trait [`rhai::ModuleResolver`][traits], which contains only one function: `resolve`. When Rhai prepares to load a module, `ModuleResolver::resolve` is called with the name diff --git a/doc/src/language/modules/resolvers.md b/doc/src/language/modules/resolvers.md index 3377cb56..ed2bf54c 100644 --- a/doc/src/language/modules/resolvers.md +++ b/doc/src/language/modules/resolvers.md @@ -5,7 +5,7 @@ Module Resolvers When encountering an [`import`] statement, Rhai attempts to _resolve_ the module based on the path string. -_Module Resolvers_ are service types that implement the [`ModuleResolver`]({{rootUrl}}/rust/traits.md) trait. +_Module Resolvers_ are service types that implement the [`ModuleResolver`][traits] trait. There are a number of standard resolvers built into Rhai, the default being the `FileModuleResolver` which simply loads a script file based on the path (with `.rhai` extension attached) and execute it to form a module. diff --git a/doc/src/language/num-fn.md b/doc/src/language/num-fn.md index 1e415e11..a963c7e2 100644 --- a/doc/src/language/num-fn.md +++ b/doc/src/language/num-fn.md @@ -6,7 +6,7 @@ Numeric Functions Integer Functions ---------------- -The following standard functions (defined in the [`BasicMathPackage`]({{rootUrl}}/rust/packages.md) but excluded if using a [raw `Engine`]) +The following standard functions (defined in the [`BasicMathPackage`][packages] but excluded if using a [raw `Engine`]) operate on `i8`, `i16`, `i32`, `i64`, `f32` and `f64` only: | Function | Description | @@ -18,7 +18,7 @@ operate on `i8`, `i16`, `i32`, `i64`, `f32` and `f64` only: Floating-Point Functions ----------------------- -The following standard functions (defined in the [`BasicMathPackage`]({{rootUrl}}/rust/packages.md) but excluded if using a [raw `Engine`]) +The following standard functions (defined in the [`BasicMathPackage`][packages] but excluded if using a [raw `Engine`]) operate on `f64` only: | Category | Functions | diff --git a/doc/src/language/object-maps.md b/doc/src/language/object-maps.md index dc1adc45..5cf6ae67 100644 --- a/doc/src/language/object-maps.md +++ b/doc/src/language/object-maps.md @@ -39,7 +39,7 @@ The index notation allows setting/getting properties of arbitrary names (even th Built-in Functions ----------------- -The following methods (defined in the [`BasicMapPackage`]({{rootUrl}}/rust/packages.md) but excluded if using a [raw `Engine`]) +The following methods (defined in the [`BasicMapPackage`][packages] but excluded if using a [raw `Engine`]) operate on object maps: | Function | Parameter(s) | Description | diff --git a/doc/src/language/string-fn.md b/doc/src/language/string-fn.md index 8504e2e3..504ea0a6 100644 --- a/doc/src/language/string-fn.md +++ b/doc/src/language/string-fn.md @@ -3,7 +3,7 @@ Built-in String Functions {{#include ../links.md}} -The following standard methods (mostly defined in the [`MoreStringPackage`]({{rootUrl}}/rust/packages.md) but excluded if +The following standard methods (mostly defined in the [`MoreStringPackage`][packages] but excluded if using a [raw `Engine`]) operate on [strings]: | Function | Parameter(s) | Description | diff --git a/doc/src/language/strings-chars.md b/doc/src/language/strings-chars.md index f7019048..b6372240 100644 --- a/doc/src/language/strings-chars.md +++ b/doc/src/language/strings-chars.md @@ -6,7 +6,7 @@ Strings and Characters String in Rhai contain any text sequence of valid Unicode characters. Internally strings are stored in UTF-8 encoding. -Strings can be built up from other strings and types via the `+` operator (provided by the [`MoreStringPackage`]({{rootUrl}}/rust/packages.md) +Strings can be built up from other strings and types via the `+` operator (provided by the [`MoreStringPackage`][packages] but excluded if using a [raw `Engine`]). This is particularly useful when printing output. [`type_of()`] a string returns `"string"`. diff --git a/doc/src/language/timestamps.md b/doc/src/language/timestamps.md index 3d02797e..47ba302b 100644 --- a/doc/src/language/timestamps.md +++ b/doc/src/language/timestamps.md @@ -3,12 +3,12 @@ {{#include ../links.md}} -Timestamps are provided by the [`BasicTimePackage`]({{rootUrl}}/rust/packages.md) (excluded if using a [raw `Engine`]) +Timestamps are provided by the [`BasicTimePackage`][packages] (excluded if using a [raw `Engine`]) via the `timestamp` function. Timestamps are not available under [`no_std`]. -The Rust type of a timestamp is `std::time::Instant` ([`instant::Instant`](https://crates.io/crates/instant) in [WASM] builds). +The Rust type of a timestamp is `std::time::Instant` ([`instant::Instant`] in [WASM] builds). [`type_of()`] a timestamp returns `"timestamp"`. @@ -16,7 +16,7 @@ The Rust type of a timestamp is `std::time::Instant` ([`instant::Instant`](https Built-in Functions ----------------- -The following methods (defined in the [`BasicTimePackage`]({{rootUrl}}/rust/packages.md) but excluded if using a [raw `Engine`]) operate on timestamps: +The following methods (defined in the [`BasicTimePackage`][packages] but excluded if using a [raw `Engine`]) operate on timestamps: | Function | Parameter(s) | Description | | ----------------------------- | ---------------------------------- | -------------------------------------------------------- | diff --git a/doc/src/language/values-and-types.md b/doc/src/language/values-and-types.md index ddadc21f..5a5ae2e0 100644 --- a/doc/src/language/values-and-types.md +++ b/doc/src/language/values-and-types.md @@ -5,21 +5,21 @@ Values and Types The following primitive types are supported natively: -| Category | Equivalent Rust types | [`type_of()`] | `to_string()` | -| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------- | ----------------------- | -| **Integer number** | `u8`, `i8`, `u16`, `i16`,
`u32`, `i32` (default for [`only_i32`]),
`u64`, `i64` _(default)_ | `"i32"`, `"u64"` etc. | `"42"`, `"123"` etc. | -| **Floating-point number** (disabled with [`no_float`]) | `f32`, `f64` _(default)_ | `"f32"` or `"f64"` | `"123.4567"` etc. | -| **Boolean value** | `bool` | `"bool"` | `"true"` or `"false"` | -| **Unicode character** | `char` | `"char"` | `"A"`, `"x"` etc. | -| **Immutable Unicode [string]** | `rhai::ImmutableString` (implemented as `Rc` or `Arc`) | `"string"` | `"hello"` etc. | -| **[`Array`]** (disabled with [`no_index`]) | `rhai::Array` | `"array"` | `"[ ?, ?, ? ]"` | -| **[Object map]** (disabled with [`no_object`]) | `rhai::Map` | `"map"` | `"#{ "a": 1, "b": 2 }"` | -| **[Timestamp]** (implemented in the [`BasicTimePackage`]({{rootUrl}}/rust/packages.md), disabled with [`no_std`]) | `std::time::Instant` ([`instant::Instant`](https://crates.io/crates/instant) if not [WASM] build) | `"timestamp"` | _not supported_ | -| **[Function pointer]** (disabled with [`no_function`]) | _None_ | `Fn` | `"Fn(foo)"` | -| **[`Dynamic`] value** (i.e. can be anything) | `rhai::Dynamic` | _the actual type_ | _actual value_ | -| **System integer** (current configuration) | `rhai::INT` (`i32` or `i64`) | `"i32"` or `"i64"` | `"42"`, `"123"` etc. | -| **System floating-point** (current configuration, disabled with [`no_float`]) | `rhai::FLOAT` (`f32` or `f64`) | `"f32"` or `"f64"` | `"123.456"` etc. | -| **Nothing/void/nil/null/Unit** (or whatever it is called) | `()` | `"()"` | `""` _(empty string)_ | +| Category | Equivalent Rust types | [`type_of()`] | `to_string()` | +| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------- | ----------------------- | +| **Integer number** | `u8`, `i8`, `u16`, `i16`,
`u32`, `i32` (default for [`only_i32`]),
`u64`, `i64` _(default)_ | `"i32"`, `"u64"` etc. | `"42"`, `"123"` etc. | +| **Floating-point number** (disabled with [`no_float`]) | `f32`, `f64` _(default)_ | `"f32"` or `"f64"` | `"123.4567"` etc. | +| **Boolean value** | `bool` | `"bool"` | `"true"` or `"false"` | +| **Unicode character** | `char` | `"char"` | `"A"`, `"x"` etc. | +| **Immutable Unicode [string]** | `rhai::ImmutableString` (implemented as `Rc` or `Arc`) | `"string"` | `"hello"` etc. | +| **[`Array`]** (disabled with [`no_index`]) | `rhai::Array` | `"array"` | `"[ ?, ?, ? ]"` | +| **[Object map]** (disabled with [`no_object`]) | `rhai::Map` | `"map"` | `"#{ "a": 1, "b": 2 }"` | +| **[Timestamp]** (implemented in the [`BasicTimePackage`][packages], disabled with [`no_std`]) | `std::time::Instant` ([`instant::Instant`] if not [WASM] build) | `"timestamp"` | _not supported_ | +| **[Function pointer]** (disabled with [`no_function`]) | _None_ | `Fn` | `"Fn(foo)"` | +| **[`Dynamic`] value** (i.e. can be anything) | `rhai::Dynamic` | _the actual type_ | _actual value_ | +| **System integer** (current configuration) | `rhai::INT` (`i32` or `i64`) | `"i32"` or `"i64"` | `"42"`, `"123"` etc. | +| **System floating-point** (current configuration, disabled with [`no_float`]) | `rhai::FLOAT` (`f32` or `f64`) | `"f32"` or `"f64"` | `"123.456"` etc. | +| **Nothing/void/nil/null/Unit** (or whatever it is called) | `()` | `"()"` | `""` _(empty string)_ | All types are treated strictly separate by Rhai, meaning that `i32` and `i64` and `u32` are completely different - they even cannot be added together. This is very similar to Rust. diff --git a/doc/src/links.md b/doc/src/links.md index 8f3bcf15..ae6ef01d 100644 --- a/doc/src/links.md +++ b/doc/src/links.md @@ -17,6 +17,7 @@ [WASM]: {{rootUrl}}/start/builds/wasm.md [`Engine`]: {{rootUrl}}/engine/hello-world.md +[traits]: {{rootUrl}}/rust/traits.md [`private`]: {{rootUrl}}/engine/call-fn.md [`Func`]: {{rootUrl}}/engine/func.md [`eval_expression`]: {{rootUrl}}/engine/expressions.md @@ -38,6 +39,8 @@ [custom type]: {{rootUrl}}/rust/custom.md [custom types]: {{rootUrl}}/rust/custom.md +[`instant::Instant`]: https://crates.io/crates/instant + [`print`]: {{rootUrl}}/language/print-debug.md [`debug`]: {{rootUrl}}/language/print-debug.md @@ -79,7 +82,6 @@ [OOP]: {{rootUrl}}/language/oop.md - [maximum statement depth]: {{rootUrl}}/safety/max-stmt-depth.md [maximum call stack depth]: {{rootUrl}}/safety/max-call-stack.md [maximum number of operations]: {{rootUrl}}/safety/max-operations.md diff --git a/doc/src/rust/print-custom.md b/doc/src/rust/print-custom.md index 7205e1c3..c729c49d 100644 --- a/doc/src/rust/print-custom.md +++ b/doc/src/rust/print-custom.md @@ -10,8 +10,8 @@ is `T : Display + Debug`): | Function | Signature | Typical implementation | Usage | | ----------- | ------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- | | `to_string` | \|s: &mut T\| -> ImmutableString | `s.to_string().into()` | Converts the custom type into a [string] | -| `print` | \|s: &mut T\| -> ImmutableString | `s.to_string().into()` | Converts the custom type into a [string] for the [`print`](#print-and-debug) statement | -| `debug` | \|s: &mut T\| -> ImmutableString | `format!("{:?}", s).into()` | Converts the custom type into a [string] for the [`debug`](#print-and-debug) statement | +| `print` | \|s: &mut T\| -> ImmutableString | `s.to_string().into()` | Converts the custom type into a [string] for the [`print`] statement | +| `debug` | \|s: &mut T\| -> ImmutableString | `format!("{:?}", s).into()` | Converts the custom type into a [string] for the [`debug`] statement | | `+` | \|s1: ImmutableString, s: T\| -> ImmutableString | `s1 + s` | Append the custom type to another [string], for `print("Answer: " + type);` usage | | `+` | \|s: T, s2: ImmutableString\| -> ImmutableString | `s.to_string().push_str(&s2).into();` | Append another [string] to the custom type, for `print(type + " is the answer");` usage | | `+=` | \|s1: &mut ImmutableString, s: T\| | `s1 += s.to_string()` | Append the custom type to an existing [string], for `s += type;` usage | diff --git a/doc/src/safety/index.md b/doc/src/safety/index.md index 2a06c1f4..22ae237d 100644 --- a/doc/src/safety/index.md +++ b/doc/src/safety/index.md @@ -21,7 +21,7 @@ The most important resources to watch out for are: Alternatively, it may create a degenerated deep expression with so many levels that the parser exhausts the call stack when parsing the expression; or even deeply-nested statement blocks, if nested deep enough. - Another way to cause a stack overflow is to load a [self-referencing module]({{rootUrl}}/language/modules/import.md). + Another way to cause a stack overflow is to load a [self-referencing module][`import`]. * **Overflows**: A malicious script may deliberately cause numeric over-flows and/or under-flows, divide by zero, and/or create bad floating-point representations, in order to crash the system. diff --git a/doc/src/safety/max-modules.md b/doc/src/safety/max-modules.md index d707ee64..adb1c133 100644 --- a/doc/src/safety/max-modules.md +++ b/doc/src/safety/max-modules.md @@ -10,8 +10,7 @@ of modules to zero does _not_ indicate unlimited modules, but disallows loading A script attempting to load more than the maximum number of modules will terminate with an error result. -This limit can also be used to stop [`import`-loops]({{rootUrl}}/language/modules/import.md) -(i.e. cycles of modules referring to each other). +This limit can also be used to stop [`import`-loops][`import`] (i.e. cycles of modules referring to each other). This check can be disabled via the [`unchecked`] feature for higher performance (but higher risks as well). diff --git a/doc/src/start/builds/minimal.md b/doc/src/start/builds/minimal.md index a76075e6..d1da0f01 100644 --- a/doc/src/start/builds/minimal.md +++ b/doc/src/start/builds/minimal.md @@ -45,7 +45,7 @@ Both of these have little code size savings. Use a Raw [`Engine`] ------------------- -[`Engine::new_raw`](#raw-engine) creates a _raw_ engine. +[`Engine::new_raw`][raw `Engine`] creates a _raw_ engine. A _raw_ engine supports, out of the box, only a very [restricted set]({{rootUrl}}/engine/raw.md#built-in-operators) of basic arithmetic and logical operators.