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

Merge pull request #590 from tamasfe/feat-definitions

Browse Source 
feat: Basic definition files
This commit is contained in:
Stephen Chung 2022-07-26 21:53:43 +08:00 committed by GitHub
commit a891b54d0f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 7022 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Cargo.toml
View File

@ -13,7 +13,7 @@ homepage = "https://rhai.rs"
repository = "https://github.com/rhaiscript"
readme = "README.md"
license = "MIT OR Apache-2.0"
include = ["/src/**/*.rs", "/Cargo.toml", "/README.md"]
include = ["/src/**/*", "/Cargo.toml", "/README.md", "LICENSE*"]
keywords = ["scripting", "scripting-engine", "scripting-language", "embedded"]
categories = ["no-std", "embedded", "wasm", "parser-implementations"]
@ -86,6 +86,10 @@ required-features = ["debugging"]
name = "serde"
required-features = ["serde"]
[[example]]
name = "definitions"
required-features = ["metadata"]
[profile.release]
lto = "fat"
codegen-units = 1

3
examples/README.md
View File

@ -5,7 +5,7 @@ Standard Examples
-----------------
| Example | Description |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`arrays_and_structs`](arrays_and_structs.rs) | shows how to register a Rust type and using it with arrays |
| [`callback`](callback.rs) | shows how to store a Rhai closure and call it later within Rust |
| [`custom_types_and_methods`](custom_types_and_methods.rs) | shows how to register a Rust type and methods/getters/setters for it |
@ -15,6 +15,7 @@ Standard Examples
| [`simple_fn`](simple_fn.rs) | shows how to register a simple Rust function |
| [`strings`](strings.rs) | shows different ways to register Rust functions taking string arguments |
| [`threading`](threading.rs) | shows how to communicate with an `Engine` running in a separate thread via an MPSC channel |
| [`definitions`](./definitions) | shows how to generate definition files for manual inspection or for use with [Rhai LSP](https://github.com/rhaiscript/lsp), requires the `metadata` feature |
Scriptable Event Handler With State Examples

251
examples/definitions/.rhai/definitions/__builtin-operators__.d.rhai Normal file
View File

@ -0,0 +1,251 @@
module static;
op ==(i64, i64) -> bool;
op !=(i64, i64) -> bool;
op >(i64, i64) -> bool;
op >=(i64, i64) -> bool;
op <(i64, i64) -> bool;
op <=(i64, i64) -> bool;
op &(i64, i64) -> i64;
op |(i64, i64) -> i64;
op ^(i64, i64) -> i64;
op ..(i64, i64) -> Range<i64>;
op ..=(i64, i64) -> RangeInclusive<i64>;
op ==(bool, bool) -> bool;
op !=(bool, bool) -> bool;
op >(bool, bool) -> bool;
op >=(bool, bool) -> bool;
op <(bool, bool) -> bool;
op <=(bool, bool) -> bool;
op &(bool, bool) -> bool;
op |(bool, bool) -> bool;
op ^(bool, bool) -> bool;
op ==((), ()) -> bool;
op !=((), ()) -> bool;
op >((), ()) -> bool;
op >=((), ()) -> bool;
op <((), ()) -> bool;
op <=((), ()) -> bool;
op +(i64, i64) -> i64;
op -(i64, i64) -> i64;
op *(i64, i64) -> i64;
op /(i64, i64) -> i64;
op %(i64, i64) -> i64;
op **(i64, i64) -> i64;
op >>(i64, i64) -> i64;
op <<(i64, i64) -> i64;
op +(f64, f64) -> f64;
op -(f64, f64) -> f64;
op *(f64, f64) -> f64;
op /(f64, f64) -> f64;
op %(f64, f64) -> f64;
op **(f64, f64) -> f64;
op ==(f64, f64) -> bool;
op !=(f64, f64) -> bool;
op >(f64, f64) -> bool;
op >=(f64, f64) -> bool;
op <(f64, f64) -> bool;
op <=(f64, f64) -> bool;
op +(f64, i64) -> f64;
op -(f64, i64) -> f64;
op *(f64, i64) -> f64;
op /(f64, i64) -> f64;
op %(f64, i64) -> f64;
op **(f64, i64) -> f64;
op ==(f64, i64) -> bool;
op !=(f64, i64) -> bool;
op >(f64, i64) -> bool;
op >=(f64, i64) -> bool;
op <(f64, i64) -> bool;
op <=(f64, i64) -> bool;
op +(i64, f64) -> f64;
op -(i64, f64) -> f64;
op *(i64, f64) -> f64;
op /(i64, f64) -> f64;
op %(i64, f64) -> f64;
op **(i64, f64) -> f64;
op ==(i64, f64) -> bool;
op !=(i64, f64) -> bool;
op >(i64, f64) -> bool;
op >=(i64, f64) -> bool;
op <(i64, f64) -> bool;
op <=(i64, f64) -> bool;
op +(Decimal, Decimal) -> Decimal;
op -(Decimal, Decimal) -> Decimal;
op *(Decimal, Decimal) -> Decimal;
op /(Decimal, Decimal) -> Decimal;
op %(Decimal, Decimal) -> Decimal;
op **(Decimal, Decimal) -> Decimal;
op ==(Decimal, Decimal) -> bool;
op !=(Decimal, Decimal) -> bool;
op >(Decimal, Decimal) -> bool;
op >=(Decimal, Decimal) -> bool;
op <(Decimal, Decimal) -> bool;
op <=(Decimal, Decimal) -> bool;
op +(Decimal, i64) -> Decimal;
op -(Decimal, i64) -> Decimal;
op *(Decimal, i64) -> Decimal;
op /(Decimal, i64) -> Decimal;
op %(Decimal, i64) -> Decimal;
op **(Decimal, i64) -> Decimal;
op ==(Decimal, i64) -> bool;
op !=(Decimal, i64) -> bool;
op >(Decimal, i64) -> bool;
op >=(Decimal, i64) -> bool;
op <(Decimal, i64) -> bool;
op <=(Decimal, i64) -> bool;
op +(i64, Decimal) -> Decimal;
op -(i64, Decimal) -> Decimal;
op *(i64, Decimal) -> Decimal;
op /(i64, Decimal) -> Decimal;
op %(i64, Decimal) -> Decimal;
op **(i64, Decimal) -> Decimal;
op ==(i64, Decimal) -> bool;
op !=(i64, Decimal) -> bool;
op >(i64, Decimal) -> bool;
op >=(i64, Decimal) -> bool;
op <(i64, Decimal) -> bool;
op <=(i64, Decimal) -> bool;
op +(String, String) -> String;
op -(String, String) -> String;
op ==(String, String) -> bool;
op !=(String, String) -> bool;
op >(String, String) -> bool;
op >=(String, String) -> bool;
op <(String, String) -> bool;
op <=(String, String) -> bool;
op +(char, char) -> String;
op ==(char, char) -> bool;
op !=(char, char) -> bool;
op >(char, char) -> bool;
op >=(char, char) -> bool;
op <(char, char) -> bool;
op <=(char, char) -> bool;
op +(char, String) -> String;
op ==(char, String) -> bool;
op !=(char, String) -> bool;
op >(char, String) -> bool;
op >=(char, String) -> bool;
op <(char, String) -> bool;
op <=(char, String) -> bool;
op +(String, char) -> String;
op -(String, char) -> String;
op ==(String, char) -> bool;
op !=(String, char) -> bool;
op >(String, char) -> bool;
op >=(String, char) -> bool;
op <(String, char) -> bool;
op <=(String, char) -> bool;
op +((), String) -> String;
op ==((), String) -> bool;
op !=((), String) -> bool;
op >((), String) -> bool;
op >=((), String) -> bool;
op <((), String) -> bool;
op <=((), String) -> bool;
op +(String, ()) -> String;
op ==(String, ()) -> bool;
op !=(String, ()) -> bool;
op >(String, ()) -> bool;
op >=(String, ()) -> bool;
op <(String, ()) -> bool;
op <=(String, ()) -> bool;
op +(Blob, Blob) -> Blob;
op +(Blob, char) -> Blob;
op ==(Blob, Blob) -> bool;
op !=(Blob, Blob) -> bool;
op ==(Range<i64>, RangeInclusive<i64>) -> bool;
op !=(Range<i64>, RangeInclusive<i64>) -> bool;
op ==(RangeInclusive<i64>, Range<i64>) -> bool;
op !=(RangeInclusive<i64>, Range<i64>) -> bool;
op ==(Range<i64>, Range<i64>) -> bool;
op !=(Range<i64>, Range<i64>) -> bool;
op ==(RangeInclusive<i64>, RangeInclusive<i64>) -> bool;
op !=(RangeInclusive<i64>, RangeInclusive<i64>) -> bool;
op ==(?, ?) -> bool;
op !=(?, ?) -> bool;
op >(?, ?) -> bool;
op >=(?, ?) -> bool;
op <(?, ?) -> bool;
op <=(?, ?) -> bool;
op &=(bool, bool);
op |=(bool, bool);
op +=(i64, i64);
op -=(i64, i64);
op *=(i64, i64);
op /=(i64, i64);
op %=(i64, i64);
op **=(i64, i64);
op >>=(i64, i64);
op <<=(i64, i64);
op &=(i64, i64);
op |=(i64, i64);
op ^=(i64, i64);
op +=(f64, f64);
op -=(f64, f64);
op *=(f64, f64);
op /=(f64, f64);
op %=(f64, f64);
op **=(f64, f64);
op +=(f64, i64);
op -=(f64, i64);
op *=(f64, i64);
op /=(f64, i64);
op %=(f64, i64);
op **=(f64, i64);
op +=(Decimal, Decimal);
op -=(Decimal, Decimal);
op *=(Decimal, Decimal);
op /=(Decimal, Decimal);
op %=(Decimal, Decimal);
op **=(Decimal, Decimal);
op +=(Decimal, i64);
op -=(Decimal, i64);
op *=(Decimal, i64);
op /=(Decimal, i64);
op %=(Decimal, i64);
op **=(Decimal, i64);
op +=(String, String);
op -=(String, String);
op +=(String, char);
op -=(String, char);
op +=(char, String);
op +=(char, char);
op +=(Array, Array);
op +=(Array, ?);
op +=(Blob, Blob);
op +=(Blob, i64);
op +=(Blob, char);
op +=(Blob, String);

170
examples/definitions/.rhai/definitions/__builtin__.d.rhai Normal file
View File

@ -0,0 +1,170 @@
module static;
/// Display any data to the standard output.
///
/// # Example
///
/// ```rhai
/// let answer = 42;
///
/// print(`The Answer is ${answer}`);
/// ```
fn print(data: ?);
/// Display any data to the standard output in debug format.
///
/// # Example
///
/// ```rhai
/// let answer = 42;
///
/// debug(answer);
/// ```
fn debug(data: ?);
/// Get the type of a value.
///
/// # Example
///
/// ```rhai
/// let x = "hello, world!";
///
/// print(x.type_of()); // prints "string"
/// ```
fn type_of(data: ?) -> String;
/// Create a function pointer to a named function.
///
/// If the specified name is not a valid function name, an error is raised.
///
/// # Example
///
/// ```rhai
/// let f = Fn("foo"); // function pointer to 'foo'
///
/// f.call(42); // call: foo(42)
/// ```
fn Fn(fn_name: String) -> FnPtr;
/// Call a function pointed to by a function pointer,
/// passing following arguments to the function call.
///
/// If an appropriate function is not found, an error is raised.
///
/// # Example
///
/// ```rhai
/// let f = Fn("foo"); // function pointer to 'foo'
///
/// f.call(1, 2, 3); // call: foo(1, 2, 3)
/// ```
fn call(fn_ptr: FnPtr, ...args: ?) -> ?;
/// Call a function pointed to by a function pointer, binding the `this` pointer
/// to the object of the method call, and passing on following arguments to the function call.
///
/// If an appropriate function is not found, an error is raised.
///
/// # Example
///
/// ```rhai
/// fn add(x) {
/// this + x
/// }
///
/// let f = Fn("add"); // function pointer to 'add'
///
/// let x = 41;
///
/// let r = x.call(f, 1); // call: add(1) with 'this' = 'x'
///
/// print(r); // prints 42
/// ```
fn call(obj: ?, fn_ptr: FnPtr, ...args: ?) -> ?;
/// Curry a number of arguments into a function pointer and return it as a new function pointer.
///
/// # Example
///
/// ```rhai
/// fn foo(x, y, z) {
/// x + y + z
/// }
///
/// let f = Fn("foo");
///
/// let g = f.curry(1, 2); // curried arguments: 1, 2
///
/// g.call(3); // call: foo(1, 2, 3)
/// ```
fn curry(fn_ptr: FnPtr, ...args: ?) -> FnPtr;
/// Return `true` if a script-defined function exists with a specified name and
/// number of parameters.
///
/// # Example
///
/// ```rhai
/// fn foo(x) { }
///
/// print(is_def_fn("foo", 1)); // prints true
/// print(is_def_fn("foo", 2)); // prints false
/// print(is_def_fn("foo", 0)); // prints false
/// print(is_def_fn("bar", 1)); // prints false
/// ```
fn is_def_fn(fn_name: String, num_params: i64) -> bool;
/// Return `true` if a variable matching a specified name is defined.
///
/// # Example
///
/// ```rhai
/// let x = 42;
///
/// print(is_def_var("x")); // prints true
/// print(is_def_var("foo")); // prints false
///
/// {
/// let y = 1;
/// print(is_def_var("y")); // prints true
/// }
///
/// print(is_def_var("y")); // prints false
/// ```
fn is_def_var(var_name: String) -> bool;
/// Return `true` if the variable is shared.
///
/// # Example
///
/// ```rhai
/// let x = 42;
///
/// print(is_shared(x)); // prints false
///
/// let f = || x; // capture 'x', making it shared
///
/// print(is_shared(x)); // prints true
/// ```
fn is_shared(variable: ?) -> bool;
/// Evaluate a text script within the current scope.
///
/// # Example
///
/// ```rhai
/// let x = 42;
///
/// eval("let y = x; x = 123;");
///
/// print(x); // prints 123
/// print(y); // prints 42
/// ```
fn eval(script: String) -> ?;
fn contains(string: String, find: String) -> bool;
fn contains(range: Range<i64>, value: i64) -> bool;
fn contains(range: RangeInclusive<i64>, value: i64) -> bool;
fn contains(map: Map, string: String) -> bool;
fn contains(blob: Blob, value: i64) -> bool;
fn contains(string: String, ch: char) -> bool;

3
examples/definitions/.rhai/definitions/__scope__.d.rhai Normal file
View File

@ -0,0 +1,3 @@
module static;
let hello_there;

5731
examples/definitions/.rhai/definitions/__static__.d.rhai Normal file
View File

File diff suppressed because it is too large Load Diff

5
examples/definitions/.rhai/definitions/general_kenobi.d.rhai Normal file
View File

@ -0,0 +1,5 @@
module general_kenobi;
/// Returns a string where `hello there `
/// is repeated `n` times.
fn hello_there(n: i64) -> String;

44
examples/definitions/main.rs Normal file
View File

@ -0,0 +1,44 @@
use rhai::{plugin::*, Engine, Scope};
#[export_module]
pub mod general_kenobi {
/// Returns a string where `hello there `
/// is repeated `n` times.
pub fn hello_there(n: i64) -> String {
use std::convert::TryInto;
"hello there ".repeat(n.try_into().unwrap())
}
}
fn main() {
let mut engine = Engine::new();
let mut scope = Scope::new();
// This variable will also show up in the definitions,
// since it will be part of the scope.
scope.push("hello_there", "hello there");
#[cfg(not(feature = "no_module"))]
engine.register_static_module("general_kenobi", exported_module!(general_kenobi).into());
// Custom operators also show up in definitions.
#[cfg(not(feature = "no_custom_syntax"))]
{
engine.register_custom_operator("minus", 100).unwrap();
engine.register_fn("minus", |a: i64, b: i64| a - b);
}
engine
.eval_with_scope::<()>(
&mut scope,
r#"
hello_there = general_kenobi::hello_there(4 minus 2);
"#,
)
.unwrap();
engine
.definitions_with_scope(&scope)
.write_to_dir("examples/definitions/.rhai/definitions")
.unwrap();
}

3
examples/definitions/script.rhai Normal file
View File

@ -0,0 +1,3 @@
// The following will be valid based on the definitions.
hello_there = general_kenobi::hello_there(123);
print(hello_there);

251
src/api/definitions/builtin-operators.d.rhai Normal file
View File

@ -0,0 +1,251 @@
module static;
op ==(i64, i64) -> bool;
op !=(i64, i64) -> bool;
op >(i64, i64) -> bool;
op >=(i64, i64) -> bool;
op <(i64, i64) -> bool;
op <=(i64, i64) -> bool;
op &(i64, i64) -> i64;
op |(i64, i64) -> i64;
op ^(i64, i64) -> i64;
op ..(i64, i64) -> Range<i64>;
op ..=(i64, i64) -> RangeInclusive<i64>;
op ==(bool, bool) -> bool;
op !=(bool, bool) -> bool;
op >(bool, bool) -> bool;
op >=(bool, bool) -> bool;
op <(bool, bool) -> bool;
op <=(bool, bool) -> bool;
op &(bool, bool) -> bool;
op |(bool, bool) -> bool;
op ^(bool, bool) -> bool;
op ==((), ()) -> bool;
op !=((), ()) -> bool;
op >((), ()) -> bool;
op >=((), ()) -> bool;
op <((), ()) -> bool;
op <=((), ()) -> bool;
op +(i64, i64) -> i64;
op -(i64, i64) -> i64;
op *(i64, i64) -> i64;
op /(i64, i64) -> i64;
op %(i64, i64) -> i64;
op **(i64, i64) -> i64;
op >>(i64, i64) -> i64;
op <<(i64, i64) -> i64;
op +(f64, f64) -> f64;
op -(f64, f64) -> f64;
op *(f64, f64) -> f64;
op /(f64, f64) -> f64;
op %(f64, f64) -> f64;
op **(f64, f64) -> f64;
op ==(f64, f64) -> bool;
op !=(f64, f64) -> bool;
op >(f64, f64) -> bool;
op >=(f64, f64) -> bool;
op <(f64, f64) -> bool;
op <=(f64, f64) -> bool;
op +(f64, i64) -> f64;
op -(f64, i64) -> f64;
op *(f64, i64) -> f64;
op /(f64, i64) -> f64;
op %(f64, i64) -> f64;
op **(f64, i64) -> f64;
op ==(f64, i64) -> bool;
op !=(f64, i64) -> bool;
op >(f64, i64) -> bool;
op >=(f64, i64) -> bool;
op <(f64, i64) -> bool;
op <=(f64, i64) -> bool;
op +(i64, f64) -> f64;
op -(i64, f64) -> f64;
op *(i64, f64) -> f64;
op /(i64, f64) -> f64;
op %(i64, f64) -> f64;
op **(i64, f64) -> f64;
op ==(i64, f64) -> bool;
op !=(i64, f64) -> bool;
op >(i64, f64) -> bool;
op >=(i64, f64) -> bool;
op <(i64, f64) -> bool;
op <=(i64, f64) -> bool;
op +(Decimal, Decimal) -> Decimal;
op -(Decimal, Decimal) -> Decimal;
op *(Decimal, Decimal) -> Decimal;
op /(Decimal, Decimal) -> Decimal;
op %(Decimal, Decimal) -> Decimal;
op **(Decimal, Decimal) -> Decimal;
op ==(Decimal, Decimal) -> bool;
op !=(Decimal, Decimal) -> bool;
op >(Decimal, Decimal) -> bool;
op >=(Decimal, Decimal) -> bool;
op <(Decimal, Decimal) -> bool;
op <=(Decimal, Decimal) -> bool;
op +(Decimal, i64) -> Decimal;
op -(Decimal, i64) -> Decimal;
op *(Decimal, i64) -> Decimal;
op /(Decimal, i64) -> Decimal;
op %(Decimal, i64) -> Decimal;
op **(Decimal, i64) -> Decimal;
op ==(Decimal, i64) -> bool;
op !=(Decimal, i64) -> bool;
op >(Decimal, i64) -> bool;
op >=(Decimal, i64) -> bool;
op <(Decimal, i64) -> bool;
op <=(Decimal, i64) -> bool;
op +(i64, Decimal) -> Decimal;
op -(i64, Decimal) -> Decimal;
op *(i64, Decimal) -> Decimal;
op /(i64, Decimal) -> Decimal;
op %(i64, Decimal) -> Decimal;
op **(i64, Decimal) -> Decimal;
op ==(i64, Decimal) -> bool;
op !=(i64, Decimal) -> bool;
op >(i64, Decimal) -> bool;
op >=(i64, Decimal) -> bool;
op <(i64, Decimal) -> bool;
op <=(i64, Decimal) -> bool;
op +(String, String) -> String;
op -(String, String) -> String;
op ==(String, String) -> bool;
op !=(String, String) -> bool;
op >(String, String) -> bool;
op >=(String, String) -> bool;
op <(String, String) -> bool;
op <=(String, String) -> bool;
op +(char, char) -> String;
op ==(char, char) -> bool;
op !=(char, char) -> bool;
op >(char, char) -> bool;
op >=(char, char) -> bool;
op <(char, char) -> bool;
op <=(char, char) -> bool;
op +(char, String) -> String;
op ==(char, String) -> bool;
op !=(char, String) -> bool;
op >(char, String) -> bool;
op >=(char, String) -> bool;
op <(char, String) -> bool;
op <=(char, String) -> bool;
op +(String, char) -> String;
op -(String, char) -> String;
op ==(String, char) -> bool;
op !=(String, char) -> bool;
op >(String, char) -> bool;
op >=(String, char) -> bool;
op <(String, char) -> bool;
op <=(String, char) -> bool;
op +((), String) -> String;
op ==((), String) -> bool;
op !=((), String) -> bool;
op >((), String) -> bool;
op >=((), String) -> bool;
op <((), String) -> bool;
op <=((), String) -> bool;
op +(String, ()) -> String;
op ==(String, ()) -> bool;
op !=(String, ()) -> bool;
op >(String, ()) -> bool;
op >=(String, ()) -> bool;
op <(String, ()) -> bool;
op <=(String, ()) -> bool;
op +(Blob, Blob) -> Blob;
op +(Blob, char) -> Blob;
op ==(Blob, Blob) -> bool;
op !=(Blob, Blob) -> bool;
op ==(Range<i64>, RangeInclusive<i64>) -> bool;
op !=(Range<i64>, RangeInclusive<i64>) -> bool;
op ==(RangeInclusive<i64>, Range<i64>) -> bool;
op !=(RangeInclusive<i64>, Range<i64>) -> bool;
op ==(Range<i64>, Range<i64>) -> bool;
op !=(Range<i64>, Range<i64>) -> bool;
op ==(RangeInclusive<i64>, RangeInclusive<i64>) -> bool;
op !=(RangeInclusive<i64>, RangeInclusive<i64>) -> bool;
op ==(?, ?) -> bool;
op !=(?, ?) -> bool;
op >(?, ?) -> bool;
op >=(?, ?) -> bool;
op <(?, ?) -> bool;
op <=(?, ?) -> bool;
op &=(bool, bool);
op |=(bool, bool);
op +=(i64, i64);
op -=(i64, i64);
op *=(i64, i64);
op /=(i64, i64);
op %=(i64, i64);
op **=(i64, i64);
op >>=(i64, i64);
op <<=(i64, i64);
op &=(i64, i64);
op |=(i64, i64);
op ^=(i64, i64);
op +=(f64, f64);
op -=(f64, f64);
op *=(f64, f64);
op /=(f64, f64);
op %=(f64, f64);
op **=(f64, f64);
op +=(f64, i64);
op -=(f64, i64);
op *=(f64, i64);
op /=(f64, i64);
op %=(f64, i64);
op **=(f64, i64);
op +=(Decimal, Decimal);
op -=(Decimal, Decimal);
op *=(Decimal, Decimal);
op /=(Decimal, Decimal);
op %=(Decimal, Decimal);
op **=(Decimal, Decimal);
op +=(Decimal, i64);
op -=(Decimal, i64);
op *=(Decimal, i64);
op /=(Decimal, i64);
op %=(Decimal, i64);
op **=(Decimal, i64);
op +=(String, String);
op -=(String, String);
op +=(String, char);
op -=(String, char);
op +=(char, String);
op +=(char, char);
op +=(Array, Array);
op +=(Array, ?);
op +=(Blob, Blob);
op +=(Blob, i64);
op +=(Blob, char);
op +=(Blob, String);

170
src/api/definitions/builtin.d.rhai Normal file
View File

@ -0,0 +1,170 @@
module static;
/// Display any data to the standard output.
///
/// # Example
///
/// ```rhai
/// let answer = 42;
///
/// print(`The Answer is ${answer}`);
/// ```
fn print(data: ?);
/// Display any data to the standard output in debug format.
///
/// # Example
///
/// ```rhai
/// let answer = 42;
///
/// debug(answer);
/// ```
fn debug(data: ?);
/// Get the type of a value.
///
/// # Example
///
/// ```rhai
/// let x = "hello, world!";
///
/// print(x.type_of()); // prints "string"
/// ```
fn type_of(data: ?) -> String;
/// Create a function pointer to a named function.
///
/// If the specified name is not a valid function name, an error is raised.
///
/// # Example
///
/// ```rhai
/// let f = Fn("foo"); // function pointer to 'foo'
///
/// f.call(42); // call: foo(42)
/// ```
fn Fn(fn_name: String) -> FnPtr;
/// Call a function pointed to by a function pointer,
/// passing following arguments to the function call.
///
/// If an appropriate function is not found, an error is raised.
///
/// # Example
///
/// ```rhai
/// let f = Fn("foo"); // function pointer to 'foo'
///
/// f.call(1, 2, 3); // call: foo(1, 2, 3)
/// ```
fn call(fn_ptr: FnPtr, ...args: ?) -> ?;
/// Call a function pointed to by a function pointer, binding the `this` pointer
/// to the object of the method call, and passing on following arguments to the function call.
///
/// If an appropriate function is not found, an error is raised.
///
/// # Example
///
/// ```rhai
/// fn add(x) {
/// this + x
/// }
///
/// let f = Fn("add"); // function pointer to 'add'
///
/// let x = 41;
///
/// let r = x.call(f, 1); // call: add(1) with 'this' = 'x'
///
/// print(r); // prints 42
/// ```
fn call(obj: ?, fn_ptr: FnPtr, ...args: ?) -> ?;
/// Curry a number of arguments into a function pointer and return it as a new function pointer.
///
/// # Example
///
/// ```rhai
/// fn foo(x, y, z) {
/// x + y + z
/// }
///
/// let f = Fn("foo");
///
/// let g = f.curry(1, 2); // curried arguments: 1, 2
///
/// g.call(3); // call: foo(1, 2, 3)
/// ```
fn curry(fn_ptr: FnPtr, ...args: ?) -> FnPtr;
/// Return `true` if a script-defined function exists with a specified name and
/// number of parameters.
///
/// # Example
///
/// ```rhai
/// fn foo(x) { }
///
/// print(is_def_fn("foo", 1)); // prints true
/// print(is_def_fn("foo", 2)); // prints false
/// print(is_def_fn("foo", 0)); // prints false
/// print(is_def_fn("bar", 1)); // prints false
/// ```
fn is_def_fn(fn_name: String, num_params: i64) -> bool;
/// Return `true` if a variable matching a specified name is defined.
///
/// # Example
///
/// ```rhai
/// let x = 42;
///
/// print(is_def_var("x")); // prints true
/// print(is_def_var("foo")); // prints false
///
/// {
/// let y = 1;
/// print(is_def_var("y")); // prints true
/// }
///
/// print(is_def_var("y")); // prints false
/// ```
fn is_def_var(var_name: String) -> bool;
/// Return `true` if the variable is shared.
///
/// # Example
///
/// ```rhai
/// let x = 42;
///
/// print(is_shared(x)); // prints false
///
/// let f = || x; // capture 'x', making it shared
///
/// print(is_shared(x)); // prints true
/// ```
fn is_shared(variable: ?) -> bool;
/// Evaluate a text script within the current scope.
///
/// # Example
///
/// ```rhai
/// let x = 42;
///
/// eval("let y = x; x = 123;");
///
/// print(x); // prints 123
/// print(y); // prints 42
/// ```
fn eval(script: String) -> ?;
fn contains(string: String, find: String) -> bool;
fn contains(range: Range<i64>, value: i64) -> bool;
fn contains(range: RangeInclusive<i64>, value: i64) -> bool;
fn contains(map: Map, string: String) -> bool;
fn contains(blob: Blob, value: i64) -> bool;
fn contains(string: String, ch: char) -> bool;

371
src/api/definitions/mod.rs Normal file
View File

@ -0,0 +1,371 @@
use crate::{
module::FuncInfo, plugin::*, tokenizer::is_valid_function_name, Engine, Module, Scope,
};
use core::{cmp::Ordering, fmt, iter};
#[cfg(feature = "no_std")]
use std::prelude::v1::*;
#[cfg(feature = "no_std")]
use alloc::borrow::Cow;
#[cfg(not(feature = "no_std"))]
use std::borrow::Cow;
impl Engine {
/// Return [`Definitions`] that can be used to
/// generate definition files that contain all
/// the visible items in the engine.
///
/// # Example
///
/// ```no_run
/// # use rhai::Engine;
/// # fn main() -> std::io::Result<()> {
/// let engine = Engine::new();
/// engine
/// .definitions()
/// .write_to_dir(".rhai/definitions")?;
/// # Ok(())
/// # }
/// ```
pub fn definitions(&self) -> Definitions {
Definitions {
engine: self,
scope: None,
}
}
/// Return [`Definitions`] that can be used to
/// generate definition files that contain all
/// the visible items in the engine and the
/// given scope.
///
/// # Example
///
/// ```no_run
/// # use rhai::{Engine, Scope};
/// # fn main() -> std::io::Result<()> {
/// let engine = Engine::new();
/// let scope = Scope::new();
/// engine
/// .definitions_with_scope(&scope)
/// .write_to_dir(".rhai/definitions")?;
/// # Ok(())
/// # }
/// ```
pub fn definitions_with_scope<'e>(&'e self, scope: &'e Scope<'e>) -> Definitions<'e> {
Definitions {
engine: self,
scope: Some(scope),
}
}
}
/// Definitions helper that is used to generate
/// definition files based on the contents of an [`Engine`].
#[must_use]
pub struct Definitions<'e> {
engine: &'e Engine,
scope: Option<&'e Scope<'e>>,
}
impl<'e> Definitions<'e> {
/// Write all the definition files returned from [`iter_files`] to a directory.
///
/// This function will create the directory path if it does not yet exist,
/// it will also override any existing files as needed.
#[cfg(all(not(feature = "no_std"), not(target_family = "wasm")))]
pub fn write_to_dir(&self, path: impl AsRef<std::path::Path>) -> std::io::Result<()> {
use std::fs;
let path = path.as_ref();
fs::create_dir_all(path)?;
fs::write(
path.join("__builtin__.d.rhai"),
include_bytes!("builtin.d.rhai"),
)?;
fs::write(
path.join("__builtin-operators__.d.rhai"),
include_bytes!("builtin-operators.d.rhai"),
)?;
fs::write(path.join("__static__.d.rhai"), self.static_module())?;
if self.scope.is_some() {
fs::write(path.join("__scope__.d.rhai"), self.scope())?;
}
for (name, decl) in self.modules() {
fs::write(path.join(format!("{name}.d.rhai")), decl)?;
}
Ok(())
}
/// Iterate over the generated definition files.
///
/// The returned iterator yields all the definition files as (filename, content) pairs.
pub fn iter_files(&self) -> impl Iterator<Item = (String, String)> + '_ {
IntoIterator::into_iter([
(
"__builtin__.d.rhai".to_string(),
include_str!("builtin.d.rhai").to_string(),
),
(
"__builtin-operators__.d.rhai".to_string(),
include_str!("builtin-operators.d.rhai").to_string(),
),
("__static__.d.rhai".to_string(), self.static_module()),
])
.chain(iter::from_fn(move || {
if self.scope.is_some() {
Some(("__scope__.d.rhai".to_string(), self.scope()))
} else {
None
}
}))
.chain(
self.modules()
.map(|(name, def)| (format!("{name}.d.rhai"), def)),
)
}
/// Return the definitions for the globally available
/// items of the engine.
///
/// The definitions will always start with `module static;`.
#[must_use]
pub fn static_module(&self) -> String {
let mut s = String::from("module static;\n\n");
let mut first = true;
for m in &self.engine.global_modules {
if !first {
s += "\n\n";
}
first = false;
m.write_definition(&mut s, self).unwrap();
}
s
}
/// Return the definitions for the available
/// items of the scope.
///
/// The definitions will always start with `module static;`,
/// even if the scope is empty or none was provided.
#[must_use]
pub fn scope(&self) -> String {
let mut s = String::from("module static;\n\n");
if let Some(scope) = self.scope {
scope.write_definition(&mut s).unwrap();
}
s
}
/// Return module name and definition pairs for each registered module.
///
/// The definitions will always start with `module <module name>;`.
///
/// If the feature `no_module` is enabled, this will yield no elements.
pub fn modules(&self) -> impl Iterator<Item = (String, String)> + '_ {
#[cfg(not(feature = "no_module"))]
let m = {
let mut m = self
.engine
.global_sub_modules
.iter()
.map(move |(name, module)| {
(
name.to_string(),
format!("module {name};\n\n{}", module.definition(self)),
)
})
.collect::<Vec<_>>();
m.sort_by(|(name1, _), (name2, _)| name1.cmp(name2));
m
};
#[cfg(feature = "no_module")]
let m = Vec::new();
m.into_iter()
}
}
impl Module {
fn definition(&self, def: &Definitions) -> String {
let mut s = String::new();
self.write_definition(&mut s, def).unwrap();
s
}
fn write_definition(&self, writer: &mut dyn fmt::Write, def: &Definitions) -> fmt::Result {
let mut first = true;
let mut vars = self.iter_var().collect::<Vec<_>>();
vars.sort_by(|(a, _), (b, _)| a.cmp(b));
for (name, _) in vars {
if !first {
writer.write_str("\n\n")?;
}
first = false;
write!(writer, "const {name}: ?;")?;
}
let mut func_infos = self.iter_fn().collect::<Vec<_>>();
func_infos.sort_by(|a, b| match a.metadata.name.cmp(&b.metadata.name) {
Ordering::Equal => match a.metadata.params.cmp(&b.metadata.params) {
Ordering::Equal => (a.metadata.params_info.join("")
+ a.metadata.return_type.as_str())
.cmp(&(b.metadata.params_info.join("") + b.metadata.return_type.as_str())),
o => o,
},
o => o,
});
for f in func_infos {
if !first {
writer.write_str("\n\n")?;
}
first = false;
if f.metadata.access == FnAccess::Private {
continue;
}
#[cfg(not(feature = "no_custom_syntax"))]
let operator = def.engine.custom_keywords.contains_key(&f.metadata.name)
|| (!f.metadata.name.contains('$') && !is_valid_function_name(&f.metadata.name));
#[cfg(feature = "no_custom_syntax")]
let operator =
!f.metadata.name.contains('$') && !is_valid_function_name(&f.metadata.name);
f.write_definition(writer, def, operator)?;
}
Ok(())
}
}
impl FuncInfo {
fn write_definition(
&self,
writer: &mut dyn fmt::Write,
def: &Definitions,
operator: bool,
) -> fmt::Result {
for comment in &*self.metadata.comments {
writeln!(writer, "{comment}")?;
}
if operator {
writer.write_str("op ")?;
} else {
writer.write_str("fn ")?;
}
if let Some(name) = self.metadata.name.strip_prefix("get$") {
write!(writer, "get {name}(")?;
} else if let Some(name) = self.metadata.name.strip_prefix("set$") {
write!(writer, "set {name}(")?;
} else {
write!(writer, "{}(", self.metadata.name)?;
}
let mut first = true;
for i in 0..self.metadata.params {
if !first {
writer.write_str(", ")?;
}
first = false;
let (param_name, param_type) = self
.metadata
.params_info
.get(i)
.map(|s| {
let mut s = s.splitn(2, ':');
(
s.next().unwrap_or("_").split(' ').last().unwrap(),
s.next()
.map(|ty| def_type_name(ty, def.engine))
.unwrap_or(Cow::Borrowed("?")),
)
})
.unwrap_or(("_", "?".into()));
if operator {
write!(writer, "{param_type}")?;
} else {
write!(writer, "{param_name}: {param_type}")?;
}
}
write!(
writer,
") -> {};",
def_type_name(&self.metadata.return_type, def.engine)
)?;
Ok(())
}
}
/// We have to transform some of the types.
///
/// This is highly inefficient and is currently based on
/// trial and error with the core packages.
///
/// It tries to flatten types, removing `&` and `&mut`,
/// and paths, while keeping generics.
///
/// Associated generic types are also rewritten into regular
/// generic type parameters.
fn def_type_name<'a>(ty: &'a str, engine: &'a Engine) -> Cow<'a, str> {
let ty = engine.format_type_name(ty).replace("crate::", "");
let ty = ty.strip_prefix("&mut").unwrap_or(&*ty).trim();
let ty = ty.split("::").last().unwrap();
let ty = ty
.strip_prefix("RhaiResultOf<")
.and_then(|s| s.strip_suffix('>'))
.map(str::trim)
.unwrap_or(ty);
ty.replace("Iterator<Item=", "Iterator<")
.replace("Dynamic", "?")
.replace("INT", "int")
.replace("FLOAT", "float")
.replace("&str", "String")
.replace("ImmutableString", "String")
.into()
}
impl Scope<'_> {
fn write_definition(&self, writer: &mut dyn fmt::Write) -> fmt::Result {
let mut first = true;
for (name, constant, _) in self.iter_raw() {
if !first {
writer.write_str("\n\n")?;
}
first = false;
let kw = if constant { "const" } else { "let" };
write!(writer, "{kw} {name};")?;
}
Ok(())
}
}

3
src/api/mod.rs
View File

@ -28,6 +28,9 @@ pub mod custom_syntax;
pub mod deprecated;
#[cfg(feature = "metadata")]
pub mod definitions;
use crate::{Dynamic, Engine, Identifier};
#[cfg(not(feature = "no_custom_syntax"))]

3
src/lib.rs
View File

@ -181,6 +181,9 @@ pub use types::{
#[cfg(not(feature = "no_custom_syntax"))]
pub use api::custom_syntax::Expression;
#[cfg(feature = "metadata")]
pub use api::definitions::Definitions;
/// _(debugging)_ Module containing types for debugging.
/// Exported under the `debugging` feature only.
#[cfg(feature = "debugging")]