Add use_symbols! to enable using Lisp symbols w/o repeated interning

Author: ubolonton

CHANGELOG.md

@@ -6,6 +6,7 @@ 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.
 - Raised the minimum supported Rust version to 1.45.
 
 ## [0.16.2] - 2021-03-04

src/global.rs

@@ -95,12 +95,6 @@ impl<'e> IntoLisp<'e> for &'e GlobalRef {
     }
 }
 
-impl<'e> IntoLisp<'e> for &'e OnceGlobalRef {
-    #[inline(always)]
-    fn into_lisp(self, env: &'e Env) -> Result<Value<'e>> {
-        Ok(self.bind(env))
-    }
-}
 
 impl<'e> Value<'e> {
     /// Creates a new [`GlobalRef`] for this value.
@@ -112,10 +106,50 @@ impl<'e> Value<'e> {
     }
 }
 
+/// Declares global references. These will be initialized when the module is loaded.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! global_refs {
+    ($($name:ident)*) => {
+        $(
+            #[allow(non_upper_case_globals)]
+            pub static $name: &'static $crate::OnceGlobalRef = {
+                static X: $crate::OnceGlobalRef = $crate::OnceGlobalRef::new();
+                &X
+            };
+        )*
+    };
+    ($registrator_name:ident ($init_method:ident) =>
+        $(
+            $name:ident $( => $lisp_name:expr )?
+        )*
+    ) => {
+        $crate::global_refs! {
+            $($name)*
+        }
+
+        #[$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")
+                .push(::std::boxed::Box::new(|env| {
+                    $(
+                        #[allow(unused_variables)]
+                        let name = $crate::deps::emacs_macros::lisp_name!($name);
+                        $( let name = $lisp_name; )?
+                        $crate::OnceGlobalRef::$init_method(&$name, env, name)?;
+                    )*
+                    Ok(())
+                }));
+        }
+    };
+}
+
 /// A [`GlobalRef`] that can be initialized once. This is useful for long-lived values that should
-/// be initialized when the module is loaded, such as frequently-used symbols.
+/// be initialized when the dynamic module is loaded. A typical use case is specifying
+/// frequently-used symbols, which can be done with the help of the macro [`use_symbols!`].
 ///
-/// [`GlobalRef`]: struct.GlobalRef.html
+/// [`use_symbols`]: crate::use_symbols
 #[derive(Debug)]
 #[repr(transparent)]
 pub struct OnceGlobalRef {
@@ -158,6 +192,13 @@ impl OnceGlobalRef {
     }
 }
 
+impl<'e> IntoLisp<'e> for &'e OnceGlobalRef {
+    #[inline(always)]
+    fn into_lisp(self, env: &'e Env) -> Result<Value<'e>> {
+        Ok(self.bind(env))
+    }
+}
+
 impl Deref for OnceGlobalRef {
     type Target = GlobalRef;
 

src/lib.rs

@@ -52,6 +52,7 @@ mod value;
 mod types;
 mod error;
 mod call;
+#[macro_use]
 mod global;
 mod symbol;
 mod subr;
@@ -66,5 +67,6 @@ pub mod raw {
 /// External dependencies that are mostly used by macros instead of user code.
 #[doc(hidden)]
 pub mod deps {
+    pub use emacs_macros;
     pub use ctor;
 }

src/macros.rs

@@ -64,40 +64,6 @@ macro_rules! unsafe_raw_call_value_unprotected {
     };
 }
 
-/// Declare global references. These should be initialized when the module is loaded.
-macro_rules! global_refs {
-    ($($name:ident)*) => {
-        $(pub static $name: &'static $crate::global::OnceGlobalRef = {
-            static x: $crate::global::OnceGlobalRef = $crate::global::OnceGlobalRef::new();
-            &x
-        };)*
-    };
-    ($registrator_name:ident ($init_method:ident) =>
-        $(
-            $name:ident $( => $lisp_name:expr )?
-        )*
-    ) => {
-        global_refs! {
-            $($name)*
-        }
-
-        #[$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")
-                .push(Box::new(|env| {
-                    $(
-                        #[allow(unused_variables)]
-                        let name = ::emacs_macros::lisp_name!($name);
-                        $( let name = $lisp_name; )?
-                        $crate::global::OnceGlobalRef::$init_method(&$name, env, name)?;
-                    )*
-                    Ok(())
-                }));
-        }
-    };
-}
-
 /// Declares that this module is GPL-compatible. Emacs will not load it otherwise.
 #[macro_export]
 #[allow(non_snake_case)]

src/subr.rs

@@ -1,5 +1,3 @@
-#![allow(non_upper_case_globals)]
-
 global_refs! {common(init_to_function) =>
     cons car cdr
     vector make_vector

src/symbol.rs

@@ -1,8 +1,23 @@
-#![allow(non_upper_case_globals)]
-
 use crate::{Env, Result, Value, global::{GlobalRef, OnceGlobalRef}};
 
-global_refs! {common(init_to_symbol) =>
+/// Defines static [`&OnceGlobalRef`] variables that point to corresponding Lisp symbols.
+///
+/// This macro accepts a space-separated list of identifiers, and determine the Lisp symbol names by
+/// replacing underscores with hyphens.
+///
+/// It can be used only once per Rust `mod`.
+///
+/// [`&OnceGlobalRef`]: OnceGlobalRef
+#[macro_export]
+macro_rules! use_symbols {
+    ($( $name:ident $( => $lisp_name:expr )? )*) => {
+        $crate::global_refs! {__emrs_init_global_refs_to_symbols__(init_to_symbol) =>
+            $( $name $( => $lisp_name )? )*
+        }
+    }
+}
+
+use_symbols! {
     nil t
     error
     rust_error