Debian Codegraph @

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

raw
1 %%% ====================================================================
2 %%% @LaTeX-style-file{
3 %%% filename = "dialogl.dtx",
4 %%% version = "1.99a",
5 %%% date = "2013/01/24",
6 %%% author = "Michael Downes",
7 %%% copyright = "This file is part of the dialogl package, released
8 %%% under the LPPL; see dialogl.ins for details."
9 %%% keywords = "TeX, dialog",
10 %%% supported = "no",
11 %%% abstract = "This file provides macros for writing
12 %%% messages and menus on screen, and reading user responses. It
13 %%% can be used with LaTeX as a documentstyle option, or in
14 %%% other forms of TeX by a standard \input statement.",
15 %%% }
16 %%% ====================================================================
17 %
18 % \iffalse
19 %<*driver>
20 \input{dia-driv.tex}
21 %</driver>
22 % \fi
23 %
24 % \section{History}
25 % This file, \fn{dialog.sty}, was born out of a utility called
26 % \fn{listout.tex} that I wrote for my personal use. The purpose of
27 % \fn{listout.tex} was to facilitate printing out plain text
28 % files\Dash electronic mail, program source files in various
29 % programming languages, and, foremost, \tex/ macro files and log
30 % files. An important part of my \tex/ programming practice is to
31 % print out a macro file on paper and read it through, marking
32 % corrections along the way, then use the marked copy as a script
33 % for editing the file. (For one thing, this allows me to analyze
34 % and mark corrections while riding the bus to work, or
35 % sitting out in the back yard to supervise the kids.) The output I
36 % normally desired was two `pages' per sheet of U.S. letter-size
37 % paper printed landscape, in order to conserve paper.
38 %
39 % Once created, \fn{listout.tex} quickly became my favorite means
40 % of printing out plain text files, not to mention an indispensable
41 % tool in my debugging toolbox: I turn on \cw{tracingmacros} and
42 % \cw{tracingcommands}, then print out the resulting log file so
43 % that I can see several hundred lines of the log at once (by
44 % spreading out two or three pages on my desk with 100+ lines per
45 % page); then I trace through, cross things out, label other
46 % things, draw arrows, and so forth.
47 %
48 % I soon added a filename prompting loop to make it convenient to
49 % print multiple files in a single run. In the process of
50 % perfecting this simple prompting routine\Dash over two or three
51 % years\Dash and adding the ability to optionally specify things like
52 % number of columns at run time, eventually I wrote so much
53 % dialog-related macro code that it became clear this code should
54 % be moved out of \fn{listout.tex} into its own module. The result
55 % was \fn{dialog.sty}.
56 %
57 % Before getting into the macro definitions and technical
58 % commentary, here are descriptions from the user's
59 % perspective of the functions defined in this file.
60 %
61 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
62 % \section{Message-sending functions}
63 %
64 %\begin{usage}
65 %\mesj{<text>}
66 %\end{usage}
67 % Sends the message verbatim: category 12 for all special
68 % characters except braces, tab characters, and carriage returns:
69 %
70 %^^V { } ^^I ^^M
71 %
72 % Naturally, the catcode changes are effective only if \cw{mesj} is
73 % used directly, not inside a macro argument or definition
74 % replacement text.
75 %
76 % Multiple spaces in the argument of \cw{mesj} print as multiple
77 % spaces on screen. A tab character produces always eight spaces;
78 % `smart' handling of tabs is more complicated than I would care to
79 % attempt.
80 %
81 % Line breaks in the argument of \cw{mesj} will produce line breaks
82 % on screen. That is, you don't need to enter a special sequence
83 % such as \ctrl{J}\qc{\%} to get line breaks. See the technical
84 % commentary for \cw{mesjsetup} for details. Even though curly
85 % braces are left with their normal catcodes, they can be printed
86 % in a message without any problem, if they occur in balanced
87 % pairs. If not, the message should be sent using \cw{xmesj}
88 % instead of \cw{mesj}.
89 %
90 % Because of its careful handling of the message text, \cw{mesj} is
91 % extremely easy to use. The only thing you have to worry about is
92 % having properly matched braces. Beyond that, you simply type
93 % everything exactly as you want it to appear on screen.
94 %
95 %\begin{usage}
96 %\xmesj{<text>}
97 %\end{usage}
98 % This is like \cw{mesj} but expands embedded control sequences
99 % instead of printing them verbatim. All special characters have
100 % category 12 except backslash, percent, braces, tab, return, and
101 % ampersand:
102 %
103 %^^V \ % { } ^^I ^^M &
104 %
105 % The first four have normal \tex/ catcodes to make it possible to
106 % use most normal \tex/ commands, and comments, in the message
107 % text. \ctrl{I} and \ctrl{M} are catcode 13 and behave as
108 % described for \cw{mesj}. The \qc{\&} is a special convenience, an
109 % abbreviation for \cw{noexpand}, to use for controlling expansion
110 % inside the message text.
111 %
112 % Doubled backslash \cs{\\} in the argument will produce a single
113 % category 12 backslash character\Dash thus, \verb'\\xxx' can be used
114 % instead of \cw{string}\cw{xxx} or \cw{noexpand}\cw{xxx} (notice
115 % that this works even for outer things like \cw{bye} or
116 % \cw{newif}). Similarly \cs{\%}, \cs{\{}, \cs{\}} and \cs{\&}
117 % produce the corresponding single characters.
118 %
119 % Category 12 space means that you cannot write something like
120 %
121 %^^V \ifvmode h\else v\fi rule
122 %
123 % in the argument of \cw{xmesj} without getting a space after the
124 % \cw{ifvmode}, \cw{else}, and \cw{fi}.%^^A
125 %^^A
126 %\footnote{Well, actually, you could replace each space by
127 %\qc{\%}\meta{newline} to get rid of it. But that makes the message
128 %text harder to read for the programmer.}
129 %^^A
130 % Since occasionally this may be troublesome, \cs{\.} is defined
131 % inside the argument of \cw{xmesj} to be a `control word
132 % terminator': If the expansion of \cw{foo} is \verb'abc', then
133 % \verb'\foo\.xyz' produces \verb'abcxyz' on screen (as opposed to
134 % \verb'\foo xyz' which would produce \verb'abc xyz'). Thus the
135 % above conditional could be written as
136 %
137 %^^V \ifvmode\.h\else\.v\fi\.rule
138 %
139 % Even though the catcode changes done by \cw{xmesj} setup have no
140 % effect if \cw{xmesj} is used inside an argument or definition
141 % replacement text, I find it convenient occasionally to use
142 % \cw{xmesj} in those contexts, in order to get other aspects of the
143 % \cw{xmesj} setup. For instance, if you need to embed a message
144 % that contains a percent sign inside a definition, you can write
145 %
146 %^^V \def\foo{...
147 %^^V \xmesj{... this is a percent
148 %^^V sign: \% (sans backslash) ...}
149 %^^V ...}
150 %
151 % To further support such uses of \cw{xmesj}, the following changes
152 % are also done by \cw{xmesj} setup: the backslash-space control
153 % symbol {\tt\bslash\char32} is made equivalent to \cw{space};
154 % \cs{\^^J} and \cs{\^^M} are defined to produce a \cw{newlinechar};
155 % and active tilde \qc{\~} will produce a category-12 tilde.
156 %
157 % Among other things, this setup makes it easier to obtain
158 % newlines and multiple spaces in an embedded message. For example,
159 % in the following definition the message will have a line break on
160 % screen for each backslash at the end of a line, and the third
161 % line will be indented four spaces.
162 %
163 %^^V \def\bar{...
164 %^^V \xmesj{First line\
165 %^^V Second line\
166 %^^V \ \ \ \ Indented line\
167 %^^V Last line}%
168 %^^V ...}
169 %
170 % The alternative of defining a separate message function
171 % \cw{barfoo} with \cw{f[x]mesj} and calling \cw{barfoo} inside of
172 % \cw{bar} would allow more natural entry of the newlines and the
173 % multiple spaces, but would be slightly more expensive in string
174 % pool and hash table usage.
175 %
176 %\begin{usage}
177 %\promptmesj{<text>}
178 %\promptxmesj{<text>}
179 %\end{usage}
180 % These are like \cw{mesj}, \cw{xmesj} but use \cw{message} rather
181 % than \cw{immediate}\cw{write}\verb'16' internally, thus if the
182 % following operation is a \cw{read}, the user will see the cursor
183 % on screen at the end of the last line, as may be desired when
184 % prompting for a short reply, rather than at the beginning of the
185 % next line. The character \qc{\!} is preempted internally for
186 % newlinechar, for these two functions only,
187 % which means that it cannot be actually printed in
188 % the message text. Use of a visible character such as \qc{\!},
189 % rather than the normal \cw{newlinechar} \ctrl{J}, is necessary
190 % for robustness because of the fact that the \cw{message}
191 % primitive was unable to use an `invisible' character (outside the
192 % range 32--126) for newlines up until \tex/ version 3.1415, which
193 % some users do not yet have (at the time of this writing\Dash July
194 % 1994).
195 %
196 %\begin{usage}
197 %\storemesj\foo{<text>}
198 %\storexmesj\foo{<text>}
199 %\end{usage}
200 % These functions are similar to \cw{mesj}, \cw{xmesj} but store the
201 % given text in the control sequence \cw{foo} instead of immediately
202 % sending the message. Standard \tex/ parameter syntax can be used
203 % to make \cw{foo} a function with arguments, e.g. after
204 %
205 %^^V \storemesj\foo#1{...#1...}
206 %
207 % then you can later write
208 %
209 %^^V \message{\foo{\the\hsize}}
210 %
211 % and get the current value of \cw{hsize} into the middle of the
212 % message text. Consequently also in the x-version \cw{storexmesj} a
213 % category-12 \qc{\#} character can be obtained with \cs{\#}.
214 %
215 %\begin{usage}
216 %\fmesj\foobar#1#2...{...#1...#2...}
217 %\end{usage}
218 % Defines \cw{foobar} as a function that will take the given
219 % arguments, sow them into the message text \verb"{...}", and send
220 % the message. In the message text all special characters are
221 % category 12 except for braces, \qc{\#}, tab, and carriage return.
222 %
223 % If an unmatched brace or a \qc{\#} must be printed in the message
224 % text \cw{fxmesj} must be used instead. (\arg{#} could be used to
225 % insert a single category-6 \qc{\#} token into the message text, and
226 % \tex/ would print it without an error, but both \cw{message} and
227 % \cw{write} would print it as two \arg{#} characters, even though
228 % it's only a single token internally.)
229 %
230 %\begin{usage}
231 %\fxmesj\foobar#1#2...{...#1...#2...}
232 %\end{usage}
233 % Combination of \cw{xmesj} and \cw{fmesj}. Defines \cw{foobar} like
234 % \cw{fmesj}, but with full expansion of the replacement text and
235 % with normal category codes for backslash, percent, braces, and hash
236 % \qc{\#}. The control symbols \cs{\\} \cs{\%} \cs{\{} \cs{\}}
237 % \cs{\&} and \cs{\.} can be used as in \cw{xmesj}, with also \cs{\#}
238 % for printing a \qc{\#} character of category 12.
239 %
240 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
241 % \section{Reading functions}
242 %
243 %\begin{usage}
244 %\readline{<default>}\answer
245 %\end{usage}
246 % This reads a line of input from the user into the macro
247 % \cw{answer}. (The macro name can be anything chosen by the
248 % programmer, not just \cw{answer}.) Before reading, all special
249 % characters are deactivated, so that the primitive \cw{read} will
250 % not choke if the user happens to enter something like \cw{newif}
251 % or {\sc control-l} or \qc{\}}. Depending on the operating
252 % system, certain characters\Dash e.g., {\sc control-c}, {\sc
253 % control-z}, {\sc control-d}, {\sc control-h}\Dash might have
254 % special effects instead of being entered into the replacement
255 % text of \cw{answer}, regardless of the catcode changes. To
256 % take the most obvious example, under most
257 % operating systems, typing {\sc control-h} (the Rubout or
258 % Backward-Delete key) will delete the previous character from the
259 % user's response, instead of entering an \ascii/ character 8
260 % into \cw{answer}.
261 %
262 % There is one significant exception from the catcode changes that
263 % are done for \cw{readline}: spaces and tabs retain their normal
264 % catcode of 10, so that multiple spaces in an answer will be
265 % reduced to a single space, and macros with normal space-delimited
266 % arguments will work when applied to the answer. (I can't think of
267 % any likely scenario where category 12 for spaces would be
268 % useful.) Also, the catcode of \ctrl{M} is set to 9 (ignore) so
269 % that an empty line\Dash meaning that the user just pressed the
270 % carriage return/enter key\Dash will result in an empty \cw{answer}.
271 % If the answer is empty, the given default string will be
272 % substituted. The default string can be empty.
273 %
274 %\begin{usage}
275 %\xreadline{<default>}\answer
276 %\end{usage}
277 % Like \cw{readline} but the answer is read as executable tokens;
278 % the usual catcodes of the \tex/ special characters remain in
279 % effect while reading the answer. A few common outer things
280 % (\cw{bye}, \cs{\+}, \cw{newif}, \ctrl{L}, among others) are
281 % neutralized before the \cw{read} is done, but the user can still
282 % cause problems by entering some other outer control sequence or
283 % unbalanced braces. I doubt there's any bulletproof solution, if
284 % the tokens are to remain executable, short of the usual last
285 % resort: reading the answer using \cw{readline}, writing it to a
286 % file, then inputting the file.
287 %
288 %\begin{usage}
289 %\readchar{<default>}\answer
290 %\end{usage}
291 % This is like \cw{readline} but it reduces the answer to its first
292 % character. \meta{default} is either a single character or empty.
293 %
294 %\begin{usage}
295 %\readChar{<default>}\answer
296 %\end{usage}
297 % This is like \cw{readchar} and also uppercases the answer.
298 %
299 %\begin{usage}
300 %\changecase\uppercase\answer
301 %\end{usage}
302 % The function \cw{changecase} redefines its second argument, which
303 % must be a macro, to contain the same text as before, but
304 % uppercased or lowercased according to the first argument. Thus
305 % \cw{readChar}\verb'{Q}'\cw{answer} is equivalent to
306 %
307 %^^V \readchar{q}\answer
308 %^^V \changecase\uppercase\answer
309 %
310 % It might sometimes be desirable to force lower case before using
311 % a file name given by the user, for example.
312 %
313 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
314 % \section{Checking functions}
315 %
316 %\begin{usage}
317 %\checkinteger\reply\tempcount
318 %\end{usage}
319 % To read in and check an answer that is supposed to be an integer,
320 % use \cw{readline}{}\cw{reply} and then apply \cw{checkinteger} to
321 % the \cw{reply}, supplying a count register, not necessarily named
322 % \cw{tempcount}, wherein \cw{checkinteger} will leave the validated
323 % integer. If \cw{reply} does not contain a valid integer the
324 % returned value will be \verb'-'\cw{maxdimen}.
325 %
326 % At the present time only decimal digits are handled;
327 % some valid \tex/ numbers such as \verb'"AB', \verb'`\@',
328 % \cw{number}\cw{prevgraf}, or a count register name, will not be
329 % recognized by \cw{checkinteger}. There seems to be no bulletproof
330 % way to allow these possibilities.
331 %
332 % Tests that hide \cw{checkinteger} under the hood, such as a
333 % \cw{nonnegativeinteger} test, are not provided because as often as
334 % not the number being prompted for will have to be tested to see if
335 % it falls inside a more specific range, such as 0\dash 255 for an
336 % 8-bit number or 1\dash 31 for a date, and it seems common sense to
337 % omit overhead if it would usually be redundant. It's easy enough to
338 % define such a test for yourself, if you want one.
339 %
340 %\begin{usage}
341 %\checkdimen\reply\tempdim
342 %\end{usage}
343 % Analog of \cw{checkinteger} for dimension values. If \cw{reply}
344 % does not contain a valid dimension the value returned in
345 % \cw{tempdim} will be \verb'-'\cw{maxdimen}.
346 %
347 % Only explicit dimensions with decimal digits, optional decimal
348 % point and more decimal digits, followed by explicit units
349 % \verb'pt' \verb'cm' \verb'in' or whatever are checked for; some
350 % valid \tex/ dimensions such as \cw{parindent},
351 % \verb'.3'\cw{baselineskip}, or \cw{fontdimen}\verb'5'\cw{font}
352 % will not be recognized by \cw{checkdimen}.
353 %
354 % \subsection*{What good is all this?}
355 % What good is all this stuff, practically speaking?\Dash you may
356 % ask. Well, a typical application might be something like: At the
357 % beginning of a document, prompt interactively to find out if the
358 % user wants to print on A4 or US letter-size paper, or change the
359 % top or left margin. Such a query could be done like this:
360 %
361 %^^V \promptxmesj{
362 %^^V Do you want to print on A4 or US letter paper?
363 %^^V Enter u or U for US letter, anything else for A4: }
364 %^^V \readChar{A}\reply % default = A4
365 %^^V \if U\reply \textheight=11in \textwidth=8.5in
366 %^^V \else \textheight=297mm \textwidth=210mm \fi
367 %^^V % Subtract space for 1-inch margins
368 %^^V \addtolength{\textheight}{-2in}
369 %^^V \addtolength{\textwidth}{-2in}
370 %^^V
371 %^^V \promptxmesj{
372 %^^V Left margin setting? [Return = keep current value,
373 %^^V \the\oddsidemargin]: }
374 %^^V \readline{\the\oddsidemargin}\reply
375 %^^V \checkdimen\reply{\dimen0}
376 %^^V \ifdim\dimen0>-\maxdimen
377 %^^V \setlength\oddsidemargin{\dimen0}%
378 %^^V \xmesj{OK, using new left margin of %
379 %^^V \the\oddsidemargin.}
380 %^^V \else
381 %^^V \xmesj{Sorry, I don't understand %
382 %^^V that reply: `\reply'.\
383 %^^V Using default value: \the\oddsidemargin.}
384 %^^V \fi
385 %
386 % Although \latex/'s \cw{typeout} and \cw{typein} functions can
387 % be used for this same task, they are rather more awkward, and
388 % checking the margin value for validity would be quite difficult.
389 %
390 % \StopEventually{}
391 %
392 % \section{Implementation}
393 % Standard package identification:
394 % \begin{macrocode}
395 %<*2e>
396 \NeedsTeXFormat{LaTeX2e}
397 \ProvidesPackage{dialog}[1994/11/08 v0.9y]
398 %</2e>
399 % \end{macrocode}
400 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
401 % \section{Preliminaries}
402 %
403 % \begin{macrocode}
404 %<*2e>
405 \RequirePackage{grabhedr}
406 %</2e>
407 % \end{macrocode}
408 %
409 % If \fn{grabhedr.sty} is not already loaded, load it now. The
410 % \cw{trap.input} function is explained in \fn{grabhedr.doc}.
411 % \begin{macrocode}
412 %<*209>
413 \csname trap.input\endcsname
414 \input grabhedr.sty \relax
415 \fileversiondate{dialog.sty}{0.9y}{1994/11/08}%
416 %</209>
417 % \end{macrocode}
418 %
419 % The functions \cw{localcatcodes} and \cw{restore\-catcodes} are
420 % defined in \fn{grabhedr.sty}. We use them to save and restore
421 % catcodes of any special characters needed in this file whose
422 % current catcodes might not be what we want them to be. Saving and
423 % restoring catcode of at-sign \qc{\@} makes this file work equally
424 % well as a \latex/ documentstyle option or as a simple input file in
425 % other contexts. The double quote character \qc{\"} might be active
426 % for German and other languages. Saving and restoring tilde \qc{\~},
427 % hash \qc{\#}, caret \qc{\^}, and left quote \qc{\`} catcodes is
428 % normally redundant but reduces the number of assumptions we must
429 % rely on. (The following catcodes are assumed: \qc{\\} 0, \qc{\{} 1,
430 % \qc{\}} 2, \qc{\%} 14, {\tt a}\dash {\tt z} {\tt A}\dash {\tt Z}
431 % 11, {\tt 0}\dash {\tt 9} \qc{\.} \qc{\-} 12. Also note that
432 % \cw{endlinechar} is assumed to have a non-null value.)
433 % \begin{macrocode}
434 %% The line break is significant here:
435 \localcatcodes{\@{11}\ {10}\
436 {5}\~{13}\"{12}\#{6}\^{7}\`{12}}
437 % \end{macrocode}
438 %
439 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
440 % \section{Definitions}
441 %
442 % \begin{macro}{\otherchars}
443 %
444 % For deactivating characters with special catcodes during
445 % \cw{readline} we use, instead of \cw{dospecials}, a more
446 % bulletproof (albeit slower) combination of \cw{otherchars},
447 % \cw{controlchars}, and \cw{highchars} that covers all characters in
448 % the range 0\dash 255 except letters and digits. Handling the
449 % characters above 127 triples the overhead done for each read
450 % operation or message definition but seems mandatory for maximum
451 % robustness.^^A
452 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
453 % \footnote{If you are using \fn{dialog.sty} functions on a slow
454 % computer, you might want to try setting \cw{highchars} = empty to
455 % see if that helps the speed.}
456 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
457 %
458 % \cw{otherchars} includes the thirty-three nonalphanumeric visible
459 % characters (counting space as visible). It is intended as an
460 % executable list like \cw{dospecials} but, as an exercise in
461 % memory conservation, it is constructed without the \cw{do}s. For
462 % the usual application of changing catcodes, the list can still be
463 % executed nicely as shown below. Also, if we arrange to
464 % make sure that each character token gets category 12, it's not
465 % necessary to use control symbols such as \cs{\%} in place of
466 % those few special characters that would otherwise be difficult to
467 % place inside of a definition. This avoids a problem that would
468 % otherwise arise if we included \cs{\+} in the list and tried to
469 % process the list with a typical definition of \cs{do}: \cs{\+} is
470 % `outer' in plain \tex/ and would cause an error message when
471 % \cw{do} attempted to read it as an argument. (As a matter of fact
472 % the catcode changes below show a different way around that
473 % problem, but a list of category-12 character tokens is a fun
474 % thing to have around anyway.)
475 %
476 % \begin{macrocode}
477 \begingroup
478 % \end{macrocode}
479 % First we start a group to localize \cw{catcode} changes. Then we
480 % change all relevant catcodes to 12 except for backslash, open
481 % brace, and close brace, which can be handled by judicious
482 % application of \cw{escapechar}, \cw{string}, \cw{edef}, and
483 % \cw{xdef}. By defining \cw{do} in a slightly backward way, so that
484 % it doesn't take an argument, we don't need to worry about the
485 % presence of \cs{\+} in the list of control symbols. Notice the
486 % absence of \cs{\`} from the list of control symbols; it was already
487 % catcoded to 12 in the \cw{localcatcodes} declaration at the
488 % beginning of this file\Dash otherwise it would be troublesome to
489 % make the definition of \cw{do} bulletproof (consider the
490 % possibilities that \qc{\`} might have catcode 0, 5, 9, or 14).
491 %
492 % \begin{macrocode}
493 \def\do{12 \catcode`}
494 \catcode`\~\do\!\do\@\do\#\do\$\do\^\do\&
495 \do\*\do\(\do\)\do\-\do\_\do\=\do\[\do\]
496 \do\;\do\:\do\'\do\"\do\<\do\>\do\,\do\.
497 \do\/\do\?\do\|12\relax
498 % \end{macrocode}
499 % To handle backslash and braces, we define \cs{\\},
500 % \cs{\{}, and \cs{\}} to produce the corresponding category-12
501 % character tokens. Setting \cw{escapechar} to $-1$ means that
502 % \cw{string} will omit the leading backslash that it would
503 % otherwise produce when applied to a control sequence.
504 % \begin{macrocode}
505 \escapechar -1
506 \edef\\{\string\\}
507 \edef\{{\string\{}\edef\}{\string\}}
508 % \end{macrocode}
509 % Space and percent are done last. Then, with almost all the
510 % special characters now category 12, it's rather easy to define
511 % \cw{otherchars}.
512 % \begin{macrocode}
513 \catcode`\ =12\catcode`\%=12
514 \xdef\otherchars
515 { !"#$%&'()*+,-./:;<=>?[\\]^_`\{|\}~}
516 \endgroup % ^ ^ ^
517 % \end{macrocode}
518 % \end{macro}
519 %
520 % \begin{macro}{\controlchars}
521 %
522 % \cw{controlchars} is another list for the control characters
523 % \ascii/ 0\dash 31 and 127. The construction of this list is similar
524 % to the construction of \cw{otherchars}. We need to turn off
525 % \cw{endlinechar} because the catcode of \ctrl{M} is going to be
526 % changed. The \ctrl{L} inside the \cw{gdef} is not a problem (as it
527 % might have been, due to the usual outerness of \ctrl{L}) because
528 % the catcode is changed from 13 to 12 before that point.
529 %
530 % \begin{macrocode}
531 \begingroup
532 \endlinechar = -1
533 \def\do{12 \catcode`}
534 \catcode`\^^@\do\^^A\do\^^B\do\^^C
535 \do\^^D\do\^^E\do\^^F\do\^^G\do\^^H\do\^^I
536 \do\^^J\do\^^K\do\^^L\do\^^M\do\^^N\do\^^O
537 \do\^^P\do\^^Q\do\^^R\do\^^S\do\^^T\do\^^U
538 \do\^^V\do\^^W\do\^^X\do\^^Y\do\^^Z\do\^^[
539 \do\^^\\do\^^]\do\^^^\do\^^_\do\^^? 12\relax
540 %
541 \gdef\controlchars{^^@^^A^^B^^C^^D^^E^^F^^G
542 ^^H^^I^^J^^K^^L^^M^^N^^O^^P^^Q^^R^^S^^T
543 ^^U^^V^^W^^X^^Y^^Z^^[^^\^^]^^^^^_^^?}
544 \endgroup
545 % \end{macrocode}
546 % \end{macro}
547 %
548 % \begin{macro}{\highchars}
549 % And finally, the list \cw{highchars} contains characters
550 % 128\dash 255, the ones that have the eighth bit set.
551 %
552 % \begin{macrocode}
553 \begingroup
554 \def\do{12 \catcode`}
555 \catcode`\^^80\do\^^81\do\^^82\do\^^83\do\^^84
556 \do\^^85\do\^^86\do\^^87\do\^^88\do\^^89\do\^^8a
557 \do\^^8b\do\^^8c\do\^^8d\do\^^8e\do\^^8f
558 \do\^^90\do\^^91\do\^^92\do\^^93\do\^^94\do\^^95
559 % \end{macrocode}
560 %\verbdots\iffalse
561 \do\^^96\do\^^97\do\^^98\do\^^99\do\^^9a\do\^^9b
562 \do\^^9c\do\^^9d\do\^^9e\do\^^9f
563 \do\^^a0\do\^^a1\do\^^a2\do\^^a3\do\^^a4\do\^^a5
564 \do\^^a6\do\^^a7\do\^^a8\do\^^a9\do\^^aa\do\^^ab
565 \do\^^ac\do\^^ad\do\^^ae\do\^^af
566 \do\^^b0\do\^^b1\do\^^b2\do\^^b3\do\^^b4\do\^^b5
567 \do\^^b6\do\^^b7\do\^^b8\do\^^b9\do\^^ba\do\^^bb
568 \do\^^bc\do\^^bd\do\^^be\do\^^bf
569 \do\^^c0\do\^^c1\do\^^c2\do\^^c3\do\^^c4\do\^^c5
570 \do\^^c6\do\^^c7\do\^^c8\do\^^c9\do\^^ca\do\^^cb
571 \do\^^cc\do\^^cd\do\^^ce\do\^^cf
572 \do\^^d0\do\^^d1\do\^^d2\do\^^d3\do\^^d4\do\^^d5
573 \do\^^d6\do\^^d7\do\^^d8\do\^^d9\do\^^da\do\^^db
574 \do\^^dc\do\^^dd\do\^^de\do\^^df
575 \do\^^e0\do\^^e1\do\^^e2\do\^^e3\do\^^e4\do\^^e5
576 \do\^^e6\do\^^e7\do\^^e8\do\^^e9\do\^^ea\do\^^eb
577 \do\^^ec\do\^^ed\do\^^ee\do\^^ef
578 \do\^^f0\do\^^f1\do\^^f2\do\^^f3\do\^^f4\do\^^f5
579 \do\^^f6\do\^^f7\do\^^f8\do\^^f9\do\^^fa\do\^^fb
580 %\fi
581 % \begin{macrocode}
582 \do\^^fc\do\^^fd\do\^^fe\do\^^ff 12\relax
583 %
584 \gdef\highchars{%
585 ^^80^^81^^82^^83^^84^^85^^86^^87^^88%
586 ^^89^^8a^^8b^^8c^^8d^^8e^^8f%
587 ^^90^^91^^92^^93^^94^^95^^96^^97^^98%
588 % \end{macrocode}
589 %\verbdots\iffalse
590 ^^99^^9a^^9b^^9c^^9d^^9e^^9f%
591 ^^a0^^a1^^a2^^a3^^a4^^a5^^a6^^a7^^a8%
592 ^^a9^^aa^^ab^^ac^^ad^^ae^^af%
593 ^^b0^^b1^^b2^^b3^^b4^^b5^^b6^^b7^^b8%
594 ^^b9^^ba^^bb^^bc^^bd^^be^^bf%
595 ^^c0^^c1^^c2^^c3^^c4^^c5^^c6^^c7^^c8%
596 ^^c9^^ca^^cb^^cc^^cd^^ce^^cf%
597 ^^d0^^d1^^d2^^d3^^d4^^d5^^d6^^d7^^d8%
598 ^^d9^^da^^db^^dc^^dd^^de^^df%
599 ^^e0^^e1^^e2^^e3^^e4^^e5^^e6^^e7^^e8%
600 ^^e9^^ea^^eb^^ec^^ed^^ee^^ef%
601 ^^f0^^f1^^f2^^f3^^f4^^f5^^f6^^f7^^f8%
602 %\fi
603 % \begin{macrocode}
604 ^^f9^^fa^^fb^^fc^^fd^^fe^^ff}
605 \endgroup
606 % \end{macrocode}
607 % \end{macro}
608 %
609 % \begin{macro}{\actively}
610 %
611 % The function \cw{actively} makes a given character active and
612 % carries out the assignment given as the first argument. The
613 % assignment can be embedded in the replacement text of a macro
614 % definition without requiring any special setup to produce an active
615 % character in the replacement text. The argument should be a control
616 % symbol, e.g. \cw{@} or \cs{\#} or \cs{\^^M}, rather than a single
617 % character. (Except that \qc{\+} is safer than \cs{\+} in
618 % \plaintex/.) If the assignment is a definition (\cw{def},
619 % \cw{edef}, \cw{gdef}, \cw{xdef}) it is allowed to take arguments in
620 % the normal \tex/ way. Prefixes such as \cw{global}, \cw{long}, or
621 % \cw{outer} must go inside the first argument rather than before
622 % \cw{actively}.
623 %
624 % Usage:
625 %\begin{usage}
626 %\actively\def\?{<replacement text>}
627 %\actively\def\%#1#2{<replacement text>}
628 %\actively{\global\let}\^^@=\space
629 %\end{usage}
630 % One place where this function can be put to good use is in
631 % making \ctrl{M} active in order to get special action at the end
632 % of each line of input. The usual way of going about this would be
633 % to write
634 %
635 %^^V \def\par{something}\obeylines
636 %
637 % \noindent which is a puzzling construction to the \tex/ novice
638 % who doesn't know what \cw{obeylines} does with \cw{par}. The same
639 % effect could be gotten a little more transparently with
640 %
641 %^^V \actively\def\^^M{something}
642 %
643 % In the definition of \cw{actively} we use the unique properties
644 % of \cw{lowercase} to create an active character with the right
645 % character code, overlapping with a \cw{begingroup} \cw{endgroup}
646 % structure that localizes the necessary lc-code change.
647 % \begin{macrocode}
648 \def\actively#1#2{\catcode`#2\active
649 \begingroup \lccode`\~=`#2\relax
650 \lowercase{\endgroup#1~}}
651 % \end{macrocode}
652 % \end{macro}
653 %
654 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
655 %
656 % \begin{macro}{\mesjsetup}
657 %
658 % The \cw{mesjsetup} function starts a group to localize catcode
659 % changes. The group will be closed eventually by a separate
660 % function that does the actual sending or stores the message text
661 % for later retrieval.
662 %
663 % We want to change the catcode of each character in the three
664 % lists \cw{otherchars}, \cw{controlchars}, and \cw{highchars} to
665 % 12. After giving \cw{do} a recursive definition, we apply it to
666 % each of the three lists, adding a suitable element at the end of
667 % the list to make the recursion stop there. This allows
668 % leaving out the \cw{do} tokens from the character lists, without
669 % incurring the cost of an if test at each recursion step.
670 % \begin{macrocode}
671 \def\mesjsetup{\begingroup \count@=12
672 \def\do##1{\catcode`##1\count@ \do}%
673 % \end{macrocode}
674 % The abbreviation \cw{xp@} = \cw{expandafter} is from
675 % \fn{grabhedr.sty}.
676 % \begin{macrocode}
677 \xp@\do\otherchars{a11 \@gobbletwo}%
678 \xp@\do\controlchars{a11 \@gobbletwo}%
679 \xp@\do\highchars{a11 \@gobbletwo}%
680 % \end{macrocode}
681 % Make the tab character produce eight spaces:
682 % \begin{macrocode}
683 \actively\edef\^^I{ \space\space\space
684 \space\space\space\space}%
685 % \end{macrocode}
686 % The convenient treatment of newlines in the argument of \cw{mesj}
687 % (every line break produces a line break on screen) is achieved by
688 % making the \ctrl{M} character active and defining it to produce a
689 % category-12 \ctrl{J} character. Although for \cw{mesj} it would
690 % have sufficed to make \ctrl{M} category 12 and locally set
691 % \cw{newlinechar} = \ctrl{M} while sending the message, it turns out
692 % to be useful for other functions to have the \ctrl{M} character
693 % active, so that it can be remapped to an arbitrary function for
694 % handling new lines (e.g., perhaps adding extra spaces at the
695 % beginning of each line). And if \cw{mesj} treats \ctrl{M} the same,
696 % we can arrange for it to share the setup routines needed for the
697 % other functions.
698 % \begin{macrocode}
699 \endlinechar=`\^^M\actively\let\^^M=\relax
700 \catcode`\{=1 \catcode`\}=2 }
701 % \end{macrocode}
702 % \end{macro}
703 %
704 % \begin{macro}{\sendmesj}
705 %
706 % In \cw{sendmesj} we go to a little extra trouble to make sure
707 % \ctrl{M} produces a newline character, no matter what the value of
708 % \cw{newlinechar} might be in the surrounding environment. The
709 % impending \cw{endgroup} will restore \cw{newlinechar} to its
710 % previous value. One reason for using \ctrl{J} (instead of, say,
711 % \ctrl{M} directly) is to allow e.g. \cw{mesj}\verb'{xxx^^Jxxxx}' to
712 % be written inside a definition, as is sometimes convenient. This
713 % would be difficult with \ctrl{M} instead of \ctrl{J} because of
714 % catcodes.
715 %
716 % \begin{macrocode}
717 \def\sendmesj{\newlinechar`\^^J%
718 \actively\def\^^M{^^J}%
719 \immediate\write\sixt@@n{\mesjtext}\endgroup}
720 % \end{macrocode}
721 % \end{macro}
722 %
723 % \begin{macro}{\mesj}
724 %
725 % Given the support functions defined above, the definition of
726 % \cw{mesj} is easy: Use \cw{mesjsetup} to clear all special
727 % catcodes, then set up \cw{sendmesj} to be triggered by the next
728 % assignment, then read the following balanced-braces group into
729 % \cw{mesjtext}. As soon as the definition is completed, \tex/ will
730 % execute \cw{sendmesj}, which will send the text and close the
731 % group that was started in \cw{mesjsetup} to localize the catcode
732 % changes.
733 %
734 % \begin{macrocode}
735 \def\mesj{\mesjsetup \afterassignment\sendmesj
736 \def\mesjtext}
737 % \end{macrocode}
738 % \end{macro}
739 %
740 % \begin{macro}{\sendprompt}
741 %
742 % The \cw{sendprompt} function is just like \cw{sendmesj} except
743 % that it uses \cw{message} instead of \cw{write}, as might be
744 % desired when prompting for user input, so that the on-screen
745 % cursor stays on the same line as the prompt instead of hopping
746 % down to the beginning of the next line. In order for newlines to
747 % work with \cw{message} we must use a visible character instead of
748 % \ctrl{J}. When everyone has \tex/ version 3.1415 or later this
749 % will no longer be true. The choice of \qc{\!} might be construed
750 % (if you wish) as editorial comment that \qc{\!} should not be
751 % shouted at the user in a prompt.
752 %
753 % \begin{macrocode}
754 \def\sendprompt{%
755 \newlinechar`\!\relax \actively\def\^^M{!}%
756 \message{\mesjtext}\endgroup}
757 % \end{macrocode}
758 % \end{macro}
759 %
760 % \begin{macro}{\promptmesj}
761 %
762 % This function is like \cw{mesj} but uses \cw{sendprompt} instead of
763 % \cw{sendmesj}.
764 %
765 % \begin{macrocode}
766 \def\promptmesj{\mesjsetup
767 \afterassignment\sendprompt \def\mesjtext}
768 % \end{macrocode}
769 % \end{macro}
770 %
771 % \begin{macro}{\storemesj}
772 %
773 % Arg \arg{1} of \cw{storemesj} is the control sequence under which
774 % the message text is to be stored.
775 % \begin{macrocode}
776 \def\storemesj#1{\mesjsetup
777 \catcode`\#=6 % to allow arguments if needed
778 \afterassignment\endgroup
779 \long\gdef#1}
780 % \end{macrocode}
781 % \end{macro}
782 %
783 % \begin{macro}{\fmesj}
784 %
785 % While \cw{storemesj}\cw{foo}\verb"{...}" is more or less the
786 % same as \cw{def}\cw{foo}\verb"{...}" with special catcode
787 % changes, \cw{fmesj}\cw{foo}\verb"{...}" corresponds to
788 % \cw{def}\cw{foo}\qc{\{}\cw{mesj}\verb"{...}}", that is, after
789 % \cw{fmesj}\cw{foo} the function \cw{foo} can be executed directly
790 % to send the message. Thus \cw{storemesj} is typically used for
791 % storing pieces of messages, while \cw{fmesj} is used for storing
792 % entire messages.
793 %
794 % To read the parameter text \arg{2}, we use the peculiar
795 % \verb'#{' feature of \tex/ to read everything up to the opening
796 % brace.
797 % \begin{macrocode}
798 \def\fmesj#1#2#{\mesjsetup
799 \catcode`\#=6 % restore to normal
800 % \end{macrocode}
801 % The parameter text \arg{2} must be stored in a token register
802 % rather than a macro to avoid problems with \qc{\#} characters.
803 % The \cw{long} prefix is just to admit the (unlikely) possibility
804 % of using \cw{fmesj} to define something such as an error message
805 % saying `You can't use \arg{1} here' where one of the
806 % possibilities for \arg{1} is \cw{string}\cw{par}.
807 % \begin{macrocode}
808 \toks@{\long\gdef#1#2}%
809 % \end{macrocode}
810 % Define \cw{@tempa} to put together the first two arguments and
811 % [pseudo]argument \arg{3} and make the definition of \arg{1}.
812 % \begin{macrocode}
813 \def\@tempa{%
814 \edef\@tempa{%
815 \the\toks@{%
816 % \end{macrocode}
817 % The abbreviation \cw{nx@} = \cw{noexpand} is from
818 % \fn{grabhedr.sty}.
819 % \begin{macrocode}
820 \begingroup\def\nx@\mesjtext{\the\toks2 }%
821 \nx@\sendmesj}%
822 }%
823 \@tempa
824 \endgroup % Turn off the \mesjsetup catcodes
825 }%
826 \afterassignment\@tempa
827 \toks2=}
828 % \end{macrocode}
829 % \end{macro}
830 %
831 % \begin{macro}{\xmesjsetup}
832 %
833 % \cw{xmesjsetup} is like \cw{mesjsetup} except it prepares to allow
834 % control sequence tokens and normal comments in the message text.
835 % For \tex/nicians' convenience certain other features are
836 % thrown in.
837 %
838 % Here, unlike the setup for \cw{xreadline}, I don't bother to
839 % remove the outerness of \cw{bye}, \cw{newif}, etc., because I
840 % presume the arguments of \cw{xmesj}, \cw{fxmesj},
841 % \cw{storexmesj}, \cw{fxmenu}, etc.\ are more likely to be written
842 % by a \tex/nician than by an average end user, whereas
843 % \cw{xreadline} is designed to handle arbitrary input from
844 % arbitrary users.
845 %
846 % \begin{macrocode}
847 \def\xmesjsetup{\mesjsetup
848 % \end{macrocode}
849 % Throw in pseudo braces just in case we are inside an \cw{halign}
850 % with \cs{\\} let equal to \cw{cr} at the time when \cw{xmesjsetup}
851 % is called. (As might happen in \amstex/.)
852 % \begin{macrocode}
853 \iffalse{\fi
854 \catcode`\\=0 \catcode`\%=14
855 % \end{macrocode}
856 % Define {\def~{\spacefactor1500 \space}%
857 % \cs{\%}~\cs{\\}~\cs{\{}~\cs{\}}~\cs{\&}} to produce the
858 % corresponding single characters, category 12. The \cw{lowercase}
859 % trick here allows these definitions to be nonglobal.
860 % \begin{macrocode}
861 \begingroup \lccode`\0=`\\\lccode`\1=`\{%
862 \lccode`\2=`\}\lccode`\3=`\%%
863 \lowercase{\endgroup \def\\{0}\def\{{1}%
864 \def\}{2}\def\%{3}}%
865 \iffalse}\fi
866 \edef\&{\string &}%
867 % \end{macrocode}
868 % Let \qc{\&} \qc{\=} \cw{noexpand} for expansion control inside the
869 % argument text; let active \ctrl{M} \qc{\=} \cw{relax} so that
870 % newlines will remain inert during the expansion.
871 % \begin{macrocode}
872 \actively\let\&=\noexpand
873 \actively\let\^^M=\relax
874 % \end{macrocode}
875 % Define \cs{\.} to be a noop, for terminating a control word when
876 % it is followed by letters and no space is wanted.
877 % \begin{macrocode}
878 \def\.{}%
879 % \end{macrocode}
880 % Support for use of \cw{xmesj} inside a definition replacement
881 % text or macro argument: control-space
882 % \verb*"\ " = \cw{space}, tilde \qc{\~} prints as itself,
883 % \cs{\^^M} (i.e., a lone backslash at the end of a line) will
884 % produce a newline, also \cs{\^^J}, while finally \cw{par} \qc{\=}
885 % blank line translates to two newlines.
886 % \begin{macrocode}
887 \def\ { }\edef~{\string ~}%
888 % \end{macrocode}
889 % Define \cs{\^^M} to produce an active \ctrl{M} character, which (we
890 % hope) will be suitably defined to produce a newline or whatever.
891 % \begin{macrocode}
892 \begingroup \lccode`\~=`\^^M%
893 \lowercase{\endgroup \def\^^M{~}}%
894 \let\^^J\^^M \def\par{\^^M\^^M}%
895 }
896 % \end{macrocode}
897 % \end{macro}
898 %
899 % \begin{macro}{\xmesj}
900 %
901 % \cw{xmesj} uses \cw{xmesjsetup} and \cw{edef}.
902 % \begin{macrocode}
903 \def\xmesj{\xmesjsetup \afterassignment\sendmesj
904 \edef\mesjtext}
905 % \end{macrocode}
906 % \end{macro}
907 %
908 % \begin{macro}{\promptxmesj}
909 %
910 % \cw{promptxmesj} is analogous to \cw{promptmesj}, but with
911 % expansion.
912 % \begin{macrocode}
913 \def\promptxmesj{\xmesjsetup
914 \afterassignment\sendprompt \edef\mesjtext}
915 % \end{macrocode}
916 % \end{macro}
917 %
918 % \begin{macro}{\storexmesj}
919 %
920 % And \cw{storexmesj} is like \cw{storemesj}, with expansion. Since
921 % we allow arguments for the function being defined, we also must
922 % define \cs{\#} to produce a single category-12 \qc{\#} character so
923 % that there will be a way to print \qc{\#} in the message text.
924 % \begin{macrocode}
925 \def\storexmesj#1#2#{\xmesjsetup
926 \catcode`\#=6 % to allow arguments if needed
927 \edef\#{\string##}%
928 \afterassignment\endgroup
929 \long\xdef#1#2}
930 % \end{macrocode}
931 % \end{macro}
932 %
933 % \begin{macro}{\fxmesj}
934 %
935 % And \cw{fxmesj} is the expansive analog of \cw{fmesj}.
936 % \begin{macrocode}
937 \def\fxmesj#1#2#{\xmesjsetup
938 \catcode`\#=6 % restore to normal
939 \edef\#{\string##}%
940 \toks@{\long\xdef#1#2}%
941 \def\@tempa{%
942 \edef\@tempa{%
943 \the\toks@{\begingroup
944 \def\nx@\nx@\nx@\mesjtext{\the\toks\tw@}%
945 \nx@\nx@\nx@\sendmesj}}%
946 \@tempa % execute the constructed xdef
947 \endgroup % restore normal catcodes
948 }%
949 \afterassignment\@tempa
950 \toks\tw@=}
951 % \end{macrocode}
952 % \end{macro}
953 %
954 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
955 % \section{Reading functions}
956 %
957 % \begin{macro}{\readline}
958 % The \cw{readline} function gets one line of input from the user.
959 % Arguments are: \arg{1} default to be used if the user response is
960 % empty (i.e., if the user just pressed the return/enter key),
961 % \arg{2} macro to receive the input.
962 %
963 % \begin{macrocode}
964 \def\readline#1#2{%
965 \begingroup \count@ 12 %
966 \def\do##1{\catcode`##1\count@ \do}%
967 \xp@\do\otherchars{a11 \@gobbletwo}%
968 \xp@\do\controlchars{a11 \@gobbletwo}%
969 \xp@\do\highchars{a11 \@gobbletwo}%
970 % \end{macrocode}
971 % Make spaces and tabs normal instead of category 12.
972 % \begin{macrocode}
973 \catcode`\ =10 \catcode`\^^I=10 %
974 \catcode`\^^M=9 % ignore
975 % \end{macrocode}
976 % Reset end-of-line char to normal, just in case.
977 % \begin{macrocode}
978 \endlinechar`\^^M
979 % \end{macrocode}
980 % We go to a little trouble to avoid \cw{gdef}-ing \arg{2}, in order
981 % to prevent save stack buildup if the user of \cw{readline} carries
982 % on unaware doing local redefinitions of \arg{2} after the initial
983 % read.
984 % \begin{macrocode}
985 \read\m@ne to#2%
986 \edef#2{\def\nx@#2{#2}}%
987 \xp@\endgroup #2%
988 \ifx\@empty#2\def#2{#1}\fi
989 }
990 % \end{macrocode}
991 % \end{macro}
992 %
993 % \begin{macro}{\xreadline}
994 %
995 % \cw{xreadline} is like \cw{readline} except that it leaves almost
996 % all catcodes unchanged so that the return value is executable
997 % tokens instead of strictly character tokens of category 11 or 12.
998 % \begin{macrocode}
999 \def\xreadline#1#2{%
1000 \begingroup
1001 % \end{macrocode}
1002 % Render some outer control sequences innocuous.
1003 % \begin{macrocode}
1004 \xp@\let\csname bye\endcsname\relax
1005 \xp@\let\csname newif\endcsname\relax
1006 \xp@\let\csname newcount\endcsname\relax
1007 \xp@\let\csname newdimen\endcsname\relax
1008 \xp@\let\csname newskip\endcsname\relax
1009 \xp@\let\csname newmuskip\endcsname\relax
1010 \xp@\let\csname newtoks\endcsname\relax
1011 \xp@\let\csname newbox\endcsname\relax
1012 \xp@\let\csname newinsert\endcsname\relax
1013 \xp@\let\csname +\endcsname\relax
1014 \actively\let\^^L\relax
1015 \catcode`\^^M=9 % ignore
1016 \endlinechar`\^^M% reset to normal
1017 \read\m@ne to#2%
1018 \toks@\xp@{#2}%
1019 \edef\@tempa{\def\nx@#2{\the\toks@}}%
1020 \xp@\endgroup \@tempa
1021 \ifx\@empty#2\def#2{#1}\fi
1022 }
1023 % \end{macrocode}
1024 % \end{macro}
1025 %
1026 % \begin{macro}{\readchar}
1027 %
1028 % \cw{readchar} reduces the user response to a single character.
1029 % \begin{macrocode}
1030 \def\readchar#1#2{%
1031 \readline{#1}#2%
1032 % \end{macrocode}
1033 % If the user's response and the default response are both empty,
1034 % we need something after \arg{1} to keep \cw{@car} from running
1035 % away, so we add an empty pair of braces.
1036 % \begin{macrocode}
1037 \edef#2{\xp@\@car#2#1{}\@nil}%
1038 }
1039 % \end{macrocode}
1040 % \end{macro}
1041 %
1042 % \begin{macro}{\readChar}
1043 %
1044 % \cw{readChar} reduces the user response to a single uppercase
1045 % character. (This is useful to simplify testing the response
1046 % later with \cw{if}.)
1047 %
1048 % \begin{macrocode}
1049 \def\readChar#1#2{%
1050 \readline{#1}#2%
1051 \changecase\uppercase#2%
1052 % \end{macrocode}
1053 % Reduce \arg{2} to its first character, or the first character of
1054 % \arg{1}, if \arg{2} is empty. The extra braces \verb'{}' are to
1055 % prevent a runaway argument error from \cw{@car} if \arg{2} and
1056 % \arg{1} are both empty.
1057 % \begin{macrocode}
1058 \edef#2{\xp@\@car #2#1{}\@nil}%
1059 }
1060 % \end{macrocode}
1061 % \end{macro}
1062 %
1063 % \begin{macro}{\changecase}
1064 % The function \cw{changecase} uppercases or lowercases the
1065 % replacement text of its second argument, which
1066 % must be a macro. The first argument should be \cw{uppercase} or
1067 % \cw{lowercase}.
1068 % \begin{macrocode}
1069 \def\changecase#1#2{\@casetoks\xp@{#2}%
1070 \edef#2{#1{\def\nx@#2{\the\@casetoks}}}#2}
1071 % \end{macrocode}
1072 % \end{macro}
1073 %
1074 % \begin{macro}{\@casetoks}
1075 % We allocate a token register just for the use of \cw{changecase}
1076 % because it might be used at a low level internally where we don't
1077 % want to interfere with other uses of the scratch token registers
1078 % 0\dash 9.
1079 % \begin{macrocode}
1080 \newtoks\@casetoks
1081 % \end{macrocode}
1082 % \end{macro}
1083 %
1084 % A common task in reading user input is to verify, when an answer
1085 % of a certain kind was requested, that the response has indeed the
1086 % desired form\Dash for example, if a nonnegative integer is required
1087 % for subsequent processing, it behooves us to verify that we have
1088 % a nonnegative integer in hand before doing anything that might
1089 % lead to inconvenient error messages. However, it's not easy to
1090 % decide how best to handle such verification. One possibility
1091 % might be to have a function
1092 %
1093 %^^V \readnonnegativeinteger\foo
1094 %
1095 % to do all the work of going out and fetching a number from the
1096 % user and leaving it in the macro \cw{foo}. Another possibility
1097 % would be to read the response using \cw{readline} and then apply
1098 % a separate function that can be used in combination with \cw{if},
1099 % for example
1100 %
1101 %^^V \readline{}\reply
1102 %^^V \if\validnumber\reply ... \else ... \fi
1103 %
1104 % For maximum flexibility, a slightly lower-level approach is
1105 % chosen here. The target syntax is
1106 %
1107 %^^V \readline{}\reply
1108 %^^V \checkinteger\reply\tempcount
1109 %
1110 % where \cw{tempcount} will be set to \verb'-'\cw{maxdimen} if
1111 % \cw{reply} does {\em not\/} contain a valid integer. (Negative
1112 % integers are allowed, as long as they are greater than
1113 % \verb'-'\cw{maxdimen}.) Then the function that calls
1114 % \cw{checkinteger} is free to make additional checks on the range
1115 % of the reply and give error messages tailored to the
1116 % circumstances. And the handling of an empty \cw{reply} can be
1117 % arbitrarily customized, something that would tend to be
1118 % inconvenient for the first method mentioned.
1119 %
1120 % The first and second approaches can be built on top of the third
1121 % if desired, e.g.\ (for the second approach)
1122 %
1123 %^^V \def\validnumber#1{TT\fi
1124 %^^V \checkinteger#1\tempcount%
1125 %^^V \ifnum\tempcount>-\maxdimen }
1126 %
1127 % The curious \verb'TT\fi'\verbdots\cw{ifnum} construction is from
1128 % \TeXhax{} 1989, no.~20 and no.~38 (a suggestion of D. E. Knuth in
1129 % reply to a query by S. von Bechtolsheim).
1130 %
1131 % \begin{macro}{\checkinteger}
1132 %
1133 % The arguments of \cw{checkinteger}'s are: \arg{2}, a count register
1134 % to hold the result; \arg{1}, a macro holding zero or more arbitrary
1135 % characters of category 11 or 12.
1136 %
1137 % \begin{macrocode}
1138 \def\checkinteger#1#2{\let\scansign@\@empty
1139 \def\scanresult@{#2}%
1140 \xp@\scanint#1x\endscan}
1141 % \end{macrocode}
1142 % \end{macro}
1143 %
1144 % \begin{macro}{\scanint}
1145 %
1146 % To validate a number, the function \cw{scanint} must first scan
1147 % away leading \qc{\+} or \qc{\-} signs (keeping track in
1148 % \cw{scansign@}), then look at the first token after that: if it's
1149 % a digit, fine, scan that digit and any succeeding digits into the
1150 % given count register (\cw{scanresult@}), ending with \cw{endscan}
1151 % to get rid of any following garbage tokens that might just
1152 % possibly show up.
1153 %
1154 % Typical usage of \cw{scanint} includes initializing \cw{scansign@}
1155 % to empty, as in the definition of \cw{checkinteger}.
1156 %\begin{usage}
1157 %\let\scansign@\@empty
1158 %\def\scanresult@{\tempcount}%
1159 %\xp@\scanint\reply x\endscan
1160 %\end{usage}
1161 % Assumption: \cw{reply} is either empty or contains only category
1162 % 11 or 12 characters (which it will if you used \cw{readline}!). If
1163 % a separate check is done earlier to trap the case where \cw{reply}
1164 % is empty\Dash for example, by using a nonempty default for
1165 % \cw{readline}\Dash then the \verb'x' before \cw{endscan} is
1166 % superfluous.
1167 %
1168 % Arg \arg{1} = next character from the string being tested.
1169 % The test whether \arg{1} is a decimal digit is similar in spirit
1170 % to the test \verb'\if!#1!' to see if an argument is empty
1171 % (\TB, Appendix~D, p.~376).
1172 % \begin{macrocode}
1173 \def\scanint#1{%
1174 \ifodd 0#11 %
1175 % \end{macrocode}
1176 % Is \arg{1} a decimal digit? If so read all digits into
1177 % \cw{scanresult@} with the sign prefix.
1178 % \begin{macrocode}
1179 \def\@tempa{\afterassignment\endscan
1180 \scanresult@=\scansign@#1}%
1181 \else
1182 \if -#1\relax
1183 % \end{macrocode}
1184 % Here we flipflop the sign; watch closely.
1185 % \begin{macrocode}
1186 \edef\scansign@{%
1187 \ifx\@empty\scansign@ -\fi}%
1188 \def\@tempa{\scanint}%
1189 \else
1190 % \end{macrocode}
1191 % A plus sign can just be ignored.
1192 % \begin{macrocode}
1193 \if +#1\relax
1194 \def\@tempa{\scanint}%
1195 \else % not a valid number
1196 \def\@tempa{%
1197 \scanresult@=-\maxdimen\endscan}%
1198 \fi\fi\fi
1199 \@tempa
1200 }
1201 % \end{macrocode}
1202 % \end{macro}
1203 %
1204 % \begin{macro}{\endscan}
1205 % The \cw{endscan} function just gobbles any remaining garbage. It
1206 % uses its own name as the argument delimiter.
1207 % \begin{macrocode}
1208 \def\endscan#1\endscan{}
1209 % \end{macrocode}
1210 % \end{macro}
1211 %
1212 % \begin{macro}{\dimenfirstpart}
1213 % \begin{macro}{\dimentoks}
1214 % \cw{dimenfirstpart}, a count register, receives the digits, if
1215 % any, preceding the decimal point. \cw{dimentoks}, a token
1216 % register, receives any digits after the decimal point.
1217 % \begin{macrocode}
1218 \newcount\dimenfirstpart
1219 \newtoks\dimentoks
1220 % \end{macrocode}
1221 % \end{macro}
1222 % \end{macro}
1223 %
1224 % \begin{macro}{\scandimen}
1225 %
1226 % \cw{scandimen} is similar to \cw{scanint} but has to call some
1227 % auxiliary functions to scan the various subcomponents of a
1228 % dimension (leading digits, decimal point, fractional part, and
1229 % units, with optional {\tt true}, in addition to the sign). The
1230 % minimum requirements of \tex/'s syntax for dimensions are a digit
1231 % or decimal point \qc{\+} the units; all the other components are
1232 % optional (\TB, Exercise~10.3, p.~58).
1233 %
1234 % When scanning for the digits of a fractional part, we can't throw
1235 % away leading zeros; therefore we don't read the fractional part
1236 % into a count register as we did for the digits before the decimal
1237 % point; instead we read the digits one by one and store them in
1238 % \cw{dimentoks}.
1239 %
1240 % The function that calls \cw{scandimen} should initialize
1241 % \cw{scansign@} to \cw{@empty}, \cw{dimenfirstpart} to \cw{z@},
1242 % \cw{dimentoks} to empty \verb'{}', and \cw{dimentrue@} to
1243 % \cw{@empty}.
1244 %
1245 % Test values: {\tt 0pt}, {\tt 1.1in}, {\tt -2cm}, {\tt .3mm}, {\tt
1246 % 0.4dd}, {\tt 5.cc}, {\tt.10000000009pc}, \cw{hsize}, {\tt em}.
1247 %
1248 % \begin{macrocode}
1249 \def\scandimen#1{%
1250 \ifodd 0#11
1251 \def\@tempa{\def\@tempa{\scandimenb}%
1252 \afterassignment\@tempa
1253 \dimenfirstpart#1}%
1254 \else
1255 % \end{macrocode}
1256 %
1257 % The following test resolves to true if \arg{1} is either a period
1258 % or a comma (both recognized by \tex/ as decimal point
1259 % characters).
1260 %
1261 % \begin{macrocode}
1262 \if \if,#1.\else#1\fi.%
1263 \def\@tempa{\scandimenc}%
1264 \else
1265 \if -#1% then flipflop the sign
1266 \edef\scansign@{%
1267 \ifx\@empty\scansign@ -\fi}%
1268 \def\@tempa{\scandimen}%
1269 \else
1270 \if +#1% then ignore it
1271 \def\@tempa{\scandimen}%
1272 \else % not a valid dimen
1273 \def\@tempa{%
1274 \scanresult@=-\maxdimen\endscan}%
1275 \fi\fi\fi\fi
1276 \@tempa
1277 }
1278 % \end{macrocode}
1279 % \end{macro}
1280 %
1281 % \begin{macro}{\scandimenb}
1282 %
1283 % Scan for an optional decimal point.
1284 %
1285 % \begin{macrocode}
1286 \def\scandimenb#1{%
1287 \if \if,#1.\else#1\fi.%
1288 \def\@tempa{\scandimenc}%
1289 \else
1290 % \end{macrocode}
1291 % If the decimal point is absent, we need to put back \arg{2} and
1292 % rescan it to see if it is the first letter of the units.
1293 % \begin{macrocode}
1294 \def\@tempa{\scanunitsa#1}%
1295 \fi
1296 \@tempa
1297 }
1298 % \end{macrocode}
1299 % \end{macro}
1300 %
1301 % \begin{macro}{\scandimenc}
1302 %
1303 % Scan for the fractional part: digits after the decimal point.
1304 %
1305 % \begin{macrocode}
1306 \def\scandimenc#1{%
1307 % \end{macrocode}
1308 % If \arg{1} is a digit, add it to \cw{dimentoks}.
1309 % \begin{macrocode}
1310 \ifodd 0#11 \dimentoks\xp@{%
1311 \the\dimentoks#1}%
1312 \def\@tempa{\scandimenc}%
1313 \else
1314 % \end{macrocode}
1315 % Otherwise rescan \arg{1}, presumably the first letter of the
1316 % units.
1317 % \begin{macrocode}
1318 \def\@tempa{\scanunitsa#1}%
1319 \fi
1320 \@tempa
1321 }
1322 % \end{macrocode}
1323 % \end{macro}
1324 %
1325 % \begin{macro}{\scanunitsa}
1326 %
1327 % \begin{macrocode}
1328 \def\scanunitsa#1\endscan{%
1329 % \end{macrocode}
1330 % Check for \verb'true' qualifier.
1331 % \begin{macrocode}
1332 \def\@tempa##1true##2##3\@tempa{##2}%
1333 % \end{macrocode}
1334 %
1335 % The peculiar nature of \cw{lowercase} is evident here as we are
1336 % able to apply it to only the test part of the conditional without
1337 % running into brace-matching problems. (Compare the braces in this
1338 % example to something like \cw{message}\qc{\{}\cw{iffalse}
1339 % \verb"A}"\cw{else} \verb"B}"\cw{fi}.)
1340 %
1341 % \begin{macrocode}
1342 \lowercase{%
1343 \xp@\ifx\xp@\end
1344 \@tempa#1true\end\@tempa
1345 }%
1346 % \end{macrocode}
1347 % No \verb'true' was found:
1348 % \begin{macrocode}
1349 \let\dimentrue@\@empty
1350 \def\@tempa{\scanunitsb#1\endscan}%
1351 \else
1352 \def\dimentrue@{true}%
1353 \def\@tempa##1true##2\@tempa{%
1354 \def\@tempa{##1}%
1355 \ifx\@tempa\@empty
1356 \def\@tempa{\scanunitsb##2\endscan}%
1357 \else
1358 \def\@tempa{\scanunitsb xx\endscan}%
1359 \fi}%
1360 \@tempa#1\@tempa
1361 \fi
1362 \@tempa
1363 }
1364 % \end{macrocode}
1365 % \end{macro}
1366 %
1367 % \begin{macro}{\scanunitsb}
1368 %
1369 % Scan for the name of the units and complete the assignment of the
1370 % scanned value to \cw{scanresult@}. Notice that, because of the way
1371 % \cw{scanunitsb} picks up \arg{1} and \arg{2} as macro arguments,
1372 % \verb"p t" is allowed as a variation of \verb"pt". Eliminating
1373 % this permissiveness doesn't seem worth the speed penalty
1374 % that would be incurred in \cw{scanunitsb}.
1375 %
1376 % The method for detecting a valid units string is to define the
1377 % scratch function \cw{@tempa} to apply \tex/'s parameter-matching
1378 % abilities to a special string that will yield a boolean value
1379 % of true if and only if the given string is a valid \tex/ unit.
1380 % \begin{macrocode}
1381 \def\scanunitsb#1#2{%
1382 \def\@tempa##1#1#2##2##3\@nil{##2}%
1383 \def\@tempb##1{T\@tempa
1384 pcTptTcmTccTemTexTinTmmTddTspT##1F\@nil}%
1385 % \end{macrocode}
1386 % Force lowercase just in case the units were entered with
1387 % uppercase letters (accepted by \tex/, so we had better accept
1388 % uppercase also).
1389 % \begin{macrocode}
1390 \lowercase{%
1391 \if\@tempb{#1#2}%
1392 }%
1393 \scanresult@=\scansign@
1394 \number\dimenfirstpart.\the\dimentoks
1395 \dimentrue@#1#2\relax
1396 \else
1397 \scanresult@=-\maxdimen
1398 \fi
1399 % \end{macrocode}
1400 % Call \cw{endscan} to gobble garbage tokens, if any.
1401 % \begin{macrocode}
1402 \endscan
1403 }
1404 % \end{macrocode}
1405 % \end{macro}
1406 %
1407 % \begin{macro}{\checkdimen}
1408 %
1409 % Argument \arg{2} must be a dimen register; \arg{1} is expected to
1410 % be a macro holding zero or more arbitrary characters of category 11
1411 % or 12.
1412 % \begin{macrocode}
1413 \def\checkdimen#1#2{%
1414 \let\scansign@\@empty \def\scanresult@{#2}%
1415 \let\dimentrue@\@empty
1416 \dimenfirstpart\z@ \dimentoks{}%
1417 \xp@\scandimen#1xx\endscan
1418 }
1419 % \end{macrocode}
1420 % \end{macro}
1421 %
1422 % Finish up.
1423 % \begin{macrocode}
1424 \restorecatcodes
1425 \endinput
1426 % \end{macrocode}
1427 %
1428 % \CheckSum{858}
1429 % \Finale