Debian Codegraph @

texmf-dist/tex/plain/advice/advice.tex

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