Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % !TeX program = pdflatex
3 % !TeX encoding = utf-8
4 % !TeX spellcheck = en_US
5 %<*internal>
6 \begingroup
7 %</internal>
8 %<*install>
9 \input{l3docstrip.tex}
10 \keepsilent
11 \askforoverwritefalse
12 \preamble
13 ----------------------------------------------------------------
14
15 xpeek: Define commands that peek ahead in the input stream
16
17 Copyright © 2012 by Joel C. Salomon.
18
19 This work consists of the file xpeek.dtx,
20 and the derived files xpeek.ins,
21 xpeek.pdf, &
22 xpeek.sty.
23 It may be distributed and/or modified under the conditions of the
24 LaTeX Project Public License (LPPL), either version 1.3c of this
25 license or (at your option) any later version. The latest version
26 of this license is at ‹http://www.latex-project.org/lppl.txt›.
27
28 This work is “maintained” (per LPPL maintenance status) by
29 Joel C. Salomon ‹[email protected]›.
30
31 ----------------------------------------------------------------
32 \endpreamble
33 \declarepreamble\minimalpreamble
34 \endpreamble
35 \postamble
36 \endpostamble
37 \usedir{tex/latex/xpeek}
38 \generate{
39 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
40 }
41 \nopreamble\nopostamble
42 \generate{
43 \file{\jobname.tests}{\from{\jobname.dtx}{tests}}
44 }
45 \generate{
46 \file{\jobname-test.tex}{\from{\jobname.dtx}{testsuite,tests}}
47 }
48 %</install>
49 %<install>\endbatchfile
50 %<*internal>
51 \usepreamble\minimalpreamble
52 \usepostamble\defaultpostamble
53 \usedir{source/latex/xpeek}
54 \generate{
55 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
56 }
57 \endgroup
58 %</internal>
59 %<*driver>
60 \pdfobjcompresslevel=0
61 \RequirePackage[utf8]{inputenc}
62 \documentclass[full]{l3doc}
63 \usepackage{xpeek}
64 \usepackage{xspace}
65 \usepackage[all]{foreign}
66 \usepackage{qstest}
67
68 ^^A Set up formatting options
69
70 ^^A Format URLs surrounded by guillemets
71 \DeclareUrlCommand\url
72 {\def\UrlLeft##1\UrlRight{\text{‹}\href{##1}{##1}\text{›}}}
73 \DeclareUrlCommand\email
74 {\def\UrlLeft##1\UrlRight{\text{‹}\href{mailto:##1}{##1}\text{›}}}
75 \urlstyle{same}
76
77 ^^A Make Unicode curly quotes (“”) behave correctly
78 \AtBeginDocument{
79 \sfcode\csname\encodingdefault\string\textquotedblright\endcsname=0
80 }
81 \xspaceaddexceptions{”}
82
83 ^^A Define indented verbatim environment
84 \DefineVerbatimEnvironment{IVerbatim}{Verbatim}%
85 {xleftmargin=2.5\rmemwidth, gobble=4}
86 \newlength\rmemwidth
87 \AtBeginDocument{
88 \setlength\rmemwidth{\fontdimen6\font}
89 }
90
91 ^^A Enable line continuations in `syntax` environments
92 \NewDocumentCommand \fixsyntaxlines {}
93 {\def\^^M{\unskip\space\ignorespaces}}
94
95 \begin{document}
96 \DocInput{\jobname.dtx}
97 \end{document}
98 %</driver>
99 % \fi
100 %
101 % \changes{Version 0.1}{2012/08/09}{First useful version}
102 %
103 % \GetFileInfo{\jobname.sty}
104 %
105 % \DoNotIndex
106 % {
107 % \ProvidesExplPackage, \RequirePackage, \NewDocumentCommand,
108 % \ExplSyntaxOn, \ExplSyntaxOff
109 % \documentclass, \usepackage,
110 % \begin, \end,
111 % \xspace,
112 % \bool_new:N, \bool_set_true:N, \bool_set_false:N, \bool_if:NTF,
113 % \hbox_set:Nn, \box_wd:N, \l_tmpa_box, \l_tmpb_box,
114 % \cs_new_protected:Npn,
115 % \dim_use:N,
116 % \peek_after:Nw,
117 % \prg_new_protected_conditional:Npnn,
118 % \prg_return_true:, \prg_return_false:,
119 % \tl_new:N, \tl_clear:N, \tl_const:Nn, \tl_set:Nn,
120 % \tl_put_right:Nn,
121 % \tl_map_inline:Nn, \tl_map_break:,
122 % \c_empty_tl,
123 % \token_if_eq_charcode:NNT,
124 % \xsp, \c_xsp_exceptions_tl,
125 % }
126 %
127 % \NewDocumentCommand \releasenote {}
128 % {This file describes release \fileversion, last revised \filedate.}
129 % \title{The \pkg{\jobname} package\thanks\releasenote}
130 %
131 % \urldef{\urlxthinsp}{\url}{http://tex.stackexchange.com/a/59542/2966}
132 % \urldef{\urlxflw}{\url}{http://tex.stackexchange.com/q/63568/2966}
133 % \urldef{\urlxign}{\url}{http://tex.stackexchange.com/q/63971/2966}
134 % \urldef{\urlltxl}
135 % {\url}{http://thread.gmane.org/gmane.comp.tex.latex.latex3/2894}
136 % \NewDocumentCommand \acknote {}
137 % {The original code is due to Enrico “egreg” Gregorio,
138 % based on an answer he gave to a question of mine on
139 % \href{http://tex.stackexchange.com}{\TeX.SX};
140 % see \urlxthinsp.
141 % Enrico, Joseph Wright, Bruno Le Floch, \& Clemens Niederberger
142 % helped iron out the implementation;
143 % Bruno also wrote the initial version of the documentation
144 % and the near-final version of much of the code.
145 % See \urlxflw, \urlxign, \& \urlltxl.}
146 % \author{Joel C. Salomon\\\email{[email protected]}\thanks\acknote}
147 % \date{Released \filedate}
148 %
149 % \maketitle
150 %
151 % \begin{abstract}
152 % The \pkg{\jobname} package provides functions
153 % for defining \& managing commands which,
154 % like the familiar \cs{xspace},
155 % “peek” ahead at what follows them in the input stream.
156 % They compare this token against a stored list
157 % and choose an action depending on whether there was a match.
158 % \end{abstract}
159 %
160 % \tableofcontents
161 %
162 % \begin{documentation}
163 %
164 % \section{Introduction}
165 %
166 % This package provides functions for defining \cs{xspace}-like commands.
167 % Such commands “peek” ahead into the input stream
168 % to see what follows their invocations;
169 % their behavior varies depending on what it is that comes next.
170 %
171 % Probably the most common \LaTeX\ command of this sort is \cs{textit}.
172 % It looks ahead at the token following its argument
173 % and decides whether to insert italic correction afterward.
174 % Table~\ref{tab:itcor} compares the use of \cs{textit}
175 % against using the font-switch command \cs{itshape}
176 % with \& without explicit italic correction.
177 % \begin{table}[hbp]\centering
178 % \begin{tabular}{|lll|}
179 % \hline
180 % |{\itshape half}hearted| &
181 % {\itshape half}hearted &
182 % (overlap)\\
183 % |{\itshape half\/}hearted| &
184 % {\itshape half\/}hearted &
185 % (correct)\\
186 % |\textit{half}hearted| &
187 % \textit{half}hearted &
188 % (correctly including italic correction)\\
189 % ^^A There’s a bug in the package `trace` which breaks suppression
190 % ^^A of italic correction; see latex3/svn-mirror#96 for details.
191 % ^^A As a temporary work-around, include `\nocorr` where needed.
192 % |by {\itshape half}.| &
193 % by {\itshape half}. &
194 % (correct)\\
195 % |by {\itshape half\/}.| &
196 % by {\itshape half\/}. &
197 % (too wide)\\
198 % |by \textit{half}.| &
199 % by \textit{half\nocorr}. &
200 % (correctly omitting italic correction)\\
201 % \hline
202 % \end{tabular}
203 % \caption{Automatic italic correction with \cs{textit}}
204 % \label{tab:itcor}
205 % \end{table}
206 % Notice how \cs{textit} seems to just “do the right thing”
207 % when it comes to inserting or omitting italic correction.
208 %
209 % It is, unfortunately, not hard to confuse \cs{textit}.
210 % As an example, consider the following code:
211 % \begin{IVerbatim}
212 % \NewDocumentCommand \naif {} {\textit{na\"\i f}}
213 % He was a true \naif.
214 % \end{IVerbatim}
215 % This yields
216 % \begin{quote}
217 % \NewDocumentCommand \naif {} {\textit{na\"\i f\nocorr}}
218 % He was a true \naif.
219 % \end{quote}
220 % So far, so good.
221 % But using this macro in middle of a sentence
222 % may produce results the naïve user does not expect.
223 % For example, try
224 % \begin{IVerbatim}
225 % He was such a \naif he expected this example to work.
226 % \end{IVerbatim}
227 % yielding
228 % \begin{quote}
229 % \NewDocumentCommand \naif {} {\textit{na\"\i f}}
230 % He was such a \naif he expected this example to work.
231 % \end{quote}
232 % Oops.
233 % We forgot that command words eat the spaces that follow them.
234 %
235 % This is usually the point where \TeX perts explain
236 % about following command words with explicit spaces,
237 % \eg, writing “|such a \naif\ he |…”,
238 % or following such commands with an empty group,
239 % “|such a \naif{} he |…”, \eg.
240 %
241 % Others, more pragmatically-inclined,
242 % will mention the \pkg{xspace} package.
243 % This is the sort of use-case it was developed for, after all,
244 % so let’s try it:
245 % \begin{IVerbatim}
246 % \NewDocumentCommand \naif {} {\textit{na\"\i f}\xspace}
247 % He was such a \naif he expected this example to work.
248 % \end{IVerbatim}
249 % This produces
250 % \begin{quote}
251 % \NewDocumentCommand \naif {} {\textit{na\"\i f}\xspace}
252 % He was such a \naif he expected this example to work.
253 % \end{quote}
254 % Even “such a \foreign{naïf}” can get the right result sometimes.
255 %
256 % But you see, there’s a kinda hitch.^^A
257 % \footnote{Cue Malcolm Reynolds: “Don’t complicate things.”}
258 % Recall the first time we used the macro:
259 % \begin{IVerbatim}
260 % He was a true \naif.
261 % \end{IVerbatim}
262 % Now it yields this:
263 % \begin{quote}
264 % \NewDocumentCommand \naif {} {\textit{na\"\i f}\xspace}
265 % He was a true \naif.
266 % \end{quote}
267 % Notice that ugly space between the \textit{f} and the period?
268 % That’s italic correction being added where it doesn’t belong.
269 %
270 % The trouble lies in how \LaTeX\ implements the \cs{textit} logic.
271 % The macro is clever enough to look ahead,
272 % seeking for short punctuation (\eg, the comma \& period)
273 % which should not be preceded by italic correction.
274 % What the macro finds first, though,
275 % is that invocation of \cs{xspace} we added.
276 % That’s not one of the “no italic correction” tokens,
277 % so the correction gets added and the sentence looks ugly.
278 %
279 % That’s where this package comes in.
280 %
281 % (As a side note, Phillip G. Ratcliffe’s \pkg{foreign} package,
282 % bundled with both MiK\TeX\ and \TeX~Live
283 % and available from CTAN at \url{http://ctan.org/pkg/foreign},
284 % is an excellent tool for this sort of foreign-word macro
285 % and was one of the inspirations for this package.)
286 %
287 % Commands generated via the tools the \pkg{xpeek} package provides
288 % can peek ahead in the input stream,
289 % like \cs{textit} and \cs{xspace},
290 % checking whether the next token is on their match-list.
291 % What \pkg{xpeek} adds is
292 % the ability to ignore certain tokens during that peek-ahead.
293 % These ignored tokens are not lost;
294 % the scan-ahead routine saves them
295 % and they are restored when the command executes.
296 %
297 % \section{Documentation}
298 %
299 % At this point in the development of \pkg{xpeek},
300 % only one set of follower-dependent functions is defined.
301 % Later versions will provide tools for defining such function sets.
302 %
303 % \subsection{Match- \& Ignore-Lists}
304 %
305 % \begin{variable}{\g_xpeek_matchlist_tl, \g_xpeek_ignorelist_tl}
306 % \begin{syntax}
307 % \cs{tl_gput_right:Nn} \cs{g_xpeek_\meta{list}_tl} \Arg{tokens}
308 % \cs{tl_gremove_all:Nn} \cs{g_xpeek_\meta{list}_tl} \Arg{tokens}
309 % \end{syntax}
310 % These two token-lists are the heart of \pkg{xpeek}.
311 %
312 % The \textit{match-list} is similar to \pkg{xspace}’s exceptions list
313 % or \LaTeX’s \cs{nocorrlist} list for suppressing italic correction.
314 %
315 % The functionality enabled by the \emph{ignore-list},
316 % on the other hand,
317 % is the \foreign{raison d’être} of this package.
318 % For example,
319 % if \LaTeX’s \cs{textit} had an ignore-list
320 % and the token \cs{xspace} were in that list,
321 % then the definition
322 % \begin{IVerbatim}[gobble=6]
323 % \NewDocumentCommand \naif {} {\textit{na\"\i f}\xspace}
324 % \end{IVerbatim}
325 % from the example above
326 % would have worked properly:
327 % \cs{textit} would have ignored the \cs{xspace},
328 % looked past it \& seen the period,
329 % and therefore omitted italic correction.
330 % When that was done, \cs{xspace} would execute;
331 % it too would see the period,
332 % and therefore would not insert a space.
333 % \end{variable}
334 %
335 % \subsection{Peek-ahead}
336 %
337 % \begin{function}{\xpeek_after:nw}
338 % \begin{syntax}
339 % \cs{xpeek_after:nw} \Arg{code} \meta{token}
340 % \end{syntax}
341 % Similar to \pkg{expl3}’s \cs{peek_after:Nw},
342 % this sets the test variable \cs{l_peek_token} to \meta{token}
343 % then executes the \Arg{code}.
344 % The \meta{token} remains in the input stream.
345 % \end{function}
346 %
347 % \subsection{Collecting Ignored Tokens}
348 %
349 % \begin{function}{\xpeek_collect_do:nn}
350 % \begin{syntax}\fixsyntaxlines
351 % \cs{xpeek_collect_do:nn} \Arg{ignore-list} \Arg{operation} \
352 % \meta{the rest of the input-stream}
353 % \end{syntax}
354 % This collects all leading tokens in the input stream
355 % which are in the ignore-list,
356 % and passes them as an argument to the operation.
357 % For example, the invocation
358 % \begin{IVerbatim}[gobble=6]
359 % \xpeek_collect_do:nn { abc } { \foo \bar } caada
360 % \end{IVerbatim}
361 % will collect the leading “\texttt{caa}” from the input stream
362 % and pass those tokens as an argument to
363 % the operation “|\foo \bar|”.
364 % \Ie, the code above is equivalent to this:
365 % \begin{IVerbatim}[gobble=6]
366 % \foo \bar { caa } da
367 % \end{IVerbatim}
368 % (Note that it’s \cs{bar} \emph{within} the \Arg{operation}
369 % that gets the collected tokens as an argument.)
370 % \end{function}
371 %
372 % \subsection{Searching Through Token-Lists}
373 %
374 % \begin{function}{\xpeek_if_in:NNTF}
375 % \begin{syntax}\fixsyntaxlines
376 % \cs{xpeek_if_in:NNTF} \cs{\meta{haystack}} \cs{\meta{needle}} \
377 % \Arg{true-code} \Arg{false-code}
378 % \end{syntax}
379 % Among the variants of \cs{tl_if_in:Nn(TF)} defined in \pkg{expl3},
380 % the form \cs{tl_if_in:NNTF} is missing.
381 % But that’s the form needed in this package,
382 % in constructions like this:
383 % \begin{IVerbatim}[gobble=6, commandchars=+\[\]]
384 % \xpeek_if_in:NNTF \g_xpeek_matchlist_tl \l_peek_token
385 % +marg[true-code] +marg[false-code]
386 % \end{IVerbatim}
387 % So we define it ourselves.
388 % \end{function}
389 %
390 % \section{Example}
391 %
392 % As a demonstration,
393 % here’s an example of using the \pkg{xpeek} facilities
394 % to implement correct automatic italic correction \ala \cs{textit}.
395 %
396 % We set the match-list equal to \LaTeX’s default \cs{nocorrlist};
397 % as mentioned above, \cs{xspace} needs to be in the ignore-list:
398 % \begin{IVerbatim}
399 % \tl_gset:Nn \g_xpeek_matchlist_tl { , . }
400 % \tl_gset:Nn \g_xpeek_ignorelist_tl { \xspace }
401 % \end{IVerbatim}
402 % (Note that this does not require \cs{xspace} to be defined;
403 % it merely ensure that
404 % the macro will work correctly
405 % if it is defined.)
406 %
407 % Next, we declare the new italicization command \cs{xit}.
408 % It calls \cs{xpeek_collect_do:nn} to collect
409 % any instances of \cs{xspace} that might follow the invocation.
410 % These are saved, but ignored for the time being.
411 %
412 % It’s within the \Arg{code} argument to \cs{xpeek_collect_do:nn},
413 % between \cs{group_begin:} and \cs{group_end:},
414 % that the italicization happens.
415 % Before we return to the default font, though,
416 % the code checks whether \cs{l_peek_token} is in the ignore-list;
417 % it then decides whether to include italic correction.
418 %
419 % Recall next that the last command within the \Arg{code}
420 % is what will get the collected tokens as an argument.
421 % Since we want to keep \cs{xspace} if it’s there,
422 % we finish up the code with \cs{use:n},
423 % which simply puts its argument into the input stream.
424 %
425 % Here’s the code:
426 % \begin{IVerbatim}
427 % \NewDocumentCommand \xit {m}
428 % {
429 % \xpeek_collect_do:nn \g_xpeek_ignorelist_tl
430 % {
431 % \group_begin:
432 % \itshape #1
433 % \xpeek_if_in:NNTF \g_xpeek_matchlist_tl \l_peek_token
434 % { } { \/ }
435 % \group_end:
436 % \use:n
437 % }
438 % }
439 % \end{IVerbatim}
440 %
441 % Finally, define the command we tried to make work in the introduction,
442 % and see whether we’ve made it work:
443 % \begin{IVerbatim}
444 % \NewDocumentCommand \naif {} {\xit{na\"\i f}\xspace}
445 % He was a true \naif.
446 % He was such a \naif he expected this example to work.
447 % \end{IVerbatim}
448 % The code above yields this result:
449 % \begin{quote}
450 % \ExplSyntaxOn
451 % \tl_gset:Nn \g_xpeek_matchlist_tl { , . }
452 % \tl_gset:Nn \g_xpeek_ignorelist_tl { \xspace }
453 % \NewDocumentCommand \xit {m}
454 % {
455 % \xpeek_collect_do:nn \g_xpeek_ignorelist_tl
456 % {
457 % \group_begin:
458 % \itshape #1
459 % \xpeek_if_in:NNTF \g_xpeek_matchlist_tl \l_peek_token
460 % { } { \/ }
461 % \group_end:
462 % \use:n
463 % }
464 % }
465 % \ExplSyntaxOff
466 % \NewDocumentCommand \naif {} {\xit{na\"\i f}\xspace}
467 % He was a true \naif.
468 % He was such a \naif he expected this example to work.
469 % \end{quote}
470 % And work it does.
471 %
472 % \end{documentation}
473 %
474 % \begin{implementation}
475 %
476 % \section{\pkg{\jobname} Implementation}
477 %
478 % \begin{macrocode}
479 %<*package>
480 % \end{macrocode}
481 %
482 % \begin{macrocode}
483 %<@@=xpeek>
484 % \end{macrocode}
485 %
486 % \begin{macrocode}
487 \RequirePackage{expl3, xparse}
488 % \end{macrocode}
489 %
490 % \begin{macrocode}
491 \ProvidesExplPackage
492 {xpeek} {2012/08/15} {0.2}
493 {Define commands that peek ahead in the input stream}
494 % \end{macrocode}
495 %
496 % \subsection{Match- \& Ignore-Lists}
497 %
498 % \begin{variable}{\g_xpeek_matchlist_tl, \g_xpeek_ignorelist_tl}
499 % Define the lists.
500 % \begin{macrocode}
501 \tl_new:N \g_xpeek_matchlist_tl
502 \tl_new:N \g_xpeek_ignorelist_tl
503 % \end{macrocode}
504 % \end{variable}
505 %
506 % \subsection{Peek-ahead}
507 %
508 % \begin{macro}[internal]{\xpeek_after:nw}
509 % \begin{variable}[aux]{\l_@@_code_tl}
510 % Define a function (AKA “token-list”) to hold the code passed in.
511 % \begin{macrocode}
512 \tl_new:N \l_@@_code_tl
513 % \end{macrocode}
514 % Store the argument in \cs{l_@@_code_tl},
515 % then defer to \cs{peek_after:Nw}
516 % \begin{macrocode}
517 \cs_new_protected:Npn \xpeek_after:nw #1
518 {
519 \tl_set:Nn \l_@@_code_tl {#1}
520 \peek_after:Nw \l_@@_code_tl
521 }
522 % \end{macrocode}
523 % \end{variable}
524 % \end{macro}
525 %
526 % \subsection{Collecting Ignored Tokens}
527 %
528 % \begin{macro}{\xpeek_collect_do:nn}
529 % \begin{macro}[aux]{\@@_collect_do:nnn}
530 % \begin{variable}[aux]{\l_@@_collected_tokens_tl}
531 % \begin{arguments}
532 % \item Tokens to collect from the input stream
533 % \item The operation to be performed on the collected tokens
534 % \item The next token on the input stream
535 % (for \cs{@@_collect_do:nnn}).
536 % \end{arguments}\noindent
537 % Define a list to save collected tokens in.
538 % \begin{macrocode}
539 \tl_new:N \l_@@_collected_tokens_tl
540 % \end{macrocode}
541 % Clear list and defer to auxiliary function.
542 % \begin{macrocode}
543 \cs_new_protected:Npn \xpeek_collect_do:nn #1#2
544 {
545 \tl_clear:N \l_@@_collected_tokens_tl
546 \@@_collect_do:nnn {#1} {#2} {}
547 }
548 % \end{macrocode}
549 % Recursively consume tokens from the input stream
550 % so long as they match the collect-list,
551 % then apply the operation to the collected tokens.
552 % The last matching token will not yet have been collected,
553 % so pass it to the operation as well.
554 % (If there were no matching tokens,
555 % |#3| will be the empty argument
556 % that was passed by \cs{xpeek_collect_do:nn}.)
557 % \begin{macrocode}
558 \cs_new_protected:Npn \@@_collect_do:nnn #1#2#3
559 {
560 \xpeek_after:nw
561 {
562 \xpeek_if_in:NNTF #1 \l_peek_token
563 {
564 \tl_put_right:Nn \l_@@_collected_tokens_tl {#3}
565 \@@_collect_do:nnn {#1} {#2}
566 }
567 {
568 #2 { \l_@@_collected_tokens_tl #3 }
569 }
570 }
571 }
572 % \end{macrocode}
573 % \end{variable}
574 % \end{macro}
575 % \end{macro}
576 %
577 % \subsection{Searching Through Token-Lists}
578 %
579 % \begin{macro}{\xpeek_if_in:NNTF}
580 % \begin{variable}[aux]{\l_@@_bool}
581 % \begin{arguments}
582 % \item Token-list to search through (the “haystack”)
583 % \item Token to search for (the “needle”)
584 % \end{arguments}\noindent
585 % Define an internal flag.
586 % \begin{macrocode}
587 \bool_new:N \l_@@_bool
588 % \end{macrocode}
589 % Map the “haystack”, searching for the “needle”.
590 % \begin{macrocode}
591 \prg_new_protected_conditional:Npnn \xpeek_if_in:NN #1#2 { TF }
592 {
593 \bool_set_false:N \l_@@_bool
594 \tl_map_inline:Nn #1
595 {
596 \token_if_eq_charcode:NNT #2 ##1
597 {
598 \bool_set_true:N \l_@@_bool
599 \tl_map_break:
600 }
601 }
602 \bool_if:NTF \l_@@_bool
603 { \prg_return_true: } { \prg_return_false: }
604 }
605 % \end{macrocode}
606 % \end{variable}
607 % \end{macro}
608 %
609 % \begin{macrocode}
610 %</package>
611 % \end{macrocode}
612 %
613 % \section{Test Suite}
614 %
615 % \changes{Version 0.2}{2012/08/15}{Added test-suite}
616 %
617 % ^^A Reset line numbers in code listings
618 % \makeatletter
619 % \c@CodelineNo 0
620 % \makeatother
621 %
622 % The test suite below is run automatically
623 % when this document is produced.
624 % It can also be run separately by executing
625 % \begin{IVerbatim}[commandchars=+\[\]]
626 % latex +jobname-test
627 % \end{IVerbatim}
628 % at the command prompt.
629 %
630 % \input{\jobname.tests}
631 %
632 % \begin{macrocode}
633 %<testsuite>\documentclass{article}
634 %<testsuite>\usepackage{xparse, expl3, xpeek, qstest}
635 %<testsuite>\begin{document}
636 %<*tests>
637 % \end{macrocode}
638 %
639 % \subsection{Set-Up: Wrapping \cs{Expect}}
640 %
641 % \begin{macro}[internal]{\ExpectIdenticalWidths}
642 % Since the commands \pkg{xpeek} helps produce are not expandable,
643 % directly comparing their outputs is not feasible.
644 % Instead, typeset two versions into boxes
645 % and have \pkg{qstest} compare these boxes’ widths.
646 % (Thanks to Heiko Oberdiek for this technique;
647 % see \url{http://tex.stackexchange.com/q/67192/2966}.)
648 % \begin{macrocode}
649 \ExplSyntaxOn
650 \NewDocumentCommand \ExpectIdenticalWidths { m m }
651 {
652 \hbox_set:Nn \l_tmpa_box {#1}
653 \hbox_set:Nn \l_tmpb_box {#2}
654 \Expect
655 * {\dim_use:N \box_wd:N \l_tmpa_box}
656 * {\dim_use:N \box_wd:N \l_tmpb_box}
657 }
658 \ExplSyntaxOff
659 % \end{macrocode}
660 % \end{macro}
661 %
662 % \subsection{Emulating \cs{xspace}}
663 %
664 % Define a simple analogue to \cs{xspace}.
665 % \begin{macrocode}
666 \ExplSyntaxOn
667 \tl_const:Nn \c_xsp_exceptions_tl { ,;:.!? }
668 \NewDocumentCommand \xsp {}
669 {
670 \xpeek_collect_do:nn \c_empty_tl
671 {
672 \xpeek_if_in:NNTF \c_xsp_exceptions_tl \l_peek_token
673 { } { ~ }
674 }
675 }
676 \ExplSyntaxOff
677 % \end{macrocode}
678 % Test \cs{xsp}, ensuring that it is space-factor–agnostic.
679 % \begin{macrocode}
680 \begin{qstest}{Emulating \xspace}{xpeek}
681 \ExpectIdenticalWidths{foo bar}{foo\xsp bar}
682 \ExpectIdenticalWidths{foo. bar}{foo\xsp. bar}
683 \ExpectIdenticalWidths{FOO. bar}{FOO\xsp. bar}
684 \ExpectIdenticalWidths{foo. bar}{foo.\xsp bar}
685 \ExpectIdenticalWidths{FOO. bar}{FOO.\xsp bar}
686 \end{qstest}
687 % \end{macrocode}
688 %
689 % \begin{macrocode}
690 %</tests>
691 %<testsuite>\end{document}
692 % \end{macrocode}
693 % N.B\@. The stand-alone test-suite will not produce any output,
694 % only a log file.
695 %
696 % \end{implementation}
697 %
698 % \PrintChanges
699 %
700 % \PrintIndex