rhai/README.md

81 lines
4.9 KiB
Markdown
Raw Normal View History

2020-03-09 05:53:07 +01:00
Rhai - Embedded Scripting for Rust
=================================
2016-02-29 22:43:45 +01:00
2020-03-22 03:18:16 +01:00
![GitHub last commit](https://img.shields.io/github/last-commit/jonathandturner/rhai)
[![Build Status](https://github.com/jonathandturner/rhai/workflows/Build/badge.svg)](https://github.com/jonathandturner/rhai/actions)
2020-03-22 03:18:16 +01:00
[![license](https://img.shields.io/github/license/jonathandturner/rhai)](https://github.com/license/jonathandturner/rhai)
2020-07-11 07:11:44 +02:00
[![crates.io](https://img.shields.io/crates/v/rhai.svg)](https://crates.io/crates/rhai/)
[![crates.io](https://img.shields.io/crates/d/rhai)](https://crates.io/crates/rhai/)
2020-03-22 03:18:16 +01:00
[![API Docs](https://docs.rs/rhai/badge.svg)](https://docs.rs/rhai/)
2020-04-05 17:43:40 +02:00
Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way
to add scripting to any application.
2016-03-02 20:53:12 +01:00
2020-06-18 07:01:07 +02:00
Supported targets and builds
---------------------------
2020-06-17 03:54:17 +02:00
* All common CPU targets for Windows, Linux and MacOS.
* WebAssembly (WASM)
* `no-std`
2020-06-17 03:54:17 +02:00
2020-07-16 06:09:40 +02:00
Standard features
-----------------
2016-03-03 15:59:53 +01:00
2020-06-22 16:02:49 +02:00
* Easy-to-use language similar to JavaScript+Rust with dynamic typing.
2020-06-20 09:57:15 +02:00
* Tight integration with native Rust [functions](https://schungx.github.io/rhai/rust/functions.html) and [types]([#custom-types-and-methods](https://schungx.github.io/rhai/rust/custom.html)), including [getters/setters](https://schungx.github.io/rhai/rust/getters-setters.html), [methods](https://schungx.github.io/rhai/rust/custom.html) and [indexers](https://schungx.github.io/rhai/rust/indexers.html).
* Freely pass Rust variables/constants into a script via an external [`Scope`](https://schungx.github.io/rhai/rust/scope.html).
* Easily [call a script-defined function](https://schungx.github.io/rhai/engine/call-fn.html) from Rust.
2020-05-31 09:55:02 +02:00
* Fairly low compile-time overhead.
2020-07-04 16:53:00 +02:00
* Fairly efficient evaluation (1 million iterations in 0.3 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
2020-05-18 03:36:34 +02:00
one single source file, all with names starting with `"unsafe_"`).
2020-07-04 10:21:15 +02:00
* Re-entrant scripting engine can be made `Send + Sync` (via the `sync` feature).
2020-06-20 09:57:15 +02:00
* [Function overloading](https://schungx.github.io/rhai/language/overload.html).
2020-07-09 13:54:28 +02:00
* [Operator overloading](https://schungx.github.io/rhai/rust/operators.html).
2020-06-29 17:55:28 +02:00
* Dynamic dispatch via [function pointers](https://schungx.github.io/rhai/language/fn-ptr.html).
* Some support for [object-oriented programming (OOP)](https://schungx.github.io/rhai/language/oop.html).
2020-06-20 09:57:15 +02:00
* Organize code base with dynamically-loadable [modules](https://schungx.github.io/rhai/language/modules.html).
2020-07-04 10:21:15 +02:00
* Serialization/deserialization support via [serde](https://crates.io/crates/serde) (requires the `serde` feature).
2020-06-20 09:57:15 +02:00
* Scripts are [optimized](https://schungx.github.io/rhai/engine/optimize.html) (useful for template-based machine-generated scripts) for repeated evaluations.
* Support for [minimal builds](https://schungx.github.io/rhai/start/builds/minimal.html) by excluding unneeded language [features](https://schungx.github.io/rhai/start/features.html).
2020-07-16 06:09:40 +02:00
Protection against attacks
--------------------------
2020-07-13 07:41:01 +02:00
* Sand-boxed - the scripting engine, if declared immutable, cannot mutate the containing environment unless explicitly permitted (e.g. via a `RefCell`).
* Rugged - protected against malicious attacks (such as [stack-overflow](https://schungx.github.io/rhai/safety/max-call-stack.html), [over-sized data](https://schungx.github.io/rhai/safety/max-string-size.html), and [runaway scripts](https://schungx.github.io/rhai/safety/max-operations.html) etc.) that may come from untrusted third-party user-land scripts.
* Track script evaluation [progress](https://schungx.github.io/rhai/safety/progress.html) and manually terminate a script run.
2020-07-16 06:09:40 +02:00
For those who actually want their own language
2020-07-13 07:41:01 +02:00
---------------------------------------------
* Use as a [DSL](https://schungx.github.io/rhai/engine/dsl.html).
* Restrict the language by surgically [disabling keywords and operators](https://schungx.github.io/rhai/engine/disable.html).
2020-07-16 06:09:40 +02:00
* Define [custom operators](https://schungx.github.io/rhai/engine/custom-op.html).
2020-07-13 07:41:01 +02:00
* Extend the language with [custom syntax](https://schungx.github.io/rhai/engine/custom-syntax.html).
Documentation
-------------
2020-05-24 06:40:28 +02:00
2020-06-21 18:03:45 +02:00
See [The Rhai Book](https://schungx.github.io/rhai) for details on the Rhai scripting engine and language.
2020-06-29 17:55:28 +02:00
Playground
----------
An [Online Playground](https://alvinhochun.github.io/rhai-demo/) is available with syntax-highlighting editor.
Scripts can be evaluated directly from the editor.
License
-------
2020-07-25 08:06:04 +02:00
Licensed under either:
2020-07-25 08:06:04 +02:00
* [Apache License, Version 2.0](https://github.com/jonathandturner/rhai/blob/master/LICENSE-APACHE.txt), or
* [MIT license](https://github.com/jonathandturner/rhai/blob/master/LICENSE-MIT.txt)
2020-07-26 04:07:40 +02:00
at your choice.
2020-07-25 08:06:04 +02:00
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.