Debian Codegraph @

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

raw
1 \documentclass{ltxdoc}
2
3 \EnableCrossrefs
4 \CodelineIndex
5 \RecordChanges
6
7 \usepackage{mdframed}
8 \usepackage{minted}
9 \usepackage{multicol}
10 \usepackage{luacode}
11 \usepackage{syntax}
12 \usepackage{color}
13
14 \definecolor{gray}{gray}{0.75}
15
16 \usemintedstyle{friendly}
17 \BeforeBeginEnvironment{minted}{\begin{mdframed}}
18 \AfterEndEnvironment{minted}{\end{mdframed}}
19 \setminted{
20 breaklines=true,
21 fontsize=\footnotesize,
22 style=manni,
23 }
24 \def\lua#1{\mintinline{lua}|#1|}
25 \def\latex#1{\mintinline{latex}|#1|}
26
27 % File names must not contain underscores
28 \NewDocumentCommand { \InputLatex } { O{} m } {
29 \begin{mdframed}
30 \inputminted[linenos=false,#1]{latex}{examples/#2}
31 \end{mdframed}
32 }
33
34 \NewDocumentCommand { \InputTex } { O{} m } {
35 \begin{mdframed}
36 \inputminted[linenos=false,#1]{tex}{examples/#2}
37 \end{mdframed}
38 }
39
40 \NewDocumentCommand { \InputLua } { O{} m } {
41 \begin{mdframed}
42 \inputminted[linenos=false,#1]{lua}{examples/#2}
43 \end{mdframed}
44 }
45
46 \begin{document}
47
48 \providecommand*{\url}{\texttt}
49
50 \title{The \textsf{lparse} package}
51 \author{%
52 Josef Friedrich\\%
53 \url{[email protected]}\\%
54 \href{https://github.com/Josef-Friedrich/lparse}
55 {github.com/Josef-Friedrich/lparse}%
56 }
57 \date{0.3.0 from 2025/07/02}
58
59 \maketitle
60
61 \InputLatex[firstline=5,lastline=14]{lualatex/title-page.tex}
62
63 \newpage
64
65 \tableofcontents
66
67 \newpage
68
69 % \section{Einführung}
70 \section{Introduction}
71
72 % Der Name |lparse| ist von |xparse| abgeleitet.
73 The name |lparse| is derived from |xparse|.
74 %
75 % Das |x| wurde durch |l| ersetzt, da dieses Packet nur zusammen mit
76 % Lua\TeX{} funktioniert.
77 The |x| has been replaced by |l| because this package only works with Lua\TeX{}.
78 %
79 % |l| steht für \emph{Lua}
80 |l| stands for \emph{Lua}.
81 %
82 % Ebenso wie bei dem Paket |xparse| ist es möglich, die Argumente eines
83 % Makros mit Hilfe einer speziellen Syntax bestehend aus einzelnen
84 % Buchstaben zu beschreiben.
85 Just as with |xparse|, it is possible to use a special syntax consisting
86 of single letters to express the arguments of a macro.
87 %
88 % |lparse| ist jedoch im Stande unabhängig von der verwendeten
89 % Makrosammlung - ob LaTeX oder ConTeXt oder sogar Plain TeX - Argumente
90 % einzulesen.
91 However, |lparse| is able to read arguments regardless of the macro
92 systemd used - whether \LaTeX{} or Con\TeX{}t or even plain \TeX.
93 %
94 % Als Engine musst natürlich immer LuaTeX verwendet werden.
95 Of course, Lua\TeX{} must always be used as the engine.
96
97 \subsection*{Similar projects}
98
99 % Für ConTeXt gibt es einen ähnlichen Argumenten scanner.
100 For Con\TeX{}t there is a similar argument scanner (see Con\TeX{}t Lua
101 Document
102 \href{http://www.pragma-ade.nl/general/manuals/cld-mkiv.pdf}{cld-mkiv}).
103 %
104 % Dieser Scanner ist in folgenden Dateien implementiert
105 This scanner is implemented in the following files:
106 \href{https://github.com/contextgarden/context/blob/main/tex/context/base/mkiv/toks-scn.lua}{toks-scn.lua}
107 \href{https://github.com/contextgarden/context/blob/main/tex/context/base/mkiv/toks-aux.lua}{toks-aux.lua}
108 \href{https://github.com/contextgarden/context/blob/main/tex/context/base/mkiv/toks-ini.lua}{toks-ini.lua}
109 % Con\TeX{}t scanner verwendet offenbar die Token Bibliothek des LuaTeX Nachfolgeprojekts luametaTeX
110 %
111 Con\TeX{}t scanner apparently uses the token library of the LuaTeX
112 successor project luameta\TeX:
113 \href{https://github.com/contextgarden/context/blob/main/source/luametatex/source/lua/lmttokenlib.c}{lmttokenlib.c}
114
115 \section{The Lua API of \texttt{lparse}}
116
117 \subsection{Description of the argument specification}
118 %
119 % Folgende Listen, die die Argumenttypen beschreiben, entstammen den
120 % Handbücher usrguide bzw. xparse.
121 The following lists describing the argument types are
122 taken from the manuals
123 \href{http://mirrors.ctan.org/macros/latex/base/usrguide.pdf}{usrguide}
124 and
125 \href{http://mirrors.ctan.org/macros/latex/contrib/l3packages/xparse.pdf}{xparse}.
126 %
127 % Die Beschreibungstexte der einzelnen Argumententypen wurden nur leicht angepasst.
128 The descriptive texts of the individual argument types have only been
129 slightly adjusted.
130 %
131 % Die noch nicht unterstützen Argumentypen sind eingeklammert.
132 The argument types that are not yet supported are bracketed.
133
134 % /usr/local/texlive/texmf-dist/source/latex/l3packages/xparse/xparse.dtx
135 \begin{itemize}
136 \item[m] A standard mandatory argument, which can either be a single
137 token alone or multiple tokens surrounded by curly braces |{}|.
138 Regardless of the input, the argument will be passed to the
139 internal code without the outer braces. This is the \pkg{lparse}
140 type specifier for a normal \TeX{} argument.
141
142 \item[r] Given as \texttt{r}\meta{token1}\meta{token2}, this denotes a
143 \enquote{required} delimited argument, where the delimiters are
144 \meta{token1} and \meta{token2}. If the opening delimiter
145 \meta{token1} is missing, |nil| will be
146 returned after a suitable error.
147
148 \item[R] Given as \texttt{R}\meta{token1}\meta{token2}\marg{default},
149 this is a \enquote{required} delimited argument as for~\texttt{r},
150 but it has a user-definable recovery \meta{default} instead of
151 |nil|.
152
153 \item[v] Reads an argument \enquote{verbatim}, between the following
154 character and its next occurrence.
155
156 \color{gray}
157
158 \item[(b)] Not implemented! Only suitable in the argument specification of an
159 environment, it denotes the body of the environment, between
160 |\begin|\marg{environment} and |\end|\marg{environment}.
161
162 \end{itemize}
163 The types which define optional arguments are:
164 \begin{itemize}
165 \item[o] A standard \LaTeX{} optional argument, surrounded with square
166 brackets, which will supply
167 |nil| if not given (as described later).
168
169 \item[d] Given as \texttt{d}\meta{token1}\meta{token2}, an optional
170 argument which is delimited by \meta{token1} and \meta{token2}.
171 As with \texttt{o}, if no
172 value is given |nil| is returned.
173
174 \item[O] Given as \texttt{O}\marg{default}, is like \texttt{o}, but
175 returns \meta{default} if no value is given.
176
177 \item[D] Given as \texttt{D}\meta{token1}\meta{token2}\marg{default},
178 it is as for \texttt{d}, but returns \meta{default} if no value is given.
179 Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are
180 short-cuts to an appropriated-constructed \texttt{D} type argument.
181
182 \item[s] An optional star, which will result in a value
183 |true| if a star is present and |false|
184 otherwise (as described later).
185
186 \item[t] An optional \meta{token}, which will result in a value
187 |true| if \meta{token} is present and |false|
188 otherwise. Given as \texttt{t}\meta{token}.
189
190 \color{gray}
191
192 \item[(e)] Not implemented! Given as \texttt{e}\marg{tokens}, a set of optional
193 \emph{embellishments}, each of which requires a \emph{value}.
194 If an embellishment is not present, |-NoValue-| is returned. Each
195 embellishment gives one argument, ordered as for the list of
196 \meta{tokens} in the argument specification. All \meta{tokens}
197 must be distinct. \emph{This is an experimental type}.
198 \item[(E)] Not implemented! As for \texttt{e} but returns one or more \meta{defaults}
199 if values are not given: \texttt{E}\marg{tokens}\marg{defaults}.
200 \end{itemize}
201
202 \subsection{Function: \texttt{scan}}
203
204 \InputTex{luatex/function-scan.tex}
205
206 \subsection{Function: \texttt{register_csname(csname, fn, opts)}}
207
208 The function \lua{register_csname(csname, fn, opts)} registers a Lua
209 function under a control sequence name (csname). The first argument is
210 the control sequence name without the leading backslash. The second
211 argument is the Lua function to be called when the command name is
212 called in the TeX code.
213
214 \InputTex{luatex/function-register-csname.tex}
215
216
217 % Hilfsfunktionen
218 \subsection{Auxiliary functions}
219
220 %
221 % Einige Hilfsfunktionen werden in der Tabelle utils exportiert.
222 Some auxiliary functions are exported in the \lua{utils} table:
223
224 \begin{minted}{lua}
225 local lparse = require('lparse')
226
227 local parse_spec = lparse.utils.parse_spec
228 local scan_oarg = lparse.utils.scan_oarg
229 \end{minted}
230
231 %%
232 %
233 %%
234
235 \subsubsection*{Function: \texttt{utils.scan_oarg(init_delim, end_delim)}}
236
237 % Plain \TeX{} kennt keine optionalen Argumente (oarg).
238 Plain \TeX{} does not know optional arguments \oarg{oarg}.
239 %
240 % Die Funktion ermöglicht es nicht nur in \LaTeX{}, sondern auch in
241 % Plain \TeX{} nach optionalen Argumenten zu suchen.
242 The function \lua{scan_oarg} allows to search for optional arguments not only
243 in \LaTeX{} but also in Plain \TeX.
244 %
245 % Die Funktion basiert auf der Token-Bibliothek.
246 The function uses the token library built into Lua\TeX{}.
247 %
248 % Die beiden Parameter \lua{initial_delimiter} und \lua{end_delimiter}
249 % können weggelassen werden.
250 The two parameters \lua{init_delim} and \lua{end_delim} can
251 be omitted.
252 %
253 % Dann werden eckige Klammern als Begrenzungszeichen angenommen.
254 Then square brackets are assumed to be delimiters.
255 %
256 % \lua{utils.scan_oarg('(', ')')} sucht beispielsweise nach an einem
257 % optionalen Argument in runden Klammern.
258 \lua{utils.scan_oarg('(', ')')} searches for an optional argument in
259 round brackets, for example.
260 %
261 % Die Funktion gibt die Zeichenkette zwischen den Begrenzungszeichen
262 % zurück, oder nil wenn Begrenzungszeichen gefunden werden konnten.
263 The function returns the string between the delimiters or \lua{nil} if
264 no delimiters could be found.
265 %
266 % Die Begrenzungszeichen sind im Ergebnis nicht enthalten.
267 The delimiters themselves are not included in the result.
268 %
269 % Nach dem \latex{\directlua{}} darf das Makro, indem
270 % \lua{utils.scan_oarg} eingesetzt wird, zu keinen Zeichen expandieren.
271 After the \latex{\directlua{}}, the macro using \lua{scan_oarg}
272 must not expand to any characters.
273
274 \InputTex{luatex/function-utils.scan-oarg.tex}
275
276 \section{Known limitations}
277
278 % Im einigen Lua\LaTeX{} Umgebungen funktioniert das Scannen nach
279 % optionalen Argument (oargs) nicht.
280 In some Lua\LaTeX{} environments, scanning for optional arguments
281 (oargs) does not work.
282 % Ich weiß leider nicht warum.
283 Unfortunately I don't know why.
284 % Über Hilfe wäre ich sehr dankbar.
285 I would be very grateful for help.
286
287 \subsection{In tabular environment}
288
289 % Steht in einer |tabular|-Umgebung vor einem Kommando, der mit |lparse|
290 % gescannt wird, ein beliebert Text funktioniert es nicht, sonst schon.
291 In a |tabular| environment, if a command that is scanned with |lparse| is
292 preceded by any text, it does not work, otherwise it does.
293
294 \InputTex{lualatex/error-tabular.tex}
295
296 \subsection{In multline environment}
297
298 \InputTex{lualatex/error-multline.tex}
299
300 \clearpage
301
302 \section{Implementation}
303
304 The source code is hosted on
305 \href{https://github.com/Josef-Friedrich/lparse}{Github}. The
306 following links will take you to the individual files:
307
308 \begin{itemize}
309 \item \href{https://github.com/Josef-Friedrich/lparse/blob/main/lparse.lua}{lparse.lua}
310
311 \item \href{https://github.com/Josef-Friedrich/lparse/blob/main/lparse.sty}{lparse.sty}
312
313 \item \href{https://github.com/Josef-Friedrich/lparse/blob/main/lparse.tex}{lparse.tex}
314 \end{itemize}
315
316 \pagebreak
317 \PrintIndex
318 \end{document}