Debian Codegraph @

texmf-dist/doc/luatex/luapackageloader/luapackageloader.tex

raw
1 \documentclass[a4paper]{article}
2
3 %% Language and font encodings
4 \usepackage[english]{babel}
5 \usepackage[utf8x]{inputenc}
6 \usepackage[T1]{fontenc}
7
8 %% Sets page size and margins
9 \usepackage[a4paper,top=3cm,bottom=2cm,left=3cm,right=3cm,marginparwidth=1.75cm]{geometry}
10
11 %% Useful packages
12 \usepackage[colorlinks=true,
13 linkcolor = blue,
14 urlcolor = blue,
15 citecolor = blue,
16 anchorcolor = blue]{hyperref}
17 \usepackage{xcolor}
18 \usepackage{minted}
19 \usepackage{csquotes}
20
21 \definecolor{LG}{HTML}{F9F9F9}
22
23 %% Informations
24 \title{\textsf{luapackageloader} package}
25 \author{Deepak Jois \\ \href{[email protected]}{[email protected]}}
26
27 \begin{document}
28 \maketitle
29
30 \section*{Introduction}
31 LuaTeX modifies the package loading behavior for Lua package, as mentioned in
32 Section 3.2 of the LuaTeX manual:
33
34 \begin{displayquote}
35 LuaTEX is able to use the kpathsea library to find require()d modules. For this
36 purpose, \texttt{package.searchers[2]} is replaced by a different loader function,
37 that decides at runtime whether to use kpathsea or the built-in core Lua
38 function. It uses kpathsea when that is already initialized at that point in
39 time, otherwise it reverts to using the normal \texttt{package.path} loader.
40 \end{displayquote}
41
42 What this means is that once kpathsea is initialized, the normal package
43 loading behavior is no longer available.
44
45 This package allows Lua package loading behavior inside LuaTeX to use \textit{both}
46 kpathsea and the default loading mechanism. If the module is not available in kpathsea,
47 LuaTeX will try to load it from \texttt{package.path}. This functionality is very useful,
48 for instance when you need to use \href{https://luarocks.org/}{LuaRocks} modules inside LuaTeX.
49
50 \section{Installation}
51
52 Install this package like any other \TeX~or \LaTeX~package.
53
54 \section{Dependencies}
55
56 This package depends on \href{https://www.ctan.org/pkg/ifluatex}{ifluatex} CTAN package.
57
58 \section{Usage}
59
60 \subsection{Plain \TeX}
61 In Plain \TeX, you can import the module as follows:
62
63 \begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
64 \input luapackageloader.sty
65 \end{minted}
66
67 \subsection{\LaTeX}
68
69 In \LaTeX, add the \texttt{luapackageloader} packages to your document:
70
71 \begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
72 \usepackage{luapackageloader}
73 \end{minted}
74
75 \subsection{Loading Packages}
76
77 Once you have imported \texttt{luapackageloader}, it adds a table called
78 \texttt{luapackageloader} under the global namepace, and automatically
79 overrides the default LuaTeX package searchers. It should be possible to load a
80 Lua package (including \href{https://luarocks.org/}{LuaRocks} modules, as long
81 as \texttt{package.path} and \texttt{package.cpath} is setup properly in your
82 environment) as follows:
83
84 \begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
85 \directlua{
86 local serpent = require("serpent") % luarocks install serpent
87 }
88 \end{minted}
89
90 \subsection{Reverting to default loading behavior}
91
92 The package loading can be reverted back to the default LuaTeX behavior using the \texttt{restore\_kpse\_searchers()}
93 \begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
94 \directlua{
95 luapackageloader.resetore_kpse_searchers()
96 }
97 \end{minted}
98
99 \subsection{Manually setting up to load Lua packages}
100
101 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.
102
103 \begin{minted}[bgcolor=LG, fontsize=\footnotesize]{tex}
104 \input luapackageloader.sty
105 \directlua{
106 % Let’s revert the package searchers to their default loading behavior.
107 luapackageloader.restore_kpse_searchers()
108
109 % Some code here...
110
111 % Now let’s setup the package searchers to use Lua searchers again.
112 luapackageloader.add_lua_searchers()
113 }
114 \end{minted}
115
116 \end{document}