Debian Codegraph @

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

raw
1 \errorcontextlines=\maxdimen
2 % \iffalse
3 %%
4 %% Copyright (C) 2006, 2007 QuinScape GmbH
5 %% http://www.quinscape.de
6 %
7 % This file may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 % http://www.latex-project.org/lppl.txt
12 % \fi
13 %
14 % \CheckSum{1258}
15 % \section{Using \texttt{qstest}}
16 %
17 % The basic idea of \texttt{qstest} is to let the user specify a
18 % number of tests that can be performed either at package load time or
19 % while running a separate test file through \LaTeX. If you are
20 % writing |.dtx| files, it is a good idea to use Docstrip `modules'
21 % for specifying which lines are to be used for testing. The file
22 % |qstest.dtx| from which both the style file as well as this
23 % documentation have been generated has been done in this manner.
24 %
25 % Since the following tests should be ignored when the |dtx| file is
26 % compiled itself, we use this for skipping over the tests:
27 % \begin{macrocode}
28 %<*dtx>
29 \iffalse
30 %</dtx>
31 % \end{macrocode}
32 %
33 % A standalone test file actually does not need a preamble. We can
34 % load the packages with \cmd{\RequirePackage} and just go ahead. Let
35 % us demonstrate how to build such a test file by testing the |qstest|
36 % package itself:
37 % \begin{macrocode}
38 %<*test>
39 \RequirePackage{qstest}
40 % \end{macrocode}
41 %
42 % \subsection{Pattern and keyword lists}
43 %
44 % Check section \href{file:makematch#patterns}{``Match patterns and
45 % targets''} of the |makematch| package for an explanation of the
46 % comma-separated pattern and keyword lists. In a nutshell, both are
47 % lists of arbitrary material that is not expanded but rather used in
48 % sanitized (printable) form. Patterns may contain wildcard
49 % characters |*| matching zero or more characters, and may be preceded
50 % by |!| in order to negate a match from an earlier pattern in the
51 % pattern list. Leading spaces before an item in either list are
52 % discarded.
53 %
54 % \subsection{Specifying test sets}
55 %
56 % \DescribeMacro{\IncludeTests} This macro specifies a pattern list
57 % matched to tests' keyword lists in order to determine the tests to
58 % be included in this test run. The characters |*| and |!| are
59 % interpreted as explained above.
60 %
61 % For example,
62 % \begin{quote}
63 % |\IncludeTests{*, !\cs}|
64 % \end{quote}
65 % will run all tests except those that have a test keyword of |\cs| in
66 % their list of keywords. It is a good convention to specify the
67 % principal macro or environment to be tested as the first keyword.
68 %
69 % The default is to include all tests. If you are interspersing
70 % possibly expensive tests with your source file, you might want to
71 % specify something like
72 % \begin{quote}
73 % |\IncludeTests{*, !expensive}|
74 % \end{quote}
75 % or even
76 % \begin{quote}
77 % |\IncludeTests{}|
78 % \end{quote}
79 % in your document preamble, and then possibly override this on the
80 % command line with
81 % \begin{quote}
82 % |latex "\AtBeginDocument{\IncludeTests{*}}\input{file}"|
83 % \end{quote}
84 % or similar for getting a more complete test.
85 %
86 % \DescribeMacro{\TestErrors} This defines test patterns that will
87 % throw an error when failing. A test that throws an error will not
88 % also add a warning to the standard log file with extension |log|
89 % since that would be redundant.
90 %
91 % The default is |\TestErrors{*, !fails}|, have all tests that are not
92 % marked as broken throw an error when they fail.
93 %
94 % The throwing of errors does not depend on the logging settings (see
95 % below) for the default |log| file.
96 %
97 % \DescribeMacro{\LogTests} This macro receives three arguments. The
98 % first is the filename extension of a log file (the extension |log|
99 % is treated specially and uses package warning and info commands to
100 % log test failures and passes, respectively). The second is a
101 % keyword list that indicates which passed tests are to be logged.
102 % The third is a keyword list specifying which failed tests are to be
103 % logged. Let us open a file logging everything:
104 % \begin{macrocode}
105 \LogTests{lgout}{*}{*}
106 % \end{macrocode}
107 % The choice of |lgout| is made to make it possible to also have
108 % |lgin| for comparison purposes: the latter would be an |lgout| file
109 % from a previous, `definitive run', renamed and checked into version
110 % control, for the sake of being able to compare the log output from
111 % different versions.
112 %
113 % An already open log file stays open and just changes what is logged.
114 % By default, the standard |log|
115 % \mbox{(pseudo-)}\discretionary{}{}{}file is already open and logs
116 % everything.
117 %
118 % Passed and failed tests are not completely symmetric with regard to
119 % logging: test failures are logged and/or indicated on the individual
120 % failed assertions, while a successful test is only logged and/or
121 % indicated in summary.
122 %
123 % \DescribeMacro{\LogClose} You can explicitly close a log file if you
124 % want to reread it in the course of processing, or call an executable
125 % that would process it. The standard file with extension |log| will
126 % not actually get closed and flushed if you do this (though logging
127 % would stop on it), but all others might. The actual example for
128 % this follows after the tests. You can reopen a closed log file
129 % using \cmd{\LogTests}. It will then get rewritten from the
130 % beginning (with the exception for the standard |log| file, of
131 % course).
132 %
133 % \subsection{The tests}
134 %
135 % \DescribeEnv{qstest}
136 % Tests are performed within the |qstest| environment. The
137 % environment gets two arguments. The first is the name of the test
138 % recorded in the log file. The second is a list of test keywords
139 % used for deciding which tests are performed and logged.
140 %
141 % Before delving in the details of what kind of tests you can perform
142 % in this environment, we list the various commands that are given
143 % patterns and thus control what kind of tests are performed and
144 % logged.
145 %
146 % \DescribeMacro{\Expect}
147 % This is the workhorse for checking that values, dimensions, macros
148 % and other things are just like the test designer would expect them
149 % to be.
150 %
151 % This macro basically receives two brace-delimited
152 % arguments\footnote{The arguments are collected with a token register
153 % assignment. This gives several options for specifying them,
154 % including giving a token register without braces around it. It
155 % also makes it possible to precede the \textsl{balanced text} with
156 % \cmd{\expandafter} and similar expandable stuff.} and checks that
157 % they are equal after being passed through \cmd{\def} and sanitized.
158 % This means that you can't normally use |#| except when followed by a
159 % digit (all from 1 to 9 are allowed) or |#|. If you precede one of
160 % those arguments with |*| it gets passed through through \cmd{\edef}
161 % instead of \cmd{\def}. There may also be additional tokens like
162 % |\expandafter| before the opening brace. Note that the combination
163 % of \cmd{\edef} and |\the|\meta{token variable} can be used to pass
164 % through |#| characters without interpretation. e\TeX\ provides a
165 % similar effect with \cmd{\unexpanded}. So if you want to compare a
166 % token list that may contain isolated hash characters, you can do so
167 % by writing something like
168 % \begin{macrocode}
169 %<*etex>
170 \begin{qstest}{# in isolation}{\Expect, #, \unexpanded}
171 \toks0{# and #}
172 \Expect*{\the\toks0}*{\unexpanded{# and #}}
173 \end{qstest}
174 %</etex>
175 % \end{macrocode}
176 % Since the sanitized version will convert |#| macro parameters to the
177 % string |##|, you might also do this explicitly (and without e\TeX)
178 % as
179 % \begin{macrocode}
180 \begin{qstest}{# in isolation 2}{\Expect, #, \string}
181 \toks0{# and #}
182 \Expect*{\the\toks0}*{\string#\string# and \string#\string#}
183 \end{qstest}
184 % \end{macrocode}
185 % If the token register is guaranteed to only contain `proper' |#|
186 % characters that are either followed by another |#| or a digit, you
187 % can let the normal interpretation of a macro parameter for
188 % \cmd{\def} kick in and use this as
189 % \begin{macrocode}
190 \begin{qstest}{# as macro parameter}{\Expect, #}
191 \toks0{\def\xxx#1{}}
192 \Expect\expandafter{\the\toks0}{\def\xxx#1{}}
193 \end{qstest}
194 % \end{macrocode}
195 % In this manner, |#1| is interpreted (and sanitized) as a macro
196 % parameter on both sides, and consequently no doubling of |#|
197 % occurs.
198 %
199 % Before the comparison is done, both arguments are sanitized,
200 % converted into printing characters with standardized catcodes
201 % throughout\footnote{Spaces get catcode~10, all other characters
202 % catcode~12.}. A word of warning: both sanitization as well as
203 % using \cmd{\meaning} still depend on catcode settings, since
204 % single-letter control sequences (made from a catcode 11 letter)
205 % are followed by a space, and other single-character control
206 % sequences are not. For that reason, a standalone test file for
207 % \LaTeX\ class or package files will usually need to declare
208 % \begin{macrocode}
209 \makeatletter
210 % \end{macrocode}
211 % in order to make `|@|' a letter, like it usually is in such
212 % files.
213 %
214 % All of the of the following expectations would turn out correct:
215 % \begin{macrocode}
216 \begin{qstest}{Some LaTeX definitions}{\Expect}
217 \Expect*{\meaning\@gobble}{\long macro:#1->}
218 \Expect*{\the\maxdimen}{16383.99998pt}
219 \end{qstest}
220 % \end{macrocode}
221 % Note that there is no way to convert the contents of a box into a
222 % printable rendition, so with regard to boxes, you will be mostly
223 % reduced to check that dimensions of a box meet expectations.
224 %
225 % \subsection{Expecting \texttt{ifthen} conditions}
226 % \DescribeMacro{\ExpectIfThen}
227 % This is used for evaluating a condition as provided by the
228 % |ifthen| package. See its docs for the kind of condition that is
229 % possible there. You just specify one argument: the condition that
230 % you expect to be true. Here is an example:
231 % \begin{macrocode}
232 \RequirePackage{ifthen}
233 \begin{qstest}{\ExpectIfThen}{\ExpectIfThen}
234 \ExpectIfThen{\lengthtest{\maxdimen=16383.99998pt}\AND
235 \maxdimen>1000000000}
236 \end{qstest}
237 % \end{macrocode}
238 %
239 % \subsection{Dimension ranges}
240 %
241 % \DescribeMacro{\InRange} Sometimes we want to check whether some
242 % dimension is not exactly like some value, but rather in some range.
243 % We do this by specifying as the second argument to \cmd{\Expect} an
244 % artificial macro with two arguments specifying the range in
245 % question. This will make \cmd{\Expect} succeed if its first
246 % argument is in the range specified by the two arguments to
247 % \cmd{\InRange}.
248 %
249 % The range is specified as two \TeX\ dimens. If you use a dimen
250 % register and you want to have a possible error message display the
251 % value instead of the dimen register, you can do so by using the |*|
252 % modifier before \cmd{\InRange} (which will cause the value to be
253 % expanded before printing and comparing) and put \cmd{\the} before
254 % the dimen register since such register are not expandible by
255 % themselves.
256 %
257 % Here are some examples:
258 % \begin{macrocode}
259 \begin{qstest}{\InRange success}{\InRange}
260 \dimen@=10pt
261 \Expect*{\the\dimen@}\InRange{5pt}{15pt}
262 \Expect*{\the\dimen@}\InRange{10pt}{15pt}
263 \Expect*{\the\dimen@}\InRange{5pt}{10pt}
264 \end{qstest}
265 \begin{qstest}{\InRange failure}{\InRange, fails}
266 \dimen@=10pt \dimen@ii=9.99998pt
267 \Expect*{\the\dimen@}\InRange{5pt}{\dimen@ii}
268 \dimen@ii=10.00002pt
269 \Expect*{\the\dimen@}*\InRange{\the\dimen@ii}{15pt}
270 \end{qstest}
271 % \end{macrocode}
272 % \DescribeMacro{\NearTo} This requires e\TeX's arithmetic and will
273 % not be available for versions built without e\TeX\ support. The
274 % macro is used in lieu of an expected value and is similar to
275 % \cmd{InRange} in that it is a pseudovalue to be used for the second
276 % argument of \cmd{\Expect}. It makes \cmd{\Expect} succeed if its
277 % own mandatory argument is close to the first argument from
278 % \cmd{\Expect}, where closeness is defined as being within |0.05pt|.
279 % This size can be varied by specifying a different one as optional
280 % argument to \cmd{\NearTo}. Here is a test:
281 % \begin{macrocode}
282 %<*etex>
283 \begin{qstest}{\NearTo success}{\NearTo}
284 \dimen@=10pt
285 \Expect*{\the\dimen@}\NearTo{10.05pt}
286 \Expect*{\the\dimen@}\NearTo{9.95pt}
287 \Expect*{\the\dimen@}\NearTo[2pt]{12pt}
288 \Expect*{\the\dimen@}\NearTo[0.1pt]{9.9pt}
289 \end{qstest}
290 \begin{qstest}{\NearTo failure}{\NearTo, fails}
291 \dimen@=10pt
292 \Expect*{\the\dimen@}\NearTo{10.05002pt}
293 \Expect*{\the\dimen@}\NearTo[1pt]{11.00001pt}
294 \end{qstest}
295 %</etex>
296 % \end{macrocode}
297 %
298 % \subsection{Saved results}
299 %
300 % The purpose of saved results is to be able to check that the value
301 % has remained the same over passes. Results are given a unique label
302 % name and are written to an auxiliary file where they can be read in
303 % for the sake of comparison. One can use the normal |aux| file for
304 % this purpose, but it might be preferable to use a separate dedicated
305 % file. That way it is possible to input a versioned \emph{copy} of
306 % this file and have a fixed point of reference rather than the last
307 % run.
308 %
309 % While the |aux| file is read in automatically at the beginning of
310 % the document, this does not happen with explicitly named files. You
311 % have to read them in yourself, preferably using
312 % \begin{quote}
313 % |\InputIfFileExists|\marg{filename}|{}{}|
314 % \end{quote}
315 % so that no error is thrown when the file does not yet exist.
316 %
317 % \DescribeMacro{\SaveValueFile} This gets one argument specifying
318 % which file name to use for saving results. If this is specified, a
319 % special file is opened. If \cmd{\SaveValueFile} is not called, the
320 % standard |aux| file is used instead, but then you can only save
321 % values after |\begin||{document}|. |\jobname.qsout| seems like a
322 % useful file name to use here (the extension |out| is already in
323 % use by PDF\TeX).
324 % \begin{macrocode}
325 \begin{qstest}{\SavedValue}{\SavedValue}
326 \SaveValueFile{\jobname.qsout}
327 % \end{macrocode}
328 % If this were a real test instead of just documentation, we probably
329 % would have written something like
330 % \begin{quote}
331 % |\InputIfFileExists{\jobname.qsin}{}{}|
332 % \end{quote}
333 % first in order to read in values from a previous run. The given
334 % file would have been a copy of a previous |qsout| file, possibly
335 % checked into version control in order to make sure behavior is
336 % consistent across runs. If it is an error to not have such a file
337 % (once you have established appropriate testing), you can just write
338 % \begin{quote}
339 % |\input{\jobname.qsin}|
340 % \end{quote}
341 % instead, of course.
342 %
343 % \DescribeMacro{\CloseValueFile} This macro takes no argument and
344 % will close a value save file if one is open (using this has no
345 % effect if no file has been opened and values are saved on the |aux|
346 % file instead). We'll demonstrate use of it later. It is probably
347 % only necessary for testing |qstest| itself (namely, when you read in
348 % saved values in the same run), or when you do the
349 % processing/comparison with a previous version by executing commands
350 % via \TeX's |\write18| mechanism.
351 %
352 % \DescribeMacro{\SaveValue} This gets the label name as first
353 % argument. If you are using the non-e\TeX-version, the label name
354 % gets sanitized using \cmd{\string} and so can't deal with
355 % non-character material except at its immediate beginning. The
356 % e\TeX-version has no such constraint.
357 %
358 % The second argument is the same kind of argument as \cmd{\Expect}
359 % expects, namely something suitable for a token register assignment
360 % which is passed through \cmd{\def} if not preceded by |*|, and by
361 % \cmd{\edef} if preceded by |*|. The value is written out to the
362 % save file where it can be read in afterwards.
363 %
364 % Let us save a few values under different names now:
365 % \begin{macrocode}
366 \SaveValue{\InternalSetValue}*{\meaning\InternalSetValue}
367 \SaveValue{\IncludeTests}*{\meaning\IncludeTests}
368 \SaveValue{whatever}*{3.1415}
369 \SaveValue{\maxdimen}*{\the\maxdimen}
370 % \end{macrocode}
371 % \DescribeMacro{\InternalSetValue} A call to this macro is placed
372 % into the save file for each call of \cmd{\SaveValue}. The details
373 % are not really relevant: in case you run into problems while
374 % inputting the save file, it might be nice to know.
375 %
376 % \DescribeMacro{\SavedValue} This is used for retrieving a saved
377 % value. When used as the second argument to \cmd{\Expect}, it will
378 % default to the value of the first argument to \cmd{\Expect} unless
379 % it has been read in from a save file. This behavior is intended for
380 % making it easy to add tests and saved values and not get errors at
381 % first, until actually values from a previous test become available.
382 %
383 % Consequently, the following tests will all turn out true before we
384 % read in a file, simply because all the saved values are not yet
385 % defined and default to the expectations:
386 % \begin{macrocode}
387 \Expect{Whatever}\SavedValue{\InternalSetValue}
388 \Expect[\IncludeTests]{Whatever else}\SavedValue{\IncludeTests}
389 \Expect[whatever]{2.71828}\SavedValue{whatever}
390 \Expect[undefined]{1.618034}\SavedValue{undefined}
391 % \end{macrocode}
392 % After closing and rereading the file, we'll need to be more careful
393 % with our expectations, but the last line still works since there
394 % still is no saved value for ``undefined''.
395 % \begin{macrocode}
396 \CloseValueFile
397 \input{\jobname.qsout}
398 \Expect*{\meaning\InternalSetValue}\SavedValue{\InternalSetValue}
399 \Expect[\IncludeTests]*{\meaning\IncludeTests}%
400 \SavedValue{\IncludeTests}
401 \Expect[whatever]{3.1415}\SavedValue{whatever}
402 \Expect[undefined]{1.618034}\SavedValue{undefined}
403 \end{qstest}
404 % \end{macrocode}
405 % Ok, and now lets take the previous tests which succeeded again and
406 % let them fail now that the variables are defined:
407 % \begin{macrocode}
408 \begin{qstest}{\SavedValue failure}{\SavedValue,fails}
409 \Expect{Whatever}\SavedValue{\InternalSetValue}
410 \Expect[\IncludeTests]{Whatever else}\SavedValue{\IncludeTests}
411 \Expect{2.71828}\SavedValue{whatever}
412 \end{qstest}
413 % \end{macrocode}
414 %
415 %
416 % \subsection{Checking for call sequences}
417 % \DescribeEnv{ExpectCallSequence} The environment
418 % |ExpectCallSequence| tells the test system that macros are going to
419 % be called in a certain order and with particular types of arguments.
420 %
421 % It gets as an argument the expected call sequence. The call
422 % sequence contains entries that look like a macro definition:
423 % starting with the macro name followed with a macro argument list and
424 % a brace-enclosed substitution text that gets executed in place of
425 % the macro. The argument list given to this macro substitution will
426 % get as its first argument a macro with the original definition of
427 % the control sequence, so you can get at the original arguments for
428 % this particular macro call starting with |#2|. As a consequence, if
429 % you specify no arguments at all and an empty replacement text for
430 % the substitution, the original macro gets executed with the original
431 % arguments.
432 %
433 % \DescribeMacro{\CalledName} If you want to get back from the control
434 % sequence with the original meaning in |#1| to the original macro
435 % name, you can use \cmd{\CalledName} on it. This will expand to the
436 % original control sequence \emph{name}, all in printable characters
437 % fit for output or typesetting in a typewriter font (or use in
438 % \cmd{\csname}), but without leading backslash character. You can
439 % get to the control sequence itself by using
440 % \begin{quote}
441 % |\csname \CalledName#1\endcsname|
442 % \end{quote}
443 % and to a printable version including backslash by using
444 % \begin{quote}
445 % |\expandafter \string \csname \CalledName#1\endcsname|
446 % \end{quote}
447 %
448 % Going into more detail, a substitution function is basically defined
449 % using
450 % \begin{quote}
451 % |\protected| |\long| |\def|
452 % \end{quote}
453 % so it will not usually get expanded except when hit with
454 % \cmd{\expandafter} or actually being executed. Note that you can't
455 % use this on stuff that has to work at expansion time. This really
456 % works mainly with macros that would also be suitable candidates for
457 % \cmd{\DeclareRobustCommand}.
458 %
459 % It is also a bad idea to trace a conditional in this manner: while
460 % the substitution could be made to work when being executed, it will
461 % appear like an ordinary macro when being skipped, disturbing the
462 % conditional nesting.
463 %
464 % Only macros occuring somewhere in the call sequence will get
465 % tracked, other macros are not affected. The environment can
466 % actually get nested, in which case the outer sequences will get
467 % tracked independently from the inner sequence.
468 %
469 % This makes it possible to use |ExpectCallSequence| in order to
470 % spoof, for example, both input consuming and output producing macros
471 % without knowing the exact relationship of both.
472 %
473 % Apart from specifying macro calls, the call sequence specification
474 % can contain special characters that also carry meaning:
475 % \begin{description}
476 % \item[\texttt{\string`}] If this is set in the call sequence, it
477 % places the initial parsing state here. This will make it an error
478 % if non-matching entries occur at the start of the sequence, which
479 % otherwise is effectively enclosed with
480 % \begin{quote}
481 % |.{}*(|\meta{sequence}|).{}*|
482 % \end{quote}
483 % meaning that nonmatching entries before the first and after the
484 % last matching item of the sequence are ignored by default (this
485 % makes it closer to normal regexp matchers). Since the matching
486 % will then start at |`|, you can put macros before that position
487 % that you want to be flagged if they occur in the sequence, even
488 % when they are mentioned nowhere else (macros which would be an
489 % error if actually called). Also available as the more customary
490 % |^| character, but that tends to behave worse in \LaTeX-aware
491 % editors.
492 % \item[\texttt{\string'}] This indicates the last call sequence
493 % element to be matched. If any traced macros appear after this
494 % point, an error will get generated. Any immediately following
495 % call sequence entries will not get reached.
496 % \item[|.|] A single dot indicates a wildcard: any of the tracked
497 % control sequences might occur here. You still have to follow this
498 % with macro arguments and a braced replacement text. Wildcards are
499 % considered as a fallback when nothing else matches.
500 % \item[|(|\dots|)|] Parens may be used for grouping alternatives
501 % and\slash or combining items for the sake of repeating
502 % specifications, of which there are three:
503 % \item[|?|] If a question mark follows either a macro call, wildcard
504 % call, parenthesized group, or call sequence end, the item before
505 % it is optional.
506 % \item[|+|] A plus sign following an item means that this item may be
507 % repeated one or more times.
508 % \item[|*|] An asterisk following an item means that this item may be
509 % repeated zero or more times.
510 % \item[\texttt{\string|}] A vertical bar separates alternatives.
511 % Alternatives extend as far as possible, to the next bar, to an
512 % enclosing paren group, or to the start and\slash or end of the
513 % whole call sequence specification if nothing else intervenes.
514 % \end{description}
515 % Note that opposed to traditional regexp evaluation, no backtracking
516 % is employed: at each point in the call sequence, the next match is
517 % immediately chosen and a choice can (for obvious reasons) not be
518 % reverted. It is the task of the user to specify a call sequence in
519 % a sufficiently non-ambiguous manner that will make the call sequence
520 % tracing not pick dead ends.
521 % \begin{macrocode}
522 \begin{qstest}{ExpectCallSequence}{ExpectCallSequence}
523 \def\e{e} \def\f{f}
524 \def\g{g} \def\h{h}
525 \begin{ExpectCallSequence}{`\e#1{%
526 \Expect\expandafter{\csname\CalledName#1\endcsname}{\e }%
527 \Expect*{\meaning#1}{macro:->e}}+\f#1{}'}
528 \e \e \e \e \f
529 \end{ExpectCallSequence}
530 \end{qstest}
531 % \end{macrocode}
532 %
533 % \subsection{Ending a standalone test file}
534 % One finishes a standalone test file by calling the \LaTeX\ control
535 % sequence \cmd{\quit}. This stops processing even when we did not
536 % actually get into a document. We don't actually do this here since
537 % there will be further tests in the full documentation file.
538 % However, we will now close the log file we opened for this demonstration.
539 % \begin{macrocode}
540 \LogClose{lgout}
541 %</test>
542 % \end{macrocode}
543 % \IfFileExists{qstest-qs.lgout}{%
544 % And now we will show the resulting standalone log file:
545 % \IndexInput{qstest-qs.lgout}}{%
546 % \GenericError{(\jobname) }%
547 % {`qstest-qs.lgout' is missing}
548 % {Please run `qstest-qs.tex' (unpacked by `qstest.ins') through LaTeX first.}
549 % {Documentation will be incomplete otherwise.}}
550 %
551 % We can now stop skipping if we are compiling the |dtx| file
552 % standalone.
553 % \begin{macrocode}
554 %<*dtx>
555 \fi
556 %</dtx>
557 % \end{macrocode}
558 % \StopEventually{}
559 % \section{The driver file}
560 % \begin{macrocode}
561 %<*driver>
562 \documentclass{ltxdoc}
563 \usepackage{qstest}
564 \usepackage{hyperref}
565 \OnlyDescription
566 %<driver> \AlsoImplementation
567 \begin{document}
568 \GetFileInfo{qstest.sty}
569 \date{\filedate}
570 \title{\texttt{\filename}\\\fileinfo\\version \fileversion}
571 \author{David Kastrup\thanks{\href{mailto:[email protected]}
572 {[email protected]}, \href{http://quinscape.de}{QuinScape
573 GmbH}}}
574 \maketitle
575 \DocInput{qstest.dtx}
576 \end{document}
577 %</driver>
578 % \end{macrocode}
579 % \hypertarget{installer}{%
580 % \section{The installer file}
581 % }
582 % If you did not get an installer file with the package, you can
583 % recreate it by running
584 % \begin{quote}
585 % |tex docstrip|
586 % \end{quote}
587 % and specifying |dtx| as input extension, |ins| as output extension,
588 % |installer| as option list and |qstest| as input file name.
589 %
590 % Installations with a non-e\TeX-based \LaTeX\ can try to remove the
591 % |etex| option from the style, but it will impact robustness and
592 % performance of the package.
593 %
594 % When called from a Makefile, you want to allow overwriting files,
595 % and you don't want to install into the final target tree. In this
596 % case, call
597 % \begin{quote}
598 % |tex "\let\Make=y \input makematch.ins"|
599 % \end{quote}
600 % \begin{macrocode}
601 %<*installer>
602 \input docstrip
603 \ifx\Make y\askforoverwritefalse\fi
604 \generate{
605 \file{qstest.drv}{\from{qstest.dtx}{driver,test,etex}}
606 \file{qstest-qs.tex}{\from{qstest.dtx}{test,etex}}
607 \file{makematch.drv}{\from{makematch.dtx}{driver,etex}}
608 \file{makematch-qs.tex}{\from{makematch.dtx}{test,etex}}
609 \ifx\Make y\else \usedir{tex/latex/qstest}\fi
610 \file{qstest.sty}{\from{qstest.dtx}{package,etex}}
611 \file{makematch.sty}{\from{makematch.dtx}{package,etex}}}
612 \endbatchfile
613 %</installer>
614 % \end{macrocode}
615 %
616 % \section{The Implementation}
617 % \subsection{Front matter}
618 % Some data and version magic from SVN keyword expansion.
619 % \begin{macrocode}
620 %<*package>
621 \NeedsTeXFormat{LaTeX2e}
622 \def\next$Id: #1.dtx #2 #3-#4-#5 #6${%
623 \ProvidesPackage{#1}[#3/#4/#5 1.#2 QuinScape Unit Test Package]
624 }
625 \next
626 $Id: qstest.dtx 7896 2007-02-21 14:03:26Z dkastrup $
627 \RequirePackage{makematch}
628 \newtoks\qst@tmptoks
629 % \end{macrocode}
630 %
631 % \subsection{Error logging and treatment}
632 % \begin{macro}{\TestErrors}
633 % This defines test patterns that will throw an error when failing.
634 % \begin{macrocode}
635 \newcommand*{\TestErrors}{\MakeMatcher[,]\qst@errorcheck}
636 \TestErrors{*, !fails}
637 \newif\ifqst@error
638 \def\qst@ifqst@error{\qst@errorcheck\qst@options
639 \qst@errortrue\qst@errorfalse\ifqst@error}
640 % \end{macrocode}
641 % \end{macro}
642 % \begin{macro}{\qst@failed}
643 % This is the internal macro we call for every failure. It gets the
644 % test message which is expanded and then sanitized.
645 % \begin{macrocode}
646 \long\def\qst@error#1{%
647 \global\qst@testpassedfalse
648 \global\let\qst@lastfailure\qst@testname
649 \edef\qst@message{Failed: \qst@testname^^J#1}%
650 \@onelevel@sanitize\qst@message
651 \qst@failed}
652 % \end{macrocode}
653 % \end{macro}
654 % \begin{macro}{\ifqst@testpassed}
655 % This is used to flag failures in a test.
656 % \begin{macrocode}
657 \newif\ifqst@testpassed
658 % \end{macrocode}
659 % \end{macro}
660 %
661 % \subsection{Logging}
662 % \label{sec:logging}
663 % \begin{macro}{\LogTests}
664 % This macro receives three arguments. The first is the filename
665 % extension of a log file. The second is a keyword list that
666 % indicates which passed tests are to be logged. The third is a
667 % keyword list indicating which failed tests are to be logged.
668 % \begin{macrocode}
669 \newcommand{\LogTests}[3]{%
670 %<etex> \ifcsname qst:log:#1\endcsname \else
671 %<*!etex>
672 {\expandafter}\expandafter\ifx\csname qst:log:#1\endcsname
673 \@undefined
674 %</!etex>
675 \expandafter\newwrite\csname qst:log:#1\endcsname
676 \qst@gpush\qst@passed{\qst@logentry+{#1}}%
677 \qst@gpush\qst@failed{\qst@logentry-{#1}}%
678 \global\expandafter\let\csname qst:+log:#1\endcsname\qst@matchnever
679 \global\expandafter\let\csname qst:-log:#1\endcsname\qst@matchnever
680 \fi
681 \expandafter\ifx \csname qst:+log:#1\endcsname \qst@matchnever
682 \PackageInfo{qstest}{Logging on: \jobname.#1}%
683 \ifnum\csname qst:log:#1\endcsname>\m@ne
684 \immediate\openout\csname qst:log:#1\endcsname\jobname.#1\relax
685 \fi
686 \fi
687 \MakeMatcher[,]\qst@tmp{#2}%
688 \global\expandafter\let\csname qst:+log:#1\endcsname\qst@tmp
689 \MakeMatcher[,]\qst@tmp{#3}%
690 \global\expandafter\let\csname qst:-log:#1\endcsname\qst@tmp
691 }
692 % \end{macrocode}
693 % \end{macro}
694 % \begin{macro}{\qst@gpush}
695 % \begin{macrocode}
696 %<*etex>
697 \long\def\qst@gpush#1#2{\xdef#1{\unexpanded{#2}%
698 \unexpanded\expandafter{#1}}}
699 %</etex>
700 %<*!etex>
701 \long\def\qst@gpush#1#2{\qst@tmptoks{#2}%
702 \qst@tmptoks\expandafter{\the\expandafter\qst@tmptoks#1}%
703 \xdef#1{\the\qst@tmptoks}}
704 %</!etex>
705 % \end{macrocode}
706 % \end{macro}
707 %
708 % \begin{macro}{\qst@logentry}
709 % \begin{macrocode}
710 \def\qst@logentry#1#2{\qst@maybelog#1{#2}{%
711 \immediate\write\csname qst:log:#2\endcsname{\qst@message}}}
712 % \end{macrocode}
713 % \end{macro}
714 % \begin{macro}{\qst@maybelog}
715 % \begin{macrocode}
716 \def\qst@maybelog#1#2#3{\csname qst:#1log:#2\endcsname\qst@options
717 {#3}{}}
718 % \end{macrocode}
719 % \end{macro}
720 % If the user specifies |log| as the extension, we don't want to
721 % overwrite the log file. Instead we convert this to package warnings
722 % and infos.
723 % \begin{macrocode}
724 \expandafter\let\csname qst:log:log\endcsname\m@ne
725 \global\expandafter\let\csname qst:+log:log\endcsname\qst@matchalways
726 \global\expandafter\let\csname qst:-log:log\endcsname\qst@matchalways
727 \def\qst@passed{\qst@maybelog+{log}%
728 {\PackageInfo{qstest}{\qst@message}}}
729 \def\qst@failed{\ifqst@error
730 \PackageError{qstest}{\qst@message}{}%
731 \else
732 \qst@maybelog-{log}{\PackageWarning{qstest}{\qst@message}}%
733 \fi}
734 % \end{macrocode}
735 % \begin{macro}{\LogClose}
736 % This closes the specified log file again. This is needed if the
737 % log file gets processed during the \TeX\ run, like with verbatim
738 % input or by running a |\write18| process on it. It is possible to
739 % reopen the file later. Specifying |log| will not actually close
740 % the log file, but just stop logging.
741 % \begin{macrocode}
742 \newcommand*\LogClose[1]{%
743 \expandafter\ifx \csname qst:+log:#1\endcsname\qst@matchnever
744 \else
745 \PackageInfo{qstest}{Logging off: \jobname.#1}%
746 \ifnum\csname qst:log:#1\endcsname>\m@ne
747 \immediate\closeout\csname qst:log:#1\endcsname
748 \fi
749 \global\expandafter\let\csname qst:+log:#1\endcsname\qst@matchnever
750 \global\expandafter\let\csname qst:-log:#1\endcsname\qst@matchnever
751 \fi
752 }
753 %</package>
754 %<*test>
755 \IncludeTests{*}
756 \makeatletter
757 \begin{qstest}{\LogClose}{}
758 \begin{ExpectCallSequence}{%
759 `\PackageInfo#1#2#3{\Expect[##1]{#2}{qstest}%
760 \Expect[##2]{#3}{Logging off: \jobname.log}%
761 #1{#2}{#3}}'}
762 \LogClose{log}
763 \end{ExpectCallSequence}
764 \end{qstest}
765 \begin{qstest}{\LogTests}{}
766 \begin{ExpectCallSequence}{%
767 \PackageInfo#1#2#3{\Expect[##1]{#2}{qstest}%
768 \Expect[##2]{#3}{Logging on: \jobname.log}%
769 #1{#2}{#3}}}
770 \LogTests{log}{*}{*}
771 \end{ExpectCallSequence}
772 \end{qstest}
773 %</test>
774 %<*package>
775 % \end{macrocode}
776 % \end{macro}
777 %
778 % \subsection{The test code itself}
779 %
780 % \begin{macro}{\IncludeTests}
781 % This defines the test case patterns to be included. Keyword
782 % specifications and patterns are `sanitized': macros are not
783 % expanded, and everything but spaces is converted to catcode~12
784 % characters. At the start of a pattern or a keyword, spaces get
785 % ignored. Spaces inside of patterns or keywords should work as
786 % expected, however.
787 % \begin{macrocode}
788 \def\IncludeTests{\MakeMatcher[,]\qst@includecheck}
789 \let\qst@includecheck\qst@matchalways
790 % \end{macrocode}
791 % \end{macro}
792 % \begin{environment}{qstest}
793 % This is the environment for defining a test. |#1| is the name of
794 % the test for the log file. The name is sanitized, so control
795 % sequence names can be used verbatim. |#2| is a sequence of
796 % options that may be matched by the patterns from
797 % \cmd{\IncludeTests}. If there is no match the environment is
798 % skipped like a comment environment.
799 % \begin{macrocode}
800 \RequirePackage{verbatim}
801 \newenvironment{qstest}[2]{%
802 % \end{macrocode}
803 % We sanitize test name and options. In case people nest tests, we
804 % don't want to announce an outer test passed when a single inner test
805 % has passed. So we don't set \cmd{\qst@testpassedtrue} globally.
806 % While a mixture of local and global assignments should in general be
807 % avoided as it leads to ``savestack buildup'', this can't actually
808 % happen here since the local assignment is done only once at the
809 % start of a group.
810 % \begin{macrocode}
811 \qst@testpassedtrue
812 %<etex> \edef\qst@testname{\detokenize{#1}}%
813 %<*!etex>
814 \qst@tmptoks{#1}%
815 \edef\qst@testname{\the\qst@tmptoks}%
816 \@onelevel@sanitize\qst@testname
817 %</!etex>
818 \MakeMatchTarget[,]\qst@options{#2}%
819 \let\ifqst@error\qst@ifqst@error
820 \qst@includecheck\qst@options\ignorespaces{%
821 \let\endqstest\endcomment}}%
822 {\ifqst@testpassed
823 \edef\qst@message{Passed: \qst@testname}%
824 \qst@passed
825 \else
826 \ifx\qst@testname\qst@lastfailure
827 \else
828 \edef\qst@message{Failed: \qst@testname}%
829 \qst@failed
830 \fi
831 \fi}
832 % \end{macrocode}
833 % \end{environment}
834 % \begin{macro}{\qst@testname}
835 % Let us set up a default test name in case any tests occur outside
836 % of a |qstest| environment.
837 % \begin{macrocode}
838 \def\qst@testname{unspecified}
839 % \end{macrocode}
840 % \end{macro}
841 %
842 % \begin{macro}{\Expect}
843 % This macro basically receives two brace-delimited
844 % arguments\footnote{Actually, the arguments are collected with a
845 % token register assignment. This gives several options for
846 % specifying them, including giving a token register without
847 % braces around it.} and checks that they are equal after being
848 % passed through \cmd{\def} and sanitized.
849 % If you precede one of those arguments
850 % with |*| it gets passed through through \cmd{\edef} instead of
851 % \cmd{\def}. There may also be additional tokens like
852 % |\expandafter| before the opening brace.
853 % \begin{macrocode}
854 \newcommand\Expect[1][]{%
855 %<etex> \edef\qst@tmpc{\unexpanded{#1}}%
856 %<!etex> \qst@tmptoks{#1}%
857 %<!etex> \edef\qst@tmpc{\the\qst@tmptoks}%
858 \qst@expectarg\qst@defaultvalue\qst@expecttwo}
859 \def\qst@expectarg#1#2{%
860 \@ifstar{\qst@expectargii\edef#1#2}{\qst@expectargii\def#1#2}}
861 \def\qst@expectargii#1#2#3{\long\def\qst@tmp##1{%
862 #1#2####1####2####3####4####5####6####7####8####9{##1}%
863 \@onelevel@sanitize#2#3}%
864 \afterassignment\qst@expectargiii
865 \qst@tmptoks=}
866 \def\qst@expectargiii{\expandafter
867 \qst@tmp\expandafter{\the\qst@tmptoks}}
868 \def\qst@expecttwo{%
869 \ifx\qst@tmpc\@empty
870 \edef\qst@tmpc{\the\qst@tmptoks}%
871 \fi
872 \qst@expectarg\qst@tmpb\qst@expectfinish}
873 \def\qst@expectfinish{%
874 \ifx\qst@defaultvalue\qst@tmpb
875 \else
876 %<!etex> \qst@tmptoks\expandafter{\qst@tmpc}%
877 \qst@error{
878 %<!etex> \string\Expect: \the\qst@tmptoks^^J
879 %<etex> \string\Expect: \unexpanded\expandafter{\qst@tmpc}^^J
880 <\qst@tmpb^^J
881 >\qst@defaultvalue}%
882 \fi}
883 % \end{macrocode}
884 % \end{macro}
885 %
886 % \subsection{Dimension ranges}
887 %
888 % \begin{macro}{\InRange}
889 % This is used as a second argument for \cmd{\Expect}. It will
890 % make \cmd{\Expect} succeed if the first argument of \cmd{\Expect}
891 % happens to lie in the closed range defined by the two arguments of
892 % \cmd{\InRange}.
893 % \begin{macrocode}
894 \def\InRange#1#2{%
895 \ifcase
896 \ifdim\qst@defaultvalue<#1\@ne\fi
897 \ifdim\qst@defaultvalue>#2\@ne\fi
898 \tw@
899 \or
900 \qst@afterfi{{in [#1..#2]}}%
901 \or
902 \qst@afterfi{\expandafter{\qst@defaultvalue}}%
903 \fi}
904 % \end{macrocode}
905 % \begin{macro}{\qst@afterfi}
906 % This is just a helper macro cleaning up a following |\fi|.
907 % \begin{macrocode}
908 \def\qst@afterfi#1#2\fi{\fi#1}
909 % \end{macrocode}
910 % \end{macro}
911 % \end{macro}
912 % \begin{macro}{\NearTo}
913 % This is a pseudovalue like the last: it returns
914 % \cmd{\qst@defaultvalue} if the specified value |#1| is close to
915 % the given default value. There is an optional argument specifying
916 % the closeness which defaults to |0.05pt|. It requires e\TeX\
917 % since the arithmetic can't be done otherwise.
918 % \begin{macrocode}
919 %<*etex>
920 \newcommand*\NearTo[1]{%
921 \ifx[#1\expandafter\qst@nearto\expandafter[%]]
922 \else \qst@afterfi{\qst@nearto[0.05pt]{#1}}%
923 \fi}
924 \def\qst@nearto[#1]#2{%
925 \ifcase
926 \ifdim\qst@defaultvalue>\dimexpr#2+(#1)\relax \@ne\fi
927 \ifdim\qst@defaultvalue<\dimexpr#2-(#1)\relax \@ne\fi
928 \tw@
929 \or
930 \qst@afterfi{{near[#1] to #2}}%
931 \or
932 \qst@afterfi{\expandafter{\qst@defaultvalue}}%
933 \fi}
934 %</etex>
935 % \end{macrocode}
936 % \end{macro}
937 %
938 % \begin{macro}{\ExpectIfThen}
939 % This is used for evaluating a condition as provided by the
940 % |ifthen| package. See its docs for the kind of condition that is
941 % possible there.
942 % \begin{macrocode}
943 \newcommand\ExpectIfThen[1]{%
944 %<!etex> \qst@tmptoks{#1}%
945 \ifthenelse{#1}{}{%
946 \qst@error{
947 %<etex> \string\ExpectIfThen: \unexpanded{#1}%
948 %<!etex> \string\ExpectIfThen: \the\qst@tmptoks
949 }}}
950 % \end{macrocode}
951 % \end{macro}
952 %
953 %
954 % \begin{environment}{ExpectCallSequence}
955 % This tells the test system that macros are going to be called in a
956 % certain order and with particular types of arguments.
957 %
958 % The environment gets as an argument the expected call sequence.
959 % The call sequence contains entries that look like a macro
960 % definition: starting with the macro name followed with an argument
961 % list ended with |{| ^^A}%
962 % following it, followed by substitution code executed in place of
963 % the macro. The argument list actually starts with an implicit
964 % argument of |#1| which contains a macro with the original value of
965 % the control sequence, so the explicitly specified argument list
966 % starts with the argument called~|#2|.
967 %
968 % The substitution function is basically defined using
969 % \begin{quote}
970 % |\protected| |\long| |\def|
971 % \end{quote}
972 % so it will not usually get expanded except when hit with
973 % \cmd{\expandafter} or actually being executed. Note that you
974 % can't use this on stuff that has to work at expansion time. This
975 % really works mainly with macros that would also be suitable
976 % candidates for \cmd{\DeclareRobustCommand}.
977 %
978 % It is also a bad idea to trace a conditional in this manner: while
979 % the substitution should actually work when being executed, it will
980 % appear like an ordinary macro when being skipped, disturbing the
981 % conditional nesting.
982 % \begin{macro}{\qst@advance}
983 % We maintain a lot of counters and often need them expanded.
984 % Instead of allocating counter registers for them, we keep some of
985 % them in macros. Advancing such a macro is done using
986 % \cmd{\qst@advance}. Since we may do this in the middle of call
987 % tracing, we allocate our own temporary counter in the non-e\TeX\
988 % case.
989 % \begin{macrocode}
990 %<etex> \def\qst@advance#1{\edef#1{\number\numexpr(#1)+1}}
991 %<*!etex>
992 \newcount\qst@tmpcnt
993 \def\qst@advance#1{%
994 \qst@tmpcnt#1%
995 \advance\qst@tmpcnt\@ne
996 \edef#1{\number\qst@tmpcnt}}
997 %</!etex>
998 % \end{macrocode}
999 % \end{macro}
1000 %
1001 % \subsection{The regexp state machine}
1002 % The whole idea of call sequence checking is to match the calls
1003 % happening throughout controlled macros to a sort of attributed
1004 % regular expression. To facilitate that, we replace the macros by
1005 % some fixed code exercising a state machine. For each state of the
1006 % state machine, we define a state macro (taking one argument) that
1007 % contains tokens to be matched followed by a corresponding action
1008 % sequence in braces. The argument that this state macro takes is the
1009 % control sequence in question itself: by using |#1| as the matching
1010 % token, one can ensure a match at some place. This is used for
1011 % implementing wildcards.
1012 %
1013 % An action sequence may be of three kinds:
1014 % \begin{description}
1015 % \item[explicit match] this matches a given token explicitly and
1016 % causes the state to change to a defined new state, and causes an
1017 % action to be called that has been user specified for this state transition.
1018 % \item[wildcard match] instead of immediately making a state transition,
1019 % the transition is remembered in case there is not explicit match:
1020 % explicit matches have priority.
1021 % \item[empty transition] this inserts the transitions of a different
1022 % state recursively into the matching process. Every state inserted
1023 % in this manner is recorded so as to not insert it again. This is
1024 % not associated with a transition.
1025 % \end{description}
1026 %
1027 % \begin{macro}{\qst@csmaketransition}
1028 % This will perform an actual transition when called as an action
1029 % code. It receives in |#1| the state to move to, in |#2| the
1030 % transition number to use for the replacement code, in |#3| the
1031 % code sequence to be replaced. Everything until the terminating
1032 % |.| of the expanded transition table can be thrown away.
1033 % \begin{macrocode}
1034 \long\def\qst@csmaketransition#1#2#3#4.{%
1035 \qst@cssetstate{#1}%
1036 \expandafter
1037 \endgroup
1038 \csname qst@cstrans:#2\expandafter\endcsname
1039 \csname qst@cssaved\romannumeral\qst@csscope>\string#3\endcsname}
1040 % \end{macrocode}
1041 % \end{macro}
1042 % \begin{macro}{\CalledName}
1043 % This is used for getting back the original name from the saved
1044 % sequence name as text.
1045 % \begin{macrocode}
1046 \def\CalledName#1{\expandafter\expandafter\expandafter\@gobble
1047 \expandafter\strip@prefix\string#1}
1048 % \end{macrocode}
1049 % \end{macro}
1050 %
1051 % \begin{macro}{\qst@csstate}
1052 % \begin{macrocode}
1053 \def\qst@csstate{\csname qst@csstate\romannumeral
1054 \qst@csscope\endcsname}
1055 % \end{macrocode}
1056 % \end{macro}
1057 % \begin{macro}{qst@cssetstate}
1058 % \begin{macrocode}
1059 \def\qst@cssetstate#1{%
1060 \expandafter\expandafter\expandafter\xdef\qst@csstate{#1}}
1061 % \end{macrocode}
1062 % \end{macro}
1063 %
1064 % \begin{macro}{\qst@csmakewildcard}
1065 % This matches a wildcard. Since those are considered last, it just
1066 % redefines \cmd{\qst@csnomatch} to a different default behavior when
1067 % nothing matched explicitly. It also removes the replicated
1068 % control sequence name in |#3| and restarts the matching process.
1069 % Wildcards don't match the end of a match.
1070 % \begin{macrocode}
1071 \long\def\qst@csmakewildcard#1#2#3{\ifx#3\endExpectCallSequence
1072 \else
1073 \def\qst@csnomatch{\qst@csmaketransition{#1}{#2}}%
1074 \fi
1075 \qst@tmp}
1076 % \end{macrocode}
1077 % \end{macro}
1078 % \begin{macro}{\qst@cscheckempty}
1079 % This first checks whether the current state has already been
1080 % considered (entering it into \cmd{\qst@lockout} if it has not),
1081 % then expands its table here and resumes the search.
1082 % \begin{macrocode}
1083 \long\def\qst@cscheckempty#1#2{%
1084 \ifcase\qst@cslockout{#1}\z@
1085 \expandafter\def\expandafter\qst@cslockout
1086 \expandafter##\expandafter1\expandafter{%
1087 \qst@cslockout{##1}\ifnum##1=#1\@ne\fi}%
1088 \expandafter\expandafter\expandafter\qst@tmp
1089 \csname qst@csstate:#1\expandafter\endcsname\expandafter#2%
1090 \or \expandafter\qst@tmp
1091 \fi}
1092 % \end{macrocode}
1093 % \end{macro}
1094 % \begin{macro}{\qst@csnext}
1095 % This does the work of finding a transition from the current state
1096 % given a specified lookahead token. It does this via defining
1097 % \cmd{\qst@tmp} to a macro picking out the given token from the
1098 % following string, taking the corresponding sequence to be called
1099 % for it and calling it with the token as an argument.
1100 %
1101 % The lockout sequence in \cmd{\qst@cslockout} is preloaded with one
1102 % comparison locking out the current state.
1103 % \begin{macrocode}
1104 \long\def\qst@csnext#1#2{%
1105 \begingroup
1106 \edef\qst@csscope{#1}%
1107 \let\qst@csnomatch=\qst@csunexpected
1108 \def\qst@cslockout##1{\ifnum\qst@csstate=##1\@ne\fi}%
1109 \long\def\qst@tmp##1#2##2{##2#2}%
1110 \expandafter\expandafter\expandafter\qst@tmp
1111 \csname qst@csstate:\qst@csstate\endcsname#2%
1112 #2{\qst@csnomatch}.}
1113 %<*!etex>
1114 \let\qst@csnextii\qst@csnext
1115 \def\qst@csnext{\ifx\protect\@typeset@protect
1116 \expandafter\qst@csnextii
1117 \else \expandafter \@firstoftwo \expandafter \protect
1118 \fi}
1119 %</!etex>
1120 % \end{macrocode}
1121 % \end{macro}
1122 %
1123 % \begin{macro}{\qst@csunexpected}
1124 % This is the default if we have had no match:
1125 % \begin{macrocode}
1126 \long\def\qst@csunexpected#1#2.{%
1127 \qst@error{
1128 ExpectCallSequence: \string#1}%
1129 \expandafter\expandafter\expandafter
1130 \endgroup
1131 \qst@cssavedcs#1%
1132 }
1133 \long\def\qst@cssavedcs#1{%
1134 \csname qst@cssaved\romannumeral\qst@csscope>\string#1\endcsname}
1135 % \end{macrocode}
1136 % \end{macro}
1137 % \begin{macro}{\qst@csaddstate}
1138 % This does the actual work of adding something to the state table.
1139 % Uses \cmd{\def}.
1140 % \begin{macrocode}
1141 \long\def\qst@csaddstate#1#2{%
1142 %<etex> \ifcsname qst@csstate:#1\endcsname \else
1143 %<!etex> \expandafter\ifx\csname qst@csstate:#1\endcsname\relax
1144 \expandafter\let\csname qst@csstate:#1\endcsname \@gobble
1145 \fi
1146 \long\expandafter
1147 \def\csname qst@csstate:#1\expandafter\endcsname
1148 \expandafter##\expandafter1\expandafter{\romannumeral
1149 \expandafter\expandafter\expandafter\z@
1150 \csname qst@csstate:#1\endcsname{##1}#2}}
1151 % \end{macrocode}
1152 % \end{macro}
1153 % \begin{macro}{\qst@csaddempty}
1154 % \begin{macrocode}
1155 \def\qst@csaddempty#1#2{%
1156 \expandafter\qst@csaddstate\expandafter{\number#1\expandafter}%
1157 \expandafter{\expandafter##\expandafter1\expandafter{\expandafter
1158 \qst@cscheckempty\expandafter{\number#2}}}}
1159 % \end{macrocode}
1160 % \end{macro}
1161 % \begin{macro}{\qst@csallocstate}
1162 % \begin{macro}{\qst@csalloctrans}
1163 % Those maintain the currently available next state, and the
1164 % currently available next transition.
1165 % \begin{macrocode}
1166 \def\qst@csallocstate{0}
1167 \def\qst@csalloctrans{0}
1168 % \end{macrocode}
1169 % \end{macro}
1170 % \end{macro}
1171 % \begin{macro}{\qst@csscope}
1172 % When we are nesting |ExpectCallSequence| environments,
1173 % this keeps track of the scope we are in.
1174 % \begin{macrocode}
1175 \def\qst@csscope{0}
1176 % \end{macrocode}
1177 % \end{macro}
1178 % \begin{macrocode}
1179 \newenvironment{ExpectCallSequence}[1]
1180 {%
1181 \qst@advance\qst@csscope
1182 \qst@cssetstate{\qst@csallocstate}%
1183 \let\qst@csgroupstate\qst@csallocstate
1184 \qst@advance\qst@csgroupstate
1185 \qst@advance\qst@csgroupstate
1186 \let\qst@csstack\@empty
1187 \qst@csparse.{}*(#1){...}%
1188 }{%
1189 \def\qst@cssavedcs{\@gobble}%
1190 \expandafter\qst@csnext\expandafter\qst@csscope
1191 \csname end {ExpectCallSequence}\endcsname}
1192 % \end{macrocode}
1193 % \end{environment}
1194 % \begin{macro}{\qst@csparse}
1195 % This is doing the basic parsing. We are having some problems
1196 % stopping non-e\TeX\ from hitting on the string space. This
1197 % approach will not work with implicit characters like
1198 % \cmd{\bgroup}, but then there are not too many of those around,
1199 % and so the impact on string space should be tolerable.
1200 % \begin{macrocode}
1201 \long\def\qst@csparse#1{%
1202 %<etex> \ifcsname qst@csparse:\string#1\endcsname
1203 %<*!etex>
1204 \ifcase
1205 \ifcat\relax\noexpand#1%
1206 \else
1207 \expandafter \ifx \csname qst@csparse:\string#1\endcsname \relax
1208 \else @ne \fi
1209 \fi \m@ne
1210 \or
1211 %</!etex>
1212 \csname qst@csparse:\string#1\expandafter\expandafter\expandafter
1213 \endcsname
1214 \expandafter\@gobble
1215 \else
1216 \expandafter\qst@csparsedefault
1217 \fi{#1}}
1218 % \end{macrocode}
1219 % \end{macro}
1220 % \begin{macro}{\qst@csparse:...}
1221 % This is what we do at the end of the patterns: we just jump to
1222 % state~0. At state~0 we add a wildcard restoring any remaining
1223 % macro redirection when it occurs, and let the end of the call
1224 % sequence be allowed there to move to state~1. Oh, and we actually
1225 % call the macro then.
1226 % \begin{macrocode}
1227 \expandafter\def\csname qst@cstrans:0\endcsname
1228 #1{\expandafter\let\csname\CalledName#1\endcsname= #1%
1229 \let#1=\@undefined
1230 \csname\CalledName#1\endcsname}
1231 \qst@csaddstate0{#1{\qst@csmakewildcard00}}
1232 \qst@csaddempty{0}{1}
1233 \expandafter\qst@csaddstate\expandafter1\expandafter{%
1234 \csname end {ExpectCallSequence}\endcsname{\qst@csmaketransition21}}
1235 \expandafter\let\csname qst@cstrans:1\endcsname\@gobble
1236
1237 \def\qst@csalloctrans{2}
1238 \def\qst@csallocstate{3}
1239
1240 \expandafter\let\csname end {ExpectCallSequence}\endcsname
1241 \endExpectCallSequence
1242
1243 \expandafter\def\csname qst@csparse:...\endcsname{%
1244 \ifx\qst@csstack\@empty
1245 \else
1246 \PackageError{qstest}{Unmatched `(' in call sequence %)
1247 specification}{You need to fix this}%
1248 \loop
1249 \qst@csstack
1250 \ifx\qst@csstack\@empty
1251 \else
1252 \repeat
1253 \fi
1254 \qst@csaddempty{\qst@csallocstate}{0}%
1255 \qst@advance\qst@csallocstate
1256 \ignorespaces}
1257 % \end{macrocode}
1258 % \end{macro}
1259 % \begin{macro}{\qst@csparsedefault}
1260 % Ok, here is the default action. We resolve any pending state to
1261 % the next available state and set \cmd{\qst@cslaststate} accordingly.
1262 % Then we add a pending transition from the last state to the next
1263 % state. The saved definition is not overwritten if the macro
1264 % itself already has the proper setting. The purpose of that is to
1265 % be able to preserve undefined macros.
1266 % \begin{macrocode}
1267 \long\def\qst@csparsedefault#1{%
1268 %<*etex>
1269 \ifcsname qst@cssaved\romannumeral\qst@csscope>\string#1\endcsname
1270 \else \protected
1271 %</etex>
1272 %<*!etex>
1273 {\expandafter}%
1274 \expandafter\ifx\csname qst@cssaved\romannumeral\qst@csscope>%
1275 \string#1\endcsname \@undefined
1276 %</!etex>
1277 \edef\qst@tmp{\noexpand\qst@csnext \qst@csscope \noexpand#1}%
1278 \ifx#1\qst@tmp
1279 \else
1280 \expandafter\let
1281 \csname qst@cssaved\romannumeral\qst@csscope>\string#1\endcsname
1282 = #1%
1283 \let#1\qst@tmp
1284 \fi
1285 \fi
1286 \qst@csparsetransition{#1}\qst@csmaketransition}
1287 % \end{macrocode}
1288 % \end{macro}
1289 % \begin{macro}{\qst@csparsetransition}
1290 % Ok, here we read in the code for an actual transition. This will
1291 % create a new definition using \cmd{\def}.
1292 % \begin{macrocode}
1293 \long\def\qst@csparsetransition#1#2{%
1294 \let\qst@cslaststate\qst@csallocstate
1295 \qst@advance\qst@csallocstate
1296 \long\edef\qst@tmp##1##2{%
1297 \noexpand\qst@csaddstate{\qst@cslaststate}{%
1298 ##1{%
1299 ##2{\qst@csallocstate}%
1300 {\qst@csalloctrans}}}}%
1301 \qst@tmp{#1}{#2}%
1302 \expandafter\qst@advance\expandafter\qst@csalloctrans
1303 \expandafter\afterassignment\expandafter\qst@csparse
1304 \expandafter\long\expandafter\def
1305 \csname qst@cstrans:\qst@csalloctrans\endcsname}
1306 % \end{macrocode}
1307 % \end{macro}
1308 % \begin{macro}{\qst@csparse:.}
1309 % \begin{macrocode}
1310 \expandafter\def\csname qst@csparse:.\endcsname{%
1311 \qst@csparsetransition{##1}\qst@csmakewildcard}
1312 % \end{macrocode}
1313 % \end{macro}
1314 % \begin{macro}{\qst@csparse:?}
1315 % This turns the last element into an optional element.
1316 % \begin{macrocode}
1317 \expandafter\def\csname qst@csparse:?\endcsname{%
1318 \qst@csensurelaststate?%
1319 \qst@csaddempty\qst@cslaststate\qst@csallocstate
1320 \let\qst@cslaststate\@undefined
1321 \qst@csparse}
1322 % \end{macrocode}
1323 % \end{macro}
1324 % \begin{macro}{\qst@csensurelaststate}
1325 % This checks that we have a valid last state to hook onto. There
1326 % is no really useful error recovery if we haven't.
1327 % \begin{macrocode}
1328 \def\qst@csensurelaststate#1{\ifx\qst@cslaststate\@undefined
1329 \PackageError{qstest}{Unexpected `#1' in call sequence}{%
1330 Expect chaos to ensue}%
1331 \def\qst@cslaststate{0}%
1332 \fi}
1333 % \end{macrocode}
1334 % \end{macro}
1335 % \begin{macro}{\qst@csparse:*}
1336 % This would need to make the pending state identical with the
1337 % previous state while leaving all of it pending. But we can't
1338 % retroactively make previous states pending again, so we instead
1339 % make do with adding an empty transition from the previous state to
1340 % the next pending one.
1341 % \begin{macrocode}
1342 \expandafter\def\csname qst@csparse:*\endcsname{%
1343 \qst@csensurelaststate*%
1344 \qst@csaddempty\qst@csallocstate\qst@cslaststate
1345 \qst@advance\qst@csallocstate
1346 \qst@csaddempty\qst@cslaststate\qst@csallocstate
1347 \let\qst@cslaststate\@undefined
1348 \qst@csparse}
1349 % \end{macrocode}
1350 % \end{macro}
1351 % \begin{macro}{\qst@csparse:+}
1352 % This is somewhat similar. Note that we have to add an empty
1353 % transition at the end (like with |*| previously) to make sure that
1354 % something like |\a{}+\b{}+| does not match |\a\b\a|.
1355 % \begin{macrocode}
1356 \expandafter\def\csname qst@csparse:+\endcsname{%
1357 \qst@csensurelaststate+%
1358 \qst@csaddempty\qst@csallocstate\qst@cslaststate
1359 \let\qst@cslaststate\qst@csallocstate
1360 \qst@advance\qst@csallocstate
1361 \qst@csaddempty\qst@cslaststate\qst@csallocstate
1362 \let\qst@cslaststate\@undefined
1363 \qst@csparse}
1364 % \end{macrocode}
1365 % \end{macro}
1366 % \begin{macro}{\qst@csparse:(}^^A%{)}
1367 % Ok, now we are getting into grouping. This adds a bit of
1368 % complexity, but it is actually rather containable (took a lot of
1369 % work, though).
1370 % \begin{macrocode}
1371 \expandafter\def\csname qst@csparse:(\endcsname{%
1372 %<!etex> \qst@tmptoks\expandafter{\qst@csstack}%
1373 \edef\qst@csstack{\def\noexpand\qst@csstack{%
1374 %<etex> \unexpanded\expandafter{\qst@csstack}%
1375 %<!etex> \the\qst@tmptoks
1376 }%
1377 \def\noexpand\qst@csgroupstate{\qst@csgroupstate}}%
1378 \let\qst@csgroupstate\qst@csallocstate
1379 \qst@advance\qst@csallocstate
1380 \qst@csaddempty\qst@csgroupstate\qst@csallocstate
1381 \qst@csparse}
1382 % \end{macrocode}
1383 % \end{macro}
1384 % \DeleteShortVerb\|
1385 % \begin{macro}{\qst@csparse:|}
1386 % \begin{macrocode}
1387 \expandafter\def\csname qst@csparse:|\endcsname{%
1388 \let\qst@cslaststate\qst@csallocstate
1389 %<!etex> \qst@tmptoks\expandafter{\qst@csstack}%
1390 %<!etex> \edef\qst@csstack{\the\qst@csstack
1391 %<etex> \edef\qst@csstack{\unexpanded\expandafter{\qst@csstack}%
1392 \noexpand\qst@csaddempty{\qst@cslaststate}%
1393 \noexpand\qst@csallocstate}%
1394 \qst@advance\qst@csallocstate
1395 \qst@csaddempty\qst@csgroupstate\qst@csallocstate
1396 \let\qst@cslaststate\@undefined
1397 \qst@csparse}
1398 % \end{macrocode}
1399 % \end{macro}
1400 % \MakeShortVerb\|
1401 % \begin{macro}{\qst@csparse:)}^^A%{(}
1402 % \begin{macrocode}
1403 \expandafter\def\csname qst@csparse:)\endcsname{%
1404 \let\qst@cslaststate\qst@csgroupstate
1405 \ifx\qst@csstack\@empty
1406 \PackageError{qstest}{Unmatched `)' in call sequence
1407 specification}{You need to fix this}%
1408 \fi
1409 \qst@csstack
1410 \qst@csparse
1411 }
1412 % \end{macrocode}
1413 % \end{macro}
1414 % \begin{macro}{\qst@csparse:`}
1415 % We don't check whether this is actually the first encounter with
1416 % |`|: we just reset the state machine to come here.
1417 % \begin{macrocode}
1418 \expandafter\def\csname qst@csparse:`\endcsname{%
1419 \qst@cssetstate{\qst@csallocstate}%
1420 \let\qst@cslaststate\@undefined
1421 \qst@csparse}
1422 \expandafter\let\csname qst@csparse:^\expandafter\endcsname
1423 \csname qst@csparse:`\endcsname
1424 % \end{macrocode}
1425 % \end{macro}
1426 % \begin{macro}{\qst@csparse:'}
1427 % \begin{macrocode}
1428 \expandafter\def\csname qst@csparse:'\endcsname{%
1429 \qst@csaddempty{\qst@csallocstate}{1}%
1430 \let\qst@cslaststate\qst@csallocstate
1431 \qst@advance\qst@csallocstate
1432 \qst@csparse}
1433 \expandafter\let\csname qst@csparse:$%$
1434 \expandafter\endcsname\csname qst@csparse:'\endcsname
1435 % \end{macrocode}
1436 % \end{macro}
1437 % Ok, let us test the state machine. First define two macros that we
1438 % are going to replace:
1439 % \begin{macrocode}
1440 %</package>
1441 %<*test>
1442 \begin{qstest}{ExpectCallSequence state machine}%
1443 {ExpectCallSequence,internal}
1444 \def\foo#1#2#3{\relax\relax}
1445 \let\fie\relax
1446 % \end{macrocode}
1447 % The free state table starts at 3, the free transitions at 2.
1448 % \begin{macrocode}
1449 \Expect*{\qst@csallocstate}{3}
1450 \Expect*{\qst@csalloctrans}{2}
1451 % \end{macrocode}
1452 % Now we have an implicit start into the call sequence that is |.{}*(|
1453 % and thus takes away 3 states and one transition. The call sequence
1454 % starts off with one ignored entry and then the real state, so we
1455 % expect to be at state~7 initially.
1456 % \begin{macrocode}
1457 \begin{ExpectCallSequence}{\fie{}%
1458 `\foo#1#2#3{#2\bar{#3}}(\bar#1#2{#2}|.#1{})+%
1459 \foo#1{}}
1460 \Expect*{\qst@csstate}{7}
1461 \Expect*{\qst@csallocstate}{15}
1462 % \end{macrocode}
1463 % The state transitions actually happen before the respective code is
1464 % called, so we can actually continue in the matching sequence while
1465 % still working off the replacement for a macro:
1466 % \begin{macrocode}
1467 \foo{\Expect*{\qst@csstate}{8}}{\Expect*{\qst@csstate}{10}}
1468 \Expect*{\qst@csstate}{10}
1469 % \end{macrocode}
1470 % \cmd{\fie} will match the wildcard. Note that we arrive at a
1471 % different target state than previously. While this is
1472 % counterintuively, we have to be aware that an empty transition from
1473 % state~10 to state~12 exists, so both are actually the same state in
1474 % reality.
1475 % \begin{macrocode}
1476 \fie
1477 \Expect*{\qst@csstate}{12}
1478 % \end{macrocode}
1479 % Now \cmd{\foo} kicks us out of the matching. Again, state~14 looks
1480 % strange, but it has an empty transition to state~0, the ``match
1481 % everything until we are finished'' state.
1482 % \begin{macrocode}
1483 \foo
1484 \Expect*{\qst@csstate}{14}
1485 % \end{macrocode}
1486 % So we actually make use of this state and call \cmd{\fie} after
1487 % which it will have reverted to its original meaning:
1488 % \begin{macrocode}
1489 \fie
1490 \Expect*{\qst@csstate}{0}
1491 \Expect*{\meaning\fie}*{\meaning\relax}
1492 % \end{macrocode}
1493 % It is sort of amusing that the above assertion will fail if we write
1494 % just
1495 % \begin{quote}
1496 % |\Expect*{\meaning\fie}{\relax}|
1497 % \end{quote}
1498 % since the meaning of \cmd{\relax} is not ended with a blank, while
1499 % the printed string of its name does end with one. We check that use
1500 % of \cmd{\foo} lets us revert its meaning as well.
1501 % \begin{macrocode}
1502 \foo\junk\junk\junk
1503 \Expect*{\qst@csstate}{0}
1504 \Expect*{\meaning\foo}{macro:#1#2#3->\relax \relax}
1505 \end{ExpectCallSequence}
1506 \end{qstest}
1507 %</test>
1508 %<*package>
1509 % \end{macrocode}
1510 %
1511 % \subsection{Saved results}
1512 %
1513 % The purpose of saved results is to be able to check that the value
1514 % has remained the same over passes. Results are given a unique label
1515 % name and are written to an auxiliary file where they can be read in
1516 % for the sake of comparison. One can use the normal |.aux| file for
1517 % this purpose, but it might be preferable to use a separate dedicated
1518 % file. That way it is possible to input a versioned \emph{copy} of
1519 % this file and have a fixed point of reference rather than the last
1520 % run.
1521 %
1522 % While the |.aux| file is read in automatically at the beginning of
1523 % the document, this does not happen with explicitly named files. You
1524 % have to read them in yourself, preferably using
1525 % \begin{quote}
1526 % |\InputIfFileExists|\marg{filename}|{}{}|
1527 % \end{quote}
1528 % so that no error is thrown when the file does not yet exist.
1529 %
1530 % \begin{macro}{\SaveValueFile}
1531 % This specifies which file name to use for saving results. If this
1532 % is specified, a special file is opened. If one does not specify
1533 % this, instead the standard |.aux| file is used instead.
1534 % \begin{macrocode}
1535 \newcommand*\SaveValueFile[1]{%
1536 \ifnum\qst@savefile=\@auxout
1537 \newwrite\qst@savefile
1538 \else
1539 \immediate\closeout\qst@savefile
1540 \fi
1541 \immediate\openout\qst@savefile #1\relax}
1542 \def\qst@savefile{\@auxout}
1543 % \end{macrocode}
1544 % \end{macro}
1545 % \begin{macro}{\CloseValueFile}
1546 % This is not likely to be used except for testing this package
1547 % itself: it closes the given file so that it may be read in again
1548 % immediately.
1549 % \begin{macrocode}
1550 \newcommand*\CloseValueFile{%
1551 \ifnum\qst@savefile=\@auxout
1552 \else
1553 \immediate\closeout\qst@savefile
1554 \fi}
1555 % \end{macrocode}
1556 % \end{macro}
1557 %
1558 % \begin{macro}{\SaveValue}
1559 % This gets the label name as first argument (which gets sanitized
1560 % more or less, depending on whether you use e\TeX\ or not).
1561 %
1562 % The second argument is the same kind of argument as \cmd{\Expect}
1563 % expects.
1564 % \begin{macrocode}
1565 \newcommand\SaveValue[1]{%
1566 %<etex> \edef\qst@tmpc{\detokenize{#1}}%
1567 %<!etex> \edef\qst@tmpc{\string#1}%
1568 \ifnum\qst@savefile=\@auxout
1569 \ifx\@onlypreamble\AtBeginDocument
1570 \else
1571 \PackageError{qstest}{You need to specify \string\SaveValueFile^^J
1572 for test files without document.}{I can't use
1573 `\string\SaveValue' before either `\string\begin%
1574 {document}'^^J
1575 or `\string\SaveValueFile'}%
1576 \fi
1577 \fi
1578 \qst@expectarg\qst@defaultvalue\qst@saveval}
1579 % \end{macrocode}
1580 % \end{macro}
1581 % \begin{macro}{\qst@saveval}
1582 % This is tricky: we don't want to turn either |^^M| or |^^J| into
1583 % each other. But at least \TeX live will write out |^^J| as a
1584 % single character (causing a line break) and only |^^M| will
1585 % actually get escaped. It would be principally ok to just crank
1586 % out line feeds unmodified, if only \TeX\ would not strip spaces at
1587 % the end of a line. So we go through the string we want to put
1588 % out, and change the single character |^^J| manually into the three
1589 % characters |^^J| after which \TeX\ will preserve spaces.
1590 % \begin{macrocode}
1591 \def\qst@saveval{%
1592 {\immediate\write\qst@savefile{\string\InternalSetValue^^J%
1593 \expandafter\qst@cleanlf\qst@tmpc\qst@endcleanlf^^J%
1594 \expandafter\qst@cleanlf\qst@defaultvalue\qst@endcleanlf^^J%
1595 \string\EndInternalSetValue^^J}}}
1596 % \end{macrocode}
1597 % \end{macro}
1598 % \begin{macro}{\qst@cleanlf}
1599 % \begin{macro}{\qst@endcleanlf}
1600 % \begin{macrocode}
1601 \def\qst@cleanlf#1^^J{#1^%
1602 ^J\qst@cleanlf}
1603 \def\qst@endcleanlf^%
1604 ^J\qst@cleanlf{:^^J}
1605 % \end{macrocode}
1606 % \end{macro}
1607 % \end{macro}
1608 % \begin{macro}{\InternalSetValue}
1609 % The chosen catcodes are picked in order to have |^^xx| escapes
1610 % still work out (\TeX\ can't be kept from using them occasionally).
1611 % Of course, in case |^^| sequences have indeed been present in the
1612 % original macro (like in \cmd{\qst@cleanlf} above), we get
1613 % flummoxed. The spaces we read in here should be the same that
1614 % occur during sanitization. All of this is a bit of compromise.
1615 % Newlines separate keys and values.
1616 % \begin{macrocode}
1617 \newcommand*\InternalSetValue{\begingroup
1618 \let\do\@makeother\dospecials
1619 \endlinechar`\^^J
1620 \catcode`\^7
1621 \qst@setsavedii}
1622 \begingroup
1623 \catcode`\!=12
1624 \lccode`\!=`\\
1625 \lowercase{\endgroup
1626 \def\qst@setsavedii#1:^^J#2:^^J!}EndInternalSetValue^^J{\endgroup
1627 %<etex> \expandafter\gdef\csname qst@value:\detokenize{#1}\endcsname{#2}}
1628 %<!etex> \expandafter\gdef\csname qst@value:\string#1\endcsname{#2}}
1629 % \end{macrocode}
1630 % \end{macro}
1631 % \begin{macro}{\EndInternalSetValue}
1632 % This should actually never get encountered:
1633 % \begin{macrocode}
1634 \newcommand*{\EndInternalSetValue}{%
1635 \PackageError{qstest}{\string\InternalSetValue\space got confused}%
1636 {You probably wrote something bad to the save file}}
1637 % \end{macrocode}
1638 % \end{macro}
1639 %
1640 % \begin{macro}{\SavedValue}
1641 % This is used for retrieving a saved value. If there is no such
1642 % value, instead the current setting in \cmd{\qst@defaultvalue} is
1643 % used.
1644 % \begin{macrocode}
1645 \def\SavedValue#1{%
1646 %<*etex>
1647 \ifcsname qst@value:\detokenize{#1}\endcsname
1648 \expandafter\expandafter\expandafter
1649 {\csname qst@value:\detokenize{#1}\expandafter\endcsname\expandafter}%
1650 \else
1651 \expandafter\expandafter\expandafter{\expandafter\qst@defaultvalue
1652 \expandafter}%
1653 %</etex>
1654 %<*!etex>
1655 \expandafter\ifx\csname qst@value:\string#1\endcsname\relax
1656 \expandafter\expandafter\expandafter{\expandafter\qst@defaultvalue
1657 \expandafter}%
1658 \else
1659 \expandafter\expandafter\expandafter
1660 {\csname qst@value:\string#1\expandafter\endcsname\expandafter}%
1661 %</!etex>
1662 \fi}
1663 % \end{macrocode}
1664 % \end{macro}
1665 % \subsection{The End}
1666 % The test can be ended either in the driver file, or in a standalone
1667 % testfile. \cmd{\stop} is \LaTeX's way of ending the processing of
1668 % an input file before any document processing or setup has been done.
1669 % \begin{macrocode}
1670 %</package>
1671 %<test> \stop
1672 % \end{macrocode}
1673 % \Finale
1674