luapackageloader (27may17)

git-svn-id: svn://tug.org/texlive/trunk@44500 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 209 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/luatex/luapackageloader/README.md b/Master/texmf-dist/doc/luatex/luapackageloader/README.md
new file mode 100644
index 00000000000..0326a4110dd
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luapackageloader/README.md
@@ -0,0 +1,22 @@
+# luapackageloader
+CTAN package to allow LuaTeX to load packages from the default `package.path` and `package.cpath` locations. This could be useful
+to load external Lua modules, including modules installed via [LuaRocks](https://luarocks.org).
+
+## Usage
+See the [PDF documentation](luapackageloader.pdf) for details.
+
+Here is a quick TeX example:
+
+```tex
+\input luapackageloader
+
+% Now we proceed to load a LuaRocks package
+\directlua{
+  local spt = require("serpent")
+}
+```
+
+## License
+Distributable under the LaTeX Project Public License, version 1.3c or higher (your choice). The latest version of this license is at: http://www.latex-project.org/lppl.txt
+
+This work is "maintained" (as per LPPL maintenance status) by Deepak Jois.
diff --git a/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.lua b/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.lua
new file mode 100644
index 00000000000..7ebd5b63e31
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.lua
@@ -0,0 +1,71 @@
+-- Author: Deepak Jois
+-- License: http://www.latex-project.org/lppl.txt
+-- Date: 2017/05/26
+-- Version: 0.1
+local luapackageloader = {}
+
+-- Cache the current kpse based searchers
+local kpse_lua_searcher = package.searchers[2]
+local kpse_clua_searcher = package.searchers[3]
+
+-- Emulates the default package.searchers[2] searcher.
+local function lua_searcher(name)
+  local file, err = package.searchpath(name,package.path)
+  if err then
+    return string.format("[lua searcher]: module not found: '%s'%s", name, err)
+  else
+    return loadfile(file)
+  end
+end
+
+-- Emulates the default package.searchers[3] searcher.
+local function clua_searcher(name)
+  local file, err = package.searchpath(name, package.cpath)
+  if err then
+    return string.format("[lua C searcher]: module not found: '%s'%s", name,err)
+  else
+    local symbol = name:gsub("%.","_")
+    return package.loadlib(file, "luaopen_"..symbol)
+  end
+end
+
+local function combine_searchers(searcher1, searcher2)
+  return function(name)
+    local loader1 = searcher1(name)
+    if type(loader1) == "string" then -- Not found using searcher1. Try searcher2.
+      local loader2 = searcher2(name)
+      if type(loader2) == "string" then -- Not found using searcher2. Return error.
+        return string.format("%s\n\t%s", loader1, loader2)
+      end
+      return loader2
+    end
+    return loader1
+  end
+end
+
+--- Use package.path and package.cpath to find Lua modules,
+-- in case kpse searching fails.
+--
+-- Package searching logic is overridden by default in LuaTeX to use kpse.
+-- Calling this function reverts the searchers to use package.path and
+-- package.cpath, if the kpse based searcher is not able to locate
+-- a module.
+--
+-- Package Loading References:
+-- 1. http://www.lua.org/manual/5.2/manual.html#pdf-package.searchers
+-- 2. LuaTeX Manual, Section 3.2, Lua behavior
+function luapackageloader.add_lua_searchers()
+  package.searchers[2] = combine_searchers(kpse_lua_searcher, lua_searcher)
+  package.searchers[3] = combine_searchers(kpse_clua_searcher, clua_searcher)
+end
+
+--- Restore the kpse package searchers that are used by default in LuaTeX.
+--
+-- Call this to restore the default LuaTeX behavior for searching packages,
+-- if you had earlier overridden it using `luapackageloader.add_lua_searchers()`.
+function luapackageloader.restore_kpse_searchers()
+  package.searchers[2] = kpse_lua_searcher
+  package.searchers[3] = kpse_clua_searcher
+end
+
+return luapackageloader
diff --git a/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.pdf b/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.pdf
new file mode 100644
index 00000000000..056a1d5967b
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.pdf
diff --git a/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.tex b/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.tex
new file mode 100644
index 00000000000..4e2a9885ec9
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luapackageloader/luapackageloader.tex
@@ -0,0 +1,116 @@
+\documentclass[a4paper]{article}
+
+%% Language and font encodings
+\usepackage[english]{babel}
+\usepackage[utf8x]{inputenc}
+\usepackage[T1]{fontenc}
+
+%% Sets page size and margins
+\usepackage[a4paper,top=3cm,bottom=2cm,left=3cm,right=3cm,marginparwidth=1.75cm]{geometry}
+
+%% Useful packages
+\usepackage[colorlinks=true,
+            linkcolor = blue,
+            urlcolor  = blue,
+            citecolor = blue,
+            anchorcolor = blue]{hyperref}
+\usepackage{xcolor}
+\usepackage{minted}
+\usepackage{csquotes}
+
+\definecolor{LG}{HTML}{F9F9F9}
+
+%% Informations
+\title{\textsf{luapackageloader} package}
+\author{Deepak Jois \\ \href{deepak.jois@gmail.com}{deepak.jois@gmail.com}}
+
+\begin{document}
+\maketitle
+
+\section*{Introduction}
+LuaTeX modifies the package loading behavior for Lua package, as mentioned in
+Section 3.2 of the LuaTeX manual:
+
+\begin{displayquote}
+LuaTEX is able to use the kpathsea library to find require()d modules. For this
+purpose, \texttt{package.searchers[2]} is replaced by a different loader function,
+that decides at runtime whether to use kpathsea or the built-in core Lua
+function. It uses kpathsea when that is already initialized at that point in
+  time, otherwise it reverts to using the normal \texttt{package.path} loader.
+\end{displayquote}
+
+What this means is that once kpathsea is initialized, the normal package
+loading behavior is no longer available.
+
+This package allows Lua package loading behavior inside LuaTeX to use \textit{both}
+kpathsea and the default loading mechanism. If the module is not available in kpathsea,
+LuaTeX will try to load it from \texttt{package.path}. This functionality is very useful,
+for instance when you need to use \href{https://luarocks.org/}{LuaRocks} modules inside LuaTeX.
+
+\section{Installation}
+
+Install this package like any other \TeX~or \LaTeX~package.
+
+\section{Dependencies}
+
+This package depends on \href{https://www.ctan.org/pkg/ifluatex}{ifluatex} CTAN package.
+
+\section{Usage}
+
+\subsection{Plain \TeX}
+In Plain \TeX, you can import the module as follows:
+
+\begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
+\input luapackageloader.sty
+\end{minted}
+
+\subsection{\LaTeX}
+
+In \LaTeX, add the \texttt{luapackageloader} packages to your document:
+
+\begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
+\usepackage{luapackageloader}
+\end{minted}
+
+\subsection{Loading Packages}
+
+Once you have imported \texttt{luapackageloader}, it adds a table called
+\texttt{luapackageloader} under the global namepace, and automatically
+overrides the default LuaTeX package searchers. It should be possible to load a
+Lua package (including \href{https://luarocks.org/}{LuaRocks} modules, as long
+as \texttt{package.path} and \texttt{package.cpath} is setup properly in your
+environment) as follows:
+
+\begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
+\directlua{
+  local serpent = require("serpent") % luarocks install serpent
+}
+\end{minted}
+
+\subsection{Reverting to default loading behavior}
+
+The package loading can be reverted back to the default LuaTeX behavior using the \texttt{restore\_kpse\_searchers()}
+\begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
+\directlua{
+  luapackageloader.resetore_kpse_searchers()
+}
+\end{minted}
+
+\subsection{Manually setting up to load Lua packages}
+
+This package exposes the function \texttt{add\_lua\_searchers()}, to manually setup the package searchers again, if it was reverted for some reason, after loading the package.
+
+\begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
+\input luapackageloader.sty
+\directlua{
+  % Let’s revert the package searchers to their default loading behavior.
+  luapackageloader.restore_kpse_searchers()
+
+ % Some code here...
+
+  % Now let’s setup the package searchers to use Lua searchers again.
+  luapackageloader.add_lua_searchers()
+}
+\end{minted}
+
+\end{document}