Debian Codegraph @

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

raw
1 %\iffalse
2 % xfor.dtx generated using makedtx version 0.94b (c) Nicola Talbot
3 % Command line args:
4 % -src "xfor.sty\Z=>xfor.sty"
5 % -src "sample.tex\Z=>sample.tex"
6 % -doc "xfor-manual.tex"
7 % -author "Nicola Talbot"
8 % -dir "source"
9 % xfor
10 % Created on 2009/2/5 16:02
11 %\fi
12 %\iffalse
13 %<*package>
14 %% \CharacterTable
15 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
16 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
17 %% Digits \0\1\2\3\4\5\6\7\8\9
18 %% Exclamation \! Double quote \" Hash (number) \#
19 %% Dollar \$ Percent \% Ampersand \&
20 %% Acute accent \' Left paren \( Right paren \)
21 %% Asterisk \* Plus \+ Comma \,
22 %% Minus \- Point \. Solidus \/
23 %% Colon \: Semicolon \; Less than \<
24 %% Equals \= Greater than \> Question mark \?
25 %% Commercial at \@ Left bracket \[ Backslash \\
26 %% Right bracket \] Circumflex \^ Underscore \_
27 %% Grave accent \` Left brace \{ Vertical bar \|
28 %% Right brace \} Tilde \~}
29 %</package>
30 %\fi
31 % \iffalse
32 % Doc-Source file to use with LaTeX2e
33 % Copyright (C) 2009 Nicola Talbot, all rights reserved.
34 % \fi
35 % \iffalse
36 %<*driver>
37 \documentclass[a4paper]{ltxdoc}
38 \usepackage{xfor}
39 \usepackage{ifthen}
40 \usepackage{alltt}
41 \usepackage[colorlinks,
42 bookmarks,
43 hyperindex=false,
44 pdfauthor={Nicola L.C. Talbot},
45 pdftitle={xfor: redefinition of \string\@for},
46 pdfkeywords={LaTeX,package development}]{hyperref}
47
48 \CheckSum{197}
49 \PageIndex
50 \RecordChanges
51 \newcommand*{\sty}[1]{\textsf{#1}}
52
53 \begin{document}
54 \DocInput{xfor.dtx}
55 \end{document}
56 %</driver>
57 %\fi
58 %\MakeShortVerb{"}
59 %
60 % \title{xfor v1.05: Reimplementation of \cs{@for} to allow
61 %premature termination of the loop}
62 % \author{Nicola L.C. Talbot\\[10pt]
63 %School of Computing Sciences\\
64 %University of East Anglia\\
65 %Norwich. Norfolk\\
66 %NR4 7TJ. United Kingdom.\\
67 %\url{http://theoval.cmp.uea.ac.uk/~nlct/}}
68 %
69 %\date{5th February 2009}
70 %\maketitle
71 %\tableofcontents
72 %
73 %\section{Introduction}
74 %\changes{1.0}{2007 June 27}{Initial version}
75 %The \sty{xfor} package redefines \cs{@for} so that the loop can
76 %be prematurely terminated, akin to C/Java's \texttt{break} statement
77 %except that the loop will terminate at the \emph{end} of the
78 %current iteration. The syntax for \DescribeMacro{\@for}\cs{@for}
79 %remains the same:
80 %\begin{quote}
81 %\cs{@for}\meta{cmd}":="\meta{list}"\do"\marg{body}
82 %\end{quote}
83 %where \meta{cmd} is a command name that is assigned to the current
84 %element of the list given by \meta{list} at each iteration.
85 %
86 %To terminate the loop at the end of the current
87 %iteration, use the command \DescribeMacro{\@endfortrue}\cs{@endfortrue}.
88 %This command may be used anywhere in \meta{body}, but will only
89 %take effect at the end of the current iteration.
90 %The remainder of the list is stored in
91 %\DescribeMacro{\@forremainder}\cs{@forremainder}. You can test
92 %whether the loop was prematurely terminated using the conditional
93 %\DescribeMacro{\if@endfor}\cs{if@endfor}.
94 %
95 %As from version 1.02, there is also provision for looking ahead.
96 %At each iteration in the loop, the next element is stored in
97 %\cs{@xfor@nextelement}\DescribeMacro{\@xfor@nextelement}.
98 %On the last iteration, this value
99 %will be \cs{@nil}, and so can be checked using
100 %\begin{verbatim}
101 % \ifx\@xfor@nextelement\@nnil
102 % % last iteration
103 % \else
104 % % not last iteration
105 % \fi
106 %\end{verbatim}
107 %
108 %\subsection{Example (ordered insertion)}
109 %
110 %Suppose you have list of sorted numbers stored in the command
111 %\cs{mylist}, e.g.:
112 %\begin{verbatim}
113 %\def\mylist{1,3,5,7,8,12,15,20}
114 %\end{verbatim}
115 %and you want to insert a new value given by the command
116 %\cs{newval}, e.g.
117 %\begin{verbatim}
118 %\def\newval{11}
119 %\end{verbatim}
120 %in the correct order. You can use \cs{@for} to iterate through
121 %each element in the sorted list, testing the value against the
122 %new value to be inserted. Once the new value has been inserted,
123 %the loop can be terminated, and any remaining elements can be
124 %appended to the new list. The following
125 %defines the command \cs{insertinto}\marg{new val}\marg{list}
126 %which uses this method:
127 %\begin{verbatim}
128 % \newcommand{\insertinto}[2]{%
129 % \def\nlst{}% new list initially empty
130 % \@for\n:=#2\do{%
131 % % store new list in \toks@
132 % \expandafter\toks@\expandafter{\nlst}%
133 % % test current value against new value
134 % \ifnum\n>#1\relax
135 % % new value needs to be inserted before current value
136 % \edef\newstuff{\number#1,\n}%
137 % % end for loop at the end of this iteration
138 % \@endfortrue
139 % \else
140 % \edef\newstuff{\n}%
141 % \fi
142 % % append new stuff to new list
143 % \ifx\nlst\@empty
144 % \edef\nlst{\newstuff}%
145 % \else
146 % \edef\nlst{\the\toks@,\newstuff}%
147 % \fi
148 % }%
149 % % check to see if for loop was prematurely terminated
150 % \if@endfor
151 % % loop may have been terminated during final iteration, in
152 % % which case \@forremainder is empty.
153 % \ifx\@forremainder\@empty
154 % % do nothing
155 % \else
156 % % loop prematurely ended, append remainder of original list
157 % % to new list
158 % \expandafter\toks@\expandafter{\nlst}%
159 % \edef\nlst{\the\toks@,\@forremainder}%
160 % \fi
161 % \else
162 % % wasn't prematurely terminated, so new value hasn't been added
163 % % so add now.
164 % \expandafter\toks@\expandafter{\nlst}%
165 % \ifx\nlst\@empty
166 % \edef\nlst{\number#1}%
167 % \else
168 % \edef\nlst{\the\toks@,\number#1}%
169 % \fi
170 % \fi
171 % \let#2=\nlst
172 % }
173 %\end{verbatim}
174 %The \cs{insertinto} macro can then be used as follows:
175 %\begin{verbatim}
176 %\def\mylist{1,2,5,9,12,15,18,20}%
177 %\def\newval{11}%
178 %Original list: \mylist. New value: \newval.
179 %
180 %\insertinto{\newval}{\mylist}
181 %New list: \mylist.
182 %\end{verbatim}
183 %
184 %\subsection{Example (numerical insertion sort)}
185 %
186 %Care needs to be taken when nesting \cs{@for}-loops.
187 %Suppose you have a list of unsorted numbers, say
188 %\begin{verbatim}
189 %\def\mylist{4,2,7,1,10,11,20,15}
190 %\end{verbatim}
191 %and you want to sort the list in numerical order using an insertion
192 %sort method. To do this, a macro needs to be defined which iterates
193 %through each element in the unordered list, and the element
194 %is then inserted into an ordered list. The previous example
195 %described the macro \cs{insertinto} which does this, but this results
196 %in nested \cs{@for} commands. The \cs{insertinto} command will need
197 %to be grouped to avoid errors:
198 %\begin{verbatim}
199 %\newcommand*{\insertionsort}[1]{%
200 %\def\sortedlist{}%
201 %\@for\val:=#1\do{{\insertinto{\val}{\sortedlist}}}%
202 %\let#1=\sortedlist
203 %}
204 %\end{verbatim}
205 %This won't work with the definition of \cs{insertinto} as
206 %given in the previous section, as the grouping causes the
207 %definition of the sorted list to be localised to that group.
208 %Replacing
209 %\begin{verbatim}
210 %\let#2=\nlst
211 %\end{verbatim}
212 %with
213 %\begin{verbatim}
214 %\global\let#2=\nlst
215 %\end{verbatim}
216 %at the end of the definition of \cs{insertinto} will fix that.
217 %
218 %\subsection{Example (looking ahead)}
219 %
220 %This example checks the next value to determine if the loop
221 %is on the last iteration, if it is, it does nothing, otherwise
222 %it does a semi-colon:
223 %\begin{verbatim}
224 %\makeatletter
225 %\def\mylist{1,2,3,4,5}%
226 %\@for\val:=\mylist\do{\val
227 %\ifx\@xfor@nextelement\@nnil \else ;\fi}
228 %\makeatother
229 %\end{verbatim}
230 %which produces:
231 %\makeatletter
232 %\def\mylist{1,2,3,4,5}\relax
233 %\@for\val:=\mylist\do{\val
234 %\ifx\@xfor@nextelement\@nnil \else ;\fi}
235 %\makeatother
236 %
237 %\section{Acknowledgements}
238 %
239 %Many thanks to Morten~H\o gholm for providing code to improve
240 %efficiency.
241 %
242 % \StopEventually{\phantomsection
243 %\addcontentsline{toc}{section}{Change History}
244 %\PrintChanges\phantomsection
245 %\addcontentsline{toc}{section}{Index}
246 %\PrintIndex}
247 %
248 %
249 %
250 %\section{The Code}
251 %\iffalse
252 % \begin{macrocode}
253 %<*xfor.sty>
254 % \end{macrocode}
255 %\fi
256 % Note that the internal macros used by \cs{@for} have changed
257 % in version 1.04.
258 %
259 % \begin{macrocode}
260 \NeedsTeXFormat{LaTeX2e}
261 \ProvidesPackage{xfor}[2009/02/05 v1.05 (NLCT)]
262 % \end{macrocode}
263 %\begin{macro}{\if@endfor}
264 % Define a switch to determine if the for loop should be
265 % stopped prematurely.
266 % \begin{macrocode}
267 \newif\if@endfor
268 % \end{macrocode}
269 %\end{macro}
270 %\begin{macro}{\@gobbleseven}
271 %\changes{1.04}{2009 January 25}{added by Morten H\o gholm}
272 % Ignore seven arguments.
273 % \begin{macrocode}
274 \long\def\@gobbleseven#1#2#3#4#5#6#7{}
275 % \end{macrocode}
276 %\end{macro}
277 %\begin{macro}{\@for}
278 % \cs{@for}\meta{cmd}":="\meta{list}\cs{do}\marg{body}
279 % test if the list is empty and then re-arrange
280 %\changes{1.04}{2009 January 25}{Modified by Morten H\o gholm to
281 % improve efficiency}
282 % \begin{macrocode}
283 \long\def\@for#1:=#2\do{%
284 % \end{macrocode}
285 % Initialise
286 % \begin{macrocode}
287 \@endforfalse
288 \def\@forremainder{}%
289 \expandafter\def\expandafter\@fortmp\expandafter{#2}%
290 % \end{macrocode}
291 % If list is empty do nothing
292 % \begin{macrocode}
293 \ifx\@fortmp\@empty
294 \expandafter\@gobbleseven
295 \fi
296 \expandafter\@@for\expandafter#1\expandafter{#2}%
297 }
298 % \end{macrocode}
299 %\end{macro}
300 %
301 %\begin{macro}{\@@for}
302 % Initialise for loop
303 %\changes{1.04}{2009 January 25}{Added by Morten H\o gholm}
304 % \begin{macrocode}
305 \long\def\@@for#1#2#3{%
306 \@xforloop#1{#3}#2,\@nil,\@nil,%
307 \@xfor@endmarker% magic end marker
308 }
309 % \end{macrocode}
310 %\end{macro}
311 %
312 %\begin{macro}{\@xfornoop}
313 %\changes{1.04}{2009 January 25}{second and third arguments dropped (MH)}
314 %\changes{1.04}{2009 January 25}{\cs{@fornoop} replaced by
315 % \cs{@xfornoop} to prevent conflict with \cs{@tfor}}
316 % Read up until magic end marker.
317 % \begin{macrocode}
318 \long\def\@xfornoop#1\@xfor@endmarker{}
319 % \end{macrocode}
320 %\end{macro}
321 %\begin{macro}{\@xforloop}
322 %\cs{@forloop}\marg{var}\marg{action}
323 %\changes{1.04}{2009 January 25}{Modified by Morten H\o gholm to
324 % improve efficiency}
325 %\changes{1.05}{2009 February 5}{\cs{@forloop} replaced by
326 % \cs{@xforloop} to prevent conflict with other packages that
327 % use \cs{@forloop}}
328 % \begin{macrocode}
329 \long\def\@xforloop#1#2#3,#4,{%
330 \def#1{#3}%
331 \ifx#1\@nnil
332 % \end{macrocode}
333 % Grab the \cs{@xfor@endmarker} at the very end
334 % \begin{macrocode}
335 \expandafter\@xfornoop
336 \fi
337 % \end{macrocode}
338 % Removed |\@xfor@storenext#4,\@nil|. Instead store next element
339 % in \cs{@xfor@nextelement}.
340 % \begin{macrocode}
341 \def\@xfor@nextelement{#4}%
342 #2%
343 \if@endfor
344 \expandafter\@iforgatherrest
345 \fi
346 \@xforloop#1{#2}{#4},%
347 }
348 % \end{macrocode}
349 %\end{macro}
350 %
351 %\begin{macro}{\@iforgatherrest}
352 % Gather the remainder (and store in \cs{@forremainder})
353 %\changes{1.01}{2007 July 11}{made long}%
354 %\changes{1.04}{2009 January 25}{argument syntax changed (MH)}
355 % \begin{macrocode}
356 \long\def\@iforgatherrest \@xforloop#1#2#3,#4\@xfor@endmarker{%
357 \def\@fortmp{#3}%
358 \ifx\@fortmp\@nnil
359 \def\@forremainder{}%
360 \else
361 \@forgatherrest{#3},#4\@xfor@endmarker%
362 \fi
363 }
364 % \end{macrocode}
365 %\end{macro}
366 %
367 %\begin{macro}{\@forgatherrest}
368 % Get remainder of list (stored in \cs{@forremainder}):
369 %\changes{1.01}{2007 July 11}{made long}%
370 %\changes{1.04}{2009 January 25}{argument syntax changed (MH)}
371 % \begin{macrocode}
372 \long\def\@forgatherrest#1,\@nil,\@nil,\@xfor@endmarker{%
373 \def\@forremainder{#1}%
374 }
375 % \end{macrocode}
376 %\end{macro}
377 %
378 %\changes{1.02}{2007 August 16}{Added \cs{@xfor@storenext}}%
379 %\changes{1.04}{2009 January 25}{Removed \cs{\@xfor@storenext}}%
380 %\changes{1.04}{2009 January 25}{removed \cs{@iforloop}}
381
382 %\iffalse
383 % \begin{macrocode}
384 %</xfor.sty>
385 % \end{macrocode}
386 %\fi
387 %\iffalse
388 % \begin{macrocode}
389 %<*sample.tex>
390 % \end{macrocode}
391 %\fi
392 %\section{Sample Document (sample.tex)}
393 % \begin{macrocode}
394 \listfiles
395 \documentclass{article}
396
397 \usepackage{xfor}
398
399 \makeatletter
400
401 % \insertinto{new value}{list}
402
403 \newtoks\tmptok
404
405 \newcommand{\insertinto}[2]{%
406 \def\nlst{}%
407 \@for\n:=#2\do{%
408 % store new list in \tmptok
409 \expandafter\tmptok\expandafter{\nlst}%
410 % test current value against new value
411 \ifnum\n>#1\relax
412 \edef\newstuff{\number#1,\n}%
413 % end for loop at the end of this iteration
414 \@endfortrue
415 \else
416 \edef\newstuff{\n}%
417 \fi
418 % append new stuff to new list
419 \ifx\nlst\@empty
420 \edef\nlst{\newstuff}%
421 \else
422 \edef\nlst{\the\tmptok,\newstuff}%
423 \fi
424 }%
425 % check to see if for loop was prematurely terminated
426 \if@endfor
427 % loop may have been terminated during final iteration, in
428 % which case \@forremainder is empty.
429 \ifx\@forremainder\@empty
430 % do nothing
431 \else
432 % loop prematurely ended, append remainder of original list
433 % to new list
434 \expandafter\tmptok\expandafter{\nlst}%
435 \edef\nlst{\the\tmptok,\@forremainder}%
436 \fi
437 \else
438 % wasn't prematurely terminated, so new value hasn't been added.
439 % Add now.
440 \expandafter\tmptok\expandafter{\nlst}%
441 \ifx\nlst\@empty
442 \edef\nlst{\number#1}%
443 \else
444 \edef\nlst{\the\tmptok,\number#1}%
445 \fi
446 \fi
447 \global\let#2=\nlst
448 }
449
450 % \insertionsort{list}
451 % replaces list with sorted list
452
453 \newcommand{\insertionsort}[1]{%
454 \def\sortedlist{}%
455 \@for\val:=#1\do{{\insertinto{\val}{\sortedlist}}}%
456 \let#1=\sortedlist}
457
458 \makeatother
459
460 \begin{document}
461 Unsorted list:
462 \def\mylist{4,2,7,1,10,11,20,15}\mylist.
463
464 \insertionsort{\mylist}%
465 Sorted list: \mylist.
466
467 Iterate through the list (next element in parentheses):
468 \makeatletter
469 \@for\n:=\mylist\do{%
470 \n
471 \ifx\@xfor@nextelement\@nnil
472 % last iteration
473 \else
474 (\@xfor@nextelement);
475 \fi
476 }.
477 \end{document}
478 % \end{macrocode}
479 %\iffalse
480 % \begin{macrocode}
481 %</sample.tex>
482 % \end{macrocode}
483 %\fi
484 %\Finale
485 \endinput