feat(cli): Add argument to ease soarch for 3rd party module(s)

Author: alerque

core/cli.lua

@@ -23,6 +23,11 @@ cli.parseArguments = function ()
    cliargs:option("-E, --evaluate-after=VALUE", "Evaluate Lua expression after processing input", {})
    cliargs:option("-f, --fontmanager=VALUE", "Specify which font manager to use")
    cliargs:option("-I, --include=FILE", "Deprecated, see --use, --preamble, --postamble, or multiple input files", {})
+   cliargs:option(
+      "    --luarocks-tree=LUAROCKS_TREE",
+      "Add a path to the list of LuaRocks trees searched for modules",
+      {}
+   )
    cliargs:option("-m, --makedeps=FILE", "Generate a Makefile format list of dependencies and white them to a file")
    cliargs:option("-o, --output=FILE", "Explicitly set output file name")
    cliargs:option("-O, --options=PARAMETER=VALUE[,PARAMETER=VALUE]", "Set or override document class options", {})
@@ -92,6 +97,9 @@ cli.parseArguments = function ()
    if opts.fontmanager then
       SILE.input.fontmanager = opts.fontmanager
    end
+   for _, tree in ipairs(opts["luarocks-tree"]) do
+      table.insert(SILE.input.luarocksTrees, tree)
+   end
    if opts.makedeps then
       SILE.makeDeps = require("core.makedeps")
       SILE.makeDeps.filename = opts.makedeps

core/sile.lua

@@ -150,6 +150,7 @@ SILE.input = {
    filenames = {},
    evaluates = {},
    evaluateAfters = {},
+   luarocksTrees = {},
    uses = {},
    options = {},
    preambles = {}, -- deprecated, undocumented
@@ -209,6 +210,9 @@ function SILE.init ()
       SU.deprecated("SILE.backend", "SILE.input.backend", "0.15.7", "0.17.0")
       SILE.input.backend = SILE.backend
    end
+   for _, tree in ipairs(SILE.input.luarocksTrees) do
+      _G["extendSilePathRocks"](tree)
+   end
    if not SILE.input.backend then
       SILE.input.backend = "libtexpdf"
    end
@@ -267,12 +271,22 @@ local function suggest_luarocks (module)
 
         eval $(luarocks --lua-version %s --tree path)
 
-      Thereafter running SILE as normal in the same shell should work as
-      expected:
+      Thereafter running `sile` as normal in the same shell should work as
+      expected. This code can be used in your shell's initialization script
+      to avoid having to do it manually in each new shell. This is true for
+      user home directory installations using `--local` or any specific values
+      for `--tree` other than 'lua_modules'.
+
+      As an anternative to setting up environment variables when using a
+      non-default tree location, you can use the `--luarocks-tree` option to
+      add path(s) at runtime. This is simpler to type, but must be used on each
+      and every invocation. The value for tree should be the same as used when
+      installing the LuaRock(s), or an appropriate full path to the location
+      used by `--local` (generally "$HOME/.luarocks"):
 
-        sile %s
+        sile --luarocks-tree path %s
 
-   ]]):format(SILE.lua_version, guessed_module_name, SILE.lua_version, pl.stringx.join(" ", _G.arg or {}))
+    ]]):format(SILE.lua_version, guessed_module_name, SILE.lua_version, pl.stringx.join(" ", _G.arg or {}))
 end
 
 --- Multi-purpose loader to load and initialize modules.

src/bin/sile.rs

@@ -45,6 +45,7 @@ fn main() -> Result<()> {
         args.evaluate,
         args.evaluate_after,
         args.fontmanager,
+        args.luarocks_tree,
         args.makedeps,
         args.output,
         args.option,

src/cli.rs

@@ -68,6 +68,16 @@ pub struct Cli {
     #[clap(short, long, value_name = "FONTMANAGER")]
     pub fontmanager: Option<String>,
 
+    /// Add a path to the list of LuaRocks trees searched for modules.
+    ///
+    /// When installing 3rd party SILE modules via LuaRocks there are several possible installation locations.
+    /// They may be installed to the host system, the user's home directory, a project-local path, or any arbitrary location.
+    /// In the case of the system or a project-local path called exactly `lua_modules` they will be found automatically.
+    /// In the case of any other path, SILE needs to be told where to find them.
+    /// This can be done by exporting a LUA_PATH environment variable before running SILE, or by using this option.
+    #[clap(long, value_name = "LUAROCKS_TREE")]
+    pub luarocks_tree: Option<Vec<PathBuf>>,
+
     /// Generate a Makefile format list of dependencies and white them to a file.
     ///
     /// This tracks all the files (input files, Lua libraries, fonts, images, etc.) use during the

src/lib.rs

@@ -24,6 +24,15 @@ pub fn start_luavm() -> crate::Result<Lua> {
     {
         lua = embed::inject_embedded_loaders(lua)?;
     }
+    // For parity with the legacy Lua arg parser, allows inspection of CLI args at runtime in Lua.
+    {
+        let args: Vec<String> = std::env::args().skip(1).collect();
+        let arg_table = lua.create_table()?;
+        for (i, arg) in args.iter().enumerate() {
+            arg_table.set(i + 1, arg.clone())?;
+        }
+        lua.globals().set("arg", arg_table)?;
+    }
     lua = inject_paths(lua)?;
     lua = load_sile(lua)?;
     lua = inject_version(lua)?;
@@ -104,6 +113,7 @@ pub fn run(
     evaluates: Option<Vec<String>>,
     evaluate_afters: Option<Vec<String>>,
     fontmanager: Option<String>,
+    luarocks_tree: Option<Vec<PathBuf>>,
     makedeps: Option<PathBuf>,
     output: Option<PathBuf>,
     options: Option<Vec<String>>,
@@ -138,6 +148,9 @@ pub fn run(
     if let Some(fontmanager) = fontmanager {
         sile_input.set("fontmanager", fontmanager)?;
     }
+    if let Some(trees) = luarocks_tree {
+        sile_input.set("luarocksTrees", trees)?;
+    }
     if let Some(class) = class {
         sile_input.set("class", class)?;
     }