rhai/README.md

325 lines
7.2 KiB
Markdown
Raw Normal View History

2016-02-29 22:43:45 +01:00
# Rhai - embedded scripting for Rust
2016-04-14 03:52:12 +02:00
Rhai is an embedded scripting language for Rust that gives you a safe and easy way to add scripting to your applications.
2016-03-02 20:53:12 +01:00
2016-03-03 15:59:53 +01:00
Rhai's current feature set:
2016-03-03 16:10:08 +01:00
* Easy integration with Rust functions and data types
2016-03-03 15:59:53 +01:00
* Fairly efficient (1 mil iterations in 0.75 sec on my 5 year old laptop)
2016-03-04 14:08:34 +01:00
* Low compile-time overhead (~0.6 sec debug/~3 sec release for script runner app)
2016-03-03 16:14:11 +01:00
* Easy-to-use language based on JS+Rust
2016-03-03 15:59:53 +01:00
* Support for overloaded functions
* No additional dependencies
* No unsafe code
2016-04-14 03:52:12 +02:00
**Note:** Currently, it's version 0.3.0, so the language and APIs may change before they stabilize.*
2016-03-14 16:31:24 +01:00
## Installation
You can install Rhai using crates by adding this line to your dependences:
```
[dependencies]
2016-04-14 03:52:12 +02:00
rhai = "0.3.0"
2016-03-14 16:31:24 +01:00
```
## Related
2016-03-03 16:00:29 +01:00
2016-03-04 14:13:57 +01:00
Other cool projects to check out:
* [ChaiScript](http://chaiscript.com/) - A strong inspiration for Rhai. An embedded scripting language for C++ that I helped created many moons ago, now being lead by my cousin.
2016-03-27 05:27:34 +02:00
* You can also check out the list of [scripting languages for Rust](http://libs.rs/scripting/) on [libs.rs](http://libs.rs/)
2016-03-04 14:13:57 +01:00
2016-03-31 16:01:58 +02:00
# Hello world
2016-04-14 03:52:12 +02:00
To get going with Rhai, you create an instance of the scripting engine and then run eval.
2016-02-29 22:43:45 +01:00
2016-03-02 20:40:07 +01:00
```Rust
2016-03-03 17:07:45 +01:00
extern crate rhai;
use rhai::Engine;
2016-03-02 20:40:07 +01:00
2016-03-03 17:07:45 +01:00
fn main() {
let mut engine = Engine::new();
2016-04-14 03:52:12 +02:00
if let Ok(result) = engine.eval::<i64>("40 + 2") {
2016-03-26 21:45:24 +01:00
println!("Answer: {}", result); // prints 42
2016-03-03 17:07:45 +01:00
}
2016-03-02 20:40:07 +01:00
}
```
2016-03-31 16:01:58 +02:00
2016-03-31 16:06:39 +02:00
You can also evaluate a script file:
```Rust
2016-04-14 03:52:12 +02:00
if let Ok(result) = engine.eval_file::<i64>("hello_world.rhai") { ... }
2016-03-31 16:06:39 +02:00
```
2016-03-31 16:01:58 +02:00
# Working with functions
2016-03-02 20:53:12 +01:00
Rhai's scripting engine is very lightweight. It gets its ability from the functions in your program. To call these functions, you need to register them with the scripting engine.
```Rust
2016-03-03 17:07:45 +01:00
extern crate rhai;
use rhai::{Engine, FnRegister};
2016-04-14 03:52:12 +02:00
fn add(x: i64, y: i64) -> i64 {
2016-03-02 20:53:12 +01:00
x + y
}
fn main() {
let mut engine = Engine::new();
2016-03-26 21:42:54 +01:00
engine.register_fn("add", add);
2016-04-14 03:52:12 +02:00
if let Ok(result) = engine.eval::<i64>("add(40, 2)") {
2016-03-26 21:45:24 +01:00
println!("Answer: {}", result); // prints 42
2016-03-02 20:53:12 +01:00
}
}
```
2016-03-02 20:40:07 +01:00
2016-03-31 16:01:58 +02:00
# Working with generic functions
2016-03-02 20:53:12 +01:00
Generic functions can be used in Rhai, but you'll need to register separate instances for each concrete type:
```Rust
2016-03-03 17:07:45 +01:00
use std::fmt::Display;
extern crate rhai;
use rhai::{Engine, FnRegister};
2016-03-02 20:53:12 +01:00
fn showit<T: Display>(x: &mut T) -> () {
println!("{}", x)
}
fn main() {
let mut engine = Engine::new();
2016-04-14 03:52:12 +02:00
engine.register_fn("print", showit as fn(x: &mut i64)->());
2016-03-26 21:42:54 +01:00
engine.register_fn("print", showit as fn(x: &mut bool)->());
engine.register_fn("print", showit as fn(x: &mut String)->());
2016-03-02 20:53:12 +01:00
}
```
2016-03-04 14:10:53 +01:00
You can also see in this example how you can register multiple functions (or in this case multiple instances of the same function) to the same name in script. This gives you a way to overload functions and call the correct one, based on the types of the arguments, from your script.
2016-03-03 16:14:11 +01:00
2016-03-31 16:01:58 +02:00
# Custom types and methods
2016-03-02 20:40:07 +01:00
2016-03-02 21:08:35 +01:00
Here's an more complete example of working with Rust. First the example, then we'll break it into parts:
2016-03-02 20:53:12 +01:00
2016-03-02 20:40:07 +01:00
```Rust
2016-03-03 17:07:45 +01:00
extern crate rhai;
use rhai::{Engine, FnRegister};
2016-03-10 22:48:56 +01:00
#[derive(Clone)]
2016-03-02 20:40:07 +01:00
struct TestStruct {
2016-04-14 03:52:12 +02:00
x: i64
2016-03-02 20:40:07 +01:00
}
impl TestStruct {
fn update(&mut self) {
self.x += 1000;
}
fn new() -> TestStruct {
TestStruct { x: 1 }
}
}
2016-03-03 17:07:45 +01:00
fn main() {
let mut engine = Engine::new();
2016-03-02 20:40:07 +01:00
2016-03-03 17:07:45 +01:00
engine.register_type::<TestStruct>();
2016-03-02 20:40:07 +01:00
2016-03-26 21:42:54 +01:00
engine.register_fn("update", TestStruct::update);
engine.register_fn("new_ts", TestStruct::new);
2016-03-02 20:40:07 +01:00
2016-03-26 21:42:54 +01:00
if let Ok(result) = engine.eval::<TestStruct>("var x = new_ts(); x.update(); x") {
2016-03-03 17:07:45 +01:00
println!("result: {}", result.x); // prints 1001
}
2016-03-02 20:40:07 +01:00
}
```
First, for each type we use with the engine, we need to be able to Clone. This allows the engine to pass by value and still keep its own state.
```Rust
2016-03-10 22:48:56 +01:00
#[derive(Clone)]
2016-03-02 20:40:07 +01:00
struct TestStruct {
2016-04-14 03:52:12 +02:00
x: i64
2016-03-02 20:40:07 +01:00
}
```
Next, we create a few methods that we'll later use in our scripts. Notice that we register our custom type with the engine.
2016-03-02 20:40:39 +01:00
```Rust
2016-03-02 20:40:07 +01:00
impl TestStruct {
fn update(&mut self) {
self.x += 1000;
}
fn new() -> TestStruct {
TestStruct { x: 1 }
}
}
let mut engine = Engine::new();
engine.register_type::<TestStruct>();
```
To use methods and functions with the engine, we need to register them. There are some convenience functions to help with this. Below I register update and new with the engine.
2016-03-02 20:53:12 +01:00
*Note: the engine follows the convention that methods use a &mut first parameter so that invoking methods can update the value in memory.*
2016-03-02 20:40:07 +01:00
2016-03-02 20:40:39 +01:00
```Rust
2016-03-26 21:42:54 +01:00
engine.register_fn("update", TestStruct::update);
engine.register_fn("new_ts", TestStruct::new);
2016-03-02 20:40:07 +01:00
```
Finally, we call our script. The script can see the function and method we registered earlier. We need to get the result back out from script land just as before, this time casting to our custom struct type.
2016-03-02 20:40:39 +01:00
```Rust
2016-03-26 21:42:54 +01:00
if let Ok(result) = engine.eval::<TestStruct>("var x = new_ts(); x.update(); x") {
2016-03-02 20:40:07 +01:00
println!("result: {}", result.x); // prints 1001
}
```
2016-03-04 14:27:06 +01:00
2016-03-31 16:01:58 +02:00
# Getters and setters
2016-03-10 22:25:03 +01:00
2016-04-14 03:52:12 +02:00
Similarly, you can work with members of your custom types. This works by registering a 'get' or a 'set' function for working with your struct.
2016-03-10 22:25:03 +01:00
For example:
```Rust
#[derive(Clone)]
struct TestStruct {
2016-04-14 03:52:12 +02:00
x: i64
2016-03-10 22:25:03 +01:00
}
impl TestStruct {
2016-04-14 03:52:12 +02:00
fn get_x(&mut self) -> i64 {
2016-03-10 22:25:03 +01:00
self.x
}
2016-04-14 03:52:12 +02:00
fn set_x(&mut self, new_x: i64) {
2016-03-10 22:25:03 +01:00
self.x = new_x;
}
fn new() -> TestStruct {
TestStruct { x: 1 }
}
}
let mut engine = Engine::new();
engine.register_type::<TestStruct>();
2016-03-26 21:42:54 +01:00
engine.register_get_set("x", TestStruct::get_x, TestStruct::set_x);
engine.register_fn("new_ts", TestStruct::new);
2016-03-10 22:25:03 +01:00
2016-04-14 03:52:12 +02:00
if let Ok(result) = engine.eval::<i64>("var a = new_ts(); a.x = 500; a.x") {
2016-03-10 22:25:03 +01:00
println!("result: {}", result);
}
```
2016-03-31 16:01:58 +02:00
# Maintaining state
2016-03-04 14:27:06 +01:00
By default, Rhai treats each engine invocation as a fresh one, persisting only the functions that have been defined but no top-level state. This gives each one a fairly clean starting place. Sometimes, though, you want to continue using the same top-level state from one invocation to the next.
In this example, we thread the same state through multiple invocations:
```Rust
extern crate rhai;
use rhai::{Engine, Scope};
fn main() {
let mut engine = Engine::new();
let mut scope: Scope = Vec::new();
2016-04-14 03:52:12 +02:00
if let Ok(_) = engine.eval_with_scope::<()>(&mut scope, "var x = 4 + 5") { } else { assert!(false); }
2016-03-04 14:27:06 +01:00
2016-04-14 03:52:12 +02:00
if let Ok(result) = engine.eval_with_scope::<i64>(&mut scope, "x") {
2016-03-04 14:27:06 +01:00
println!("result: {}", result);
}
}
```
2016-03-10 22:25:03 +01:00
2016-03-31 16:03:03 +02:00
# Rhai Language guide
2016-03-31 15:59:54 +02:00
## Variables
```Rust
var x = 3;
```
## Operators
```Rust
var x = (1 + 2) * (6 - 4) / 2;
```
## If
```Rust
2016-04-14 03:52:12 +02:00
if true {
2016-03-31 15:59:54 +02:00
print("it's true!");
}
else {
print("It's false!");
}
```
## While
```Rust
var x = 10;
2016-04-14 03:52:12 +02:00
while x > 0 {
2016-03-31 15:59:54 +02:00
print(x);
if x == 5 {
break;
}
x = x - 1;
}
```
## Functions
Rhai supports defining functions in script:
```Rust
fn add(x, y) {
return x + y;
}
print(add(2, 3))
```
Just like in Rust, you can also use an implicit return.
```Rust
fn add(x, y) {
x + y
}
print(add(2, 3))
```
2016-04-14 03:52:12 +02:00
## Arrays
2016-03-31 15:59:54 +02:00
You can create arrays of values, and then access them with numeric indices.
```Rust
2016-04-14 03:52:12 +02:00
var y = [1, 2, 3];
y[1] = 5;
2016-03-31 15:59:54 +02:00
print(y[1]);
```
## Members and methods
```Rust
2016-04-14 03:52:12 +02:00
var a = new_ts();
2016-03-31 15:59:54 +02:00
a.x = 500;
a.update();
```
2016-04-14 03:52:12 +02:00
## Strings and Chars
```Rust
var name = "Bob";
var middle_initial = 'C';
```
2016-03-31 15:59:54 +02:00