#![warn(missing_docs)]
mod asyncs;
mod chunk;
mod context;
mod convert;
mod debug;
mod environment;
mod hints;
mod modules;
mod native;
#[cfg(feature = "tooling")]
mod outline;
#[cfg(feature = "serde")]
pub mod serde;
mod tasks;
mod userdata;
mod value;
use std::fmt;
use std::marker::PhantomData;
use std::rc::Rc;
use rhue_bytecode::Proto;
use std::sync::Arc;
pub use asyncs::InterruptHandle;
pub use chunk::Chunk;
pub use context::{Context, ScriptError};
pub use convert::{
ArgError, Args, ConversionError, FromArg, FromValue, FromValues, IntoValue, IntoValues,
Variadic,
};
pub use debug::{DebugEvent, Debugger, HookMask, StackFrame};
pub use environment::Environment;
#[cfg(feature = "tooling")]
pub use hints::{HintKind, InlayHint};
#[cfg(feature = "tooling")]
pub use modules::Analysis;
pub use modules::Reloaded;
pub use native::{IntoAsyncNative, IntoNative, IntoNativeResult, WithContext};
#[cfg(feature = "tooling")]
pub use outline::{
Base, Exports, FieldUse, Outline, SemanticToken, Symbol, SymbolKind, TokenKind, outline,
};
pub use rhue_bytecode::is_chunk;
pub use rhue_common::{Diagnostic, Severity, SourceFile, Span};
pub use rhue_compiler::CompileOptions;
pub use rhue_derive::UserData;
pub use rhue_parser::ast::TypeMode;
pub use tasks::{Task, TaskState};
pub use userdata::{IntoMethod, TypeBuilder, Ud, UserData};
pub use value::{AnyUserData, Buffer, Function, Table, Thread, Value};
pub use rhue_vm::HeapStats;
pub fn module_paths(dir: &std::path::Path, name: &str) -> [std::path::PathBuf; 2] {
let rel: std::path::PathBuf = name.split('.').collect();
[
dir.join(rel.with_extension("rhue")),
dir.join(rel.join("init.rhue")),
]
}
pub fn is_module_name(name: &str) -> bool {
name.split('.')
.all(|part| !part.is_empty() && !part.contains(['/', '\\', ':', '\0']))
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ErrorKind {
Syntax,
Compile,
Type,
Runtime,
Load,
}
#[derive(Clone, Debug)]
pub struct Error {
pub kind: ErrorKind,
pub diagnostics: Vec<Diagnostic>,
source_name: Arc<str>,
source: Arc<str>,
}
impl Error {
fn new(kind: ErrorKind, diagnostics: Vec<Diagnostic>, source: &SourceFile) -> Self {
debug_assert!(!diagnostics.is_empty());
Error {
kind,
diagnostics,
source_name: Arc::from(&*source.name),
source: Arc::from(&*source.text),
}
}
fn location(&self) -> String {
let start = self.diagnostic().primary.span.start as usize;
let line = self.source[..start.min(self.source.len())]
.bytes()
.filter(|&b| b == b'\n')
.count()
+ 1;
format!("{}:{line}", self.source_name)
}
fn from_runtime(e: &rhue_vm::RuntimeError) -> Self {
Error::new(ErrorKind::Runtime, vec![e.to_diagnostic()], &e.source)
}
pub fn is_interrupted(&self) -> bool {
self.kind == ErrorKind::Runtime
&& self
.diagnostics
.first()
.is_some_and(|d| d.message == rhue_vm::INTERRUPTED)
}
fn from_script(e: ScriptError) -> Self {
match e.0 {
context::Repr::Thrown(r) => Error::from_runtime(r.error()),
_ => Error::new(
ErrorKind::Runtime,
vec![Diagnostic::error(e.message(), Span::default())],
&SourceFile::new("[host]", ""),
),
}
}
pub fn diagnostic(&self) -> &Diagnostic {
&self.diagnostics[0]
}
pub fn source_name(&self) -> &str {
&self.source_name
}
pub fn render(&self, color: bool) -> String {
if self.kind == ErrorKind::Load {
return format!("error: {}\n", self.diagnostic().message);
}
self.diagnostics
.iter()
.map(|d| d.render(&self.source_name, &self.source, color))
.collect()
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.diagnostic().message)
}
}
impl std::error::Error for Error {}
pub struct Engine {
vm: rhue_vm::Vm,
tasks: Option<std::rc::Rc<std::cell::RefCell<tasks::Scheduler>>>,
asyncs: std::rc::Rc<std::cell::RefCell<asyncs::AsyncState>>,
}
pub(crate) fn type_env(vm: &mut rhue_vm::Vm) -> &mut rhue_types::Env {
&mut modules::host(vm).env
}
impl Default for Engine {
fn default() -> Self {
Self::new()
}
}
impl Engine {
pub fn new() -> Self {
let mut vm = rhue_vm::Vm::new();
*vm.host_data() = Some(Box::new(modules::HostState::new(rhue_types::Env::new())));
let mut engine = Engine {
vm,
tasks: None,
asyncs: Default::default(),
};
engine.register("require", modules::require);
engine
}
pub fn bare() -> Self {
let mut vm = rhue_vm::Vm::bare();
*vm.host_data() = Some(Box::new(modules::HostState::new(rhue_types::Env::bare())));
Engine {
vm,
tasks: None,
asyncs: Default::default(),
}
}
pub fn set_default_type_mode(&mut self, mode: TypeMode) {
modules::host(&mut self.vm).default_mode = mode;
}
pub fn global_type(&mut self, name: &str) -> Option<String> {
type_env(&mut self.vm).global(name).map(|t| t.to_string())
}
pub fn declare(&mut self, name: &str, ty: &str) -> Result<(), Error> {
type_env(&mut self.vm)
.declare_global(name, ty)
.map_err(|d| Error::new(ErrorKind::Syntax, d, &SourceFile::new("<declaration>", ty)))
}
pub fn with_options(options: CompileOptions) -> Self {
let mut engine = Self::new();
*engine.options_mut() = options;
engine
}
pub fn options_mut(&mut self) -> &mut CompileOptions {
&mut modules::host(&mut self.vm).options
}
pub fn add_module(&mut self, name: &str, source: &str) {
let state = modules::host(&mut self.vm);
state.sources.insert(name.to_string(), source.to_string());
state.compiled.remove(name);
state.binary.remove(name);
}
pub fn reload_module(&mut self, name: &str, source: &str) -> Result<Reloaded, Error> {
modules::reload(&mut self.vm, name, source)
}
pub fn reload(&mut self, name: &str) -> Result<Reloaded, Error> {
let Some(source) = modules::current_source(&mut self.vm, name) else {
return Err(Error::from_script(ScriptError::new(format!(
"module '{name}' not found"
))));
};
modules::reload(&mut self.vm, name, &source)
}
pub fn loaded_modules(&mut self) -> Vec<String> {
modules::loaded_names(&mut self.vm)
}
pub fn set_module_loader(&mut self, loader: impl Fn(&str) -> Option<String> + 'static) {
modules::host(&mut self.vm).loader = Some(Rc::new(loader));
}
pub fn set_instruction_limit(&mut self, limit: Option<u64>) {
self.vm.set_instruction_limit(limit);
}
pub fn set_memory_limit(&mut self, limit: Option<usize>) {
self.vm.set_memory_limit(limit);
}
pub fn memory_used(&self) -> usize {
self.vm.memory_used()
}
pub fn set_debug_hook(
&mut self,
mask: HookMask,
mut hook: impl FnMut(&mut Debugger<'_, '_>, DebugEvent) -> Result<(), String> + 'static,
) {
self.vm.set_debug_hook(
mask,
Some(Box::new(move |ctx, event| {
hook(&mut Debugger { ctx }, event)
})),
);
}
pub fn clear_debug_hook(&mut self) {
self.vm.set_debug_hook(HookMask::default(), None);
}
pub fn gc(&mut self) {
self.vm.collect_garbage();
}
#[doc(hidden)]
pub fn set_gc_stress(&mut self, on: bool) {
self.vm.heap_mut().set_stress(on);
}
pub fn heap_stats(&self) -> HeapStats {
self.vm.heap_stats()
}
pub fn on_print(&mut self, output: impl FnMut(&str) + 'static) {
self.vm.set_output(output);
}
pub fn context(&mut self) -> Context<'_> {
Context::new(&mut self.vm)
}
pub fn set_global<V: IntoValue>(&mut self, name: &str, value: V) {
V::declare_types(&mut self.vm);
let ty = V::luau_type();
userdata::declare(type_env(&mut self.vm).declare_global(name, &ty), &ty);
self.context().set_global(name, value);
}
pub fn global(&mut self, name: &str) -> Value {
let v = self.vm.global(name);
self.context().lift(v)
}
pub fn get<T: FromValue>(&mut self, name: &str) -> Result<T, Error> {
self.context().global(name).map_err(Error::from_script)
}
pub fn register<M, F: IntoNative<M>>(&mut self, name: &str, f: F) {
F::declare_types(&mut self.vm);
let sig = F::signature();
userdata::declare(type_env(&mut self.vm).declare_global(name, &sig), &sig);
let native = f.into_native(Rc::from(name));
self.vm.register_native(name, native);
}
pub fn register_type<T: UserData>(&mut self) -> TypeBuilder<'_, T> {
let ty = userdata::type_id_of::<T>(&mut self.vm);
TypeBuilder {
vm: &mut self.vm,
ty,
_t: PhantomData,
}
}
pub fn call<R: FromValues>(
&mut self,
func: &Function,
args: impl IntoValues,
) -> Result<R, Error> {
self.context().call(func, args).map_err(Error::from_script)
}
pub fn call_value<R: FromValues>(
&mut self,
func: &Value,
args: impl IntoValues,
) -> Result<R, Error> {
self.context()
.call_value(func, args)
.map_err(Error::from_script)
}
pub fn call_global<R: FromValues>(
&mut self,
name: &str,
args: impl IntoValues,
) -> Result<R, Error> {
self.context()
.call_global(name, args)
.map_err(Error::from_script)
}
pub fn compile(&mut self, name: &str, source: &str) -> Result<Chunk, Error> {
let file = SourceFile::new(name, source);
let chunk = rhue_parser::parse_chunk(source)
.map_err(|d| Error::new(ErrorKind::Syntax, d, &file))?;
self.compile_ast(&chunk, &file)
}
pub fn compile_expr(&mut self, name: &str, source: &str) -> Result<Chunk, Error> {
let file = SourceFile::new(name, source);
let chunk =
rhue_parser::parse_expr(source).map_err(|d| Error::new(ErrorKind::Syntax, d, &file))?;
self.compile_ast(&chunk, &file)
}
fn compile_ast(
&mut self,
chunk: &rhue_parser::ast::Chunk,
file: &Rc<SourceFile>,
) -> Result<Chunk, Error> {
modules::compile_ast(&mut self.vm, chunk, file).map(|c| Chunk(c.proto))
}
#[cfg(feature = "tooling")]
pub fn analyze(&mut self, source: &str, members_at: Option<u32>) -> Analysis {
modules::analyze(&mut self.vm, source, members_at)
}
pub fn expression_type(&mut self, expr: &str) -> Result<String, Error> {
const PREFIX: &str = "--!strict\nlocal __type = (";
let source = format!("{PREFIX}{expr}\n)");
let file = SourceFile::new("<expression>", source.as_str());
let analysis = modules::analyze(&mut self.vm, &source, None);
if !analysis.diagnostics.is_empty() {
return Err(Error::new(ErrorKind::Type, analysis.diagnostics, &file));
}
let at = PREFIX.find("__type").expect("the local is in the prefix") as u32;
let name = Span::new(at, at + 6);
Ok(analysis
.types
.iter()
.rev()
.find(|(s, _)| *s == name)
.map_or_else(|| "any".to_string(), |(_, t)| t.clone()))
}
pub fn check(&mut self, name: &str, source: &str) -> Result<(), Error> {
let file = SourceFile::new(name, source);
let chunk = rhue_parser::parse_chunk(source)
.map_err(|d| Error::new(ErrorKind::Syntax, d, &file))?;
let res = rhue_compiler::resolve::resolve(&chunk)
.map_err(|d| Error::new(ErrorKind::Compile, d, &file))?;
let mode = chunk.mode.map_or(TypeMode::Strict, |(m, _)| m);
let checked = modules::check(&mut self.vm, &chunk, &res, mode);
if checked.errors.is_empty() {
Ok(())
} else {
Err(Error::new(ErrorKind::Type, checked.errors, &file))
}
}
pub fn load(&mut self, bytes: &[u8]) -> Result<Chunk, Error> {
let (proto, types) = self.read_chunk(bytes)?;
if let Some(types) = &types {
modules::declare_chunk_types(&mut self.vm, types);
}
Ok(Chunk(proto))
}
fn read_chunk(
&mut self,
bytes: &[u8],
) -> Result<(Rc<Proto>, Option<rhue_bytecode::ChunkTypes>), Error> {
let fail = |message: String, source: &Rc<SourceFile>| {
Error::new(
ErrorKind::Load,
vec![Diagnostic::error(message, Span::default())],
source,
)
};
let (proto, types) = rhue_bytecode::read_chunk(bytes)
.map_err(|e| fail(e.to_string(), &SourceFile::new("<compiled chunk>", "")))?;
rhue_bytecode::verify_once(&proto).map_err(|e| {
fail(
format!("compiled chunk rejected: {e}"),
&SourceFile::new(proto.source.name.clone(), ""),
)
})?;
Ok((proto, types))
}
pub fn compile_to_bytes(&mut self, name: &str, source: &str) -> Result<Vec<u8>, Error> {
let compiled = modules::compile_typed(&mut self.vm, name, source)?;
let types = modules::chunk_types(&compiled);
Ok(rhue_bytecode::write_chunk(&compiled.proto, Some(&types)))
}
pub fn add_module_bytes(&mut self, name: &str, bytes: &[u8]) -> Result<(), Error> {
let (proto, types) = self.read_chunk(bytes)?;
let ty = types
.as_ref()
.map(|t| modules::declare_chunk_types(&mut self.vm, t));
let state = modules::host(&mut self.vm);
state.sources.remove(name);
state.compiled.remove(name);
state.binary.insert(name.to_string(), proto);
if let Some(ty) = ty {
state.env.define_module(name, ty);
}
Ok(())
}
pub fn run(&mut self, chunk: &Chunk) -> Result<Vec<Value>, Error> {
let proto = &chunk.0;
self.verify(proto)?;
let values = self
.vm
.execute(proto)
.map_err(|e| Error::from_runtime(&e))?;
let cx = self.context();
Ok(values.into_iter().map(|v| cx.lift(v)).collect())
}
pub fn eval(&mut self, source: &str) -> Result<Vec<Value>, Error> {
self.eval_named("<eval>", source)
}
pub fn eval_named(&mut self, name: &str, source: &str) -> Result<Vec<Value>, Error> {
let proto = self.compile(name, source)?;
self.run(&proto)
}
fn verify(&self, proto: &Rc<Proto>) -> Result<(), Error> {
rhue_bytecode::verify_once(proto).map_err(|e| {
Error::new(
ErrorKind::Compile,
vec![Diagnostic::error(e.to_string(), proto.span)],
&proto.source,
)
})
}
pub fn eval_expr(&mut self, source: &str) -> Result<Value, Error> {
let proto = self.compile_expr("<expr>", source)?;
let mut values = self.run(&proto)?;
Ok(if values.is_empty() {
Value::Nil
} else {
values.swap_remove(0)
})
}
pub fn eval_as<R: FromValues>(&mut self, source: &str) -> Result<R, Error> {
let values = self.eval(source)?;
let mut cx = self.context();
R::from_values(values, &mut cx).map_err(|e| {
Error::from_script(ScriptError::new(format!(
"invalid result #{} ({})",
e.index, e.error
)))
})
}
}