Debian Codegraph @

texmf-dist/source/latex/morewrites/primargs.dtx

raw
1 % \iffalse meta-comment
2 %
3 %% File: primargs.dtx Copyright (C) 2012-2024 Bruno Le Floch
4 %%
5 %% It may be distributed and/or modified under the conditions of the
6 %% LaTeX Project Public License (LPPL), either version 1.3c of this
7 %% license or (at your option) any later version. The latest version
8 %% of this license is in the file
9 %%
10 %% http://www.latex-project.org/lppl.txt
11 %%
12 %% This work has the LPPL maintenance status 'maintained'
13 %% and the current maintainer is Bruno Le Floch.
14 %% -----------------------------------------------------------------------
15 %
16 %<*driver>
17 \documentclass[full]{l3doc}
18 \newcommand{\proc}[1]{\texttt{#1}}
19 \begin{document}
20 \DocInput{\jobname.dtx}
21 \end{document}
22 %</driver>
23 % \fi
24 %
25 % \title{The \textsf{primargs} package: \\
26 % Parsing arguments of primitives}
27 % \author{Bruno Le Floch}
28 % \date{2024/02/02}
29 %
30 % \maketitle
31 % \tableofcontents
32 %
33 % \begin{documentation}
34 %
35 % \section{\pkg{primargs} documentation}
36 %
37 % This \TeX{} and \LaTeX{} package is currently used by \pkg{morewrites}
38 % when redefining primitives: it allows to read arguments of primitives
39 % in place of \TeX{}, which is useful to add hooks to primitives. Of
40 % course, this is much slower than letting \TeX{} do things directly.
41 %
42 % All assignments done by this package are global. While a negative
43 % value of the \tn{globaldefs} (primitive) parameter normally makes all
44 % assignments local, this package makes sure \tn{globaldefs} is
45 % non-negative before assignments.
46 %
47 % \subsection{Reading one token without removing it}
48 %
49 % \begin{variable}[tested = primargs001]{\g_primargs_token}
50 % The token read by \cs{primargs_read_token:N} or
51 % \cs{primargs_read_x_token:N}. Its value is always set globally.
52 % It can be an \tn{outer} macro.
53 % \end{variable}
54 %
55 % \begin{function}[tested = primargs001]{\primargs_read_token:N}
56 % \begin{syntax}
57 % \cs{primargs_read_token:N} \meta{function}
58 % \end{syntax}
59 % Sets \cs{g_primargs_token} equal to the token following the
60 % \meta{function}, then calls the \meta{function}. The token
61 % following the \meta{function} is not removed.
62 % \begin{texnote}
63 % This is essentially \tn{global} \tn{futurelet}
64 % \cs{g_primargs_token} \meta{function}, with the added guarantee
65 % that the assignment is global even when $\tn{globaldefs}$ is negative.
66 % \end{texnote}
67 % \end{function}
68 %
69 % \begin{function}[tested = primargs001]{\primargs_read_x_token:N}
70 % \begin{syntax}
71 % \cs{primargs_read_x_token:N} \meta{function}
72 % \end{syntax}
73 % Expands tokens recursively with \cs{exp_after:wN} until encountering
74 % a non-expandable token and afterwards calls the \meta{function}.
75 % The non-expandable token following the \meta{function} is not
76 % removed and \cs{g_primargs_token} is also set (globally) equal to
77 % that token.
78 % \end{function}
79 %
80 % \subsection{Removing tokens}
81 %
82 % \begin{function}[tested = primargs005]{\primargs_remove_token:N}
83 % \begin{syntax}
84 % \cs{primargs_remove_token:N} \meta{function}
85 % \end{syntax}
86 % Removes the \meta{token} which follows the \meta{function}, then
87 % calls the \meta{function}. This also sets \cs{g_primargs_token}
88 % (globally) equal to the removed token.
89 % \end{function}
90 %
91 % \begin{function}[tested = primargs005]{\primargs_remove_one_optional_space:N}
92 % \begin{syntax}
93 % \cs{primargs_remove_one_optional_space:N} \meta{function}
94 % \end{syntax}
95 % Expands tokens following the \meta{function} until a non-expandable
96 % token is found, and sets \cs{g_primargs_token} (globally) equal to this token,
97 % then removes the token if it has catcode~$10$ (space). Finally,
98 % call the \meta{function}.
99 % \end{function}
100 %
101 % \begin{function}[tested = primargs005]{\primargs_remove_optional_spaces:N}
102 % \begin{syntax}
103 % \cs{primargs_remove_optional_spaces:N} \meta{function}
104 % \end{syntax}
105 % Expands tokens following the \meta{function}, removing any token
106 % with catcode~$10$ (space), then sets \cs{g_primargs_token} (globally) equal to
107 % the first non-space token and calls the \meta{function}.
108 % \end{function}
109 %
110 % \begin{function}[tested = primargs005]{\primargs_remove_equals:N}
111 % \begin{syntax}
112 % \cs{primargs_remove_equals:N} \meta{function}
113 % \end{syntax}
114 % Expands tokens following the \meta{function}, removing any token
115 % with catcode~$10$ (space), then sets \cs{g_primargs_token} (globally) equal to
116 % the first non-space token. If this token is an explicit~|=|
117 % character token with catcode~$12$ (other), then it is removed as
118 % well. Finally, calls the \meta{function}.
119 % \end{function}
120 %
121 % \begin{function}[added = 2014-08-06, tested = primargs005]{\primargs_remove_filler:N}
122 % \begin{syntax}
123 % \cs{primargs_remove_filler:N} \meta{function}
124 % \end{syntax}
125 % Expands tokens following the \meta{function}, removing any token
126 % with catcode~$10$ (space) or equal to \tn{relax}, then sets
127 % \cs{g_primargs_token} (globally) equal to the next
128 % token. Finally, calls the \meta{function}.
129 % \end{function}
130 %
131 % \subsection{Grabbing arguments}
132 %
133 % \begin{function}[tested = primargs002]
134 % {
135 % \primargs_get_number:N,
136 % \primargs_get_dimen:N,
137 % \primargs_get_glue:N,
138 % \primargs_get_mudimen:N,
139 % \primargs_get_muglue:N,
140 % }
141 % \begin{syntax}
142 % \cs{primargs_get_number:N} \meta{function}
143 % \end{syntax}
144 % Reads a number/dimension/glue/math dimension/math glue following the
145 % \meta{function}, then calls the \meta{function} with a braced
146 % argument containing the value found. For instance,
147 % \begin{verbatim}
148 % \primargs_get_glue:N \test 3sp plus \numexpr 2-3 fill X
149 % \end{verbatim}
150 % yields
151 % \begin{verbatim}
152 % \test {3sp plus -1fill}X
153 % \end{verbatim}
154 % A word of warning: the \cs{primargs_get_mudimen:N} function
155 % currently parses a \meta{muskip} instead of a \meta{mudimen}.
156 % \end{function}
157 %
158 % \begin{function}[updated = 2014-08-06, tested = primargs003]
159 % {\primargs_get_general_text:N}
160 % \begin{syntax}
161 % \cs{primargs_get_general_text:N} \meta{function}
162 % \end{syntax}
163 % Finds what \TeX{}'s grammar calls a \meta{general text} (that is, a
164 % \meta{filler}, a catcode~$1$ token, a \meta{balanced text}, and an
165 % explicit catcode~$2$ token) following the \meta{function}, and calls
166 % the \meta{function} with the \meta{balanced text} as a braced
167 % argument.
168 % \end{function}
169 %
170 % \begin{function}[updated = 2024-01-05, tested = primargs004]{\primargs_get_file_name:N, \primargs_get_input_file_name:N}
171 % \begin{syntax}
172 % \cs{primargs_get_file_name:N} \meta{function}
173 % \cs{primargs_get_input_file_name:N} \meta{function}
174 % \end{syntax}
175 % Reads a \meta{file name} following the \meta{function} and calls the
176 % \meta{function} with this \meta{file name} as a braced argument.
177 % The first function only allows for the historical unbraced file
178 % names that plain \TeX{} supports. The second one also allows braced
179 % file names. Historically this was first supported in \LuaTeX{} for
180 % \tn{input} and related primitives, hence the name. Now all main
181 % engines (in \TeX{}Live at least) support both syntaxes for all
182 % primitives that take file names.
183 % \begin{texnote}
184 % When braced file names are disallowed, the file name is obtained
185 % by discarding \meta{optional spaces} then repeatedly doing the
186 % following. Fully expand what follows in the input stream. If
187 % the next token is an explicit or implicit character token
188 % (regardless of its catcode) then add that character to the
189 % file name and remove it from the input stream, and go back to
190 % expanding tokens, except in one case: if the character code
191 % is~$32$ (space) and the number of quote characters (code~$34$)
192 % already in the file name is even, then the space is removed from
193 % the input stream, not included in the file name, and parsing
194 % ends. Finally, if the next token is a non-expandable command
195 % (be it a control sequence or an active character) then the file
196 % name ends and the command is left in the input stream.
197 %
198 % When braced file names are allowed, the following steps are added
199 % prior to the procedure above. First remove a \meta{filler}. If
200 % the next token is of catcode~$1$ then fully expand tokens one by
201 % one and add their string representation (with \cs{tl_to_str:n},
202 % not \cs{token_to_str:N}) to the file name.
203 % \end{texnote}
204 % \end{function}
205 %
206 % \subsection{Comments}
207 %
208 % This package is not idiomatic \pkg{expl3} and should not be used as an
209 % example of good coding practices. It uses \cs[no-index]{\ldots{}:D}
210 % primitives directly:
211 % \begin{itemize}
212 % \item to cope with \tn{outer} tokens, since this package is meant to
213 % be used quite broadly;
214 % \item for primitives with (rightfully) no \pkg{expl3} interface (or a
215 % slightly incomplete interface), namely \tn{afterassignment},
216 % \tn{globaldefs}, \tn{aftergroup}, \tn{the}, \tn{deadcycles},
217 % \tn{hoffset}, \tn{topskip}, \tn{thinmuskip}, \tn{unexpanded};
218 % \item to test that a token's meaning is a given primitive when the
219 % \pkg{expl3} interface is not (or not obviously) a copy of the primitive.
220 % \end{itemize}
221 % As a result, \emph{do not take this package as an example of how to
222 % code with \pkg{expl3}; go and see Joseph Wright's \pkg{siunitx} for
223 % instance.}
224 %
225 % Despite large efforts expended to make this package robust against
226 % changes to the \tn{globaldefs} parameter, setting it to a non-zero
227 % value may make some parts of this package crash.
228 %
229 % Tokens inserted using \tn{afterassignment} may be lost when using this
230 % package, since it uses \tn{afterassignment} internally.
231 %
232 % Todo list.
233 % \begin{itemize}
234 % \item Test all functions within alignments and understand their
235 % interaction with the master counter.
236 % \item Correct the parsing of \meta{mudimen}.
237 % \item Perhaps parse \meta{muglue} and \meta{glue} by hand to avoid bad
238 % interactions with \tn{globaldefs}. Otherwise put up a warning about
239 % \tn{globaldefs} when relevant. Better partial fix: declare a skip and a muskip.
240 % \item Write tests of engine behaviour, especially \LuaTeX{}'s \tn{input},
241 % \tn{openin}, \tn{openout} including behaviour of |#| and spaces and
242 % character-code-zero, to detect unexpected changes. In
243 % \tn{input}|{|\ldots{}\tn{input}\ldots{}|}|, \LuaTeX{} expands the
244 % inner \tn{input} but uses the inner file name as the outer file name.
245 % \end{itemize}
246 %
247 % \end{documentation}
248 %
249 % \begin{implementation}
250 %
251 % \section{\pkg{primargs} implementation}
252 %
253 %<*package>
254 % \begin{macrocode}
255 \ProvidesExplPackage
256 {primargs} {2024/02/02} {} {Parsing arguments of primitives}
257 % \end{macrocode}
258 %
259 % \begin{macrocode}
260 %<@@=primargs>
261 % \end{macrocode}
262 %
263 % \begin{function}{\@@_get_rhs:NnN, \@@_get_rhs:NoN}
264 % \begin{syntax}
265 % \cs{@@_get_rhs:NnN} \meta{register} \Arg{register rhs} \meta{function}
266 % \end{syntax}
267 % Use the \meta{register} to find a right-hand side of a valid
268 % assignment for this type of variable, and feed the value found to
269 % the \meta{function}. The value of the \meta{register} is then
270 % restored using \meta{register} |=| \meta{register rhs}, where the
271 % \meta{register rhs} should be the initial value of the
272 % \meta{register}. All those assignments are performed within a
273 % group, but some are automatically global, and \tn{globaldefs} may
274 % cause trouble with others.
275 % \end{function}
276 %
277 % \subsection{Variables and helpers}
278 %
279 % \begin{macro}{\g_@@_code_tl}
280 % Used to contain temporary code.
281 % \begin{macrocode}
282 \tl_new:N \g_@@_code_tl
283 % \end{macrocode}
284 % \end{macro}
285 %
286 % \begin{variable}{\g_@@_file_name_tl, \g_@@_file_name_level_tl}
287 % Token list used to build a file name, one character at a time.
288 % Token list holding the level of nesting in quotes or braces.
289 % \begin{macrocode}
290 \tl_new:N \g_@@_file_name_tl
291 \tl_new:N \g_@@_file_name_level_tl
292 % \end{macrocode}
293 % \end{variable}
294 %
295 % \begin{macro}{\@@_safe:}
296 % This function, which must be called in a group, cancels any
297 % \tn{afterassignment} token and makes the \tn{globaldefs} parameter
298 % non-negative. This ensures that assignments prefixed with
299 % \tn{global} are indeed global. When \tn{globaldefs} is positive,
300 % every assignment is global, and it is not possible to safely
301 % (locally) set it to zero.
302 % \begin{macrocode}
303 \cs_new_protected:Npn \@@_safe:
304 {
305 \tex_afterassignment:D \tex_relax:D
306 \if_int_compare:w 0 > \tex_globaldefs:D
307 \int_zero:N \tex_globaldefs:D
308 \fi:
309 }
310 % \end{macrocode}
311 % \end{macro}
312 %
313 % \subsection{Read token with or without expansion}
314 %
315 % \TeX{} often calls the \proc{get_x_token} procedure when parsing
316 % various parts of its grammar. This expands tokens recursively until
317 % reaching a non-expandable token. We emulate this by reading the next
318 % token with \tn{futurelet}, checking whether it is expandable or not by
319 % comparing its meaning to its meaning when acted upon by \tn{noexpand},
320 % and expanding it with \tn{expandafter} if it is expandable.
321 %
322 % One thing to be careful about is that
323 % \begin{quote}
324 % \tn{expandafter} \tn{show} \tn{noexpand} \tn{space}
325 % \end{quote}
326 % shows the \tn{meaning} of the |\notexpanded: \space|,
327 % namely \tn{relax} (frozen, in fact, hence a bit different from the
328 % normal \tn{relax}), while expanding twice with
329 % \begin{quote}
330 % \tn{expandafter} \tn{expandafter} \tn{expandafter} \tn{show}
331 % \tn{noexpand} \tn{space}
332 % \end{quote}
333 % expands the \tn{space} to the underlying space character token.
334 % What this means is that we must first check if the token is expandable
335 % or not, and only then expand, and that the token should not be queried
336 % again using \tn{futurelet}. On this latter point, run
337 % \begin{verbatim}
338 % \def \test { \show \next \futurelet \next \test }
339 % \expandafter \test \noexpand \space
340 % \end{verbatim}
341 % to see how \tn{next} changes from \tn{relax} to becoming a macro.
342 %
343 % \begin{macro}{\primargs_read_x_token:N}
344 % \begin{macro}
345 % {
346 % \@@_read_x_token:N, \@@_read_x_token_aux:N,
347 % \@@_read_x_token_std:N, \@@_read_x_token_file:N
348 % }
349 % This is a bit messy, because we need to support the fact that
350 % \TeX{} does not consider \tn{input} as expandable when it is
351 % looking for a file name. This variation is encapsulated by
352 % letting \cs{@@_read_x_token_aux:N} equal to either a standard
353 % (\texttt{std}) version or a version specific to file names
354 % (\texttt{file}).
355 %
356 % First query the following token. Then test whether it is
357 % expandable, using a variant of the \cs{token_if_expandable:NTF}
358 % test.\footnote{This \LaTeX3 test returns \texttt{false} for
359 % undefined tokens (by design), but \TeX{}'s \proc{get_x_token}
360 % expands those undefined tokens, causing errors, so we should as
361 % well.} If the token is expandable, \cs{exp_not:N} will change its
362 % \tn{meaning} to \tn{relax}, the test is \texttt{false}, we expand,
363 % and call the loop. Otherwise, we stop. In the \texttt{file}
364 % version there is an extra test for \cs{tex_input:D}. By default
365 % use the standard version.
366 % \begin{macrocode}
367 \cs_new_protected:Npn \primargs_read_x_token:N
368 {
369 \group_begin:
370 \@@_safe:
371 \@@_read_x_token:N
372 }
373 \cs_new_protected:Npn \@@_read_x_token:N
374 {
375 \tex_afterassignment:D \@@_read_x_token_aux:N
376 \tex_global:D \tex_futurelet:D \g_primargs_token
377 }
378 \cs_new_protected:Npn \@@_read_x_token_std:N
379 {
380 \exp_after:wN
381 \if_meaning:w \exp_not:N \g_primargs_token \g_primargs_token
382 \group_end: \use_i:nnnn
383 \fi:
384 \exp_after:wN \@@_read_x_token:N \exp_after:wN
385 }
386 \cs_new_eq:NN \@@_read_x_token_aux:N
387 \@@_read_x_token_std:N
388 \cs_new_protected:Npn \@@_read_x_token_file:N
389 {
390 \if_meaning:w \tex_input:D \g_primargs_token
391 \use_i_ii:nnn \group_end:
392 \fi:
393 \@@_read_x_token_std:N
394 }
395 % \end{macrocode}
396 % \end{macro}
397 % \end{macro}
398 %
399 % \begin{macro}{\primargs_read_token:N}
400 % The same without expansion, useful for instance when we already know
401 % that what follows is expanded. Interestingly, we don't ever need to
402 % take the user's function as an argument.
403 % \begin{macrocode}
404 \cs_new_protected:Npn \primargs_read_token:N
405 {
406 \group_begin:
407 \@@_safe:
408 \tex_afterassignment:D \group_end:
409 \tex_global:D \tex_futurelet:D \g_primargs_token
410 }
411 % \end{macrocode}
412 % \end{macro}
413 %
414 % \subsection{Removing tokens}
415 %
416 % \begin{macro}{\primargs_remove_token:N}
417 % Remove token using \tn{let} (note the presence of |=| and a space,
418 % to correctly remove explicit space characters), then insert the
419 % \meta{function} after closing the group.
420 % \begin{macrocode}
421 \cs_new_protected:Npn \primargs_remove_token:N #1
422 {
423 \group_begin:
424 \@@_safe:
425 \tex_aftergroup:D #1
426 \tex_afterassignment:D \group_end:
427 \tex_global:D \tex_let:D \g_primargs_token = ~
428 }
429 % \end{macrocode}
430 % \end{macro}
431 %
432 % \begin{macro}{\primargs_remove_one_optional_space:N}
433 % \begin{macro}{\@@_remove_one_optional_space:}
434 % Start a group: we will insert the \meta{function} at its end.
435 % \begin{macrocode}
436 \cs_new_protected:Npn \primargs_remove_one_optional_space:N #1
437 {
438 \group_begin:
439 \@@_safe:
440 \tex_aftergroup:D #1
441 \primargs_read_x_token:N \@@_remove_one_optional_space:
442 }
443 \cs_new_protected:Npn \@@_remove_one_optional_space:
444 {
445 \if_catcode:w \c_space_token \exp_not:N \g_primargs_token
446 \exp_after:wN \primargs_remove_token:N
447 \fi:
448 \group_end:
449 }
450 % \end{macrocode}
451 % \end{macro}
452 % \end{macro}
453 %
454 % \begin{macro}{\primargs_remove_optional_spaces:N}
455 % \begin{macro}
456 % {\@@_remove_optional_spaces:, \@@_remove_optional_spaces_aux:}
457 % Start a group, make assignments safe, then recursively expand tokens
458 % and remove any token with catcode~$10$ (space). Once another token
459 % is found, close the group hence insert the \meta{function}~|#1|.
460 % \begin{macrocode}
461 \cs_new_protected:Npn \primargs_remove_optional_spaces:N #1
462 {
463 \group_begin:
464 \@@_safe:
465 \tex_aftergroup:D #1
466 \@@_remove_optional_spaces:
467 }
468 \cs_new_protected:Npn \@@_remove_optional_spaces:
469 { \primargs_read_x_token:N \@@_remove_optional_spaces_aux: }
470 \cs_new_protected:Npn \@@_remove_optional_spaces_aux:
471 {
472 \if_catcode:w \c_space_token \exp_not:N \g_primargs_token
473 \exp_after:wN \primargs_remove_token:N
474 \exp_after:wN \@@_remove_optional_spaces:
475 \else:
476 \exp_after:wN \group_end:
477 \fi:
478 }
479 % \end{macrocode}
480 % \end{macro}
481 % \end{macro}
482 %
483 % \begin{macro}{\primargs_remove_equals:N}
484 % \begin{macro}{\@@_remove_equals:, \@@_remove_equals_aux:NN}
485 % Remove \meta{optional spaces}, then test for an explicit~|=|, both
486 % in \tn{meaning} and as a token list: once we know its \tn{meaning},
487 % we can grab it safely.
488 % \begin{macrocode}
489 \cs_new_protected:Npn \primargs_remove_equals:N #1
490 {
491 \group_begin:
492 \tex_aftergroup:D #1
493 \primargs_remove_optional_spaces:N \@@_remove_equals:
494 }
495 \cs_new_protected:Npn \@@_remove_equals:
496 {
497 \if_meaning:w = \g_primargs_token
498 \exp_after:wN \@@_remove_equals_aux:NN
499 \fi:
500 \group_end:
501 }
502 \cs_new_protected:Npn \@@_remove_equals_aux:NN #1#2
503 { \tl_if_eq:nnTF { #2 } { = } { #1 } { #1 #2 } }
504 % \end{macrocode}
505 % \end{macro}
506 % \end{macro}
507 %
508 % \begin{macro}{\primargs_remove_filler:N}
509 % \begin{macro}
510 % {
511 % \@@_remove_filler:,
512 % \@@_remove_filler_aux:,
513 % \@@_remove_filler_end:NNNNN
514 % }
515 % Within a group remove a \meta{filler}, and insert the user's |#1|
516 % after closing the group. A \meta{filler} consists of tokens with
517 % catcode~$10$ (space) or equal to \tn{relax} or to the
518 % \enquote{frozen \tn{relax}} command.
519 % \begin{macrocode}
520 \cs_new_protected:Npn \primargs_remove_filler:N #1
521 {
522 \group_begin:
523 \@@_safe:
524 \tex_aftergroup:D #1
525 \@@_remove_filler:
526 }
527 \cs_new_protected:Npn \@@_remove_filler:
528 { \primargs_read_x_token:N \@@_remove_filler_aux: }
529 \cs_new_protected:Npn \@@_remove_filler_aux:
530 {
531 \if_catcode:w \c_space_token \exp_not:N \g_primargs_token
532 \else:
533 \if_meaning:w \tex_relax:D \g_primargs_token
534 \else:
535 \exp_after:wN
536 \if_meaning:w \exp_not:N \prg_do_nothing: \g_primargs_token
537 \else:
538 \@@_remove_filler_end:NNNNN
539 \fi:
540 \fi:
541 \fi:
542 \primargs_remove_token:N \@@_remove_filler:
543 }
544 \cs_new_protected:Npn \@@_remove_filler_end:NNNNN #1#2#3#4#5
545 { #1 #2 #3 \group_end: }
546 % \end{macrocode}
547 % \end{macro}
548 % \end{macro}
549 %
550 % \subsection{Right-hand sides of assignments}
551 %
552 % The naive approach to reading an integer, or a general text, is to let
553 % \TeX{} perform an assignment to a \tn{count}, or a \tn{toks}, register
554 % and regain control using \tn{afterassignment}. The question is then
555 % to know which \tn{count} or \tn{toks} register to use. One might
556 % think that any can be used as long as the assignment happens in a
557 % group.
558 %
559 % However, there comes the question of the \tn{globaldefs} parameter.
560 % If this parameter is positive, every assignment is global, including
561 % assignments to the parameter itself, preventing us from setting it to
562 % zero locally; hence, we are stuck with global assignments (if
563 % \tn{globaldefs} is negative, we can change it, locally, to whatever
564 % value pleases us, as done by \cs{@@_safe:}). We may thus not
565 % use scratch registers to parse integers, general texts, and other
566 % pieces of \TeX{}'s grammar.
567 %
568 % For integers, we will use \tn{deadcycles}, a parameter which is
569 % automatically assigned globally, and we revert it to its previous
570 % value afterwards.
571 %
572 % \begin{macro}{\@@_get_rhs:NnN, \@@_get_rhs:NoN}
573 % The last two lines of this function are the key: assign to |#1|,
574 % then take control using \tn{afterassignment}. After the assignment,
575 % we expand the value found, |\tex_the:D #1|, within a brace group,
576 % then restore |#1| using its initial value |#2|, and end the group.
577 % The earlier use of \cs{tex_aftergroup:D} inserts the \meta{function}
578 % |#3| before the brace group containing the value found.
579 % \begin{macrocode}
580 \cs_new_protected:Npn \@@_get_rhs:NnN #1#2#3
581 {
582 \group_begin:
583 \@@_safe:
584 \tex_aftergroup:D #3
585 \tl_gset:Nn \g_@@_code_tl
586 {
587 \use:x
588 {
589 \exp_not:n { #1 = #2 \group_end: }
590 { \tex_the:D #1 }
591 }
592 }
593 \tex_afterassignment:D \g_@@_code_tl
594 #1 =
595 }
596 \cs_generate_variant:Nn \@@_get_rhs:NnN { No }
597 % \end{macrocode}
598 % \end{macro}
599 %
600 % \begin{macro}{\primargs_get_number:N}
601 % We use the general \cs{@@_get_rhs:NoN}, using the internal register
602 % \tn{deadcycles}, for which all assignments are global: thus,
603 % restoring its value will not interact badly with groups.
604 % \begin{macrocode}
605 \cs_new_protected:Npn \primargs_get_number:N
606 {
607 \@@_get_rhs:NoN \tex_deadcycles:D
608 { \tex_the:D \tex_deadcycles:D }
609 }
610 % \end{macrocode}
611 % \end{macro}
612 %
613 % \begin{macro}{\primargs_get_dimen:N}
614 % Use \tn{hoffset} as a register since it is not too likely to be
615 % changed locally (anyways, which register we use is not that
616 % important since normally, \tn{globaldefs} is zero, and everything is
617 % done within a group).
618 % \begin{macrocode}
619 \cs_new_protected:Npn \primargs_get_dimen:N
620 {
621 \@@_get_rhs:NoN \tex_hoffset:D
622 { \tex_the:D \tex_hoffset:D }
623 }
624 % \end{macrocode}
625 % \end{macro}
626 %
627 % \begin{macro}{\primargs_get_glue:N}
628 % Use \tn{topskip}.
629 % \begin{macrocode}
630 \cs_new_protected:Npn \primargs_get_glue:N
631 {
632 \@@_get_rhs:NoN \tex_topskip:D
633 { \tex_the:D \tex_topskip:D }
634 }
635 % \end{macrocode}
636 % \end{macro}
637 %
638 % \begin{macro}{\primargs_get_mudimen:N}
639 % There is no such thing as a \meta{mudimen variable}, so we're on our
640 % own to parse a \meta{mudimen}. Warn about that problem, and parse a
641 % \meta{muglue} instead.
642 % \begin{macrocode}
643 \cs_new_protected:Npn \primargs_get_mudimen:N
644 {
645 \msg_warning:nn { primargs } { get-mudimen }
646 \primargs_get_muglue:N
647 }
648 \msg_new:nnn { primargs } { get-mudimen }
649 { The~\iow_char:N\\primargs_get_mudimen:N~function~is~buggy. }
650 % \end{macrocode}
651 % \end{macro}
652 %
653 % \begin{macro}{\primargs_get_muglue:N}
654 % Use \tn{thinmuskip}.
655 % \begin{macrocode}
656 \cs_new_protected:Npn \primargs_get_muglue:N
657 {
658 \@@_get_rhs:NoN \tex_thinmuskip:D
659 { \tex_the:D \tex_thinmuskip:D }
660 }
661 % \end{macrocode}
662 % \end{macro}
663 %
664 % \begin{macro}{\primargs_get_general_text:N}
665 % \begin{macro}
666 % {\@@_get_general_text:, \@@_get_general_text_error:n}
667 % Getting a \meta{general text} is more tricky, as an assignment to
668 % \tn{errhelp} (for instance) would also allow constructions such as
669 % |\toks0|. Instead, we remove a \meta{filler} then test whether the
670 % next token (already expanded) is a catcode~$1$ token, in which case
671 % we replace it by an explicit left brace before calling the function.
672 % When the next token is not of catcode~$1$, we produce an error,
673 % attempting to imitate as closely as possible the \TeX{} error.
674 % \begin{macrocode}
675 \cs_new_protected:Npn \primargs_get_general_text:N #1
676 {
677 \group_begin:
678 \@@_safe:
679 \tex_aftergroup:D #1
680 \tex_aftergroup:D { \if_false: } \fi:
681 \primargs_remove_filler:N \@@_get_general_text:
682 }
683 \cs_new_protected:Npn \@@_get_general_text:
684 {
685 \if_catcode:w \c_group_begin_token \g_primargs_token
686 \exp_after:wN \primargs_remove_token:N
687 \else:
688 \group_begin:
689 \tex_aftergroup:D \@@_get_general_text_error:n
690 \if_catcode:w \c_group_end_token \g_primargs_token
691 \tex_aftergroup:D {
692 \tex_aftergroup:D }
693 \fi:
694 \fi:
695 \group_end:
696 }
697 \cs_new_protected:Npn \@@_get_general_text_error:n #1
698 {
699 \exp_after:wN \group_end:
700 \tex_unexpanded:D \if_int_compare:w `{ = \c_zero_int \fi: #1 }
701 }
702 % \end{macrocode}
703 % \end{macro}
704 % \end{macro}
705 %
706 % \subsection{Get file name}
707 %
708 % \begin{macro}{\primargs_get_file_name:N}
709 % Empty the file name (globally), and build it one character at a time.
710 % The \meta{function} is added at the end of a group, started here.
711 % As described in the \TeX{}book, a \meta{file name} should start with
712 % \meta{optional spaces} (\LuaTeX{} changes that to \meta{filler}),
713 % which we remove, then character tokens,
714 % ending with a non-expandable character or control sequence. After
715 % space removal, \cs{g_primargs_token} contains the next token, so no
716 % need for \cs{primargs_read_token:N}.
717 % When \TeX{} reads a file name, the \tn{input} primitive is
718 % temporarily not expandable, so we temporarily change
719 % \cs{primargs_read_x_token:N} to not expand this primitive. This is
720 % reverted by \cs{@@_get_file_name_end:}.
721 % \begin{macrocode}
722 \cs_new_protected:Npn \primargs_get_file_name:N #1
723 {
724 \group_begin:
725 \@@_safe:
726 \cs_gset_eq:NN \@@_read_x_token_aux:N
727 \@@_read_x_token_file:N
728 \tex_aftergroup:D #1
729 \tl_gclear:N \g_@@_file_name_tl
730 \tl_gset:Nn \g_@@_file_name_level_tl { 0 }
731 \primargs_remove_optional_spaces:N \@@_get_file_name_test:
732 }
733 % \end{macrocode}
734 % \end{macro}
735 %
736 % \begin{macro}{\@@_get_file_name_test:}
737 % The token read is in \cs{g_primargs_token}, and is non-expandable.
738 % If it is a control sequence, end the \meta{file name}. Spaces are
739 % special (quotes too, but that is treated elsewhere). Otherwise,
740 % we extract the character from the \tn{meaning} of the \meta{token},
741 % which we remove anyways: in that case, we'll recurse.
742 % \begin{macrocode}
743 \cs_new_protected:Npn \@@_get_file_name_test:
744 {
745 \token_if_cs:NTF \g_primargs_token
746 { \@@_get_file_name_end: }
747 {
748 \token_if_eq_charcode:NNTF \c_space_token \g_primargs_token
749 { \primargs_remove_token:N \@@_get_file_name_space: }
750 { \primargs_remove_token:N \@@_get_file_name_char: }
751 }
752 }
753 % \end{macrocode}
754 % \end{macro}
755 %
756 % \begin{macro}{\@@_get_file_name_end:}
757 % When the end of the file name is reached, reinstate the original
758 % definition of |read_x_token| so as to make \tn{input} expandable
759 % again, then end the group, after
760 % expanding the contents of \cs{g_@@_file_name_tl}.
761 % \begin{macrocode}
762 \cs_new_protected:Npn \@@_get_file_name_end:
763 {
764 \cs_gset_eq:NN \@@_read_x_token_aux:N
765 \@@_read_x_token_std:N
766 \exp_args:No \group_end: \g_@@_file_name_tl
767 }
768 % \end{macrocode}
769 % \end{macro}
770 %
771 % \begin{macro}{\@@_get_file_name_space:}
772 % We have already removed the space from the input stream. If
773 % there is an odd number of quotes so far, add a space to the
774 % file name and continue. Otherwise the file name ends.
775 % \begin{macrocode}
776 \cs_new_protected:Npn \@@_get_file_name_space:
777 {
778 \int_if_odd:nTF { \g_@@_file_name_level_tl }
779 {
780 \tl_gput_right:Nn \g_@@_file_name_tl { ~ }
781 \primargs_read_x_token:N \@@_get_file_name_test:
782 }
783 { \@@_get_file_name_end: }
784 }
785 % \end{macrocode}
786 % \end{macro}
787 %
788 % \begin{macro}{\@@_get_file_name_char:}
789 % \begin{macro}[EXP]
790 % {\@@_get_file_name_char_ii:w, \@@_get_file_name_char_iii:w}
791 % Check for a quote, which switches \cs{g_@@_file_name_level_tl}
792 % from $0$ to $1$ or back.
793 % With an explicit character, applying \tn{string} would give the
794 % character code. Here, implicit characters have to be converted too,
795 % so we must work with the \tn{meaning}, which is two or three words
796 % separated by spaces, then the character. The \texttt{ii} auxiliary
797 % removes the first two words, and duplicates the remainder (either
798 % one character, or a word and a character), and the second auxiliary
799 % leaves the second piece in the definition (in both cases, the
800 % character). Then loop with expansion. This technique would fail if
801 % the character could be a space (character code~$32$).
802 % \begin{macrocode}
803 \cs_new_protected:Npn \@@_get_file_name_char:
804 {
805 \token_if_eq_charcode:NNT " \g_primargs_token % "
806 {
807 \tl_gset:Nx \g_@@_file_name_level_tl
808 { \int_eval:n { 1 - \g_@@_file_name_level_tl } }
809 }
810 \tl_gput_right:Nx \g_@@_file_name_tl
811 {
812 \exp_after:wN \@@_get_file_name_char_ii:w
813 \token_to_meaning:N \g_primargs_token
814 \q_stop
815 }
816 \primargs_read_x_token:N \@@_get_file_name_test:
817 }
818 \cs_new:Npn \@@_get_file_name_char_ii:w #1 ~ #2 ~ #3 \q_stop
819 { \@@_get_file_name_char_iii:w #3 ~ #3 ~ \q_stop }
820 \cs_new:Npn \@@_get_file_name_char_iii:w #1 ~ #2 ~ #3 \q_stop {#2}
821 % \end{macrocode}
822 % \end{macro}
823 % \end{macro}
824 %
825 % \begin{macro}{\primargs_get_input_file_name:N}
826 % \begin{macro}
827 % {
828 % \@@_get_input_file_name_first:,
829 % \@@_get_input_file_name_loop:, \@@_get_input_file_name_test:,
830 % \@@_get_input_file_name_brace:, \@@_get_input_file_name_aux:N
831 % }
832 % In addition to file names detected by \cs{primargs_get_file_name:N}
833 % this allows for braced file names. The weird indentation is because
834 % historically we had to distinguish \LuaTeX{}, allowing braced file
835 % names, from other engines.
836 % We test for a catcode $1$ token (after a filler) then
837 % expand and collect tokens (turned to strings) one by one, counting
838 % begin-group and end-group tokens in \cs{g_@@_file_name_level_tl}.
839 % The control sequence \tn{par} is ignored. After removing a filler
840 % or after expansion, \cs{g_primargs_token} cannot be \tn{outer} hence
841 % the tests are safe. We use primitives to cope with outer macro
842 % hidden by \tn{noexpand} upon first expansion.
843 % \begin{macrocode}
844 \cs_new_protected:Npn \primargs_get_input_file_name:N #1
845 {
846 \group_begin:
847 \@@_safe:
848 \tex_aftergroup:D #1
849 \tl_gclear:N \g_@@_file_name_tl
850 \tl_gset:Nn \g_@@_file_name_level_tl { 1 }
851 \primargs_remove_filler:N \@@_get_input_file_name_first:
852 }
853 \cs_new_protected:Npn \@@_get_input_file_name_first:
854 {
855 \token_if_eq_catcode:NNTF \g_primargs_token \c_group_begin_token
856 { \primargs_remove_token:N \@@_get_input_file_name_loop: }
857 { \primargs_get_file_name:N \group_end: }
858 }
859 \cs_new_protected:Npn \@@_get_input_file_name_loop:
860 { \primargs_read_x_token:N \@@_get_input_file_name_test: }
861 \cs_new_protected:Npn \@@_get_input_file_name_test:
862 {
863 \token_if_eq_catcode:NNTF \g_primargs_token \c_group_begin_token
864 {
865 \tl_gset:Nx \g_@@_file_name_level_tl
866 { \int_eval:n { \g_@@_file_name_level_tl + 1 } }
867 \primargs_remove_token:N \@@_get_input_file_name_brace:
868 }
869 {
870 \token_if_eq_catcode:NNTF \g_primargs_token \c_group_end_token
871 {
872 \tl_gset:Nx \g_@@_file_name_level_tl
873 { \int_eval:n { \g_@@_file_name_level_tl - 1 } }
874 \int_compare:nNnTF { \g_@@_file_name_level_tl } > 0
875 { \primargs_remove_token:N \@@_get_input_file_name_brace: }
876 { \primargs_remove_token:N \@@_get_file_name_end: }
877 }
878 {
879 \token_if_eq_meaning:NNTF \g_primargs_token \c_space_token
880 {
881 \tl_gput_right:Nn \g_@@_file_name_tl { ~ }
882 \primargs_remove_token:N \@@_get_input_file_name_loop:
883 }
884 { \exp_after:wN \@@_get_input_file_name_aux:N \exp_not:N }
885 }
886 }
887 }
888 \cs_new_protected:Npn \@@_get_input_file_name_brace:
889 {
890 \tl_gput_right:Nx \g_@@_file_name_tl
891 {
892 \exp_after:wN \@@_get_file_name_char_ii:w
893 \token_to_meaning:N \g_primargs_token
894 \q_stop
895 }
896 \@@_get_input_file_name_loop:
897 }
898 \cs_new_protected:Npn \@@_get_input_file_name_aux:N #1
899 {
900 \exp_after:wN \str_if_eq:eeT
901 \exp_after:wN { \token_to_str:N #1 } { \token_to_str:N \par }
902 { \use_none:nnn }
903 \tex_xdef:D \g_@@_file_name_tl
904 {
905 \g_@@_file_name_tl
906 \exp_after:wN \tl_to_str:n \exp_after:wN { \exp_not:N #1 }
907 }
908 \@@_get_input_file_name_loop:
909 }
910 % \end{macrocode}
911 % \end{macro}
912 % \end{macro}
913 %
914 %</package>
915 %
916 % \end{implementation}
917 %
918 % \PrintIndex