Add unwinding support (returning an Error) to Luau Require implementation

Author: khvzak

mlua-sys/src/luau/luarequire.rs

@@ -26,11 +26,14 @@ pub enum luarequire_WriteResult {
 #[repr(C)]
 pub struct luarequire_Configuration {
     // Returns whether requires are permitted from the given chunkname.
-    pub is_require_allowed:
-        unsafe extern "C" fn(L: *mut lua_State, ctx: *mut c_void, requirer_chunkname: *const c_char) -> bool,
+    pub is_require_allowed: unsafe extern "C-unwind" fn(
+        L: *mut lua_State,
+        ctx: *mut c_void,
+        requirer_chunkname: *const c_char,
+    ) -> bool,
 
     // Resets the internal state to point at the requirer module.
-    pub reset: unsafe extern "C" fn(
+    pub reset: unsafe extern "C-unwind" fn(
         L: *mut lua_State,
         ctx: *mut c_void,
         requirer_chunkname: *const c_char,
@@ -39,26 +42,27 @@ pub struct luarequire_Configuration {
     // Resets the internal state to point at an aliased module, given its exact path from a configuration
     // file. This function is only called when an alias's path cannot be resolved relative to its
     // configuration file.
-    pub jump_to_alias: unsafe extern "C" fn(
+    pub jump_to_alias: unsafe extern "C-unwind" fn(
         L: *mut lua_State,
         ctx: *mut c_void,
         path: *const c_char,
     ) -> luarequire_NavigateResult,
 
     // Navigates through the context by making mutations to the internal state.
-    pub to_parent: unsafe extern "C" fn(L: *mut lua_State, ctx: *mut c_void) -> luarequire_NavigateResult,
-    pub to_child: unsafe extern "C" fn(
+    pub to_parent:
+        unsafe extern "C-unwind" fn(L: *mut lua_State, ctx: *mut c_void) -> luarequire_NavigateResult,
+    pub to_child: unsafe extern "C-unwind" fn(
         L: *mut lua_State,
         ctx: *mut c_void,
         name: *const c_char,
     ) -> luarequire_NavigateResult,
 
     // Returns whether the context is currently pointing at a module.
-    pub is_module_present: unsafe extern "C" fn(L: *mut lua_State, ctx: *mut c_void) -> bool,
+    pub is_module_present: unsafe extern "C-unwind" fn(L: *mut lua_State, ctx: *mut c_void) -> bool,
 
     // Provides a chunkname for the current module. This will be accessible through the debug library. This
     // function is only called if is_module_present returns true.
-    pub get_chunkname: unsafe extern "C" fn(
+    pub get_chunkname: unsafe extern "C-unwind" fn(
         L: *mut lua_State,
         ctx: *mut c_void,
         buffer: *mut c_char,
@@ -68,7 +72,7 @@ pub struct luarequire_Configuration {
 
     // Provides a loadname that identifies the current module and is passed to load. This function
     // is only called if is_module_present returns true.
-    pub get_loadname: unsafe extern "C" fn(
+    pub get_loadname: unsafe extern "C-unwind" fn(
         L: *mut lua_State,
         ctx: *mut c_void,
         buffer: *mut c_char,
@@ -78,7 +82,7 @@ pub struct luarequire_Configuration {
 
     // Provides a cache key representing the current module. This function is only called if
     // is_module_present returns true.
-    pub get_cache_key: unsafe extern "C" fn(
+    pub get_cache_key: unsafe extern "C-unwind" fn(
         L: *mut lua_State,
         ctx: *mut c_void,
         buffer: *mut c_char,
@@ -89,15 +93,15 @@ pub struct luarequire_Configuration {
     // Returns whether a configuration file is present in the current context.
     // If not, require-by-string will call to_parent until either a configuration file is present or
     // NAVIGATE_FAILURE is returned (at root).
-    pub is_config_present: unsafe extern "C" fn(L: *mut lua_State, ctx: *mut c_void) -> bool,
+    pub is_config_present: unsafe extern "C-unwind" fn(L: *mut lua_State, ctx: *mut c_void) -> bool,
 
     // Parses the configuration file in the current context for the given alias and returns its
     // value or WRITE_FAILURE if not found. This function is only called if is_config_present
     // returns true. If this function pointer is set, get_config must not be set. Opting in to this
     // function pointer disables parsing configuration files internally and can be used for finer
     // control over the configuration file parsing process.
     pub get_alias: Option<
-        unsafe extern "C" fn(
+        unsafe extern "C-unwind" fn(
             L: *mut lua_State,
             ctx: *mut c_void,
             alias: *const c_char,
@@ -111,7 +115,7 @@ pub struct luarequire_Configuration {
     // if is_config_present returns true. If this function pointer is set, get_alias must not be set. Opting
     // in to this function pointer enables parsing configuration files internally.
     pub get_config: Option<
-        unsafe extern "C" fn(
+        unsafe extern "C-unwind" fn(
             L: *mut lua_State,
             ctx: *mut c_void,
             buffer: *mut c_char,
@@ -134,7 +138,7 @@ pub struct luarequire_Configuration {
 }
 
 // Populates function pointers in the given luarequire_Configuration.
-pub type luarequire_Configuration_init = unsafe extern "C" fn(config: *mut luarequire_Configuration);
+pub type luarequire_Configuration_init = unsafe extern "C-unwind" fn(config: *mut luarequire_Configuration);
 
 unsafe extern "C-unwind" {
     // Initializes and pushes the require closure onto the stack without registration.

src/lib.rs

@@ -132,7 +132,7 @@ pub use crate::{
     buffer::Buffer,
     chunk::{CompileConstant, Compiler},
     function::CoverageInfo,
-    luau::{NavigateError, Require},
+    luau::{NavigateError, Require, TextRequirer},
     vector::Vector,
 };
 

src/luau/mod.rs

@@ -8,7 +8,7 @@ use crate::function::Function;
 use crate::state::{callback_error_ext, Lua};
 use crate::traits::{FromLuaMulti, IntoLua};
 
-pub use require::{NavigateError, Require};
+pub use require::{NavigateError, Require, TextRequirer};
 
 // Since Luau has some missing standard functions, we re-implement them here
 

src/luau/require.rs

@@ -8,39 +8,51 @@ use std::path::{Component, Path, PathBuf};
 use std::result::Result as StdResult;
 use std::{env, fmt, fs, mem, ptr};
 
-use crate::error::Result;
+use crate::error::{Error, Result};
 use crate::function::Function;
 use crate::state::{callback_error_ext, Lua};
 use crate::table::Table;
 use crate::types::MaybeSend;
 
 /// An error that can occur during navigation in the Luau `require` system.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg(any(feature = "luau", doc))]
+#[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
+#[derive(Debug, Clone)]
 pub enum NavigateError {
     Ambiguous,
     NotFound,
+    Other(Error),
 }
 
 #[cfg(feature = "luau")]
 trait IntoNavigateResult {
-    fn into_nav_result(self) -> ffi::luarequire_NavigateResult;
+    fn into_nav_result(self) -> Result<ffi::luarequire_NavigateResult>;
 }
 
 #[cfg(feature = "luau")]
 impl IntoNavigateResult for StdResult<(), NavigateError> {
-    fn into_nav_result(self) -> ffi::luarequire_NavigateResult {
+    fn into_nav_result(self) -> Result<ffi::luarequire_NavigateResult> {
         match self {
-            Ok(()) => ffi::luarequire_NavigateResult::Success,
-            Err(NavigateError::Ambiguous) => ffi::luarequire_NavigateResult::Ambiguous,
-            Err(NavigateError::NotFound) => ffi::luarequire_NavigateResult::NotFound,
+            Ok(()) => Ok(ffi::luarequire_NavigateResult::Success),
+            Err(NavigateError::Ambiguous) => Ok(ffi::luarequire_NavigateResult::Ambiguous),
+            Err(NavigateError::NotFound) => Ok(ffi::luarequire_NavigateResult::NotFound),
+            Err(NavigateError::Other(err)) => Err(err),
         }
     }
 }
 
+impl From<Error> for NavigateError {
+    fn from(err: Error) -> Self {
+        NavigateError::Other(err)
+    }
+}
+
 #[cfg(feature = "luau")]
 type WriteResult = ffi::luarequire_WriteResult;
 
 /// A trait for handling modules loading and navigation in the Luau `require` system.
+#[cfg(any(feature = "luau", doc))]
+#[cfg_attr(docsrs, doc(cfg(feature = "luau")))]
 pub trait Require: MaybeSend {
     /// Returns `true` if "require" is permitted for the given chunk name.
     fn is_require_allowed(&self, chunk_name: &str) -> bool;
@@ -92,15 +104,17 @@ impl fmt::Debug for dyn Require {
 }
 
 /// The standard implementation of Luau `require` navigation.
+#[doc(hidden)]
 #[derive(Default, Debug)]
-pub(super) struct TextRequirer {
+pub struct TextRequirer {
     abs_path: PathBuf,
     rel_path: PathBuf,
     module_path: PathBuf,
 }
 
 impl TextRequirer {
-    pub(super) fn new() -> Self {
+    /// Creates a new `TextRequirer` instance.
+    pub fn new() -> Self {
         Self::default()
     }
 
@@ -308,12 +322,12 @@ macro_rules! try_borrow_mut {
 }
 
 #[cfg(feature = "luau")]
-pub(super) unsafe extern "C" fn init_config(config: *mut ffi::luarequire_Configuration) {
+pub(super) unsafe extern "C-unwind" fn init_config(config: *mut ffi::luarequire_Configuration) {
     if config.is_null() {
         return;
     }
 
-    unsafe extern "C" fn is_require_allowed(
+    unsafe extern "C-unwind" fn is_require_allowed(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
         requirer_chunkname: *const c_char,
@@ -327,50 +341,58 @@ pub(super) unsafe extern "C" fn init_config(config: *mut ffi::luarequire_Configu
         this.is_require_allowed(&chunk_name)
     }
 
-    unsafe extern "C" fn reset(
+    unsafe extern "C-unwind" fn reset(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
         requirer_chunkname: *const c_char,
     ) -> ffi::luarequire_NavigateResult {
         let mut this = try_borrow_mut!(state, ctx);
         let chunk_name = CStr::from_ptr(requirer_chunkname).to_string_lossy();
-        this.reset(&chunk_name).into_nav_result()
+        callback_error_ext(state, ptr::null_mut(), true, move |_, _| {
+            this.reset(&chunk_name).into_nav_result()
+        })
     }
 
-    unsafe extern "C" fn jump_to_alias(
+    unsafe extern "C-unwind" fn jump_to_alias(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
         path: *const c_char,
     ) -> ffi::luarequire_NavigateResult {
         let mut this = try_borrow_mut!(state, ctx);
         let path = CStr::from_ptr(path).to_string_lossy();
-        this.jump_to_alias(&path).into_nav_result()
+        callback_error_ext(state, ptr::null_mut(), true, move |_, _| {
+            this.jump_to_alias(&path).into_nav_result()
+        })
     }
 
-    unsafe extern "C" fn to_parent(
+    unsafe extern "C-unwind" fn to_parent(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
     ) -> ffi::luarequire_NavigateResult {
         let mut this = try_borrow_mut!(state, ctx);
-        this.to_parent().into_nav_result()
+        callback_error_ext(state, ptr::null_mut(), true, move |_, _| {
+            this.to_parent().into_nav_result()
+        })
     }
 
-    unsafe extern "C" fn to_child(
+    unsafe extern "C-unwind" fn to_child(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
         name: *const c_char,
     ) -> ffi::luarequire_NavigateResult {
         let mut this = try_borrow_mut!(state, ctx);
         let name = CStr::from_ptr(name).to_string_lossy();
-        this.to_child(&name).into_nav_result()
+        callback_error_ext(state, ptr::null_mut(), true, move |_, _| {
+            this.to_child(&name).into_nav_result()
+        })
     }
 
-    unsafe extern "C" fn is_module_present(state: *mut ffi::lua_State, ctx: *mut c_void) -> bool {
+    unsafe extern "C-unwind" fn is_module_present(state: *mut ffi::lua_State, ctx: *mut c_void) -> bool {
         let this = try_borrow!(state, ctx);
         this.has_module()
     }
 
-    unsafe extern "C" fn get_chunkname(
+    unsafe extern "C-unwind" fn get_chunkname(
         _state: *mut ffi::lua_State,
         _ctx: *mut c_void,
         buffer: *mut c_char,
@@ -380,7 +402,7 @@ pub(super) unsafe extern "C" fn init_config(config: *mut ffi::luarequire_Configu
         write_to_buffer(buffer, buffer_size, size_out, &[])
     }
 
-    unsafe extern "C" fn get_loadname(
+    unsafe extern "C-unwind" fn get_loadname(
         _state: *mut ffi::lua_State,
         _ctx: *mut c_void,
         buffer: *mut c_char,
@@ -390,7 +412,7 @@ pub(super) unsafe extern "C" fn init_config(config: *mut ffi::luarequire_Configu
         write_to_buffer(buffer, buffer_size, size_out, &[])
     }
 
-    unsafe extern "C" fn get_cache_key(
+    unsafe extern "C-unwind" fn get_cache_key(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
         buffer: *mut c_char,
@@ -402,22 +424,20 @@ pub(super) unsafe extern "C" fn init_config(config: *mut ffi::luarequire_Configu
         write_to_buffer(buffer, buffer_size, size_out, cache_key.as_bytes())
     }
 
-    unsafe extern "C" fn is_config_present(state: *mut ffi::lua_State, ctx: *mut c_void) -> bool {
+    unsafe extern "C-unwind" fn is_config_present(state: *mut ffi::lua_State, ctx: *mut c_void) -> bool {
         let this = try_borrow!(state, ctx);
         this.has_config()
     }
 
-    unsafe extern "C" fn get_config(
+    unsafe extern "C-unwind" fn get_config(
         state: *mut ffi::lua_State,
         ctx: *mut c_void,
         buffer: *mut c_char,
         buffer_size: usize,
         size_out: *mut usize,
     ) -> WriteResult {
         let this = try_borrow!(state, ctx);
-        let Ok(config) = this.config() else {
-            return WriteResult::Failure;
-        };
+        let config = callback_error_ext(state, ptr::null_mut(), true, move |_, _| Ok(this.config()?));
         write_to_buffer(buffer, buffer_size, size_out, &config)
     }
 
@@ -429,7 +449,7 @@ pub(super) unsafe extern "C" fn init_config(config: *mut ffi::luarequire_Configu
         _loadname: *const c_char,
     ) -> c_int {
         let this = try_borrow!(state, ctx);
-        callback_error_ext(state, ptr::null_mut(), false, move |extra, _| {
+        callback_error_ext(state, ptr::null_mut(), true, move |extra, _| {
             let rawlua = (*extra).raw_lua();
             let loader = this.loader(rawlua.lua())?;
             rawlua.push(loader)?;