Debian Codegraph @

texmf-dist/source/latex/amsrefs/rkeyval.dtx

raw
1 % \def\filename{rkeyval.dtx}
2 % \def\fileversion{2.00}
3 % \def\filedate{2004/06/28}
4 %
5 % \iffalse meta-comment
6 %
7 % American Mathematical Society
8 % Technical Support
9 % Publications Technical Group
10 % 201 Charles Street
11 % Providence, RI 02904
12 % USA
13 % tel: (401) 455-4080
14 % (800) 321-4267 (USA and Canada only)
15 % fax: (401) 331-3842
16 % email: [email protected]
17 %
18 % Copyright 2001, 2010 American Mathematical Society.
19 %
20 % This work may be distributed and/or modified under the
21 % conditions of the LaTeX Project Public License, either version 1.3c
22 % of this license or (at your option) any later version.
23 % The latest version of this license is in
24 % http://www.latex-project.org/lppl.txt
25 % and version 1.3c or later is part of all distributions of LaTeX
26 % version 2005/12/01 or later.
27 %
28 % This work has the LPPL maintenance status `maintained'.
29 %
30 % The Current Maintainer of this work is the American Mathematical
31 % Society.
32 %
33 % \fi
34 %
35 % \iffalse
36 %<*driver>
37 \documentclass[draft,oneside]{amsdtx}
38 \pagestyle{myheadings}
39
40 \makeatletter
41 \DeclareRobustCommand{\fld}{\@category@index{field}}
42 \makeatother
43
44 \DoNotIndex{\@emptytoks,\@temptokenb}
45
46 \CodelineIndex
47
48 \begin{document}
49 \title{The \pkg{rkeyval} package:\protect\linebreak[1]
50 Syntactically restricted key-value scanning}
51 \author{Michael Downes and David M. Jones\\American Mathematical Society}
52 \date{Version \fileversion, \filedate}
53 \DocInput{rkeyval.dtx}
54 \PrintIndex
55 \end{document}
56 %</driver>
57 % \fi
58 %
59 % \MakeShortVerb{\|}
60 %
61 % \maketitle
62 % \markboth{The \protect\pkg{rkeyval} package}
63 % {Version \protect\fileversion, \protect\filedate}
64 %
65 % \tableofcontents
66 %
67 % \section{Introduction}
68 %
69 % The \pkg{rkeyval} package provides functions for scanning key-value
70 % notation similar to the kind of scanning supported by the standard
71 % \pkg{keyval} package. However, the syntax is more restrictive in
72 % order to make some improved error-checking possible. In particular,
73 % if a comma is omitted between two instances of |key={value}|
74 % form, the \cn{RestrictedSetKeys} command will spot the missing
75 % comma and issue a suitable error message (and it will be given at
76 % the point where the missing comma is detected, before reading any
77 % further in the \tex/ file). The standard \cn{setkeys} command, by
78 % contrast, will append the second key name to the value of the first
79 % key and discard the second value, without any notification to the
80 % user that anything has gone wrong. But that is partly because the
81 % standard \cn{setkeys} command allows implied values and does not
82 % require braces around explicit values (except when necessary to
83 % hide material that has a syntactic resemblance to a key-value
84 % pair). With \cn{RestrictedSetKeys} the value must always be present
85 % and it must be enclosed in braces.
86 %
87 %^^A Maybe commas should be optional.
88 %
89 % Further restrictions of the \cn{RestrictedSetKeys} command and its
90 % companion commands reduce memory consumption in certain ways.
91 % Defining a key creates only one control sequence, a container for
92 % holding the value. Processing of key values is normally limited to
93 % storing a value given by the user; any additional processing must
94 % be supplied separately by the programmer.
95 %
96 % Generally speaking, the error-checking done by
97 % \cn{RestrictedSetKeys} is better for applications where all the
98 % keys are expected to have textual values, while \cn{setkeys} is
99 % better when one wants to silently recover as far as possible from
100 % syntactic errors, instead of notifying the user of the errors; or
101 % when keys have nontrivial default values (i.e., not empty) or other
102 % kinds of special processing.
103 %
104 % \begin{verbatim}
105 % \RestrictedSetKeys{setup-code}{group}{code}{key={val}, ...}
106 %\end{verbatim}
107 % Normally \cn{RestrictedSetKeys} simply carries out the following
108 % assignment for each key-value pair:
109 % \begin{verbatim}
110 % \def\group'key{val}
111 %\end{verbatim}
112 % The first argument is normally empty, but the exact nature of the
113 % warnings given and other aspects of the processing can be affected
114 % by putting extra setup code there. The \pkg{amsrefs} package uses
115 % this to implement a copying operation where field name and value
116 % are written out immediately to another file instead of being stored
117 % in the usual way.
118 %
119 % Some examples for defining the key names associated with a given
120 % group. This defines ``title'' as a recognized key for the \fn{bib}
121 % group:
122 % \begin{verbatim}
123 % \DefineSimpleKey{bib}{title}
124 %\end{verbatim}
125 % If a key is defined with \cs{DefineSimpleKey}, the result of using
126 % the same key more than once in a single entry will be an error
127 % message.
128 %
129 % This defines ``title'' to be a repeatable key:
130 % \begin{verbatim}
131 % \DefineSupersedingKey{bib}{title}
132 %\end{verbatim}
133 % If it occurs more than once, the last value supersedes the earlier
134 % ones, instead of getting an error. This variation is not needed for
135 % simple usage, but in more complicated situations where key values
136 % are combined from multiple sources, it may be useful.
137 %
138 % This defines ``author'' to be a repeatable key, with each value
139 % being appended to a list of values:
140 % \begin{verbatim}
141 % \DefineAdditiveKey{bib}{author}{\name}
142 %\end{verbatim}
143 % The third argument specifies a wrapper function that should be
144 % applied to each item in the list. I.e., suppose that two author
145 % names are given:
146 % \begin{verbatim}
147 % author={Smith, J. Q.},
148 % author={Taylor, X. Y.},
149 %\end{verbatim}
150 % Then they will be stored in the form
151 % \begin{verbatim}
152 % \name{Smith, J. Q.}\name{Taylor, X. Y.}
153 %\end{verbatim}
154 %
155 % This defines ``transition'' to be a dummy key with a value that is
156 % superficially nonempty but effectly empty:
157 % \begin{verbatim}
158 % \DefineDummyKey{bib}{transition}
159 %\end{verbatim}
160 % Defining a dummy key like this can be useful in dealing with
161 % certain boundary situations that sometimes arise.
162 %
163 % \StopEventually{}
164 %
165 % \section{Implementation}
166 % Standard declaration of package name and date.
167 % \begin{macrocode}
168 \NeedsTeXFormat{LaTeX2e}
169 \ProvidesPackage{rkeyval}[2004/05/05 v1.08]
170 % \end{macrocode}
171 %
172 % \begin{macro}{\@xp}
173 % \begin{macro}{\@nx}
174 % \begin{macrocode}
175 \let\@xp\expandafter
176 \let\@nx\noexpand
177 % \end{macrocode}
178 % \end{macro}
179 % \end{macro}
180 %
181 % \begin{macro}{\@gobblethree}
182 % \begin{macro}{\@nilgobble}
183 % Not in the \latex/ kernel yet.
184 % \begin{macrocode}
185 \long\def\@gobblethree#1#2#3{}
186 \long\def\@nilgobble#1\@nil{}
187 % \end{macrocode}
188 % \end{macro}
189 % \end{macro}
190 %
191 % \begin{macro}{\@emptytoks}
192 % Using \cs{@ifundefined} here avoids problems with really old
193 % versions of \latex/ that choke on \cs{newtoks} if it is written
194 % directly in the false branch of a conditional.
195 % \begin{macrocode}
196 \@ifundefined{@emptytoks}{\csname newtoks\endcsname\@emptytoks}{}
197 % \end{macrocode}
198 % \end{macro}
199 %
200 % \begin{macro}{\@temptokenb}
201 % \begin{macrocode}
202 \@ifundefined{@temptokenb}{\csname newtoks\endcsname\@temptokenb}{}
203 % \end{macrocode}
204 % \end{macro}
205 %
206 % \begin{macro}{\@append}
207 % \begin{macrocode}
208 \def\@append#1#2#3{\@xp\def\@xp#2\@xp{#2#1{#3}}}
209 % \end{macrocode}
210 % \end{macro}
211 %
212 % \begin{macro}{\star@}
213 % Test for a trailing option marked by a star. Usage:
214 % \begin{verbatim}
215 % \newcommand{\blub}[1]{\star@{\blubaux{#1}}{default}}
216 %\end{verbatim}
217 % Arg 1 of \cs{star@} is the code to
218 % be run, arg 2 is the default value of the option (could be empty).
219 % If arg 1 is \ncn{moo}, this test discards a star and expands to
220 % \ncn{moo} if a star is found, or expands to |\moo{#2}| if
221 % not. As the example shows, arg 1 need not be a single token.
222 % \begin{macrocode}
223 \def\star@#1#2{%
224 \def\star@a##1{#1}%
225 \def\star@b{#1{#2}}%
226 \futurelet\@let@token\star@test
227 }
228
229 \def\star@test{\ifx*\@let@token \let\star@b\star@a\fi \star@b}
230 % \end{macrocode}
231 %
232 % Please note: If there is a space before the star, then the star is
233 % not treated as an option char.
234 %
235 % Why use a star? Since it's already part of standard \latex/
236 % command syntax, it's unlikely to suffer from catcode changes.
237 %
238 % Why not just put the star at the beginning in the usual way? It
239 % seemed to me that the lack of a trailing option
240 % feature was a deficiency in current \latex/ and could be given an
241 % experimental implementation in a package like this without any
242 % adverse effect on existing documents.
243 % \end{macro}
244 %
245 % Ensure non-weird catcode for relevant characters.
246 % \begin{macrocode}
247 \@ifundefined{NormalCatcodes}{\RequirePackage{pcatcode}\relax}{}
248 \PushCatcodes\NormalCatcodes
249 % \end{macrocode}
250 %
251 % \begin{macro}{\extract@group}
252 % Extracts ``group'' from |\group'field|.
253 % \begin{macrocode}
254 \def\extract@group#1{%
255 \@xp\extract@group@a\string#1\@nil
256 }
257 % \end{macrocode}
258 % \end{macro}
259 %
260 % \begin{macro}{\extract@group@a}
261 % \begin{macrocode}
262 \def\extract@group@a#1#2'{#2\@nilgobble}
263 % \end{macrocode}
264 % \end{macro}
265 %
266 % \section{Data structures}
267 %
268 % The result of scanning the key/value pairs is an assignment statement
269 % for \cs{rsk@toks}. For example, consider the entry
270 % \begin{verbatim}
271 % \bib{LelekZ1962}{article}{
272 % author={Lelek, A.},
273 % author={Zaremba, D.},
274 % title={Dimensions of irreducible ...},
275 % journal={Fund. Math.},
276 % date={1962/63},
277 % }
278 %\end{verbatim}
279 % The scanned result is to assign
280 % \begin{verbatim}
281 % \global\rsk@toks{%
282 % \set:bib'author{Lelek, A.}{}%
283 % \set:bib'author{Zaremba, D.}{}%
284 % \set:bib'title{Dimensions of irreducible ...}{}%
285 % \set:bib'journal{Fund. Math.}{}%
286 % \set:bib'date{1962/63}{}%
287 % }
288 %\end{verbatim}
289 % The extra empty arguments on each line are for auxiliary
290 % properties (see below).
291 % What happens thereafter with \cs{rsk@toks} depends on the code in
292 % the last arg of \cs{RestrictedSetKeys}.
293 %
294 % \section{Auxiliary properties}
295 %
296 % Unfortunately, the previous section isn't the entire story. In
297 % addition to the values of each field, we need to store a set of
298 % auxiliary properties associated with those values. Note that
299 % properties are explicitly associated with \emph{values}, not with
300 % keys, because each value of an additive key could have different
301 % properties.
302 %
303 % All such extra data will be stored in a special field named
304 % ``aux'', with embedded tags to indicate which field each piece of
305 % the \fld{aux} field is associated with. The extra bits can be
306 % extracted on demand using standard techniques, and the primary
307 % value of each field is not burdened with any attachments, so that
308 % comparisons or scanning of the field contents can remain as
309 % simple as possible.
310 %
311 % Thus in practice there is at least one bit of auxiliary information
312 % in every bib item, and our previous example would have the title
313 % language indicated:
314 % \begin{verbatim}
315 % \DSK@def\bib'title{Eine Bemerkung zur Darstellung von Polynomen
316 % \"{u}ber Verb\"{a}nden}%
317 % \@append\bib'title\bib'aux{\selectlanguage{german}}%
318 %\end{verbatim}
319 %
320 % \begin{macro}{\set@property}
321 % \begin{macrocode}
322 \def\set@property#1{%
323 \begingroup
324 \edef\@tempa{\extract@group#1}%
325 \edef\@tempa{%
326 \@nx\@append\@nx#1\@xp\@nx\csname \@tempa,aux\endcsname
327 }%
328 \@xp\endgroup
329 \@tempa
330 }
331 % \end{macrocode}
332 % \end{macro}
333 %
334 % \begin{macro}{\get@property}
335 % \begin{macrocode}
336 % \get@property\destination\bib'title
337 \def\get@property#1#2{%
338 \get@nth@property#1#2\m@ne
339 }
340 % \end{macrocode}
341 % \end{macro}
342 %
343 % \begin{macro}{\get@nth@property}
344 % \begin{macrocode}
345 % \get@nth@property\destination\bib'title N
346 \def\get@nth@property#1#2#3{%
347 \begingroup
348 \edef\@tempa{\extract@group#2}%
349 \@tempcnta#3\relax
350 \@tempcntb\z@
351 \@xp\scan@properties\@xp#2\csname \@tempa,aux\endcsname
352 \edef\@tempa{\def\@nx#1{\@tempa}}%
353 \@xp\endgroup
354 \@tempa
355 }
356 % \end{macrocode}
357 % \end{macro}
358 %
359 % \begin{macro}{\scan@properties}
360 % \begin{macrocode}
361 \def\scan@properties#1#2{%
362 \begingroup
363 \def\@tempa{#1}%
364 \let\@tempc\@empty
365 \@xp\find@property #2 \@nil\@nil
366 \edef\@tempa{\def\@nx\@tempa{\@tempc}}%
367 \@xp\endgroup
368 \@tempa
369 }
370 % \end{macrocode}
371 % \end{macro}
372 %
373 % \begin{macro}{\find@property}
374 % \begin{macrocode}
375 \def\find@property#1#2{%
376 \ifx\@nil#1%
377 \else
378 \def\@tempb{#1}%
379 \ifx\@tempa\@tempb
380 \ifnum\@tempcnta<\z@
381 \def\@tempc{#2}%
382 \else
383 \advance\@tempcntb\@ne
384 \ifnum\@tempcntb=\@tempcnta
385 \def\@tempc{#2}%
386 \fi
387 \fi
388 \fi
389 \@xp\find@property
390 \fi
391 }
392 % \end{macrocode}
393 % \end{macro}
394 %
395 % \begin{macro}{\reset@property}
396 % \begin{macrocode}
397 \def\reset@property#1#2{%
398 \reset@nth@property#1\m@ne{#2}%
399 }
400 % \end{macrocode}
401 % \end{macro}
402 %
403 % \begin{macro}{\reset@nth@property}
404 % \begin{macrocode}
405 % \reset@nth@property\bib'title N VALUE
406 \def\reset@nth@property#1#2#3{%
407 \begingroup
408 \edef\@tempa{\extract@group#1}%
409 \@tempcnta#2\relax
410 \@temptokena{#3}%
411 \toks@\@emptytoks
412 \@tempcntb\z@
413 \@xp\reset@scan\@xp#1\csname \@tempa,aux\endcsname
414 \edef\@tempa{%
415 \def\@xp\@nx\csname \@tempa,aux\endcsname{\the\toks@}%
416 }%
417 \@xp\endgroup
418 \@tempa
419 }
420 % \end{macrocode}
421 % \end{macro}
422 %
423 % \begin{macro}{\reset@scan}
424 % \begin{macrocode}
425 \def\reset@scan#1#2{%
426 \begingroup
427 \def\@tempa{#1}%
428 \@xp\reset@scan@a #2 \@nil\@nil
429 \edef\@tempa{\toks@{\the\toks@}}%
430 \@xp\endgroup
431 \@tempa
432 }
433 % \end{macrocode}
434 % \end{macro}
435 %
436 % \begin{macro}{\find@property}
437 % \begin{macrocode}
438 \def\reset@scan@a#1#2{%
439 \ifx\@nil#1%
440 \else
441 \def\@tempb{#1}%
442 \ifx\@tempa\@tempb
443 \ifnum\@tempcnta<\z@
444 \@temptokenb\@temptokena
445 \else
446 \advance\@tempcntb\@ne
447 \ifnum\@tempcntb=\@tempcnta
448 \@temptokenb\@temptokena
449 \fi
450 \fi
451 \else
452 \@temptokenb{#2}%
453 \fi
454 \edef\@tempb{%
455 \toks@{\the\toks@ \@nx#1{\the\@temptokenb}}%
456 }%
457 \@tempb
458 \@xp\reset@scan@a
459 \fi
460 }
461 % \end{macrocode}
462 % \end{macro}
463 %
464 % \section{Some machinery for finite state automata}
465 %
466 % Coincidentally I needed to write two finite state automaton parsers
467 % for two related packages, so after writing them separately I spent
468 % some time analyzing the code fragments they shared in common and
469 % abstracted them so that the cs names could be shared.
470 %
471 % \begin{macro}{\fsa@l}
472 % FSA lookahead.
473 % \begin{macrocode}
474 \def\fsa@l{\futurelet\@let@token\fsa@t}
475 % \end{macrocode}
476 % \end{macro}
477 %
478 % \begin{macro}{\fsa@b}
479 % FSA bypass a token. Don't delete the space at the end!
480 % \begin{macrocode}
481 \def\fsa@b{\afterassignment\fsa@l \let\@let@token= }
482 % \end{macrocode}
483 % \end{macro}
484 %
485 % \begin{macro}{\fsa@c}
486 % FSA copy a token (not space, bgroup, egroup).
487 % \begin{macrocode}
488 \def\fsa@c#1{\aftergroup#1\fsa@l}
489 % \end{macrocode}
490 % \end{macro}
491 %
492 % \begin{macro}{\fsa@n}
493 % FSA next action. This is just a placeholder definition.
494 % \begin{macrocode}
495 \let\fsa@n\@empty
496 % \end{macrocode}
497 % \end{macro}
498 %
499 % \begin{macro}{\fsa@t}
500 % FSA test. This is just a placeholder definition.
501 % \begin{macrocode}
502 \let\fsa@t\@empty
503 % \end{macrocode}
504 % \end{macro}
505 %
506 % \section{Now some of the real work}
507 %
508 % \begin{macro}{\rsk@toks}
509 % \begin{macrocode}
510 \newtoks\rsk@toks
511 % \end{macrocode}
512 % \end{macro}
513 %
514 % \begin{macro}{\rkvIfEmpty}
515 % Beginning here.
516 % \begin{macrocode}
517 \def\rkvIfEmpty#1#2{%
518 \@xp\ifx\csname#1'#2\endcsname\@empty
519 \@xp\@firstoftwo
520 \else
521 \@xp\@secondoftwo
522 \fi
523 }
524 % \end{macrocode}
525 % \end{macro}
526 %
527 % \begin{macro}{\rkvIfAdditive}
528 % \begin{macrocode}
529 \def\rkvIfAdditive#1{%
530 \@xp\let\@xp\@let@token \csname \rkv@setter#1\endcsname
531 \afterassignment\@nilgobble
532 \@xp\let\@xp\@let@token \@let@token \@empty\@empty\@nil
533 \ifx\@let@token\DSK@append
534 \@xp\@firstoftwo
535 \else
536 \@xp\@secondoftwo
537 \fi
538 }
539 % \end{macrocode}
540 % \end{macro}
541 %
542 % \begin{macro}{\rkv@setter}
543 % It irritates me that I can't embed the \ncn{csname} and
544 % \ncn{endcsname} in here.
545 % \begin{macrocode}
546 \def\rkv@setter#1{set:\@xp\@gobble\string#1}
547 % \end{macrocode}
548 % \end{macro}
549 %
550 % \begin{macro}{\rkv@DSAK}
551 % Define a simple, superseding, or additive key.
552 % \begin{macrocode}
553 \def\rkv@DSAK#1#2{%
554 \addto@group@reset#1{\let#1\@empty}%
555 \edef\@tempa{\def\csname \rkv@setter#1\endcsname}%
556 \@tempa{#2#1}%
557 }
558 % \end{macrocode}
559 % \end{macro}
560 %
561 % \begin{macro}{\rkv@DDK}
562 % This function is used for a dummy key whose value (expansion)
563 % should be empty but that should appear non-empty to
564 % \cs{rkvIfEmpty}.
565 % \begin{macrocode}
566 \def\rkv@DDK#1{%
567 \addto@group@reset#1{\def#1{\@empty}}%
568 \@xp\let\csname \rkv@setter#1\endcsname\@gobble
569 }
570 % \end{macrocode}
571 % \end{macro}
572 %
573 % \begin{macro}{\DSK@def}
574 % \begin{macrocode}
575 \def\DSK@def#1{%
576 \ifx#1\@empty\else
577 \PackageWarningNoLine{rkeyval}%
578 {Key \string#1 should not be repeated}%
579 \fi
580 \DSK@redef#1%
581 }
582 % \end{macrocode}
583 % \end{macro}
584 %
585 % \begin{macro}{\DSK@redef}
586 % We weed out empty field values for consistency with
587 % \cs{DSK@append}.
588 % \begin{macrocode}
589 \def\DSK@redef#1#2{%
590 \@ifempty{#2}{\@gobble}{%
591 \def#1{#2}%
592 \set@property#1
593 }%
594 }
595 % \end{macrocode}
596 % \end{macro}
597 %
598 % \begin{macro}{\init@group@reset}
599 % \begin{macrocode}
600 \def\init@group@reset#1{%
601 \begingroup
602 \edef\@tempb{\@xp\@nx\csname #1@reset\endcsname}%
603 \@xp\ifx\@tempb\relax
604 \@xp\xdef\@tempb{\let \csname #1,aux\endcsname\@nx\@empty}
605 \fi
606 \endgroup
607 }
608 % \end{macrocode}
609 % \end{macro}
610 %
611 % \begin{macro}{\addto@group@reset}
612 % \begin{macrocode}
613 \def\addto@group@reset#1{%
614 \begingroup
615 \edef\@tempa{\extract@group#1}%
616 \init@group@reset\@tempa
617 \edef\@tempa{%
618 \@nx\g@addto@macro\@xp\@nx\csname\@tempa @reset\endcsname
619 }%
620 \@xp\endgroup
621 \@tempa
622 }
623 % \end{macrocode}
624 % \end{macro}
625 %
626 % \begin{macro}{\DefineSimpleKey}
627 % \begin{macrocode}
628 \newcommand{\DefineSimpleKey}[2]{%
629 \@xp\rkv@DSAK
630 \csname #1'#2\endcsname
631 {\DSK@def}%
632 }
633 % \end{macrocode}
634 % \end{macro}
635 %
636 % \begin{macro}{\DefineSupersedingKey}
637 % \begin{macrocode}
638 \newcommand{\DefineSupersedingKey}[2]{%
639 \@xp\rkv@DSAK
640 \csname #1'#2\endcsname
641 {\DSK@redef}%
642 }
643 % \end{macrocode}
644 % \end{macro}
645 %
646 % \begin{macro}{\DefineAdditiveKey}
647 % \begin{macrocode}
648 \newcommand{\DefineAdditiveKey}[3]{%
649 \@xp\rkv@DSAK
650 \csname #1'#2\endcsname
651 {\DSK@append#3}%
652 }
653 % \end{macrocode}
654 % \end{macro}
655 %
656 % \begin{macro}{\DSK@append}
657 % We weed out empty field values (e.g., |editor={}| or
658 % \verb*|editor={ }|) because otherwise an additive field could
659 % end up with a value like |\name{}| which appears non-empty to
660 % \cs{rkvIfEmpty} but produces no output on the page.
661 % \begin{macrocode}
662 \def\DSK@append#1#2#3{%
663 \@ifempty{#3}{\@gobble}{%
664 \@append#1#2{#3}%
665 \set@property#2
666 }%
667 }
668 % \end{macrocode}
669 % \end{macro}
670 %
671 % \begin{macro}{\DefineDummyKey}
672 % \begin{macrocode}
673 \newcommand{\DefineDummyKey}[2]{%
674 \@xp\rkv@DDK \csname #1'#2\endcsname
675 }
676 % \end{macrocode}
677 % \end{macro}
678 %
679 % \begin{macro}{\RestrictedSetKeys}
680 % \begin{macrocode}
681 \newcommand{\RestrictedSetKeys}[3]{%
682 \global\rsk@toks\@xp{\csname #2@reset\endcsname}%
683 \def\rsk@finish{#3}%
684 \gdef\rsk@set{\@xp\rsk@set@a\csname#2'}%
685 #1\relax
686 \begingroup
687 \rsk@changecase
688 \aftergroup\rsk@set
689 % \end{macrocode}
690 % Start by removing the opening brace.
691 % \begin{macrocode}
692 \let\fsa@t\rsk@z
693 \fsa@l
694 }
695 % \end{macrocode}
696 % \end{macro}
697 %
698 % The aftergroup tokens end up looking like this:
699 % \begin{verbatim}
700 % \lowercase{\rsk@set FIELDNAME\endcsname}
701 % --> \@xp\rsk@set@a\csname bib'fieldname\endcsname
702 % --> \rsk@set@a\bib'abcdef
703 %\end{verbatim}
704 %
705 % \begin{macro}{\rsk@unknown@key}
706 % \begin{macrocode}
707 \def\rsk@unknown@key#1{%
708 \PackageWarning{rkeyval}{Unknown key: \string#1}%
709 \@xp\def\csname\rkv@setter#1\endcsname {\DSK@redef#1}%
710 }
711 % \end{macrocode}
712 % \end{macro}
713 %
714 % \section{The state machine}
715 %
716 %\begin{verbatim}
717 % State 0: Skip opening brace (\rsk@z).
718 % space -> 0
719 % { -> 2
720 % other -> error "Missing open brace"
721 %
722 % State 1: Skip comma (\rsk@a).
723 % space -> 1
724 % \par -> 1
725 % comma -> 2
726 % @ -> read optional arg; 1
727 % } -> 6
728 % other -> error "Missing comma"; 2
729 %
730 % State 2: Find field name (\rsk@b).
731 % space -> 2
732 % \par -> 2
733 % comma -> 2
734 % letter -> 3
735 % { -> error "Missing key name"; 4
736 % } -> 6
737 % other -> error "Invalid key name character"; 2
738 %
739 % State 3: Scan field name (\rsk@c).
740 % letter -> 3
741 % comma -> error "Invalid key name character"; 3
742 % equal -> 4
743 % other punct -> 3
744 % space -> 4
745 % { -> error "Missing equal sign"; 4
746 % } -> error "Missing equal sign"; 4
747 % other -> error "Invalid key name character"; 3
748 %
749 % State 4: Skip equals (\rsk@d).
750 % space -> 4
751 % equal -> 4
752 % { -> 5
753 % other -> error "Missing { for value of current key"; 5
754 %
755 % State 5: Read field value (\rsk@set@a).
756 % any -> 1
757 %
758 % State 6: Done (\rsk@end).
759 %\end{verbatim}
760 %
761 % \begin{macro}{\rsk@z}
762 % State 0: Skip opening brace.
763 % \begin{macrocode}
764 \def\rsk@z{%
765 \ifx\bgroup\@let@token
766 \let\fsa@t\rsk@b
767 \let\fsa@n\fsa@b
768 \else
769 \ifx\@sptoken\@let@token
770 \let\fsa@n\fsa@b
771 \else
772 \rsk@errf
773 \fi
774 \fi
775 \fsa@n
776 }
777 % \end{macrocode}
778 % \end{macro}
779 %
780 % \begin{macro}{\rsk@a}
781 % State 1: Skip comma.
782 % \begin{macrocode}
783 \def\rsk@a{%
784 \ifx\@let@token\@sptoken
785 \let\fsa@n\fsa@b
786 \else
787 \ifx\@let@token\par
788 \let\fsa@n\fsa@b
789 \else
790 \ifx,\@let@token
791 \endgroup
792 \let\fsa@t\rsk@b
793 \let\fsa@n\fsa@b
794 \else
795 \ifx\egroup\@let@token
796 \endgroup
797 \let\fsa@n\rsk@end
798 \else
799 \endgroup
800 \let\fsa@n\rsk@erraa
801 \fi
802 \fi
803 \fi
804 \fi
805 \fsa@n
806 }
807 % \end{macrocode}
808 % \end{macro}
809 %
810 % \begin{macro}{\rsk@b}
811 % State 2: Find field name.
812 %
813 % Allow \cs{par} here to permit a blank line after
814 % the end of one key-val pair and the start of the next (perhaps to
815 % break up a long list into sections).
816 % \begin{macrocode}
817 \def\rsk@b{%
818 \ifcat\@nx\@let@token A%
819 \let\fsa@t\rsk@c
820 \let\fsa@n\fsa@c
821 \else
822 \ifx\@sptoken\@let@token
823 \let\fsa@n\fsa@b
824 \else
825 \rsk@bb
826 \fi
827 \fi
828 \fsa@n
829 }
830 % \end{macrocode}
831 % \end{macro}
832 %
833 % \begin{macro}{\rsk@bb}
834 % \begin{macrocode}
835 \def\rsk@bb{%
836 \ifx,\@let@token
837 \let\fsa@n\fsa@b
838 \else
839 \ifx\bgroup\@let@token
840 \let\fsa@n\rsk@errb
841 \else
842 \ifx\egroup\@let@token
843 \let\fsa@n\rsk@end
844 \else
845 \ifx\par\@let@token
846 \let\fsa@n\fsa@b
847 \else
848 \let\fsa@n\rsk@errc
849 \fi
850 \fi
851 \fi
852 \fi
853 }
854 % \end{macrocode}
855 % \end{macro}
856 %
857 % \begin{macro}{\rsk@c}
858 % State 3: Scan field name.
859 % \begin{macrocode}
860 \def\rsk@c{%
861 \ifcat\@nx\@let@token A%
862 \let\fsa@n\fsa@c
863 \else
864 \ifx\@sptoken\@let@token
865 \let\fsa@t\rsk@d
866 \let\fsa@n\fsa@b
867 \else
868 \ifx=\@let@token
869 \let\saw@equal T%
870 \let\fsa@t\rsk@d
871 \let\fsa@n\fsa@b
872 \else
873 \rsk@cb
874 \fi
875 \fi
876 \fi
877 \fsa@n
878 }
879 % \end{macrocode}
880 % \end{macro}
881 %
882 % \begin{macro}{\rsk@cb}
883 % \begin{macrocode}
884 \def\rsk@cb{%
885 \ifx,\@let@token
886 \let\fsa@n\rsk@errc
887 \else
888 \ifcat\@nx\@let@token .%
889 \let\fsa@n\fsa@c
890 \else
891 \ifx\bgroup\@let@token
892 \let\fsa@n\rsk@noequal
893 \else
894 \ifx\egroup\@let@token
895 \let\fsa@n\rsk@noequal
896 \else
897 \let\fsa@n\rsk@errc
898 \fi
899 \fi
900 \fi
901 \fi
902 }
903 % \end{macrocode}
904 % \end{macro}
905 %
906 % \begin{macro}{\saw@equal}
907 % \begin{macrocode}
908 \let\saw@equal=F
909 % \end{macrocode}
910 % \end{macro}
911 %
912 % \begin{macro}{\rsk@d}
913 % State 4: Skip equals.
914 %
915 % If no equal sign ever came
916 % along, then give a warning about it and set \cs{saw@equal} to true
917 % so that when \cs{rsk@noequal} cycles through again it will take the
918 % other branch.
919 % \begin{macrocode}
920 \def\rsk@d{%
921 \ifx\bgroup\@let@token
922 \ifx\saw@equal T%
923 \aftergroup\endcsname
924 \rsk@endcase
925 \let\fsa@n\endgroup
926 \else
927 \let\saw@equal T%
928 \let\fsa@n\rsk@noequal
929 \fi
930 \else
931 \ifx\@sptoken\@let@token
932 \let\fsa@n\fsa@b
933 \else
934 \ifx=\@let@token
935 \let\saw@equal T%
936 \let\fsa@n\fsa@b
937 \else
938 \let\fsa@n\rsk@erre
939 \fi
940 \fi
941 \fi
942 \fsa@n
943 }
944 % \end{macrocode}
945 % \end{macro}
946 %
947 % \begin{macro}{\rsk@casesensitive}
948 % \begin{macrocode}
949 \def\rsk@casesensitive{%
950 \let\rsk@changecase\@empty
951 \let\rsk@endcase\@empty
952 }
953 % \end{macrocode}
954 % \end{macro}
955 %
956 % \begin{macro}{\rsk@startlc}
957 % \begin{macrocode}
958 \def\rsk@startlc{\aftergroup\lowercase\aftergroup{\iffalse}\fi}
959 % \end{macrocode}
960 % \end{macro}
961 %
962 % \begin{macro}{\rsk@endlc}
963 % \begin{macrocode}
964 \def\rsk@endlc{\iffalse{\fi\aftergroup}}
965 % \end{macrocode}
966 % \end{macro}
967 %
968 % \begin{macro}{\rsk@lowercase}
969 % \begin{macrocode}
970 \def\rsk@lowercase{%
971 \let\rsk@changecase\rsk@startlc
972 \let\rsk@endcase\rsk@endlc
973 }
974 % \end{macrocode}
975 % \end{macro}
976 %
977 % \begin{macrocode}
978 \rsk@lowercase
979 % \end{macrocode}
980 %
981 % \begin{macro}{\rsk@resume}
982 % Here we get improved reporting of error context by changing
983 % end-of-line to be different from normal space. If we don't find a
984 % comma on the current line, assume it is an error.
985 % \begin{macrocode}
986 \def\rsk@resume{%
987 \begingroup
988 \rsk@changecase
989 \aftergroup\rsk@set
990 \let\fsa@t\rsk@a
991 \begingroup
992 \catcode\endlinechar=\active
993 \lccode`\~=\endlinechar
994 \lowercase{\let~\par}%
995 \fsa@l
996 }
997 % \end{macrocode}
998 % \end{macro}
999 %
1000 % \begin{macro}{\rsk@set@a}
1001 % State 5: Read field value.
1002 % \begin{macrocode}
1003 \def\rsk@set@a#1#2{%
1004 \star@{\rsk@set@b#1{#2}}{}%
1005 }
1006 % \end{macrocode}
1007 % \end{macro}
1008 %
1009 % \begin{macro}{\rsk@set@b}
1010 % \begin{macrocode}
1011 \def\rsk@set@b#1#2#3{%
1012 \@xp\ifx \csname\rkv@setter#1\endcsname \relax
1013 \rsk@unknown@key#1%
1014 \fi
1015 \edef\@tempa{\@xp\@nx\csname \rkv@setter#1\endcsname}%
1016 \toks@\@xp{\@tempa{#2}{#3}}%
1017 \edef\@tempa{%
1018 \global\rsk@toks{\the\rsk@toks \the\toks@}%
1019 }%
1020 \@tempa
1021 \rsk@resume
1022 }
1023 % \end{macrocode}
1024 % \end{macro}
1025 %
1026 % \begin{macro}{\rsk@end}
1027 % State 6: Done.
1028 %
1029 % Lets see, now why did I add this?
1030 % \begin{macrocode}
1031 \def\rsk@end{%
1032 \global\let\rsk@set\rsk@terminate
1033 \rsk@endcase
1034 \endgroup
1035 \endcsname
1036 \afterassignment\rsk@finish
1037 \toks@\bgroup
1038 }
1039 % \end{macrocode}
1040 % \end{macro}
1041 %
1042 % \begin{macro}{\rsk@terminate}
1043 % \begin{macrocode}
1044 \def\rsk@terminate{\@xp\@gobble\csname}
1045 % \end{macrocode}
1046 % \end{macro}
1047 %
1048 % \begin{macro}{\NoCommaWarning}
1049 % \begin{macrocode}
1050 \def\NoCommaWarning{\PackageWarning{rkeyval}{Missing comma}}%
1051 % \end{macrocode}
1052 % \end{macro}
1053 %
1054 %% % \begin{macro}{\NoCommaError}
1055 %% % \begin{macrocode}
1056 %% \def\NoCommaError{\rsk@err{Missing comma}\@ehc}
1057 %% % \end{macrocode}
1058 %% % \end{macro}
1059 %
1060 % \begin{macro}{\rsk@nocomma}
1061 % \begin{macrocode}
1062 \def\rsk@nocomma{\NoCommaWarning}
1063 % \end{macrocode}
1064 % \end{macro}
1065 %
1066 % \begin{macro}{\rsk@err}
1067 % \begin{macrocode}
1068 \def\rsk@err{\PackageError{rkeyval}}
1069 % \end{macrocode}
1070 % \end{macro}
1071 %
1072 % \begin{macro}{\rsk@errf}
1073 % \begin{macrocode}
1074 \def\rsk@errf{\rsk@err{Missing open brace}\@ehc\rsk@b}
1075 % \end{macrocode}
1076 % \end{macro}
1077 %
1078 % \begin{macro}{\rsk@erraa}
1079 % \begin{macrocode}
1080 \long\def\rsk@erraa{\rsk@nocomma \let\fsa@t\rsk@b \fsa@l}
1081 % \end{macrocode}
1082 % \end{macro}
1083 %
1084 % \begin{macro}{\rsk@errb}
1085 % \begin{macrocode}
1086 \def\rsk@errb{\rsk@err{Missing key name}\@ehc\rsk@d}
1087 % \end{macrocode}
1088 % \end{macro}
1089 %
1090 % \begin{macro}{\rsk@errc}
1091 % \begin{macrocode}
1092 \def\rsk@errc{\rsk@err{Invalid key name character}\@ehc\fsa@b}
1093 % \end{macrocode}
1094 % \end{macro}
1095 %
1096 % \begin{macro}{\rsk@noequal}
1097 % \begin{macrocode}
1098 \def\rsk@noequal{\rsk@err{Missing equal sign}\@ehc\rsk@d}
1099 % \end{macrocode}
1100 % \end{macro}
1101 % \begin{macro}{\rsk@erre}
1102 % In this case we guess that the value is without braces but probably
1103 % terminated with a comma. We want to scan up to the comma in order
1104 % to get back in synch.
1105 % \begin{macrocode}
1106 \def\rsk@erre#1,{%
1107 \rsk@err{Missing open brace for key value}\@ehc
1108 \iffalse{\fi
1109 \endgroup
1110 \endcsname
1111 \rsk@endcase }{#1},%
1112 }
1113 % \end{macrocode}
1114 % \end{macro}
1115 %
1116 % \begin{macrocode}
1117 \PopCatcodes
1118 % \end{macrocode}
1119 %
1120 % The usual \cs{endinput} to ensure that random garbage at the end of
1121 % the file doesn't get copied by \fn{docstrip}.
1122 % \begin{macrocode}
1123 \endinput
1124 % \end{macrocode}
1125 %
1126 % \CheckSum{871}
1127 % \Finale