| 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 |