rhai/README.md

150 lines
8.6 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
2021-01-07 10:30:06 +01:00
![GitHub last commit](https://img.shields.io/github/last-commit/rhaiscript/rhai?logo=github)
[![Build Status](https://github.com/rhaiscript/rhai/workflows/Build/badge.svg)](https://github.com/rhaiscript/rhai/actions)
2021-04-24 16:19:41 +02:00
[![Stars](https://img.shields.io/github/stars/rhaiscript/rhai?logo=github)](https://github.com/rhaiscript/rhai)
[![License](https://img.shields.io/crates/l/rhai)](https://github.com/license/rhaiscript/rhai)
2020-10-19 11:26:47 +02:00
[![crates.io](https://img.shields.io/crates/v/rhai?logo=rust)](https://crates.io/crates/rhai/)
[![crates.io](https://img.shields.io/crates/d/rhai?logo=rust)](https://crates.io/crates/rhai/)
2021-04-25 08:39:02 +02:00
[![API Docs](https://docs.rs/rhai/badge.svg?logo=docs-rs)](https://docs.rs/rhai/)
[![VS Code plugin installs](https://img.shields.io/visual-studio-marketplace/i/rhaiscript.vscode-rhai?logo=visual-studio-code&label=vs%20code)](https://marketplace.visualstudio.com/items?itemName=rhaiscript.vscode-rhai)
[![Sublime Text package downloads](https://img.shields.io/packagecontrol/dt/Rhai.svg?logo=sublime-text&label=sublime%20text)](https://packagecontrol.io/packages/Rhai)
2021-04-24 16:19:41 +02:00
[![Discord Chat](https://img.shields.io/discord/767611025456889857.svg?logo=discord&label=discord)](https://discord.gg/HquqbYFcZ9)
2021-06-01 05:13:56 +02:00
[![Zulip Chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg?logo=zulip)](https://rhaiscript.zulipchat.com)
2021-04-24 16:19:41 +02:00
[![Reddit Channel](https://img.shields.io/reddit/subreddit-subscribers/Rhai?logo=reddit&label=reddit)](https://www.reddit.com/r/Rhai)
2020-03-22 03:18:16 +01:00
2021-03-01 05:43:11 +01:00
[![Rhai logo](https://rhai.rs/book/images/logo/rhai-banner-transparent-colour.svg)](https://rhai.rs)
2020-12-18 12:12:30 +01:00
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-10-19 08:26:15 +02:00
2021-08-30 04:14:41 +02:00
Targets and builds
------------------
2020-06-17 03:54:17 +02:00
2021-08-30 04:14:41 +02:00
* All CPU and O/S targets supported by Rust, including:
* WebAssembly (WASM)
* `no-std`
2022-02-24 01:54:37 +01:00
* Minimum Rust version 1.57
2020-06-17 03:54:17 +02:00
2020-10-19 08:26:15 +02:00
2020-07-16 06:09:40 +02:00
Standard features
-----------------
2016-03-03 15:59:53 +01:00
2021-03-21 15:30:34 +01:00
* Simple language similar to JavaScript+Rust with [dynamic](https://rhai.rs/book/language/dynamic.html) typing.
* Fairly efficient evaluation (1 million iterations in 0.3 sec on a single-core, 2.3 GHz Linux VM).
2021-01-30 00:19:54 +01:00
* Tight integration with native Rust [functions](https://rhai.rs/book/rust/functions.html) and [types]([#custom-types-and-methods](https://rhai.rs/book/rust/custom.html)), including [getters/setters](https://rhai.rs/book/rust/getters-setters.html), [methods](https://rhai.rs/book/rust/custom.html) and [indexers](https://rhai.rs/book/rust/indexers.html).
2021-03-21 15:30:34 +01:00
* Freely pass Rust values into a script as [variables](https://rhai.rs/book/language/variables.html)/[constants](https://rhai.rs/book/language/constants.html) via an external [`Scope`](https://rhai.rs/book/rust/scope.html) - all clonable Rust types are supported; no need to implement any special trait. Or tap directly into the [variable resolution process](https://rhai.rs/book/engine/var.html).
2022-02-15 12:56:42 +01:00
* Built-in support for most common [data types](https://rhai.rs/book/language/values-and-types.html) including booleans, [integers](https://rhai.rs/book/language/numbers.html), [floating-point numbers](https://rhai.rs/book/language/numbers.html) (including [`Decimal`](https://crates.io/crates/rust_decimal)), [strings](https://rhai.rs/book/language/strings-chars.html), [Unicode characters](https://rhai.rs/book/language/strings-chars.html), [arrays](https://rhai.rs/book/language/arrays.html) (including packed [byte arrays](https://rhai.rs/book/language/blobs.html)) and [object maps](https://rhai.rs/book/language/object-maps.html).
2021-01-30 00:19:54 +01:00
* Easily [call a script-defined function](https://rhai.rs/book/engine/call-fn.html) from Rust.
2021-06-22 16:32:50 +02:00
* Relatively little `unsafe` code (yes there are some for performance reasons).
2022-02-25 04:42:59 +01:00
* Few dependencies - currently only [`smallvec`](https://crates.io/crates/smallvec), [`num-traits`](https://crates.io/crates/num-traits), [`ahash`](https://crates.io/crates/ahash), [`bitflags`](https://crates.io/crates/bitflags) and [`smartstring`](https://crates.io/crates/smartstring).
2020-07-04 10:21:15 +02:00
* Re-entrant scripting engine can be made `Send + Sync` (via the `sync` feature).
* Compile once to [AST](https://rhai.rs/book/engine/compile.html) form for repeated evaluations.
2021-01-30 00:19:54 +01:00
* Scripts are [optimized](https://rhai.rs/book/engine/optimize.html) (useful for template-based machine-generated scripts).
2022-01-26 15:16:17 +01:00
* Easy custom API development via [plugins](https://rhai.rs/book/plugins) system powered by procedural macros.
2021-01-30 00:19:54 +01:00
* [Function overloading](https://rhai.rs/book/language/overload.html) and [operator overloading](https://rhai.rs/book/rust/operators.html).
* Dynamic dispatch via [function pointers](https://rhai.rs/book/language/fn-ptr.html) with additional support for [currying](https://rhai.rs/book/language/fn-curry.html).
* [Closures](https://rhai.rs/book/language/fn-closure.html) (anonymous functions) that can capture shared values.
* Some syntactic support for [object-oriented programming (OOP)](https://rhai.rs/book/language/oop.html).
2021-03-21 15:30:34 +01:00
* Organize code base with dynamically-loadable [modules](https://rhai.rs/book/language/modules.html), optionally [overriding the resolution process](https://rhai.rs/book/rust/modules/resolvers.html).
2020-07-04 10:21:15 +02:00
* Serialization/deserialization support via [serde](https://crates.io/crates/serde) (requires the `serde` feature).
2021-01-30 00:19:54 +01:00
* Support for [minimal builds](https://rhai.rs/book/start/builds/minimal.html) by excluding unneeded language [features](https://rhai.rs/book/start/features.html).
2022-01-26 15:16:17 +01:00
* A [debugging](https://rhai.rs/book/engine/debugging) interface.
2020-10-19 08:26:15 +02:00
Protected against attacks
-------------------------
2020-07-13 07:41:01 +02:00
2021-03-21 15:30:34 +01:00
* _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](https://rhai.rs/book/safety/sandbox.html) - the scripting engine, if declared immutable, cannot mutate the containing environment unless [explicitly permitted](https://rhai.rs/book/patterns/control.html).
2021-01-30 00:19:54 +01:00
* Rugged - protected against malicious attacks (such as [stack-overflow](https://rhai.rs/book/safety/max-call-stack.html), [over-sized data](https://rhai.rs/book/safety/max-string-size.html), and [runaway scripts](https://rhai.rs/book/safety/max-operations.html) etc.) that may come from untrusted third-party user-land scripts.
* Track script evaluation [progress](https://rhai.rs/book/safety/progress.html) and manually terminate a script run.
2020-07-13 07:41:01 +02:00
2020-10-19 08:26:15 +02:00
2020-07-16 06:09:40 +02:00
For those who actually want their own language
2020-07-13 07:41:01 +02:00
---------------------------------------------
2021-01-30 00:19:54 +01:00
* Use as a [DSL](https://rhai.rs/book/engine/dsl.html).
2021-12-06 14:23:18 +01:00
* Disable certain [language features](https://rhai.rs/book/engine/options.html#language-features) such as [looping](https://rhai.rs/book/engine/disable-looping.html).
* Further restrict the language by surgically [disabling keywords and operators](https://rhai.rs/book/engine/disable-keywords.html).
2021-01-30 00:19:54 +01:00
* Define [custom operators](https://rhai.rs/book/engine/custom-op.html).
* Extend the language with [custom syntax](https://rhai.rs/book/engine/custom-syntax.html).
2020-07-13 07:41:01 +02:00
2020-10-19 08:26:15 +02:00
2021-09-20 18:14:50 +02:00
Example
-------
The [`scripts`](https://github.com/rhaiscript/rhai/tree/master/scripts) subdirectory contains sample Rhai scripts.
2021-09-21 04:41:09 +02:00
Below is the standard _Fibonacci_ example for scripting languages:
2021-09-20 18:14:50 +02:00
```ts
// This Rhai script calculates the n-th Fibonacci number using a
// really dumb algorithm to test the speed of the scripting engine.
2021-09-20 18:14:50 +02:00
const TARGET = 28;
const REPEAT = 5;
2021-09-27 05:13:48 +02:00
const ANSWER = 317_811;
2021-09-20 18:14:50 +02:00
fn fib(n) {
if n < 2 {
n
} else {
fib(n-1) + fib(n-2)
}
}
2021-09-21 04:41:09 +02:00
print(`Running Fibonacci(${TARGET}) x ${REPEAT} times...`);
2021-09-20 18:14:50 +02:00
print("Ready... Go!");
let result;
let now = timestamp();
2021-12-15 05:06:17 +01:00
for n in 0..REPEAT {
2021-09-20 18:14:50 +02:00
result = fib(TARGET);
}
print(`Finished. Run time = ${now.elapsed} seconds.`);
print(`Fibonacci number #${TARGET} = ${result}`);
2021-09-27 05:13:48 +02:00
if result != ANSWER {
print(`The answer is WRONG! Should be ${ANSWER}!`);
2021-09-20 18:14:50 +02:00
}
```
2021-03-01 05:43:11 +01:00
Project Site
------------
[`rhai.rs`](https://rhai.rs)
Documentation
-------------
2020-05-24 06:40:28 +02:00
2021-03-21 15:30:34 +01:00
See [_The Rhai Book_](https://rhai.rs/book) for details on the Rhai scripting engine and language.
2020-06-29 17:55:28 +02:00
2020-10-19 08:26:15 +02:00
2020-06-29 17:55:28 +02:00
Playground
----------
2021-03-21 15:30:34 +01:00
An [_Online Playground_](https://rhai.rs/playground) is available with syntax-highlighting editor,
powered by WebAssembly.
2021-01-14 12:07:03 +01:00
2020-06-29 17:55:28 +02:00
Scripts can be evaluated directly from the editor.
2020-10-19 08:26:15 +02:00
License
-------
2020-09-28 16:14:19 +02:00
Licensed under either of the following, at your choice:
2021-01-07 10:30:06 +01:00
* [Apache License, Version 2.0](https://github.com/rhaiscript/rhai/blob/master/LICENSE-APACHE.txt), or
* [MIT license](https://github.com/rhaiscript/rhai/blob/master/LICENSE-MIT.txt)
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.