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

feat: basic definitions

Browse Source
This commit is contained in:
tamasfe 2022-07-25 19:01:06 +02:00
parent 602efc7042
commit b7b9ff29e4
No known key found for this signature in database
GPG Key ID: 2373047D27CA4E47
9 changed files with 6109 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Cargo.toml
View File

@ -82,6 +82,10 @@ name = "rhai-run"
name = "rhai-dbg"
required-features = ["debugging"]
[[example]]
name = "definitions"
required-features = ["metadata"]
[profile.release]
lto = "fat"
codegen-units = 1

23
examples/README.md
View File

@ -4,17 +4,18 @@ Sample Applications
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 |
| [`hello`](hello.rs) | simple example that evaluates an expression and prints the result |
| [`reuse_scope`](reuse_scope.rs) | evaluates two pieces of code in separate runs, but using a common `Scope` |
| [`serde`](serde.rs) | example to serialize and deserialize Rust types with [`serde`](https://crates.io/crates/serde) (requires the `serde` feature) |
| [`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 |
| 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 |
| [`hello`](hello.rs) | simple example that evaluates an expression and prints the result |
| [`reuse_scope`](reuse_scope.rs) | evaluates two pieces of code in separate runs, but using a common `Scope` |
| [`serde`](serde.rs) | example to serialize and deserialize Rust types with [`serde`](https://crates.io/crates/serde) (requires the `serde` feature) |
| [`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

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;

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

@ -0,0 +1,40 @@
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");
engine.register_static_module("general_kenobi", exported_module!(general_kenobi).into());
// Custom operators also show up in definitions.
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);

306
src/definitions.rs Normal file
View File

@ -0,0 +1,306 @@
use crate::{
module::FuncInfo, plugin::*, tokenizer::is_valid_function_name, Engine, Module, Scope,
};
use core::fmt;
use std::{borrow::Cow, fs, io, path::Path};
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() -> 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() -> 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 to a directory.
///
/// The following separate definition files are generated:
///
/// - `__static__.d.rhai`: globally available items of the engine
/// - `__scope__.d.rhai`: items in the given scope, if any
/// - a separate file for each registered module
pub fn write_to_dir(&self, path: impl AsRef<Path>) -> io::Result<()> {
let path = path.as_ref();
fs::create_dir_all(path)?;
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(())
}
/// 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_declaration(&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_declaration(&mut s).unwrap();
}
s
}
/// Return name and definition pairs for each registered module.
///
/// The definitions will always start with `module <module name>;`.
#[cfg(not(feature = "no_module"))]
pub fn modules(&self) -> impl Iterator<Item = (String, String)> + '_ {
let mut m = self
.engine
.global_sub_modules
.iter()
.map(move |(name, module)| {
(
name.to_string(),
format!("module {name};\n\n{}", module.declaration(self)),
)
})
.collect::<Vec<_>>();
m.sort_by(|(name1, _), (name2, _)| name1.cmp(name2));
m.into_iter()
}
}
impl Module {
fn declaration(&self, decl: &Definitions) -> String {
let mut s = String::new();
self.write_declaration(&mut s, decl).unwrap();
s
}
fn write_declaration(&self, writer: &mut dyn fmt::Write, decl: &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| a.metadata.name.cmp(&b.metadata.name));
for f in func_infos {
if !first {
writer.write_str("\n\n")?;
}
first = false;
if f.metadata.access == FnAccess::Private {
continue;
}
f.write_declaration(
writer,
decl.engine.custom_keywords.contains_key(&f.metadata.name)
|| (!f.metadata.name.contains('$')
&& !is_valid_function_name(&f.metadata.name)),
)?;
}
Ok(())
}
}
impl FuncInfo {
fn write_declaration(&self, writer: &mut dyn fmt::Write, 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.split(':');
(
s.next().unwrap_or("_").split(' ').last().unwrap(),
s.next().map(decl_type_name).unwrap_or(Cow::Borrowed("?")),
)
})
.unwrap_or(("_", "?".into()));
if operator {
write!(writer, "{param_type}")?;
} else {
write!(writer, "{param_name}: {param_type}")?;
}
}
write!(
writer,
") -> {};",
decl_type_name(&self.metadata.return_type)
)?;
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 decl_type_name(ty: &str) -> Cow<str> {
let ty = ty.replace("crate::", "");
let ty = ty.split("::").last().unwrap();
let ty = ty.trim();
let ty = ty.strip_prefix("&mut").unwrap_or(ty).trim();
let ty = ty
.strip_prefix("RhaiResultOf<")
.and_then(|s| s.strip_suffix('>'))
.map(str::trim)
.unwrap_or(ty);
// FIXME(tamasfe): some of the given types are unusable,
// e.g. "Range<crate" is the entire type this function receives,
// same with "crate", I have no idea where these come from.
ty.replace("Range<crate", "?")
.replace("crate", "?")
.replace("Iterator<Item=", "Iterator<")
.replace("Dynamic", "?")
.replace("INT", "int")
.replace("FLOAT", "float")
.replace("&str", "String")
.replace("ImmutableString", "String")
.into()
}
impl Scope<'_> {
fn write_declaration(&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(())
}
}

5
src/lib.rs
View File

@ -82,6 +82,8 @@ mod reify;
mod tests;
mod tokenizer;
mod types;
#[cfg(feature = "metadata")]
mod definitions;
/// Error encountered when parsing a script.
type PERR = ParseErrorType;
@ -258,6 +260,9 @@ pub mod serde;
#[cfg(not(feature = "no_optimize"))]
pub use optimizer::OptimizationLevel;
#[cfg(feature = "metadata")]
pub use definitions::Definitions;
/// Placeholder for the optimization level.
#[cfg(feature = "no_optimize")]
pub type OptimizationLevel = ();