Add define_errors! to simplify the process of defining error signals

Author: ubolonton

CHANGELOG.md

@@ -4,9 +4,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
-- Added `Env::define_error` and `Env::signal` to simplify the process of signaling Lisp errors.
 - Added `OnceGlobalRef`, which eases the initialization of static references to long-lived Lisp values.
-- Added `use_symbols!`, which enables module code to use Lisp symbols without repeatedly interning them.
+  + Added `use_symbols!`, which enables module code to use Lisp symbols without repeatedly interning them.
+  + Added `define_errors!` and `Env::signal` to simplify the process of defining and signaling custom Lisp errors.
 - Raised the minimum supported Rust version to 1.45.
 
 ## [0.16.2] - 2021-03-04

guide/src/errors.md

@@ -40,24 +40,19 @@ This is similar to handling Lisp errors. The only difference is `ErrorKind::Thro
 
 ## Signaling Lisp Errors from Rust
 
-The function `env.signal` allows signaling a Lisp error from Rust code. The error symbol must have been defined, e.g. by calling `env.define_error`:
+The function `env.signal` allows signaling a Lisp error from Rust code. The error symbol must have been defined, e.g. by the macro `define_errors!`:
 
 ```rust
-pub static my_custom_error: OnceGlobalRef = OnceGlobalRef::new();
-
-#[emacs::module]
-fn init(env: &Env) -> Result<Value<'_>> {
-    env.define_error(
-        my_custom_error.init_to_symbol("my-custom-error")?,
-        "This number should not be negative",
-        [env.intern("error")?]
-    )
+// The parentheses denote parent error signals.
+// If unspecified, the parent error signal is `error`.
+emacs::define_errors! {
+    my_custom_error "This number should not be negative" (arith_error range_error)
 }
 
 #[defun]
 fn signal_if_negative(env: &Env, x: i16) -> Result<()> {
     if (x < 0) {
-        return env.signal(&my_custom_error., ("associated", "DATA", 7))
+        return env.signal(my_custom_error., ("associated", "DATA", 7))
     }
     Ok(())
 }

src/error.rs

@@ -23,6 +23,38 @@ pub struct TempValue {
     raw: emacs_value,
 }
 
+/// Defines new error signals.
+///
+/// TODO: Document this properly.
+///
+/// This macro can be used only once per Rust `mod`.
+#[macro_export]
+macro_rules! define_errors {
+    ($( $name:ident $message:literal $( ( $( $parent:ident )+ ) )? )*) => {
+        $crate::global_refs! {__emrs_init_global_refs_to_error_symbols__(init_to_symbol) =>
+            $( $name )*
+        }
+
+        #[$crate::deps::ctor::ctor]
+        fn __emrs_define_errors__() {
+            $crate::init::__CUSTOM_ERRORS__.try_lock()
+                .expect("Failed to acquire a write lock on the list of initializers for custom error signals")
+                .push(::std::boxed::Box::new(|env| {
+                    $(
+                        env.define_error($name, $message, [
+                            $(
+                                $(
+                                    env.intern($crate::deps::emacs_macros::lisp_name!($parent))?
+                                ),+
+                            )?
+                        ])?;
+                    )*
+                    Ok(())
+                }));
+        }
+    }
+}
+
 /// Error types generic to all Rust dynamic modules.
 ///
 /// This list is intended to grow over time and it is not recommended to exhaustively match against
@@ -175,7 +207,7 @@ impl Env {
         }
     }
 
-    pub(crate) fn define_errors(&self) -> Result<()> {
+    pub(crate) fn define_core_errors(&self) -> Result<()> {
         // FIX: Make panics louder than errors, by somehow make sure that 'rust-panic is
         // not a sub-type of 'error.
         self.define_error(symbol::rust_panic, "Rust panic", (symbol::error,))?;

src/global.rs

@@ -130,8 +130,8 @@ macro_rules! global_refs {
 
         #[$crate::deps::ctor::ctor]
         fn $registrator_name() {
-            $crate::init::__PRE_INIT__.try_lock()
-                .expect("Failed to acquire a write lock on the list of initializers")
+            $crate::init::__GLOBAL_REFS__.try_lock()
+                .expect("Failed to acquire a write lock on the list of initializers for global refs")
                 .push(::std::boxed::Box::new(|env| {
                     $(
                         #[allow(unused_variables)]

src/init.rs

@@ -51,7 +51,17 @@ type FnMap = HashMap<String, InitFn>;
 /// [`emacs_module_init`].
 ///
 /// [`emacs_module_init`]: https://www.gnu.org/software/emacs/manual/html_node/elisp/Dynamic-Modules.html
-pub static __PRE_INIT__: Lazy<Mutex<Vec<InitFn>>> = Lazy::new(|| Mutex::new(vec![]));
+pub static __GLOBAL_REFS__: Lazy<Mutex<Vec<InitFn>>> = Lazy::new(|| Mutex::new(vec![]));
+
+/// Functions that will be called by [`emacs_module_init`] to define custom error signals.
+///
+/// They are called before loading module metadata, e.g. module name, function prefix.
+///
+/// This list is populated when the OS loads the dynamic library, before Emacs calls
+/// [`emacs_module_init`].
+///
+/// [`emacs_module_init`]: https://www.gnu.org/software/emacs/manual/html_node/elisp/Dynamic-Modules.html
+pub static __CUSTOM_ERRORS__: Lazy<Mutex<Vec<InitFn>>> = Lazy::new(|| Mutex::new(vec![]));
 
 /// Functions that will be called by [`emacs_module_init`] to define the module functions.
 ///
@@ -94,11 +104,16 @@ pub fn initialize<F>(env: &Env, init: F) -> os::raw::c_int
 {
     let env = panic::AssertUnwindSafe(env);
     let result = panic::catch_unwind(|| match (|| {
-        for pre_init in __PRE_INIT__.try_lock().expect("Failed to acquire a read lock on the list of initializers").iter() {
-            pre_init(&env)?;
+        for init_global_ref in __GLOBAL_REFS__.try_lock()
+            .expect("Failed to acquire a read lock on the list of initializers for global-refs").iter() {
+            init_global_ref(&env)?;
         }
-        env.define_errors()?;
+        env.define_core_errors()?;
         check_gc_bug_31238(&env)?;
+        for define_error in __CUSTOM_ERRORS__.try_lock()
+            .expect("Failed to acquire a read lock on the list of initializers for custom error signals").iter() {
+            define_error(&env)?;
+        }
         init(&env)
     })() {
         Ok(_) => 0,

test-module/src/test_error.rs

@@ -1,6 +1,6 @@
 //! Testing error reporting and handling.
 
-use emacs::{defun, CallEnv, Env, Result, Value, OnceGlobalRef};
+use emacs::{defun, CallEnv, Env, Result, Value};
 use emacs::ErrorKind::{self, Signal, Throw};
 use emacs::ResultExt;
 
@@ -87,29 +87,22 @@ fn parse_arg(env: &CallEnv) -> Result<String> {
     Ok(s)
 }
 
+emacs::define_errors! {
+    emacs_module_rs_test_error "Hello" (rust_error)
+    error_defined_without_parent "No error message"
+}
+
 pub fn init(env: &Env) -> Result<()> {
     emacs::__export_functions! {
         env, format!("{}error:", *MODULE_PREFIX), {
             "parse-arg"   => (parse_arg   , 2..5),
         }
     }
 
-    #[allow(non_upper_case_globals)]
-    static custom_error: &'static OnceGlobalRef = {
-        static custom_error: OnceGlobalRef = OnceGlobalRef::new();
-        &custom_error
-    };
-
     #[defun(mod_in_name = false, name = "error:signal-custom")]
     fn signal_custom(env: &Env) -> Result<()> {
-        env.signal(custom_error, [])
+        env.signal(emacs_module_rs_test_error, [])
     }
 
-    env.define_error(
-        custom_error.init_to_symbol(env, "emacs-module-rs-test-error")?,
-        "Hello",
-        [env.intern("rust-error")?]
-    )?;
-
     Ok(())
 }

test-module/tests/main.el

@@ -168,9 +168,12 @@
       (t/error:signal 'rust-error "abc")
     (rust-error (should (equal err '(rust-error . ("abc"))))))
   (should-error (t/error:signal-custom) :type 'emacs-module-rs-test-error)
+  (should-error (t/error:signal-custom) :type 'rust-error)
+  (should-error (t/error:signal-custom) :type 'error)
   (condition-case err
       (t/error:signal 'emacs-module-rs-test-error "abc")
-    (rust-error (should (equal err '(emacs-module-rs-test-error . ("abc")))))))
+    (rust-error (should (equal err '(emacs-module-rs-test-error . ("abc"))))))
+  (should-error (signal 'error-defined-without-parent nil) :type 'error))
 
 ;;; ----------------------------------------------------------------------------
 ;;; Functions.