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

Add writeup on Rhai usage scenarios.

Browse Source
This commit is contained in:
Stephen Chung 2020-05-31 15:55:02 +08:00
parent 840afe74bb
commit 697bb39a7f
2 changed files with 19 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@ -19,8 +19,8 @@ Features
including [getters/setters](#getters-and-setters), [methods](#members-and-methods) and [indexers](#indexers). including [getters/setters](#getters-and-setters), [methods](#members-and-methods) and [indexers](#indexers).
* Freely pass Rust variables/constants into a script via an external [`Scope`]. * Freely pass Rust variables/constants into a script via an external [`Scope`].
* Easily [call a script-defined function](#calling-rhai-functions-from-rust) from Rust. * Easily [call a script-defined function](#calling-rhai-functions-from-rust) from Rust.
* Low compile-time overhead (~0.6 sec debug/~3 sec release for `rhai_runner` sample app). * Fairly low compile-time overhead.
* Fairly efficient evaluation (1 million iterations in 0.75 sec on my 5 year old laptop). * Fairly efficient evaluation (1 million iterations in 0.25 sec on a single core, 2.3 GHz Linux VM).
* Relatively little `unsafe` code (yes there are some for performance reasons, and most `unsafe` code is limited to * Relatively little `unsafe` code (yes there are some for performance reasons, and most `unsafe` code is limited to
one single source file, all with names starting with `"unsafe_"`). one single source file, all with names starting with `"unsafe_"`).
* Re-entrant scripting [`Engine`] can be made `Send + Sync` (via the [`sync`] feature). * Re-entrant scripting [`Engine`] can be made `Send + Sync` (via the [`sync`] feature).
@ -47,10 +47,22 @@ It doesn't attempt to be a new language. For example:
* No classes. Well, Rust doesn't either. On the other hand... * No classes. Well, Rust doesn't either. On the other hand...
* No traits... so it is also not Rust. Do your Rusty stuff in Rust. * No traits... so it is also not Rust. Do your Rusty stuff in Rust.
* No structures - define your types in Rust instead; Rhai can seamlessly work with _any Rust type_. * No structures/records - define your types in Rust instead; Rhai can seamlessly work with _any Rust type_.
There is, however, a built-in [object map] type which is adequate for most uses.
* No first-class functions - Code your functions in Rust instead, and register them with Rhai. * No first-class functions - Code your functions in Rust instead, and register them with Rhai.
* No garbage collection - this should be expected, so...
* No closures - do your closure magic in Rust instead; [turn a Rhai scripted function into a Rust closure](#calling-rhai-functions-from-rust). * No closures - do your closure magic in Rust instead; [turn a Rhai scripted function into a Rust closure](#calling-rhai-functions-from-rust).
* It is best to expose an API in Rhai for scripts to call. All your core functionalities should be in Rust. * No byte-codes/JIT - Rhai has an AST-walking interpreter which will not win any speed races. The purpose of Rhai is not
to be extremely _fast_, but to make it as easy as possible to integrate with native Rust programs.
Due to this intended usage, Rhai deliberately keeps the language simple and small by omitting advanced language features
such as classes, inheritance, first-class functions, closures, concurrency, byte-codes, JIT etc.
Avoid the temptation to write full-fledge program logic entirely in Rhai - that use case is best fulfilled by
more complete languages such as JS or Lua.
Therefore, in actual practice, it is usually best to expose a Rust API into Rhai for scripts to call.
All your core functionalities should be in Rust.
This is similar to some dynamic languages where most of the core functionalities reside in a C/C++ standard library.
Installation Installation
------------ ------------

6
RELEASES.md
View File

@ -13,13 +13,13 @@ Bug fixes
--------- ---------
* Indexing with an index or dot expression now works property (it compiled wrongly before). * Indexing with an index or dot expression now works property (it compiled wrongly before).
For example, `let s = "hello"; s[s.len-1] = 'x';` now works property instead of an error. For example, `let s = "hello"; s[s.len-1] = 'x';` now works property instead of causing a runtime error.
Breaking changes Breaking changes
---------------- ----------------
* `Engine::compile_XXX` functions now return `ParseError` instead of `Box<ParseError>`. * `Engine::compile_XXX` functions now return `ParseError` instead of `Box<ParseError>`.
* The `RegisterDynamicFn` trait is merged into the `RegisterResutlFn` trait which now always returns * The `RegisterDynamicFn` trait is merged into the `RegisterResultFn` trait which now always returns
`Result<Dynamic, Box<EvalAltResult>>`. `Result<Dynamic, Box<EvalAltResult>>`.
* Default maximum limit on levels of nested function calls is fine-tuned and set to a different value. * Default maximum limit on levels of nested function calls is fine-tuned and set to a different value.
* Some operator functions are now built in (see _Speed enhancements_ below), so they are available even * Some operator functions are now built in (see _Speed enhancements_ below), so they are available even
@ -62,7 +62,7 @@ Speed enhancements
in a full clone of `a` before taking the length and throwing the copy away. Now, `a` is simply passed by reference, in a full clone of `a` before taking the length and throwing the copy away. Now, `a` is simply passed by reference,
avoiding the cloning altogether. avoiding the cloning altogether.
* A custom hasher simply passes through `u64` keys without hashing to avoid function call hash keys * A custom hasher simply passes through `u64` keys without hashing to avoid function call hash keys
(which as by themselves `u64`) being hashed twice. (which are by themselves `u64`) being hashed twice.
Version 0.14.1 Version 0.14.1