Debian Codegraph @

texmf-dist/tex/context/third/advice/t-advice.tex

raw
1 %%
2 %% This is file `t-advice.tex',
3 %% generated with the docstrip utility.
4 %%
5 %% The original source files were:
6 %%
7 %% advice.dtx (with options: `main,context')
8 %%
9 %% This file is a part of Advice, a TeX package implementing a generic
10 %% framework for extending the functionality of selected commands and
11 %% environments, available at https://ctan.org/pkg/advice and
12 %% https://github.com/sasozivanovic/advice.
13 %%
14 %% Copyright (c) 2023- Saso Zivanovic <[email protected]>
15 %% (Sa\v{s}o \v{Z}ivanovi\'{c})
16 %%
17 %% This work may be distributed and/or modified under the conditions of the
18 %% LaTeX Project Public License, either version 1.3c of this license or (at
19 %% your option) any later version. The latest version of this license is in
20 %% https://www.latex-project.org/lppl.txt and version 1.3c or later is part of
21 %% all distributions of LaTeX version 2008 or later.
22 %%
23 %% This work has the LPPL maintenance status `maintained'.
24 %% The Current Maintainer of this work is Saso Zivanovic.
25 %%
26 %% The files belonging to this work and covered by LPPL are listed in
27 %% (<texmf>/doc/generic/advice/)FILES.
28 %D \module[
29 %D file=t-advice.tex,
30 %D version=1.1.1,
31 %D title=Advice,
32 %D subtitle=Extend commands and environments,
33 %D author=Saso Zivanovic,
34 %D date=2024-03-15,
35 %D copyright=Saso Zivanovic,
36 %D license=LPPL,
37 %D ]
38 \writestatus{loading}{ConTeXt User Module / advice}
39 \unprotect
40 \startmodule[advice]
41 \input miniltx
42 \input t-collargs
43 \pgfkeys{
44 /handlers/.install advice/.code={%
45 \edef\auto@install@namespace{\pgfkeyscurrentpath}%
46 \def\advice@install@setupkey{advice}%
47 \def\advice@install@activation{immediate}%
48 \pgfqkeys{/advice/install}{#1}%
49 \normalexpanded{\noexpand\advice@install
50 {\auto@install@namespace}%
51 {\advice@install@setupkey}%
52 {\advice@install@activation}%
53 }%
54 },
55 /advice/install/.cd,
56 setup key/.store in=\advice@install@setupkey,
57 activation/.is choice,
58 activation/.append code=\def\advice@install@activation{#1},
59 activation/immediate/.code={},
60 activation/deferred/.code={},
61 }
62 \def\advice@install#1#2#3{%
63 \pgfqkeys{#1}{%
64 #2/.code 2 args={%
65 \AdviceSetup{#1}{#2}{##1}{\pgfqkeys{#1/#2}{##2}}%
66 \pgfqkeys{#1}{try activate, activate={##1}}%
67 },
68 #2'/.code 2 args={%
69 \AdviceSetup{#1}{#2}{##1}{\pgfqkeys{#1/#2}{##2}}%
70 },
71 #2 csname/.style 2 args={
72 #2/.expand once=\expandafter{\csname ##1\endcsname}{##2},
73 },
74 #2 csname'/.style 2 args={
75 #2'/.expand once=\expandafter{\csname ##1\endcsname}{##2},
76 },
77 #2 key/.style 2 args={
78 #2/.expand once=%
79 \expandafter{\csname pgfk@##1/.@cmd\endcsname}%
80 {collector=\advice@pgfkeys@collector,##2},
81 },
82 #2 key'/.style 2 args={
83 #2'/.expand once=%
84 \expandafter{\csname pgfk@##1/.@cmd\endcsname}%
85 {collector=\advice@pgfkeys@collector,##2},
86 },
87 activation/.style={/advice/activation/##1={#1}},
88 activation=#3,
89 activate deferred/.code={},
90 activate csname/.style={activate/.expand once={\csname##1\endcsname}},
91 deactivate csname/.style={deactivate/.expand once={\csname##1\endcsname}},
92 activate key/.style={activate@key={#1/activate}{##1}},
93 deactivate key/.style={activate@key={#1/deactivate}{##1}},
94 activate@key/.code n args=2{%
95 \def\advice@temp{}%
96 \def\advice@do####1{%
97 \eappto\advice@temp{,\expandonce{\csname pgfk@####1/.@cmd\endcsname}}}%
98 \forcsvlist\advice@do{##2}%
99 \pgfkeysalso{##1/.expand once=\advice@temp}%
100 },
101 #2/.cd,
102 run conditions/.store in=\AdviceRunConditions,
103 bailout handler/.store in=\AdviceBailoutHandler,
104 outer handler/.store in=\AdviceOuterHandler,
105 collector/.store in=\AdviceCollector,
106 collector options/.code={\appto\AdviceCollectorOptions{,##1}},
107 clear collector options/.code={\def\AdviceCollectorOptions{}},
108 raw collector options/.code={\appto\AdviceRawCollectorOptions{##1}},
109 clear raw collector options/.code={\def\AdviceRawCollectorOptions{}},
110 args/.store in=\AdviceArgs,
111 inner handler/.store in=\AdviceInnerHandler,
112 options/.code={\appto\AdviceOptions{,##1}},
113 clear options/.code={\def\AdviceOptions{}},
114 .unknown/.code={%
115 \eappto{\AdviceOptions}{,\pgfkeyscurrentname={\normalunexpanded{##1}}}%
116 },
117 run conditions/.default=\AdviceRuntrue,
118 bailout handler/.default=\relax,
119 outer handler/.default=\AdviceCollector,
120 collector/.default=\advice@CollectArgumentsRaw,
121 collector options/.value required,
122 raw collector options/.value required,
123 args/.default=\advice@noargs,
124 inner handler/.default=\advice@error@noinnerhandler,
125 options/.value required,
126 reset/.code={\csname\advice@setup@init@\AdviceType\endcsname},
127 after setup/.code={\appto\AdviceAfterSetup{##1}},
128 }%
129 }
130 \def\AdviceSetup#1#2#3{%
131 \begingroup
132 \def\AdviceName{#3}%
133 \advice@def@AdviceCsname
134 \collargs@cs@cases{#3}{%
135 \def\AdviceType{command}%
136 \advice@setup@init@command
137 \advice@setup@i{#3}{#1}{#3}%
138 }{%
139 \advice@error@advice@notcs{#1/#2}{#3}%
140 }{%
141 \def\AdviceType{environment}%
142 \advice@setup@init@environment
143 \expandafter\advice@setup@i\expandafter{\csname start#3\endcsname}%
144 {#1}{#3}%
145 }%
146 }
147 \def\advice@setup@i#1#2#3#4{%
148 \advice@setup@init@i{#2}{#1}%
149 \advice@setup@init@I{#2}{#1}%
150 \def\AdviceAfterSetup{}%
151 #4%
152 \advice@setup@save{#2}{#1}%
153 }
154 \def\advice@setup@init@common{%
155 \def\AdviceRunConditions{\AdviceRuntrue}%
156 \def\AdviceBailoutHandler{\relax}%
157 \def\AdviceOuterHandler{\AdviceCollector}%
158 \def\AdviceCollector{\advice@CollectArgumentsRaw}%
159 \def\AdviceCollectorOptions{}%
160 \def\AdviceInnerHandler{\advice@error@noinnerhandler}%
161 \def\AdviceOptions{}%
162 }
163 \def\advice@setup@init@command{%
164 \advice@setup@init@common
165 \def\AdviceRawCollectorOptions{}%
166 \def\AdviceArgs{\advice@noargs}%
167 }
168 \def\advice@setup@init@environment{%
169 \advice@setup@init@common
170 \edef\AdviceRawCollectorOptions{%
171 \noexpand\collargsEnvironment{\AdviceName}%
172 \noexpand\collargsEndTagtrue
173 }%
174 \def\AdviceArgs{+b}%
175 }
176 \advice@setup@init@command
177 \def\advice@init@i#1#2{\csname advice@i#1//\string#2\endcsname}
178 \def\advice@init@I#1#2{\csname advice@I#1//\string#2\endcsname}
179 \let\advice@setup@init@i\advice@init@i
180 \let\advice@setup@init@I\advice@init@I
181 \def\advice@setup@save#1#2{%
182 \normalexpanded{%
183 \endgroup
184 \noexpand\csdef{advice@i#1//\string#2}{%
185 \def\noexpand\AdviceRunConditions{\expandonce\AdviceRunConditions}%
186 \def\noexpand\AdviceBailoutHandler{\expandonce\AdviceBailoutHandler}%
187 }%
188 \noexpand\csdef{advice@I#1//\string#2}{%
189 \def\noexpand\AdviceOuterHandler{\expandonce\AdviceOuterHandler}%
190 \def\noexpand\AdviceCollector{\expandonce\AdviceCollector}%
191 \def\noexpand\AdviceRawCollectorOptions{%
192 \expandonce\AdviceRawCollectorOptions}%
193 \def\noexpand\AdviceCollectorOptions{\expandonce\AdviceCollectorOptions}%
194 \def\noexpand\AdviceArgs{\expandonce\AdviceArgs}%
195 \def\noexpand\AdviceInnerHandler{\expandonce\AdviceInnerHandler}%
196 \def\noexpand\AdviceOptions{\expandonce\AdviceOptions}%
197 }%
198 \expandonce{\AdviceAfterSetup}%
199 }%
200 }
201 \pgfkeys{
202 /advice/activation/deferred/.style={
203 #1/activate/.style={%
204 activate deferred/.append style={#1/activate={##1}}},
205 #1/deactivate/.style={%
206 activate deferred/.append style={#1/deactivate={##1}}},
207 #1/force activate/.style={%
208 activate deferred/.append style={#1/force activate={##1}}},
209 #1/try activate/.style={%
210 activate deferred/.append style={#1/try activate={##1}}},
211 },
212 /advice/activation/immediate/.style={
213 #1/activate/.code={%
214 \forcsvlist{\advice@activate{#1}}{##1}%
215 \advice@activate@forcefalse
216 \advice@activate@tryfalse
217 },
218 #1/deactivate/.code={%
219 \forcsvlist{\advice@deactivate{#1}}{##1}%
220 \advice@activate@forcefalse
221 \advice@activate@tryfalse
222 },
223 #1/force activate/.is if=advice@activate@force,
224 #1/try activate/.is if=advice@activate@try,
225 },
226 }
227 \newif\ifadvice@activate@force
228 \newif\ifadvice@activate@try
229 \def\advice@original@csname#1#2{advice@o#1//\string#2}
230 \def\advice@original@cs#1#2{\csname advice@o#1//\string#2\endcsname}
231 \def\AdviceGetOriginal#1#2{%
232 \ifcsname advice@o#1//\string#2\endcsname
233 \expandonce{\csname advice@o#1//\string#2\expandafter\endcsname\expandafter}%
234 \else
235 \normalunexpanded\expandafter{\expandafter#2\expandafter}%
236 \fi
237 }
238 \begingroup
239 \catcode`\/=0
240 \catcode`\\=12
241 /gdef/advice@backslash@other{\}%
242 /endgroup
243 \def\AdviceCsnameGetOriginal#1#2{%
244 \ifcsname advice@o#1//\advice@backslash@other#2\endcsname
245 \expandonce{\csname advice@o#1//\advice@backslash@other#2\expandafter\endcsname
246 \expandafter}%
247 \else
248 \expandonce{\csname#2\expandafter\endcsname\expandafter}%
249 \fi
250 }
251 \def\advice@activate#1#2{%
252 \collargs@cs@cases{#2}%
253 {\advice@activate@cmd{#1}{#2}}%
254 {\advice@error@activate@notcsorenv{}{#1}}%
255 {\advice@activate@env{#1}{#2}}%
256 }
257 \def\advice@deactivate#1#2{%
258 \collargs@cs@cases{#2}%
259 {\advice@deactivate@cmd{#1}{#2}}%
260 {\advice@error@activate@notcsorenv{de}{#1}}%
261 {\advice@deactivate@env{#1}{#2}}%
262 }
263 \def\advice@activate@cmd#1#2{%
264 \ifdef{#2}{%
265 \ifcsdef{\advice@original@csname{#1}{#2}}{%
266 \advice@if@our@definition{#1}{#2}{%
267 \advice@activate@error@activated{#1}{#2}{Command}{already}%
268 }{%
269 \ifadvice@activate@force
270 \advice@activate@cmd@do{#1}{#2}%
271 \else
272 \advice@activate@error@activated{#1}{#2}{Command}{already}%
273 \fi
274 }%
275 }{%
276 \advice@activate@cmd@do{#1}{#2}%
277 }%
278 }{%
279 \advice@activate@error@undefined{#1}{#2}{Command}{}%
280 }%
281 }
282 \def\advice@deactivate@cmd#1#2{%
283 \ifdef{#2}{%
284 \ifcsdef{\advice@original@csname{#1}{#2}}{%
285 \advice@if@our@definition{#1}{#2}{%
286 \advice@deactivate@cmd@do{#1}{#2}%
287 }{%
288 \advice@deactivate@error@changed{#1}{#2}%
289 }%
290 }{%
291 \advice@activate@error@activated{#1}{#2}{Command}{not yet}%
292 }%
293 }{%
294 \advice@activate@error@undefined{#1}{#2}{Command}{de}%
295 }%
296 }
297 \def\advice@if@our@definition#1#2{%
298 \protected\def\advice@temp{\advice@handle{#1}{#2}}%
299 \ifx#2\advice@temp
300 \expandafter\@firstoftwo
301 \else
302 \expandafter\@secondoftwo
303 \fi
304 }
305 \def\advice@activate@cmd@do#1#2{%
306 \cslet{\advice@original@csname{#1}{#2}}#2%
307 \protected\def#2{\advice@handle{#1}{#2}}%
308 \PackageInfo{advice (#1)}{Activated command "\string#2"}%
309 }
310 \def\advice@deactivate@cmd@do#1#2{%
311 \letcs#2{\advice@original@csname{#1}{#2}}%
312 \csundef{\advice@original@csname{#1}{#2}}%
313 \PackageInfo{advice (#1)}{Deactivated command "\string#2"}%
314 }
315 \def\advice@handle#1#2{%
316 \advice@init@i{#1}{#2}%
317 \AdviceRunfalse
318 \AdviceRunConditions
319 \advice@handle@rc{#1}{#2}%
320 }
321 \def\advice@handle@rc#1#2{%
322 \ifAdviceRun
323 \expandafter\advice@handle@outer
324 \else
325 \AdviceBailoutHandler
326 \expandafter\advice@original@cs
327 \fi
328 {#1}{#2}%
329 }
330 \def\advice@handle@outer#1#2{%
331 \def\AdviceNamespace{#1}%
332 \def\AdviceName{#2}%
333 \advice@def@AdviceCsname
334 \let\AdviceReplaced\AdviceName
335 \def\AdviceOriginal{\AdviceGetOriginal{#1}{#2}}%
336 \advice@init@I{#1}{#2}%
337 \AdviceOuterHandler
338 }
339 \def\advice@def@AdviceCsname{%
340 \begingroup
341 \escapechar=-1
342 \expandafter\expandafter\expandafter\endgroup
343 \expandafter\expandafter\expandafter\def
344 \expandafter\expandafter\expandafter\AdviceCsname
345 \expandafter\expandafter\expandafter{\expandafter\string\AdviceName}%
346 }
347 \newif\ifAdviceRun
348 \def\advice@CollectArgumentsRaw{%
349 \AdviceIfArgs{}{%
350 \expandafter\GetDocumentCommandArgSpec\expandafter{\AdviceName}%
351 \let\AdviceArgs\ArgumentSpecification
352 }%
353 \normalexpanded{%
354 \noexpand\CollectArgumentsRaw{%
355 \noexpand\collargsCaller{\expandonce\AdviceName}%
356 \expandonce\AdviceRawCollectorOptions
357 \ifdefempty\AdviceCollectorOptions{}{%
358 \noexpand\collargsSet{\expandonce\AdviceCollectorOptions}%
359 }%
360 }%
361 {\expandonce\AdviceArgs}%
362 {\expandonce\AdviceInnerHandler}%
363 }%
364 }
365 \def\advice@noargs@text{\advice@noargs}
366 \def\AdviceIfArgs{%
367 \ifx\AdviceArgs\advice@noargs@text
368 \expandafter\@secondoftwo
369 \else
370 \expandafter\@firstoftwo
371 \fi
372 }
373 \def\advice@pgfkeys@collector#1\pgfeov{%
374 \AdviceInnerHandler{#1}%
375 }
376 \def\advice@activate@env#1#2{%
377 \normalexpanded{%
378 \noexpand\advice@activate@cmd{#1}{\expandonce{\csname
379 start%
380 #2\endcsname}}%
381 }%
382 }
383 \def\advice@deactivate@env#1#2{%
384 \normalexpanded{%
385 \noexpand\advice@deactivate@cmd{#1}{\expandonce{\csname
386 start%
387 #2\endcsname}}%
388 }%
389 }
390 \def\advice@activate@error@activated#1#2#3#4{%
391 \ifadvice@activate@try
392 \else
393 \PackageError{advice (#1)}{#3 "\string#2" is #4 activated}{}%
394 \fi
395 }
396 \def\advice@activate@error@undefined#1#2#3#4{%
397 \ifadvice@activate@try
398 \else
399 \PackageError{advice (#1)}{%
400 #3 "\string#2" you are trying to #4activate is not defined}{}%
401 \fi
402 }
403 \def\advice@deactivate@error@changed#1#2{%
404 \ifadvice@activate@try
405 \else
406 \PackageError{advice (#1)}{The definition of "\string#2" has changed since we
407 have activated it. Has somebody overridden our command?}{If you have tried
408 to deactivate so that you could immediately reactivate, you may want to try
409 "force activate".}%
410 \fi
411 }
412 \def\advice@error@advice@notcs#1#2{%
413 \PackageError{advice}{The first argument of key "#1" should be either a single
414 control sequence or an environment name, not "#2"}{}%
415 }
416 \def\advice@error@activate@notcsorenv#1#2{%
417 \PackageError{advice}{Each item in the value of key "#1activate" should be
418 either a control sequence or an environment name, not "#2".}{}%
419 }
420 \def\advice@error@storecs@notcs#1#2{%
421 \PackageError{advice}{The value of key "#1" should be a single control sequence,
422 not "\string#2"}{}%
423 }
424 \def\advice@error@noinnerhandler#1{%
425 \PackageError{advice (\AdviceNamespace)}{The inner handler for
426 "\expandafter\string\AdviceName" is not defined}{}%
427 }
428 \def\AdviceTracingOn{%
429 \let\advice@init@i\advice@trace@init@i
430 \let\advice@init@I\advice@trace@init@I
431 }
432 \def\AdviceTracingOff{%
433 \let\advice@init@i\advice@setup@init@i
434 \let\advice@init@I\advice@setup@init@I
435 }
436 \long\def\advice@typeout#1{\directlua{texio.write_nl("\luaescapestring{#1}")}}
437 \def\advice@trace#1{\advice@typeout{[tracing advice] #1}}
438 \def\advice@trace@init@i#1#2{%
439 \advice@trace{Advising \detokenize\expandafter{\string#2} (\detokenize{#1})}%
440 \advice@trace{\space\space Original command meaning:
441 \expandafter\expandafter\expandafter\meaning\advice@original@cs{#1}{#2}}%
442 \advice@setup@init@i{#1}{#2}%
443 \edef\AdviceRunConditions{%
444 \expandonce\AdviceRunConditions
445 \noexpand\advice@trace{\space\space
446 Executing run conditions:
447 \detokenize\expandafter{\AdviceRunConditions}
448 -->
449 \noexpand\ifAdviceRun true\noexpand\else false\noexpand\fi
450 }%
451 }%
452 \edef\AdviceBailoutHandler{%
453 \noexpand\advice@trace{\space\space
454 Executing bailout handler:
455 \detokenize\expandafter{\AdviceBailoutHandler}}%
456 \expandonce\AdviceBailoutHandler
457 }%
458 }
459 \def\advice@trace@init@I#1#2{%
460 \advice@setup@init@I{#1}{#2}%
461 \edef\AdviceOuterHandler{%
462 \noexpand\advice@trace{\space\space
463 Executing outer handler:
464 \detokenize\expandafter{\AdviceOuterHandler}}%
465 \expandonce\AdviceOuterHandler
466 }%
467 \edef\AdviceCollector{%
468 \noexpand\advice@trace{\space\space
469 Executing collector:
470 \detokenize\expandafter{\AdviceCollector}}%
471 \noexpand\advice@trace{\space\space\space\space
472 Argument specification:
473 \detokenize\expandafter{\AdviceArgs}}%
474 \noexpand\advice@trace{\space\space\space\space
475 Options:
476 \detokenize\expandafter{\AdviceCollectorOptions}}%
477 \noexpand\advice@trace{\space\space\space\space
478 Raw options:
479 \detokenize\expandafter{\AdviceRawCollectorOptions}}%
480 \normalunexpanded{%
481 \gdef\advice@collargs@return{0}%
482 \appto\AdviceRawCollectorOptions{\advice@remember@collargs@return}%
483 }%
484 \expandonce\AdviceCollector
485 }%
486 \edef\advice@inner@handler@trace@do{%
487 \noexpand\advice@trace{\space\space
488 Executing inner handler:
489 \detokenize\expandafter{\AdviceInnerHandler}}%
490 \noexpand\advice@trace{\space\space\space\space
491 Received arguments\noexpand\advice@inner@handler@trace@printcollargsreturn:
492 \noexpand\detokenize\noexpand\expandafter{\normalunexpanded{\the\toks0}}}%
493 \noexpand\advice@trace{\space\space\space\space
494 Options:
495 \detokenize\expandafter{\AdviceOptions}}%
496 \expandonce{\AdviceInnerHandler}%
497 }%
498 \def\AdviceInnerHandler{\advice@inner@handler@trace}%
499 }
500 \def\advice@remember@collargs@return{%
501 \global\let\advice@collargs@return\collargsReturn
502 }
503 \def\advice@inner@handler@trace{%
504 \ifnum\advice@collargs@return=0
505 \expandafter\advice@inner@handler@trace@i
506 \else
507 \expandafter\advice@inner@handler@trace@ii
508 \fi
509 }
510 \def\advice@inner@handler@trace@i#1{%
511 \toks0={#1}%
512 \advice@inner@handler@trace@do{#1}%
513 }
514 \def\advice@inner@handler@trace@ii{%
515 \expandafter\toks\expandafter0\expandafter{\the\collargsArgs}%
516 \advice@inner@handler@trace@do
517 }
518 \def\advice@inner@handler@trace@printcollargsreturn{%
519 \ifnum\advice@collargs@return=0
520 \else
521 \space(collargs return=%
522 \ifcase\advice@collargs@return braced\or plain\or no\fi
523 )%
524 \fi
525 }
526 \stopmodule
527 \protect
528 \endinput
529 %%
530 %% End of file `t-advice.tex'.