Debian Codegraph @

texmf-dist/source/latex/thmtools/thm-kv.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2008-2014 by Ulrich M. Schwarz
4 % Copyright (C) 2019 by Frank Mittelbach
5 % Copyright (C) 2020- by Yukai Chou
6 %
7 % This file may be distributed and/or modified under the conditions of
8 % the LaTeX Project Public License, version 1.3c.
9 % The license can be obtained from
10 % http://www.latex-project.org/lppl/lppl-1-3c.txt
11 %
12 % \fi
13 %
14 %\iffalse (hide this from DocInput)
15 %<*kv>
16 %\fi
17 %
18 %\StopEventually{}
19 % \begin{macrocode}
20
21 \let\@xa\expandafter
22 \let\@nx\noexpand
23
24 \DeclareOption{lowercase}{%
25 \PackageInfo{thm-kv}{Theorem names will be lowercased}%
26 \global\def\thmt@modifycase{\protect\MakeLowercase}}
27
28 \DeclareOption{uppercase}{%
29 \PackageInfo{thm-kv}{Theorem names will be uppercased}%
30 \global\def\thmt@modifycase{\protect\MakeUppercase}}
31
32 \DeclareOption{anycase}{%
33 \PackageInfo{thm-kv}{Theorem names will be unchanged}%
34 \global\def\thmt@modifycase{}}
35
36 \ExecuteOptions{uppercase}
37 \ProcessOptions\relax
38
39 \RequirePackage{keyval,kvsetkeys,thm-patch}
40
41 \long\def\thmt@kv@processor@default#1#2#3{%
42 \def\kvsu@fam{#1}% new
43 \@onelevel@sanitize\kvsu@fam% new
44 \def\kvsu@key{#2}% new
45 \@onelevel@sanitize\kvsu@key% new
46 \unless\ifcsname KV@#1@\kvsu@key\endcsname
47 \unless\ifcsname KVS@#1@handler\endcsname
48 \kv@error@unknownkey{#1}{\kvsu@key}%
49 \else
50 \csname KVS@#1@handler\endcsname{#2}{#3}%
51 % still using #2 #3 here is intentional: handler might
52 % be used for strange stuff like implementing key names
53 % that contain strange characters or other strange things.
54 \relax
55 \fi
56 \else
57 \ifx\kv@value\relax
58 \unless\ifcsname KV@#1@\kvsu@key @default\endcsname
59 \kv@error@novalue{#1}{\kvsu@key}%
60 \else
61 \csname KV@#1@\kvsu@key @default\endcsname
62 \relax
63 \fi
64 \else
65 \csname KV@#1@\kvsu@key\endcsname{#3}%
66 \fi
67 \fi
68 }
69
70 \@ifpackagelater{kvsetkeys}{2012/04/23}{%
71 \PackageInfo{thm-kv}{kvsetkeys patch (v1.16 or later)}%
72 \long\def\tmp@KVS@PD#1#2#3{%
73 \def \kv@fam {#1}%
74 \unless \ifcsname KV@#1@#2\endcsname
75 \unless \ifcsname KVS@#1@handler\endcsname
76 \kv@error@unknownkey {#1}{#2}%
77 \else
78 \kv@handled@true
79 \csname KVS@#1@handler\endcsname {#2}{#3}\relax
80 \ifkv@handled@ \else
81 \kv@error@unknownkey {#1}{#2}%
82 \fi
83 \fi
84 \else
85 \ifx \kv@value \relax
86 \unless \ifcsname KV@#1@#2@default\endcsname
87 \kv@error@novalue {#1}{#2}%
88 \else
89 \csname KV@#1@#2@default\endcsname \relax
90 \fi
91 \else
92 \csname KV@#1@#2\endcsname {#3}%
93 \fi
94 \fi
95 }%
96 \ifx\tmp@KVS@PD\KVS@ProcessorDefault
97 \let\KVS@ProcessorDefault\thmt@kv@processor@default
98 \def\kv@processor@default#1#2{%
99 \begingroup
100 \csname @safe@activestrue\endcsname
101 \@xa\let\csname ifincsname\@xa\endcsname\csname iftrue\endcsname
102 \edef\KVS@temp{\endgroup
103 % 2019/12/22 removed dependency on etexcmds package
104 \noexpand\KVS@ProcessorDefault{#1}{\unexpanded{#2}}%
105 }%
106 \KVS@temp
107 }%
108 \else
109 \PackageError{thm-kv}{kvsetkeys patch failed}{Try kvsetkeys v1.16 or earlier}
110 \fi
111 }{\@ifpackagelater{kvsetkeys}{2011/04/06}{%
112 % Patch has disappeared somewhere... thanksalot.
113 \PackageInfo{thm-kv}{kvsetkeys patch (v1.13 or later)}
114 \long\def\tmp@KVS@PD#1#2#3{% no non-etex-support here...
115 \unless\ifcsname KV@#1@#2\endcsname
116 \unless\ifcsname KVS@#1@handler\endcsname
117 \kv@error@unknownkey{#1}{#2}%
118 \else
119 \csname KVS@#1@handler\endcsname{#2}{#3}%
120 \relax
121 \fi
122 \else
123 \ifx\kv@value\relax
124 \unless\ifcsname KV@#1@#2@default\endcsname
125 \kv@error@novalue{#1}{#2}%
126 \else
127 \csname KV@#1@#2@default\endcsname
128 \relax
129 \fi
130 \else
131 \csname KV@#1@#2\endcsname{#3}%
132 \fi
133 \fi
134 }%
135 \ifx\tmp@KVS@PD\KVS@ProcessorDefault
136 \let\KVS@ProcessorDefault\thmt@kv@processor@default
137 \def\kv@processor@default#1#2{%
138 \begingroup
139 \csname @safe@activestrue\endcsname
140 \let\ifincsname\iftrue
141 \edef\KVS@temp{\endgroup
142 \noexpand\KVS@ProcessorDefault{#1}{\unexpanded{#2}}%
143 }%
144 \KVS@temp
145 }
146 \else
147 \PackageError{thm-kv}{kvsetkeys patch failed, try kvsetkeys v1.13 or earlier}
148 \fi
149 }{%
150 \RequirePackage{etex}
151 \PackageInfo{thm-kv}{kvsetkeys patch applied (pre-1.13)}%
152 \let\kv@processor@default\thmt@kv@processor@default
153 }}
154
155 % useful key handler defaults.
156 \newcommand\thmt@mkignoringkeyhandler[1]{%
157 \kv@set@family@handler{#1}{%
158 \thmt@debug{Key `##1' with value `##2' ignored by #1.}%
159 }%
160 }
161 \newcommand\thmt@mkextendingkeyhandler[3]{%
162 % #1: family
163 % #2: prefix for file
164 % #3: key hint for error
165 \kv@set@family@handler{#1}{%
166 \thmt@selfextendingkeyhandler{#1}{#2}{#3}%
167 {##1}{##2}%
168 }%
169 }
170
171 \newcommand\thmt@selfextendingkeyhandler[5]{%
172 % #1: family
173 % #2: prefix for file
174 % #3: key hint for error
175 % #4: actual key
176 % #5: actual value
177 \IfFileExists{#2-#4.sty}{%
178 \PackageInfo{thmtools}%
179 {Automatically pulling in `#2-#4'}%
180 \RequirePackage{#2-#4}%
181 \ifcsname KV@#1@#4\endcsname
182 \csname KV@#1@#4\endcsname{#5}%
183 \else
184 \PackageError{thmtools}%
185 {#3 `#4' not known}
186 {I don't know what that key does.\MessageBreak
187 I've even loaded the file `#2-#4.sty', but that didn't help.
188 }%
189 \fi
190 }{%
191 \PackageError{thmtools}%
192 {#3 `#4' not known}
193 {I don't know what that key does by myself,\MessageBreak
194 and no file `#2-#4.sty' to tell me seems to exist.
195 }%
196 }%
197 }
198
199
200 \newif\if@thmt@firstkeyset
201
202 % many keys are evaluated twice, because we don't know
203 % if they make sense before or after, or both.
204 \def\thmt@trytwice{%
205 \if@thmt@firstkeyset
206 \@xa\@firstoftwo
207 \else
208 \@xa\@secondoftwo
209 \fi
210 }
211
212 \@for\tmp@keyname:=parent,numberwithin,within\do{%
213 \define@key{thmdef}{\tmp@keyname}{%
214 \thmt@trytwice{%
215 \thmt@setparent{#1}
216 \thmt@setsibling{}%
217 }{}%
218 }%
219 }
220 \newcommand\thmt@setparent{%
221 \def\thmt@parent
222 }
223
224 \@for\tmp@keyname:=sibling,numberlike,sharenumber\do{%
225 \define@key{thmdef}{\tmp@keyname}{%
226 \thmt@trytwice{%
227 \thmt@setsibling{#1}%
228 \thmt@setparent{}%
229 }{}%
230 }%
231 }
232 \newcommand\thmt@setsibling{%
233 \def\thmt@sibling
234 }
235
236 \@for\tmp@keyname:=title,name,heading\do{%
237 \define@key{thmdef}{\tmp@keyname}{\thmt@trytwice{\thmt@setthmname{#1}}{}}%
238 }
239 \newcommand\thmt@setthmname{%
240 \def\thmt@thmname
241 }
242
243 \@for\tmp@keyname:=unnumbered,starred\do{%
244 \define@key{thmdef}{\tmp@keyname}[]{\thmt@trytwice{\thmt@isnumberedfalse}{}}%
245 }
246
247 \def\thmt@YES{yes}
248 \def\thmt@NO{no}
249 \def\thmt@UNIQUE{unless unique}
250 \newif\ifthmt@isnumbered
251 \newif\ifthmt@isunlessunique
252
253 \define@key{thmdef}{numbered}[yes]{
254 \def\thmt@tmp{#1}%
255 \thmt@trytwice{%
256 \ifx\thmt@tmp\thmt@YES
257 \thmt@isnumberedtrue
258 \else\ifx\thmt@tmp\thmt@NO
259 \thmt@isnumberedfalse
260 \else\ifx\thmt@tmp\thmt@UNIQUE
261 \RequirePackage[unq]{unique}
262 \thmt@isunlessuniquetrue
263 \else
264 \PackageError{thmtools}{Unknown value `#1' to key numbered}{}%
265 \fi\fi\fi
266 }{% trytwice: after definition
267 \ifx\thmt@tmp\thmt@UNIQUE
268 \ifx\thmt@parent\@empty
269 \addtotheorempreheadhook[\thmt@envname]{\setuniqmark{\thmt@envname}}%
270 \else
271 \protected@edef\thmt@tmp{%
272 % expand \thmt@envname and \thmt@parent
273 \@nx\addtotheorempreheadhook[\thmt@envname @unique]{%
274 \@nx\setuniqmark{\thmt@envname.\@nx\@nameuse{the\thmt@parent}}}%
275 \@nx\addtotheorempreheadhook[\thmt@envname @numbered]{%
276 \@nx\setuniqmark{\thmt@envname.\@nx\@nameuse{the\thmt@parent}}}%
277 \@nx\addtotheorempreheadhook[\thmt@envname @unique]{%
278 \def\@nx\thmt@dummyctrautorefname{\thmt@thmname\@nx\@gobble}}%
279 \@nx\addtotheorempreheadhook[\thmt@envname @numbered]{%
280 \def\@nx\thmt@dummyctrautorefname{\thmt@thmname\@nx\@gobble}}%
281 }%
282 \thmt@tmp
283 \fi
284 % \addtotheorempreheadhook[\thmt@envname]{%
285 % \def\thmt@dummyctrautorefname{\thmt@thmname\@gobble}}%
286 \fi
287 }%
288 }
289
290
291 \define@key{thmdef}{preheadhook}{%
292 \thmt@trytwice{}{\addtotheorempreheadhook[\thmt@envname]{#1}}}
293 \define@key{thmdef}{postheadhook}{%
294 \thmt@trytwice{}{\addtotheorempostheadhook[\thmt@envname]{#1}}}
295 \define@key{thmdef}{prefoothook}{%
296 \thmt@trytwice{}{\addtotheoremprefoothook[\thmt@envname]{#1}}}
297 \define@key{thmdef}{postfoothook}{%
298 \thmt@trytwice{}{\addtotheorempostfoothook[\thmt@envname]{#1}}}
299
300 \define@key{thmdef}{style}{\thmt@trytwice{\thmt@setstyle{#1}}{}}
301
302 % ugly hack: style needs to be evaluated first so its keys
303 % are not overridden by explicit other settings
304 \define@key{thmdef0}{style}{%
305 \ifcsname thmt@style #1@defaultkeys\endcsname
306 \thmt@toks{\kvsetkeys{thmdef}}%
307 \@xa\@xa\@xa\the\@xa\@xa\@xa\thmt@toks\@xa\@xa\@xa{%
308 \csname thmt@style #1@defaultkeys\endcsname}%
309 \fi
310 }
311 \thmt@mkignoringkeyhandler{thmdef0}
312
313 % fallback definition.
314 % actually, only the kernel does not provide \theoremstyle.
315 % is this one worth having glue code for the theorem package?
316 \def\thmt@setstyle#1{%
317 \PackageWarning{thm-kv}{%
318 Your backend doesn't have a `\string\theoremstyle' command.
319 }%
320 }
321
322 \ifcsname theoremstyle\endcsname
323 \let\thmt@originalthmstyle\theoremstyle
324 \def\thmt@outerstyle{plain}
325 \renewcommand\theoremstyle[1]{%
326 \def\thmt@outerstyle{#1}%
327 \thmt@originalthmstyle{#1}%
328 }
329 \def\thmt@setstyle#1{%
330 \thmt@originalthmstyle{#1}%
331 }
332 \g@addto@macro\thmt@newtheorem@postdefinition{%
333 \thmt@originalthmstyle{\thmt@outerstyle}%
334 }
335 \fi
336
337
338 \thmt@mkextendingkeyhandler{thmdef}{thmdef}{\string\declaretheorem\space key}
339
340 \let\thmt@newtheorem\newtheorem
341
342 % \declaretheorem[option list 1]{thmname list}[option list 1]
343 % #1 = option list 1
344 % #2 = thmname list
345 \newcommand\declaretheorem[2][]{%
346 % TODO: use \NewDocumentCommand from xparse?
347 % xparse will be part of latex2e format from latex2e 2020 Oct.
348 \@ifnextchar[%
349 {\declaretheorem@i{#1}{#2}}
350 {\declaretheorem@i{#1}{#2}[]}%
351 }
352 \@onlypreamble\declaretheorem
353
354 % #1 = option list 1
355 % #2 = thmname list
356 % #3 = option list 2
357 \def\declaretheorem@i#1#2[#3]{%
358 \@for\thmt@tmp:=#2\do{%
359 % strip spaces, \KV@@sp@def is defined in keyval.sty
360 \@xa\KV@@sp@def\@xa\thmt@tmp\@xa{\thmt@tmp}%
361 \@xa\declaretheorem@ii\@xa{\thmt@tmp}{#1,#3}%
362 }%
363 }
364
365 % #1 = single thmname (#1 and #2 are exchanged)
366 % #2 = option list
367 \def\declaretheorem@ii#1#2{%
368 % why was that here?
369 %\let\thmt@theoremdefiner\thmt@original@newtheorem
370 % init options
371 \thmt@setparent{}%
372 \thmt@setsibling{}%
373 \thmt@isnumberedtrue
374 \thmt@isunlessuniquefalse
375 \def\thmt@envname{#1}%
376 \thmt@setthmname{\thmt@modifycase #1}%
377 % use true code in \thmt@trytwice{<true>}{<false>}
378 \@thmt@firstkeysettrue
379 % parse options
380 \kvsetkeys{thmdef0}{#2}% parse option "style" first
381 \kvsetkeys{thmdef}{#2}%
382 % call patched \newtheorem
383 \ifthmt@isunlessunique
384 \ifx\thmt@parent\@empty
385 % define normal "unless unique" thm env
386 \ifuniq{#1}{\thmt@isnumberedfalse}{\thmt@isnumberedtrue}%
387 \declaretheorem@iii{#1}%
388 \else
389 % define special "unless unique" thm env,
390 % when "numbered=unless unique" and "numberwithin=<counter>" are both used
391 \declaretheorem@iv{#1}%
392 \thmt@isnumberedtrue
393 \declaretheorem@iii{#1@numbered}%
394 \thmt@isnumberedfalse
395 \declaretheorem@iii{#1@unique}%
396 \fi
397 \else
398 % define normal thm env
399 \declaretheorem@iii{#1}%
400 \fi
401 % use false code in \thmt@trytwice{<true>}{<false>}
402 \def\thmt@envname{#1}%
403 \@thmt@firstkeysetfalse
404 % uniquely ugly kludge: some keys make only sense afterwards.
405 % and it gets kludgier: again, the default-inherited
406 % keys need to have a go at it.
407 \kvsetkeys{thmdef0}{#2}%
408 \kvsetkeys{thmdef}{#2}%
409 }
410
411 % define normal thm env, call \thmt@newtheorem
412 \def\declaretheorem@iii#1{%
413 \protected@edef\thmt@tmp{%
414 \@nx\thmt@newtheorem
415 \ifthmt@isnumbered
416 {#1}%
417 \ifx\thmt@sibling\@empty\else [\thmt@sibling]\fi
418 {\thmt@thmname}%
419 \ifx\thmt@parent\@empty\else [\thmt@parent]\fi
420 \else
421 *{#1}{\thmt@thmname}%
422 \fi
423 \relax% added so we can delimited-read everything later
424 }%
425 \thmt@debug{Define theorem `#1' by ^^J\meaning\thmt@tmp}%
426 \thmt@tmp
427 }
428
429 % define special thm env
430 \def\declaretheorem@iv#1{%
431 \protected@edef\thmt@tmp{%
432 % expand \thmt@envname and \thmt@parent
433 \@nx\newenvironment{#1}{%
434 \@nx\ifuniq{\thmt@envname.\@nx\@nameuse{the\thmt@parent}}{%
435 \def\@nx\thmt@rawenvname{#1@unique}%
436 }{%
437 \def\@nx\thmt@rawenvname{#1@numbered}%
438 }%
439 \begin{\@nx\thmt@rawenvname}%
440 }{%
441 \end{\@nx\thmt@rawenvname}%
442 }%
443 }%
444 \thmt@debug{Define special theorem `#1' by ^^J\meaning\thmt@tmp}%
445 \thmt@tmp
446 }
447
448 \providecommand\thmt@quark{\thmt@quark}
449
450 % in-document keyval, i.e. \begin{theorem}[key=val,key=val]
451
452 \thmt@mkextendingkeyhandler{thmuse}{thmuse}{\thmt@envname\space optarg key}
453
454 \addtotheorempreheadhook{%
455 \ifx\thmt@optarg\@empty\else
456 \@xa\thmt@garbleoptarg\@xa{\thmt@optarg}\fi
457 }%
458
459 \newif\ifthmt@thmuse@iskv
460
461 \providecommand\thmt@garbleoptarg[1]{%
462 \thmt@thmuse@iskvfalse
463 \def\thmt@newoptarg{\@gobble}%
464 \def\thmt@newoptargextra{}%
465 \let\thmt@shortoptarg\@empty
466 \def\thmt@warn@unusedkeys{}%
467 \@for\thmt@fam:=\thmt@thmuse@families\do{%
468 \kvsetkeys{\thmt@fam}{#1}%
469 }%
470 \ifthmt@thmuse@iskv
471 \protected@edef\thmt@optarg{%
472 \@xa\thmt@newoptarg
473 \thmt@newoptargextra\@empty
474 }%
475 \ifx\thmt@shortoptarg\@empty
476 \protected@edef\thmt@shortoptarg{\thmt@newoptarg\@empty}%
477 \fi
478 \thmt@warn@unusedkeys
479 \else
480 \def\thmt@optarg{#1}%
481 \def\thmt@shortoptarg{#1}%
482 \fi
483 }
484 % FIXME: not used?
485 % \def\thmt@splitopt#1=#2\thmt@quark{%
486 % \def\thmt@tmpkey{#1}%
487 % \ifx\thmt@tmpkey\@empty
488 % \def\thmt@tmpkey{\thmt@quark}%
489 % \fi
490 % \@onelevel@sanitize\thmt@tmpkey
491 % }
492
493 \def\thmt@thmuse@families{thm@track@keys}
494
495 \kv@set@family@handler{thm@track@keys}{%
496 \@onelevel@sanitize\kv@key
497 \@namedef{thmt@unusedkey@\kv@key}{%
498 \PackageWarning{thmtools}{Unused key `#1'}%
499 }%
500 \@xa\g@addto@macro\@xa\thmt@warn@unusedkeys\@xa{%
501 \csname thmt@unusedkey@\kv@key\endcsname
502 }
503 }
504
505 % key, code.
506 \def\thmt@define@thmuse@key#1#2{%
507 \g@addto@macro\thmt@thmuse@families{,#1}%
508 \define@key{#1}{#1}{\thmt@thmuse@iskvtrue
509 \@namedef{thmt@unusedkey@#1}{}%
510 #2}%
511 \thmt@mkignoringkeyhandler{#1}%
512 }
513
514 \thmt@define@thmuse@key{label}{%
515 \addtotheorempostheadhook[local]{\label{#1}}%
516 }
517 \thmt@define@thmuse@key{name}{%
518 \thmt@setnewoptarg #1\@iden%
519 }
520 \newcommand\thmt@setnewoptarg[1][]{%
521 \def\thmt@shortoptarg{#1}\thmt@setnewlongoptarg
522 }
523 \def\thmt@setnewlongoptarg #1\@iden{%
524 \def\thmt@newoptarg{#1\@iden}}
525
526 \providecommand\thmt@suspendcounter[2]{%
527 \@xa\protected@edef\csname the#1\endcsname{#2}%
528 \@xa\let\csname c@#1\endcsname\c@thmt@dummyctr
529 }
530
531 \providecommand\thmcontinues[1]{%
532 \ifcsname hyperref\endcsname
533 \hyperref[#1]{continuing}
534 \else
535 continuing
536 \fi
537 from p.\,\pageref{#1}%
538 }
539
540 \thmt@define@thmuse@key{continues}{%
541 \thmt@suspendcounter{\thmt@envname}{\thmt@trivialref{#1}{??}}%
542 \g@addto@macro\thmt@newoptarg{{, }%
543 \thmcontinues{#1}%
544 \@iden}%
545 }
546
547
548 % \end{macrocode}
549 %
550 % Defining new theorem styles; keys are in opt-arg
551 % even though not having any doesn't make much sense.
552 % It doesn't do anything exciting here, it's up to
553 % the glue layer to provide keys.
554 %
555 % \begin{macrocode}
556 \def\thmt@declaretheoremstyle@setup{}
557 \def\thmt@declaretheoremstyle#1{%
558 \PackageWarning{thmtools}{Your backend doesn't allow styling theorems}{}
559 }
560 \newcommand\declaretheoremstyle[2][]{%
561 \def\thmt@style{#2}%
562 \@xa\def\csname thmt@style \thmt@style @defaultkeys\endcsname{}%
563 \thmt@declaretheoremstyle@setup
564 \kvsetkeys{thmstyle}{#1}%
565 \thmt@declaretheoremstyle{#2}%
566 }
567 \@onlypreamble\declaretheoremstyle
568
569 \kv@set@family@handler{thmstyle}{%
570 \@onelevel@sanitize\kv@value
571 \@onelevel@sanitize\kv@key
572 \PackageInfo{thmtools}{%
573 Key `\kv@key' (with value `\kv@value')\MessageBreak
574 is not a known style key.\MessageBreak
575 Will pass this to every \string\declaretheorem\MessageBreak
576 that uses `style=\thmt@style'%
577 }%
578 \ifx\kv@value\relax% no value given, don't pass on {}!
579 \@xa\g@addto@macro\csname thmt@style \thmt@style @defaultkeys\endcsname{%
580 #1,%
581 }%
582 \else
583 \@xa\g@addto@macro\csname thmt@style \thmt@style @defaultkeys\endcsname{%
584 #1={#2},%
585 }%
586 \fi
587 }
588 % \end{macrocode}
589 %
590 %\iffalse
591 %</kv>
592 %\fi