Go to file

Nathan Kent 86d86a85e4 Remove unsound casting functions The casting functions in `unsafe.rs` were unsound (i.e., they allowed safe code to cause undefined behavior). While they did appear to be used in a way that wouldn't cause UB the fact that there exists unsound functions is unsettling. This commit removes those functions and replaces it with a macro that performs the same reification - the difference is that the macro call will also include the checks which are required to prevent UB. A macro was chosen instead of a function for two reasons: 1. A macro can keep the same code generation whereas a function would require going through an `Option` which has negative impacts on code generation (niche values cause poor DCE). 2. There exist other `unsafe` code blocks in the crate and an attempt to make Rhai 100% safe is completely out-of-scope for this merge request, so we may as well use `unsafe` in the macro. Regarding (2) above, I may come back at a later date with a 100% safe `reify` function but only once the other `unsafe` blocks are removed. For posterity, said function would look something like: ```rust fn reify<A: Any, C>(value: A) -> Option<C> { let mut v = Some(value); let v: &mut dyn Any = &mut v; v.downcast_mut::<Option<C>>().map(Option::take) } ```		2022-02-05 16:29:05 -08:00
.github/workflows	Benchmark with features turned on.	2022-02-02 14:47:46 +08:00
benches	Fix benchmark.	2022-01-22 23:02:32 +08:00
codegen	Do not remove doc-comments on pluging functions.	2022-01-20 09:06:09 +08:00
examples	Refactor and add state to debugger.	2022-01-28 18:59:18 +08:00
no_std/no_std_test	Fix no-std builds.	2022-01-27 15:03:50 +08:00
scripts	Format example scripts better.	2022-01-20 12:06:36 +08:00
src	Remove unsound casting functions	2022-02-05 16:29:05 -08:00
tests	Fix tests.	2022-02-04 23:02:00 +08:00
.gitignore	poc: adds rustyline to rhai-repl	2022-01-28 20:29:25 -05:00
Cargo.toml	Add bin-features to pull in all features for bin tools.	2022-02-03 21:17:47 +08:00
CHANGELOG.md	Add variable definition filter.	2022-02-04 22:59:41 +08:00
LICENSE-APACHE.txt	Remove appendix from LICENSE-APACHE.txt	2020-07-25 07:08:13 +02:00
LICENSE-MIT.txt	Add LICENSE-MIT.txt (based on Syn)	2020-07-25 07:08:16 +02:00
README.md	Fix URL.	2022-01-27 16:58:11 +08:00

README.md

Rhai - Embedded Scripting for Rust

Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way to add scripting to any application.

Targets and builds

All CPU and O/S targets supported by Rust, including:
- WebAssembly (WASM)
- no-std
Minimum Rust version 1.51

Standard features

Simple language similar to JavaScript+Rust with dynamic typing.
Fairly efficient evaluation (1 million iterations in 0.3 sec on a single-core, 2.3 GHz Linux VM).
Tight integration with native Rust functions and types, including getters/setters, methods and indexers.
Freely pass Rust values into a script as variables/constants via an external Scope - all clonable Rust types are supported; no need to implement any special trait. Or tap directly into the variable resolution process.
Built-in support for most common data types including booleans, integers, floating-point numbers (including Decimal), strings, Unicode characters, arrays and object maps.
Easily call a script-defined function from Rust.
Relatively little unsafe code (yes there are some for performance reasons).
Few dependencies - currently only smallvec, num-traits, ahash and smartstring.
Re-entrant scripting engine can be made Send + Sync (via the sync feature).
Compile once to AST form for repeated evaluations.
Scripts are optimized (useful for template-based machine-generated scripts).
Easy custom API development via plugins system powered by procedural macros.
Function overloading and operator overloading.
Dynamic dispatch via function pointers with additional support for currying.
Closures (anonymous functions) that can capture shared values.
Some syntactic support for object-oriented programming (OOP).
Organize code base with dynamically-loadable modules, optionally overriding the resolution process.
Serialization/deserialization support via serde (requires the serde feature).
Support for minimal builds by excluding unneeded language features.
A debugging interface.

Protected against attacks

Don't Panic guarantee - Any panic is a bug. Rhai subscribes to the motto that a library should never panic the host system, and is coded with this in mind.
Sand-boxed - the scripting engine, if declared immutable, cannot mutate the containing environment unless explicitly permitted.
Rugged - protected against malicious attacks (such as stack-overflow, over-sized data, and runaway scripts etc.) that may come from untrusted third-party user-land scripts.
Track script evaluation progress and manually terminate a script run.

For those who actually want their own language

Use as a DSL.
Disable certain language features such as looping.
Further restrict the language by surgically disabling keywords and operators.
Define custom operators.
Extend the language with custom syntax.

Example

The scripts subdirectory contains sample Rhai scripts.

Below is the standard Fibonacci example for scripting languages:

// This Rhai script calculates the n-th Fibonacci number using a
// really dumb algorithm to test the speed of the scripting engine.

const TARGET = 28;
const REPEAT = 5;
const ANSWER = 317_811;

fn fib(n) {
    if n < 2 {
        n
    } else {
        fib(n-1) + fib(n-2)
    }
}

print(`Running Fibonacci(${TARGET}) x ${REPEAT} times...`);
print("Ready... Go!");

let result;
let now = timestamp();

for n in 0..REPEAT {
    result = fib(TARGET);
}

print(`Finished. Run time = ${now.elapsed} seconds.`);

print(`Fibonacci number #${TARGET} = ${result}`);

if result != ANSWER {
    print(`The answer is WRONG! Should be ${ANSWER}!`);
}

Project Site

rhai.rs

Documentation

See The Rhai Book for details on the Rhai scripting engine and language.

Playground

An Online Playground is available with syntax-highlighting editor, powered by WebAssembly.

Scripts can be evaluated directly from the editor.

License

Licensed under either of the following, at your choice:

Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in this crate, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.