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

Use link redirection syntax.

Browse Source
This commit is contained in:
Stephen Chung 2020-06-27 10:43:57 +08:00
parent 14746f94ca
commit d509006264
17 changed files with 39 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/src/about/features.md
View File

@ -8,7 +8,7 @@ Easy
* Easy-to-use language similar to JavaScript+Rust with dynamic typing. * 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`]. * 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). * 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 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`). * 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. * Track script evaluation [progress] and manually terminate a script run.

2
doc/src/language/arrays.md
View File

@ -22,7 +22,7 @@ The maximum allowed size of an array can be controlled via `Engine::set_max_arra
Built-in Functions 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 | | Function | Parameter(s) | Description |
| ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |

2
doc/src/language/eval.md
View File

@ -82,7 +82,7 @@ engine.register_result_fn("eval", alt_eval);
`EvalPackage` `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 ```rust
use rhai::Engine; use rhai::Engine;

2
doc/src/language/fn-ptr.md
View File

@ -12,7 +12,7 @@ Call a function pointer using the `call` method, which needs to be called in met
Built-in methods 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]: using a [raw `Engine`]) operate on [strings]:
| Function | Parameter(s) | Description | | Function | Parameter(s) | Description |

2
doc/src/language/modules/imp-resolver.md
View File

@ -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, are resolved. For instance, modules may need to be loaded from script texts stored in a database,
not in the file system. 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`. which contains only one function: `resolve`.
When Rhai prepares to load a module, `ModuleResolver::resolve` is called with the name When Rhai prepares to load a module, `ModuleResolver::resolve` is called with the name

2
doc/src/language/modules/resolvers.md
View File

@ -5,7 +5,7 @@ Module Resolvers
When encountering an [`import`] statement, Rhai attempts to _resolve_ the module based on the path string. 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` 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. which simply loads a script file based on the path (with `.rhai` extension attached) and execute it to form a module.

4
doc/src/language/num-fn.md
View File

@ -6,7 +6,7 @@ Numeric Functions
Integer 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: operate on `i8`, `i16`, `i32`, `i64`, `f32` and `f64` only:
| Function | Description | | Function | Description |
@ -18,7 +18,7 @@ operate on `i8`, `i16`, `i32`, `i64`, `f32` and `f64` only:
Floating-Point Functions 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: operate on `f64` only:
| Category | Functions | | Category | Functions |

2
doc/src/language/object-maps.md
View File

@ -39,7 +39,7 @@ The index notation allows setting/getting properties of arbitrary names (even th
Built-in Functions 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: operate on object maps:
| Function | Parameter(s) | Description | | Function | Parameter(s) | Description |

2
doc/src/language/string-fn.md
View File

@ -3,7 +3,7 @@ Built-in String Functions
{{#include ../links.md}} {{#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]: using a [raw `Engine`]) operate on [strings]:
| Function | Parameter(s) | Description | | Function | Parameter(s) | Description |

2
doc/src/language/strings-chars.md
View File

@ -6,7 +6,7 @@ Strings and Characters
String in Rhai contain any text sequence of valid Unicode characters. String in Rhai contain any text sequence of valid Unicode characters.
Internally strings are stored in UTF-8 encoding. 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. but excluded if using a [raw `Engine`]). This is particularly useful when printing output.
[`type_of()`] a string returns `"string"`. [`type_of()`] a string returns `"string"`.

6
doc/src/language/timestamps.md
View File

@ -3,12 +3,12 @@
{{#include ../links.md}} {{#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. via the `timestamp` function.
Timestamps are not available under [`no_std`]. 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"`. [`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 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 | | Function | Parameter(s) | Description |
| ----------------------------- | ---------------------------------- | -------------------------------------------------------- | | ----------------------------- | ---------------------------------- | -------------------------------------------------------- |

30
doc/src/language/values-and-types.md
View File

@ -5,21 +5,21 @@ Values and Types
The following primitive types are supported natively: The following primitive types are supported natively:
| Category | Equivalent Rust types | [`type_of()`] | `to_string()` | | Category | Equivalent Rust types | [`type_of()`] | `to_string()` |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------- | ----------------------- | | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------- | ----------------------- |
| **Integer number** | `u8`, `i8`, `u16`, `i16`, <br/>`u32`, `i32` (default for [`only_i32`]),<br/>`u64`, `i64` _(default)_ | `"i32"`, `"u64"` etc. | `"42"`, `"123"` etc. | | **Integer number** | `u8`, `i8`, `u16`, `i16`, <br/>`u32`, `i32` (default for [`only_i32`]),<br/>`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. | | **Floating-point number** (disabled with [`no_float`]) | `f32`, `f64` _(default)_ | `"f32"` or `"f64"` | `"123.4567"` etc. |
| **Boolean value** | `bool` | `"bool"` | `"true"` or `"false"` | | **Boolean value** | `bool` | `"bool"` | `"true"` or `"false"` |
| **Unicode character** | `char` | `"char"` | `"A"`, `"x"` etc. | | **Unicode character** | `char` | `"char"` | `"A"`, `"x"` etc. |
| **Immutable Unicode [string]** | `rhai::ImmutableString` (implemented as `Rc<String>` or `Arc<String>`) | `"string"` | `"hello"` etc. | | **Immutable Unicode [string]** | `rhai::ImmutableString` (implemented as `Rc<String>` or `Arc<String>`) | `"string"` | `"hello"` etc. |
| **[`Array`]** (disabled with [`no_index`]) | `rhai::Array` | `"array"` | `"[ ?, ?, ? ]"` | | **[`Array`]** (disabled with [`no_index`]) | `rhai::Array` | `"array"` | `"[ ?, ?, ? ]"` |
| **[Object map]** (disabled with [`no_object`]) | `rhai::Map` | `"map"` | `"#{ "a": 1, "b": 2 }"` | | **[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_ | | **[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)"` | | **[Function pointer]** (disabled with [`no_function`]) | _None_ | `Fn` | `"Fn(foo)"` |
| **[`Dynamic`] value** (i.e. can be anything) | `rhai::Dynamic` | _the actual type_ | _actual value_ | | **[`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 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. | | **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)_ | | **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 - 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. they even cannot be added together. This is very similar to Rust.

4
doc/src/links.md
View File

@ -17,6 +17,7 @@
[WASM]: {{rootUrl}}/start/builds/wasm.md [WASM]: {{rootUrl}}/start/builds/wasm.md
[`Engine`]: {{rootUrl}}/engine/hello-world.md [`Engine`]: {{rootUrl}}/engine/hello-world.md
[traits]: {{rootUrl}}/rust/traits.md
[`private`]: {{rootUrl}}/engine/call-fn.md [`private`]: {{rootUrl}}/engine/call-fn.md
[`Func`]: {{rootUrl}}/engine/func.md [`Func`]: {{rootUrl}}/engine/func.md
[`eval_expression`]: {{rootUrl}}/engine/expressions.md [`eval_expression`]: {{rootUrl}}/engine/expressions.md
@ -38,6 +39,8 @@
[custom type]: {{rootUrl}}/rust/custom.md [custom type]: {{rootUrl}}/rust/custom.md
[custom types]: {{rootUrl}}/rust/custom.md [custom types]: {{rootUrl}}/rust/custom.md
[`instant::Instant`]: https://crates.io/crates/instant
[`print`]: {{rootUrl}}/language/print-debug.md [`print`]: {{rootUrl}}/language/print-debug.md
[`debug`]: {{rootUrl}}/language/print-debug.md [`debug`]: {{rootUrl}}/language/print-debug.md
@ -79,7 +82,6 @@
[OOP]: {{rootUrl}}/language/oop.md [OOP]: {{rootUrl}}/language/oop.md
[maximum statement depth]: {{rootUrl}}/safety/max-stmt-depth.md [maximum statement depth]: {{rootUrl}}/safety/max-stmt-depth.md
[maximum call stack depth]: {{rootUrl}}/safety/max-call-stack.md [maximum call stack depth]: {{rootUrl}}/safety/max-call-stack.md
[maximum number of operations]: {{rootUrl}}/safety/max-operations.md [maximum number of operations]: {{rootUrl}}/safety/max-operations.md

4
doc/src/rust/print-custom.md
View File

@ -10,8 +10,8 @@ is `T : Display + Debug`):
| Function | Signature | Typical implementation | Usage | | Function | Signature | Typical implementation | Usage |
| ----------- | ------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- | | ----------- | ------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
| `to_string` | <code>\|s: &mut T\| -> ImmutableString</code> | `s.to_string().into()` | Converts the custom type into a [string] | | `to_string` | <code>\|s: &mut T\| -> ImmutableString</code> | `s.to_string().into()` | Converts the custom type into a [string] |
| `print` | <code>\|s: &mut T\| -> ImmutableString</code> | `s.to_string().into()` | Converts the custom type into a [string] for the [`print`](#print-and-debug) statement | | `print` | <code>\|s: &mut T\| -> ImmutableString</code> | `s.to_string().into()` | Converts the custom type into a [string] for the [`print`] statement |
| `debug` | <code>\|s: &mut T\| -> ImmutableString</code> | `format!("{:?}", s).into()` | Converts the custom type into a [string] for the [`debug`](#print-and-debug) statement | | `debug` | <code>\|s: &mut T\| -> ImmutableString</code> | `format!("{:?}", s).into()` | Converts the custom type into a [string] for the [`debug`] statement |
| `+` | <code>\|s1: ImmutableString, s: T\| -> ImmutableString</code> | `s1 + s` | Append the custom type to another [string], for `print("Answer: " + type);` usage | | `+` | <code>\|s1: ImmutableString, s: T\| -> ImmutableString</code> | `s1 + s` | Append the custom type to another [string], for `print("Answer: " + type);` usage |
| `+` | <code>\|s: T, s2: ImmutableString\| -> ImmutableString</code> | `s.to_string().push_str(&s2).into();` | Append another [string] to the custom type, for `print(type + " is the answer");` usage | | `+` | <code>\|s: T, s2: ImmutableString\| -> ImmutableString</code> | `s.to_string().push_str(&s2).into();` | Append another [string] to the custom type, for `print(type + " is the answer");` usage |
| `+=` | <code>\|s1: &mut ImmutableString, s: T\|</code> | `s1 += s.to_string()` | Append the custom type to an existing [string], for `s += type;` usage | | `+=` | <code>\|s1: &mut ImmutableString, s: T\|</code> | `s1 += s.to_string()` | Append the custom type to an existing [string], for `s += type;` usage |

2
doc/src/safety/index.md
View File

@ -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 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. 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 * **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. create bad floating-point representations, in order to crash the system.

3
doc/src/safety/max-modules.md
View File

@ -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. 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) This limit can also be used to stop [`import`-loops][`import`] (i.e. cycles of modules referring to each other).
(i.e. cycles of modules referring to each other).
This check can be disabled via the [`unchecked`] feature for higher performance This check can be disabled via the [`unchecked`] feature for higher performance
(but higher risks as well). (but higher risks as well).

2
doc/src/start/builds/minimal.md
View File

@ -45,7 +45,7 @@ Both of these have little code size savings.
Use a Raw [`Engine`] 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) 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. of basic arithmetic and logical operators.