[latex3-commits] [git/LaTeX3-latex3-latex3] main: Add new command `\lua_load_module:n` (ba548f595)

[Max Chernoff]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/ba548f595b6b13aa5184b0cf2e2521305a63b88a

>---------------------------------------------------------------

commit ba548f595b6b13aa5184b0cf2e2521305a63b88a
Author: Max Chernoff <49086429+gucci-on-fleek at users.noreply.github.com>
Date:   Sat May 7 19:28:19 2022 -0600

    Add new command `\lua_load_module:n`
    
    Adds a new command `\lua_load_module:n` to the `l3luatex` module as a
    replacement for `\lua_now:n { require "module" }`.


>---------------------------------------------------------------

ba548f595b6b13aa5184b0cf2e2521305a63b88a
 l3kernel/CHANGELOG.md |  3 +++
 l3kernel/l3luatex.dtx | 69 +++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index 56151b230..9a28e9a57 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -7,6 +7,9 @@ this project uses date-based 'snapshot' version identifiers.
 
 ## [Unreleased]
 
+### Added
+- Add `\lua_load_module:n`
+
 ### Fixed
 - Typo in implemenation of titlecase `hy-x-yiwn`
 - Definition order issue with `\str_case:Nn(TF)`
diff --git a/l3kernel/l3luatex.dtx b/l3kernel/l3luatex.dtx
index 914c389e0..40e0ae009 100644
--- a/l3kernel/l3luatex.dtx
+++ b/l3kernel/l3luatex.dtx
@@ -115,6 +115,25 @@
 %   \end{texnote}
 % \end{function}
 %
+% \begin{function}[added = 2022-05-07]{\lua_load_module:n}
+%   \begin{syntax}
+%     \cs{lua_load_module:n} \Arg{Lua module name}
+%   \end{syntax}
+%   Loads a Lua module into the Lua interpreter.
+%
+%   \cs{lua_now:n} passes its \Arg{token list} argument to the Lua interpreter
+%   as a single line, with characters interpreted under the current catcode
+%   regime. These two facts mean that \cs{lua_now:n} rarely behaves as expected
+%   for larger pieces of code. Therefore, package authors should \textbf{not}
+%   write significant amounts of Lua code in the arguments to \cs{lua_now:n}.
+%   Instead, it is strongly recommended that they write the majorty of their Lua
+%   code in a separate file, and then load it using \cs{lua_load_module:n}.
+%   \begin{texnote}
+%     This is a wrapper around the Lua call
+%     \texttt{require~\string"\meta{module}\string"}.
+%   \end{texnote}
+% \end{function}
+%
 % \section{Lua interfaces}
 %
 % As well as interfaces for \TeX{}, there are a small number of Lua functions
@@ -208,9 +227,7 @@
 % \begin{macro}[EXP]{\lua_now:n, \lua_now:e}
 % \begin{macro}{\lua_shipout_e:n, \lua_shipout:n}
 % \begin{macro}[EXP]{\lua_escape:n, \lua_escape:e}
-%   Wrappers around the primitives. As with engines other than \LuaTeX{}
-%   these have to be macros, we give them the same status in all cases.
-%   When \LuaTeX{} is not in use, simply give an error message/
+%   Wrappers around the primitives.
 %    \begin{macrocode}
 \cs_new:Npn \lua_now:e #1 { \@@_now:n {#1} }
 \cs_new:Npn \lua_now:n #1 { \lua_now:e { \exp_not:n {#1} } }
@@ -219,6 +236,34 @@
   { \lua_shipout_e:n { \exp_not:n {#1} } }
 \cs_new:Npn \lua_escape:e #1 { \@@_escape:n {#1} }
 \cs_new:Npn \lua_escape:n #1 { \lua_escape:e { \exp_not:n {#1} } }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\lua_load_module:n}
+%   Wrapper around the Lua call \texttt{require~\string"\meta{module}\string"},
+%   with a friendlier error message when the module cannot be found.
+%    \begin{macrocode}
+\cs_new_protected:Npn \lua_load_module:n #1
+  {
+    \file_if_exist:nTF { #1 .lua }
+      {
+        \@@_now:n { require "\@@_escape:n { #1 }" }
+      }
+      {
+        \msg_error:nnn
+          { luatex } { module-not-found } { #1 }
+      }
+  }
+
+%    \end{macrocode}
+% \end{macro}
+%
+%   As with engines other than \LuaTeX{}
+%   these have to be macros, we give them the same status in all cases.
+%   When \LuaTeX{} is not in use, simply give an error message/
+%    \begin{macrocode}
 \sys_if_engine_luatex:F
   {
     \clist_map_inline:nn
@@ -234,7 +279,7 @@
           }
       }
     \clist_map_inline:nn
-      { \lua_shipout_e:n , \lua_shipout:n }
+      { \lua_shipout_e:n , \lua_shipout:n, \lua_load_module:n }
       {
         \cs_set_protected:Npn #1 ##1
           {
@@ -244,10 +289,6 @@
       }
   }
 %    \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
 % \subsection{Messages}
 %
 %    \begin{macrocode}
@@ -257,6 +298,18 @@
     The~feature~you~are~using~is~only~available~
     with~the~LuaTeX~engine.~LaTeX3~ignored~'#1'.
   }
+
+\msg_new:nnnn { luatex } { module-not-found }
+  { Lua~module~`#1'~not~found. }
+  {
+    The~file~`#1.lua'~could~not~be~found~in~the~current~
+    directory~or~in~the~TeX~search~path.~Please~ensure~that~
+    the~file~was~properly~installed~and~that~the~filename~
+    database~is~current.
+  }
+
+\prop_gput:Nnn \g_msg_module_name_prop { luatex } { LaTeX3 }
+\prop_gput:Nnn \g_msg_module_type_prop { luatex } { }
 %    \end{macrocode}
 %
 %    \begin{macrocode}