Debian Codegraph @

texmf-dist/source/latex/qstest/makematch.dtx

raw
1 % \iffalse
2 %%
3 %% Copyright (C) 2006, 2007 QuinScape GmbH
4 %% http://www.quinscape.de
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % http://www.latex-project.org/lppl.txt
11 % \fi
12 % \CheckSum{354}
13 % \section{Using \texttt{makematch}}
14 %
15 % The basic idea of \texttt{makematch} is to compile patterns and
16 % targets (and/or lists of them) and match the former to the latter.
17 % This functionality is used extensively in QuinScape's
18 % \href{file:qstest}{\texttt{qstest}} package for unit testing. We'll
19 % use that package for documenting usage of \texttt{makematch}; the
20 % following construct is skips the tests when \texttt{makematch.dtx} is
21 % used as a standalone file.
22 % \begin{macrocode}
23 %<*dtx>
24 \iffalse
25 %</dtx>
26 %<*test>
27 \RequirePackage{makematch,qstest}
28 \IncludeTests{*}
29 % \end{macrocode}
30 %
31 % \texttt{makematch} requires an e\TeX-based \LaTeX\ which should be
32 % standard for current \TeX\ distributions.
33 %
34 % \hypertarget{patterns}{%
35 % \subsection{Match patterns and targets}
36 % } This
37 % package has the notion of match patterns and targets. Patterns and
38 % targets get sanitized at the time they are specified; this means
39 % that nothing gets expanded, but replaced by a textual representation
40 % consisting of spaces (with catcode~10) and other characters
41 % (catcode~12). Control words are usually followed by a single space
42 % when getting sanitized.
43 %
44 % Patterns and targets are actually generalized to pattern and target
45 % lists by this package: you can, when specifying either, instead give
46 % a list by using an optional argument for specifying a list separator
47 % (the lists used in \texttt{qstest} are comma-separated).
48 %
49 % Target lists are unordered: the order of targets in them is
50 % irrelevant. Leading spaces in front of each target get stripped,
51 % all others are retained.
52 %
53 % Pattern lists similarly consist of a list of patterns, with leading
54 % spaces stripped from each pattern. In contrast to target lists, the
55 % order of pattern lists is significant, with later patterns
56 % overriding earlier ones. Also in contrast to target lists, empty
57 % patterns are removed.
58 %
59 % There are two special characters inside of a pattern: the first is
60 % the wildcard |*| which matches any number of consecutive characters
61 % (including the empty string) in a target. Wildcards can occur
62 % anywhere and more than once in a pattern.
63 %
64 % The second special character in a pattern is only recognized at the
65 % beginning of a pattern, and only if that pattern is part of a
66 % pattern list (namely, when a list separator is
67 % specified).\footnote{And if |!| is not the list separator of the
68 % list.} If a pattern is preceded by |!| then the following
69 % pattern, if it matches, causes any previous match from the pattern
70 % list to be disregarded.
71 %
72 % So for example, the pattern list |{*,!foo}| matches any target list
73 % that does not contain the match target |foo|.
74 %
75 % An empty target list |{}| is considered to contain the empty string.
76 % Thus the pattern |*| matches every target list, including empty
77 % ones, while the pattern list |{}| does not match any keyword list,
78 % including empty ones.
79 %
80 % \subsection{The Interface}
81 %
82 % \DescribeMacro{\MakeMatcher} takes two mandatory arguments. The
83 % first is a macro name. This macro will become the new matcher. The
84 % second argument of \cmd{\MakeMatcher} is the pattern to match. An
85 % optional argument before the mandatory ones can be used for
86 % specifying a list separator in which case the first mandatory
87 % argument becomes a pattern list (only in this case are leading |!|
88 % characters before list elements interpreted specially).
89 % \begin{macrocode}
90 \begin{qstest}{\MakeMatcher}{\MakeMatcher}
91 \MakeMatcher\stylefiles{*.sty}
92 \MakeMatcher\headbang{!*}
93 \MakeMatcher[,]\truestylefiles{*.sty,!.thumbnails/*,!*/.thumbnails/*}
94 % \end{macrocode}
95 % The matcher constructed in that manner is called with three
96 % arguments. The first argument is a control sequence name containing
97 % a match target (or target list) prepared using
98 % \cmd{\MakeMatchTarget} (see below).
99 %
100 % Alternatively, the first argument can be a brace-enclosed list (note
101 % that you'll need \emph{two} nested levels of braces, one for
102 % enclosing the argument, one for specifying that this is a list)
103 % which will then get passed to \cmd{\MakeMatchTarget} (see below) for
104 % processing before use. The inner level of braces inside of the
105 % first argument may be preceded by a bracketed optional argument
106 % specifying the list separator for this list.
107 %
108 % The second argument of the matcher is executed if the pattern list
109 % for which the matcher has been built matches the keyword list. The
110 % third is executed if it doesn't. List separators of pattern and
111 % keyword list are completely independent from each other. Ok, we
112 % expect the following to result just in calls of \cmd{\true} (a call
113 % of \cmd{\false} is turned into a failed expectation):
114 % \begin{macrocode}
115 \begin{qstest}{\Makematcher literal}{\MakeMatcher}
116 \begin{ExpectCallSequence}{\true{}\false{}`%
117 .#1{\Expect*{\CalledName#1}{true}}+'}
118 \stylefiles{{xxx/.thumbnails/blubb.sty}}{\true}{\false}
119 \truestylefiles{{xxx/.thumbnails/blubb.sty}}{\false}{\true}
120 \headbang{{xxx/.thumbnails/blubb.sty}}{\false}{\true}
121 \stylefiles{[ ]{x.sty.gz .thumbnails/x.sty !x}}{\true}{\false}
122 \truestylefiles{[ ]{x.sty.gz .thumbnails/x.sty !x}}{\false}{\true}
123 \headbang{[ ]{x.sty.gz .thumbnails/x.sty !x}}{\true}{\false}
124 \end{ExpectCallSequence}
125 \end{qstest}
126 % \end{macrocode}
127 %
128 % So how do we create a sanitized keyword list in a control sequence?
129 %
130 % \DescribeMacro{\MakeMatchTarget} is called with two mandatory
131 % arguments, the first being a control sequence name where the keyword
132 % list in the second argument will get stored in a sanitized form: it
133 % is converted without expansion to characters of either ``special''
134 % or ``space'' category (catcodes 12 and~10, respectively), and any
135 % leading spaces at the beginning of an element is removed. Without
136 % an optional bracketed argument, not more than sanitization and
137 % leading space stripping is done. If an optional bracketed argument
138 % before the mandatory arguments is specified, it defines the list
139 % separator: this has to be a single sanitized character token (either
140 % a space or a character of category ``other'') that is used as the
141 % list separator for the input (the finished list will actually always
142 % use the macro |\,| as a list separator).
143 % \begin{macrocode}
144 \begin{qstest}{\Makematcher with \MakeMatchTarget}%
145 {\MakeMatcher,\MakeMatchTarget}
146 \MakeMatchTarget\single{xxx/.thumbnails/blubb.sty}
147 \MakeMatchTarget[ ]\multiple{x.sty.gz .thumbnails/x.sty !x}
148 \begin{ExpectCallSequence}{\true{}\false{}`%
149 .#1{\Expect*{\CalledName#1}{true}}+'}
150 \stylefiles{\single}{\true}{\false}
151 \truestylefiles\single{\false}{\true}
152 \headbang\single{\false}{\true}
153 \stylefiles{\multiple}{\true}{\false}
154 \truestylefiles\multiple{\false}{\true}
155 \headbang\multiple{\true}{\false}
156 \end{ExpectCallSequence}
157 \end{qstest}
158 % \end{macrocode}
159 % \DescribeMacro{\MatchedTarget} This will after a match process
160 % contain the target matched by the last matching pattern (if several
161 % targets in a match target list match, only the first of those is
162 % considered and recorded), regardless of whether the corresponding
163 % pattern was negated with |!|.
164 %
165 % \DescribeMacro{\RemoveMatched} After a successful match, you can
166 % call \cmd{\RemoveMatched} with one argument: the control sequence
167 % name where the list was kept, and the match will get removed from
168 % the list. If every list element is removed, the list will be
169 % identical to \cmd{\@empty}.
170 % \begin{macrocode}
171 \begin{qstest}{\MatchedTarget}
172 {\MakeMatcher,\MakeMatchTarget,\MatchedTarget}
173 \MakeMatchTarget\single{xxx/.thumbnails/blubb.sty}
174 \MakeMatchTarget[ ]\multiple{x.sty.gz .thumbnails/x.sty !x}
175 \begin{ExpectCallSequence}{\true{}\false{}`%
176 .#1{\Expect*{\CalledName#1}{true}}+'}
177 \stylefiles{\single}{\true}{\false}
178 \Expect*{\single}{xxx/.thumbnails/blubb.sty}
179 \Expect*{\meaning\MatchedTarget}*{\meaning\single}
180 \RemoveMatched\single
181 \Expect*{\meaning\single}{macro:->}
182 \truestylefiles\single{\false}{\true}
183 \headbang\single{\false}{\true}
184 \stylefiles{\multiple}{\true}{\false}
185 \Expect*{\MatchedTarget}{.thumbnails/x.sty}
186 \RemoveMatched\multiple
187 \Expect\expandafter{\multiple}{x.sty.gz\,!x}
188 \truestylefiles\multiple{\false}{\true}
189 \Expect*{\meaning\MatchedTarget}{undefined}
190 \headbang\multiple{\true}{\false}
191 \Expect*{\MatchedTarget}{!x}
192 \RemoveMatched\multiple
193 \Expect*{\multiple}{x.sty.gz}
194 \end{ExpectCallSequence}
195 \end{qstest}
196 \end{qstest}
197 % \end{macrocode}
198 %
199 % \subsection{Notes on sanitization}
200 % Note that sanitization to printable characters has several
201 % consequences: it means that the control sequence \cmd{\,} will turn
202 % into the string |\| followed by the end of the keyword. Note also
203 % that single-character control sequences with a nonletter name are
204 % not followed by a space in sanitization. This means that
205 % sanitization depends on the current catcodes. Most particularly,
206 % sanitizing the input |\@abc12| will turn into |\@abc 12| when |@| is
207 % of catcode letter, but to |\@abc12| when |@| is a nonletter.
208 %
209 % So sanitization cannot hide all effects of catcode differences. It
210 % is still essential since otherwise braces would cause rather severe
211 % complications during matching.
212 %
213 % Another curiosity of sanitization is that explicit macro parameter
214 % characters (usually |#|) get duplicated while being sanitized.
215 %
216 % So this is the end of the documentation section, so we end our test
217 % file setup by complementing the beginning:
218 % \begin{macrocode}
219 %</test>
220 %<*dtx>
221 \fi
222 %</dtx>
223 % \end{macrocode}
224 %
225 % \StopEventually{}
226 % \section{The driver file}
227 % An explicit driver file generated by docstrip will typeset the
228 % implementation. Running the |.dtx| file through, in contrast, will
229 % only typeset the user level documentation.
230 % \begin{macrocode}
231 %<*driver>
232 \documentclass{ltxdoc}
233 \usepackage{makematch}
234 \usepackage{ifpdf}
235 \usepackage{hyperref}
236 \OnlyDescription
237 %<driver> \AlsoImplementation
238 \begin{document}
239 \GetFileInfo{makematch.sty}
240 \date{\filedate}
241 \title{\texttt{\filename}\\\fileinfo\\version \fileversion}
242 \author{David Kastrup\thanks{\href{mailto:[email protected]}%
243 {[email protected]}, \href{http://quinscape.de}{QuinScape
244 GmbH}}}
245 \maketitle
246 \DocInput{makematch.dtx}
247 \end{document}
248 %</driver>
249 % \end{macrocode}
250 % \section{The installer file}
251 %
252 % There is no separate installer file for this package as it is part
253 % of the \texttt{qstest} bundle and uses its
254 % \href{file:qstest#installer}{installer}.
255 %
256 % \section{The Implementation}
257 % \subsection{Front matter}
258 % Some data and version magic from SVN keyword expansion.
259 % \begin{macrocode}
260 %<*package>
261 \NeedsTeXFormat{LaTeX2e}
262 \def\next$#1: #2.dtx #3 #4-#5-#6 #7${%
263 \ProvidesPackage{#2}[#4/#5/#6 1.#3 Pattern matching with
264 wildcards]
265 }
266 \next
267 $Id: makematch.dtx 7925 2007-02-23 14:22:19Z dkastrup $
268 % \end{macrocode}
269 % \subsection{Pattern matching}
270 % \begin{macro}{\MakeMatcher}
271 % This is the principal magic for doing pattern matching. The
272 % control sequence name given in |#1| becomes a pattern matching
273 % engine for the pattern list specified in |#2|. If this control
274 % sequence is executed at a later point of time, it matches the
275 % compiled pattern list to the keyword list contained in the
276 % sanitized macro specified in its first argument (if the first
277 % argument itself starts with an additional opening brace, it is
278 % considered to be a keyword list that yet needs to be sanitized).
279 %
280 % Macros in |#2| are not expanded, and everything but spaces is
281 % converted to catcode~12 characters. At the start of a pattern or
282 % a keyword, spaces get ignored. Spaces inside of patterns or
283 % keywords should work as expected, however.
284 % \begin{macrocode}
285 \newcommand\MakeMatcher[3][\relax]{%
286 %<etex> \edef#2{\detokenize{#3}}%
287 %<*!etex>
288 \toks@{#3}%
289 \edef#2{\the\toks@}%
290 \@onelevel@sanitize#2%
291 %</!etex>
292 \def\qst@mmtmp##1##2#1{\qst@parseonecase{##1}{##2}}%
293 \let\qst@comma= #1\relax
294 \edef#2##1{\noexpand\qst@setup##1%
295 \expandafter\qst@parsestart\expandafter\@firstoftwo
296 % \end{macrocode}
297 % The following |{#1\m@ne}| sequence causes \cmd{\qst@parsestart} to
298 % end parsing.
299 % \begin{macrocode}
300 #2#1{#1\m@ne}\noexpand\qst@finish}}
301 % \end{macrocode}
302 % \end{macro}
303 % We define two shorthands for matchers that match always and never,
304 % respectively:
305 % \begin{macro}{\qst@matchalways}
306 % \begin{macrocode}
307 \long\def\qst@matchalways#1#2#3{#2}
308 % \end{macrocode}
309 % \end{macro}
310 % \begin{macro}{\qst@matchnever}
311 % \begin{macrocode}
312 \long\def\qst@matchnever#1#2#3{#3}
313 % \end{macrocode}
314 % \end{macro}
315 %
316 % \begin{macro}{\qst@setup}
317 % Gets one argument, namely a macro containing the match list, or
318 % otherwise a list enclosed with a level of braces, optionally
319 % preceded by the list separator to be used in brackets. This is
320 % stored in \cmd{\qst@matchlist}. Furthermore, \cmd{\qst@finish} is
321 % set to the default value indicating a non-match.
322 % \begin{macrocode}
323 \def\qst@setup{\let\MatchedTarget\@undefined
324 \let\qst@finish\@secondoftwo
325 \futurelet\qst@matchlist\qst@setupii}
326 \def\qst@setupii{\ifcase
327 \ifcat\noexpand\qst@matchlist\bgroup\@ne\fi
328 \ifx\qst@matchlist[\tw@\fi %]
329 \m@ne
330 \or
331 \expandafter\MakeMatchTarget\expandafter\qst@matchlist
332 \or
333 \expandafter\qst@setupiii
334 \else \expandafter\@gobble
335 \fi}
336 \def\qst@setupiii[#1]{\MakeMatchTarget[{#1}]\qst@matchlist}
337 % \end{macrocode}
338 % \end{macro}
339 %
340 % \begin{macro}{\qst@parsestart}
341 % This tests at the start of a new word whether we are finished or
342 % whether there is an inverted condition. Note that this will
343 % remove spaces before a word. |#1| indicates the polarity, |#2|~is
344 % always a single token, no braces possible.
345 % \begin{macrocode}
346 \def\qst@parsestart#1#2{%
347 \ifcase
348 \ifx\qst@comma#2\@ne\fi
349 \ifx\qst@comma\relax
350 \else\ifx!#2#1\tw@\@ne\fi
351 \fi
352 \thr@@
353 \or
354 \expandafter\qst@parsestart
355 \expandafter\@firstoftwo
356 \or
357 \expandafter\qst@parsestart
358 \expandafter\@secondoftwo
359 \or
360 \expandafter\qst@mmtmp
361 \expandafter#1%
362 \expandafter#2%
363 \fi
364 }
365 % \end{macrocode}
366 % \end{macro}
367 % \begin{macro}{\qst@afterfi}
368 % This is just a helper macro cleaning up a following |\fi|.
369 % \begin{macrocode}
370 \def\qst@afterfi#1#2\fi{\fi#1}
371 % \end{macrocode}
372 % \end{macro}
373 % \begin{macro}{\qst@parseonecase}
374 % We process one pattern here. A pattern ends with |,| and we have
375 % passed in |#1| the command to execute in case the pattern
376 % matches.
377 % \begin{macrocode}
378 \def\qst@parseonecase#1#2{%
379 \noexpand\qst@checkname {\qst@parsewild#2*\,23456789*}%
380 \noexpand#1\qst@parsestart\@firstoftwo}
381 % \end{macrocode}
382 % \end{macro}
383 % \begin{macro}{\qst@parsewild}
384 % This is the parsing macro for wildcards and stuff. |#1|~is
385 % material before the next |*| character or the end of the sequence,
386 % |#2|~is either empty (indicating the end of the word to match) or
387 % material coming after a wildcard and terminated by |*|,
388 % |#3|~contains the next unused parameter number, and |#4| contains
389 % following parameter numbers. If we emitted a wildcard code, we
390 % jump into \cmd{\qst@skipwild} in order to skip additional
391 % wildcards.
392 % \begin{macrocode}
393 \def\qst@parsewild#1*#2\,#3#4*{%
394 #1%
395 \ifx\,#2\,%
396 \else
397 #####3%
398 \qst@afterfi{\qst@skipwild#2\,#4*}%
399 \fi}
400 % \end{macrocode}
401 % \end{macro}
402 % \begin{macro}{\qst@skipwild}
403 % This caters for the case where successive wildcards are
404 % encountered. This is the case if |#1| is empty, meaning that the
405 % string started with |*|, but |#2| is non-empty, indicating that we
406 % are not at the terminal |*|.
407 % \begin{macrocode}
408 \def\qst@skipwild#1*#2\,{%
409 #1%
410 \ifcase
411 \ifx *#1*\ifx\,#2\,\else \@ne \fi \fi
412 \tw@
413 \or
414 \expandafter\qst@skipwild
415 \or
416 \expandafter\qst@parsewild\expandafter*%
417 \fi#2\,}
418 % \end{macrocode}
419 % \end{macro}
420 % \begin{macro}{\qst@checkname}
421 % This is called with a compiled form of a test pattern in~|#1| and
422 % a single token that will get assigned to \cmd{\qst@finish} in case
423 % that we got a match of the pattern with any of the comma-separated
424 % keywords in \cmd{\MatchList}.
425 %
426 % Here is how \cmd{\qst@checkname} works: both test pattern and
427 % option list are placed between commas (actually \cmd{\,}) so that
428 % a match of the test pattern on the list implies a full match. The
429 % test pattern happens to match itself when just interpreted as an
430 % unexpanded pattern string, and this pattern string does not
431 % contain commas in itself. We append the pattern string as an
432 % artificial last element in the option list. Since the trailing
433 % comma placed at the end of the match pattern can't match inside of
434 % an option, options are consumed only completely. If the pattern
435 % matched a string containing a comma, it actually did so across
436 % more than a single option. In that case, we remove everything up
437 % to the first comma and try again.
438 %
439 % We define \cmd{\qst@mmtmp} as a macro that matches starting at an
440 % arbitrary comma (throwing away everything preceding), then
441 % retaining the matched string (note that |#1| in the replacement
442 % text will faithfully reproduce what was matched by |#1| in the
443 % argument string, also note the difference between |#1| and |##1|),
444 % appending a separator of \cmd{\@nil} in order to delimit the
445 % matched sequence.
446 % \begin{macrocode}
447 \def\qst@checkname#1{%
448 \def\qst@mmtmp##1\,#1\,{#1\,\@nil}%
449 \expandafter\expandafter\expandafter\qst@checknameii
450 \expandafter\qst@mmtmp
451 \expandafter\,\qst@matchlist\,#1\,\@nil}
452 % \end{macrocode}
453 % \begin{macro}{\qst@checknameii}
454 % So we now do the check. If |#3| is |\@nil|, the sentinel has been
455 % consumed and we did not match anything. If this is not the case,
456 % we split the matched material at the first comma into |#1|
457 % and~|#2|. If |#2| is empty, no comma is contained in the match,
458 % so we matched a complete option. Otherwise, if |#2| is non-empty,
459 % the match contained a comma and was across several options
460 % (possibly breaking into the sentinel without consuming it). Ugh.
461 % We remove the first option that was conflated in the match, and
462 % restart the match process.
463 %
464 % Note that |#3| has its origin from behind a comma, so at its
465 % position there are no leading spaces that could get lost by it
466 % being an undelimited argument.
467 % \begin{macrocode}
468 \def\qst@checknameii#1\,#2\@nil#3{%
469 \ifcase
470 \ifx\@nil#3\@ne\fi
471 \ifx\@nil#2\@nil \tw@\fi
472 \m@ne
473 \or
474 \expandafter\qst@checknamenomatch
475 \or
476 \expandafter\qst@checknamematch
477 \fi \expandafter\qst@checknameii\qst@mmtmp#1\,#2#3}
478 % \end{macrocode}
479 % \begin{macro}{\qst@checknamenomatch}
480 % This removes remaining garbage and the code corresponding to the
481 % polarity of the test since the test is not taken.
482 % \begin{macrocode}
483 \def\qst@checknamenomatch#1\@nil#2{}
484 % \end{macrocode}
485 % \end{macro}
486 % \begin{macro}{\qst@checknamematch}
487 % We had a match, something which did not include a comma and at the
488 % same time left the sentinel at the end of the word list intact.
489 % So clean up and take over the right polarity.
490 % \begin{macrocode}
491 \def\qst@checknamematch#1\qst@mmtmp#2\,#3\@nil{%
492 \def\MatchedTarget{#2}%
493 \let\qst@finish}
494 % \end{macrocode}
495 % \end{macro}
496 % \end{macro}
497 % \end{macro}
498 % Now for removing patterns: |\romannumeral\z@| expands to
499 % nothing, but we use it as a an \cmd{\expandafter}-Propagator.
500 % \begin{macro}{\RemoveMatched}
501 % \begin{macrocode}
502 \def\RemoveMatched#1{\ifx#1\MatchedTarget
503 \let#1\@empty
504 \else
505 \expandafter\def\expandafter\qst@mmtmp
506 \expandafter##\expandafter1\expandafter\,\MatchedTarget\,{##1\,}%
507 \expandafter\def\expandafter#1\expandafter{%
508 \romannumeral\expandafter\expandafter\expandafter\z@
509 \expandafter\qst@remmat
510 \romannumeral\expandafter\expandafter\expandafter\z@
511 \expandafter\qst@mmtmp\expandafter\,#1\,\@nil}%
512 \fi}
513 % \end{macrocode}
514 % \end{macro}
515 % \begin{macro}{\qst@remmat}
516 % This is just a helper macro removing \cmd{\,} from around the
517 % list.
518 % \begin{macrocode}
519 \def\qst@remmat\,#1\,\@nil{#1}
520 % \end{macrocode}
521 % \end{macro}
522 %
523 % Ok, let's test this thing for some patterns.
524 % \begin{macrocode}
525 %</package>
526 %<*test>
527 \makeatletter
528 \begin{qstest}{\MakeMatcher internals}{\MakeMatcher,internal}
529 \MakeMatcher\sometest{}
530 \Expect*{\meaning\sometest}{macro:#1->\qst@setup#1\qst@finish}
531 \MakeMatcher[,]\sometest{ a, bc*, !woozle**, !*#*woz***.*x, !!*ab}
532 \Expect*{\meaning\sometest}{macro:#1->%
533 \qst@setup#1%
534 \qst@checkname{a}\@firstoftwo
535 \qst@checkname{bc##2}\@firstoftwo
536 \qst@checkname{woozle##2}\@secondoftwo
537 \qst@checkname{##2####3woz##4.##5x}\@secondoftwo
538 \qst@checkname{##2ab}\@firstoftwo
539 \qst@finish}
540 \MakeMatcher[ ]\another{ a bc* ! woozle** ! *#*woz***.*x ! ! *ab}
541 \Expect*{\meaning\another}*{\meaning\sometest}
542 \end{qstest}
543 %</test>
544 %<*package>
545 % \end{macrocode}
546 %
547 % \begin{macro}{\MakeMatchTarget}
548 % This gets two obligatory arguments, a control sequence name and
549 % the keyword list. This list is sanitized and prepared for
550 % matching. The list sanitized in this manner is stored in the
551 % control sequence in~|#2|, the first obligatory argument. The
552 % gobbledygook before and after the detokenized content is there to
553 % get started nicely into the loop with \cmd{\qst@mmtmp} and get out
554 % again without having to employ expensive tests. The purpose of
555 % \cmd{\qst@mmtmp} is to remove leading spaces from list elements
556 % and replace the list separator (which defaults to `|,|' but can be
557 % specified with an optional argument to \cmd{\MakeMatchTarget})
558 % with the sentinel separator |\,| which can't otherwise occur in a
559 % sanitized list. There are several special values for the list
560 % separator that make sense:
561 % \begin{description}
562 % \item[\textvisiblespace] A space character (catcode 10). List
563 % entries are separated by spaces.
564 % \item[$\textrm{other}_{12}$] A character of catcode~12 that is
565 % going to be used as a list separator. Don't use anything other
566 % than sanitized characters, or the effects will be as with the
567 % following:
568 % \item[\texttt{\string\relax}] The default, does not do any list
569 % replacement.
570 % \end{description}
571 % Don't ever pass anything other than a single token (possibly
572 % brace-enclosed) in this manner, or things will go really wrong.
573 % \begin{macrocode}
574 \newcommand\MakeMatchTarget[3][\relax]{%
575 \def\qst@mmtmp##1#1##2{##1\noexpand\,\qst@mmtmp##2}%
576 %<*etex>
577 \edef#2{\expandafter\qst@mmtmp\expandafter
578 \@gobbletwo\expandafter#1\detokenize{#3}\iffalse#1\fi}%
579 %</etex>
580 %<*!etex>
581 \toks@{#3}%
582 \edef#2{\the\toks@}%
583 \@onelevel@sanitize#2%
584 \edef#2{\expandafter\qst@mmtmp\expandafter
585 \@gobbletwo\expandafter#1#2\iffalse#1\fi}%
586 %</!etex>
587 }
588 % \end{macrocode}
589 % \end{macro}
590 % \subsection{The End}
591 % The test can be ended either in the driver file, or in a standalone
592 % testfile. \cmd{\stop} is \LaTeX's way of ending the processing of
593 % an input file before any document processing or setup has been done.
594 % \begin{macrocode}
595 %</package>
596 %<test>\stop
597 % \end{macrocode}
598 % \Finale