Debian Codegraph @

texmf-dist/source/latex/fifo-stack/fifo-stack.dtx

raw
1 % \changes{1.0}{2014/03/24}{Initial version}
2 %
3 % \iffalse
4 %<*never>
5 \documentclass{ltxdoc}
6 \usepackage{fifo-stack}
7 \usepackage{hyperref}
8 \GetFileInfo{fifo-stack.sty}
9 \CodelineIndex
10 \EnableCrossrefs
11 \RecordChanges
12 \begin{document}
13 \CheckSum{12}
14 \DocInput{fifo-stack.dtx}
15 \section{Copyright and \LaTeX\ Project Public License}
16 \begin{verbatim}
17 %txsBeginComment
18
19 Copyright (C) 2014 Stephen Gaito (PerceptiSys Ltd)
20
21 This work may be distributed and/or modified under the conditions of the
22 LaTeX Project Public License, either version 1.3 of this license or (at
23 your option) any later version.
24
25 The latest version of this license is in
26 http://www.latex-project.org/lppl.txt and version 1.3 or later is part of
27 all distributions of LaTeX version 2005/12/01 or later.
28
29 This work has the LPPL maintenance status `maintained'.
30
31 The Current Maintainer of this work is Stephen Gaito.
32
33 The released source can be found at:
34 https://github.com/diSimplex/latexFifoStack/tree/master/texStyle
35
36 The development source can be found at:
37 https://github.com/stephengaito/latexFifoStack/tree/master/texStyle
38
39 This work consists of the files fifo-stack.dtx, and fifo-stack.ins.
40
41 The command:
42 pdflatex fifo-stack.ins
43 followed by:
44 pdflatex fifo-stack.dtx
45 will produce the derived files: fifo-stack.sty, fifo-stack-test.tex,
46 and fifo-stack.pdf.
47
48 The command:
49 pdflatex fifo-stack-test.tex
50 will regression test the fifo-stack package. Output will be found in
51 fifo-stack-test.lgout. If pdflatex completes with no errors, then all
52 regression tests passed.
53
54 %txsEndComment
55 \end{verbatim}
56 \PrintIndex
57 \PrintChanges
58 \end{document}
59 %</never>
60 % \fi
61 %
62 % \DoNotIndex{\edef,\advance,\else,\csname,\endcsname,\expandafter}
63 % \DoNotIndex{\ifx,\fi,\input,\ifnum,\relax,\newcount,\romannumeral}
64 % \DoNotIndex{\the,\typeout,\xdef,\global,\newcommand,\RequirePackage}
65 % \DoNotIndex{\PackageError,\ProvidesPackage,\gdef}
66 % \DoNotIndex{\IncludeTests,\LogClose,\LogTests,\Expect,\ExpectIfThen}
67 % \DoNotIndex{\isnamedefined,\isundefined}
68 % \DoNotIndex{\stop,\makeatletter,\makeatother,\begin,\end,\def,\let}
69 % \DoNotIndex{\testFSDestroy@fifo@stack@count@top}
70 % \DoNotIndex{\testFSDestroy@fifo@stack@count@bottom}
71 % \DoNotIndex{\testFSDestroy@fifo@stack@count@size}
72 % \DoNotIndex{\fifo@stack@top@testFSDestroy}
73 % \DoNotIndex{\fifo@stack@bottom@testFSDestroy}
74 %
75 % \title{A \LaTeX\ FIFO/Stack implementation for Package writers}
76 % \author{Stephen \textsc{Gaito}}
77 % \date{\filedate}
78 % \maketitle
79 % \begin{abstract}
80 % This package provides a \LaTeX\ implementation of a FIFO/Stack system
81 % independent from the \TeX\ stack itself. It is based on Benjamin Bayart's
82 % excellent \href{http://www.ctan.org/pkg/stack}{stack} package from
83 % \href{http://www.ctan.org}{CTAN}.
84 %
85 % This package by itself is of no use to anyone other than macro-developers.
86 %
87 % Note that to simplify the computations, this package makes essential use of
88 % $\varepsilon$-\TeX's \verb|\numexpr| macro. Fortunately most modern \TeX,
89 % \LaTeX\ and pdf\LaTeX's are actually $\varepsilon$-\TeX.
90 % \end{abstract}
91 % \tableofcontents
92 %
93 % \section{Using the FIFO/stack package}
94 %
95 % All of the macros provided by this package are meant to be used by package
96 % developers (there is no meaningful use of a FIFO or stack in a final
97 % document, they will only to be used in a package), so, all of those macros
98 % have capital letters in their names, following old guidelines for \LaTeX3
99 % project.
100 %
101 % To ensure these macros do not clash with other packages, the names of all
102 % macros begin with ``FS''.
103 %
104 % \subsection{FIFO/Stack creation and destruction commands}
105 %
106 % To create a new FIFO/stack:
107 % \begin{quote}
108 % \DescribeMacro{\FSCreate}\verb|\FSCreate{fifoStackName}{defaultValue}|
109 % \end{quote}
110 % This macro simply initializes all the required data for the FIFO/stack named by
111 % the value of the first argument, \verb|fifoStackName|. The second argument,
112 % \verb|defaultValue|, is the value of the top of the FIFO/stack whenever the
113 % FIFO/stack is empty.
114 %
115 % To clear an existing FIFO/stack of all of its current elements:
116 % \begin{quote}
117 % \DescribeMacro{\FSClear}\verb|\FSClear{fifoStackName}|
118 % \end{quote}
119 % This macro empties the FIFO/stack named \verb|fifoStackName|, but the
120 % FIFO/stack can still be used to \verb|\FSPush| or \verb|\FSUnshift| new
121 % elements.
122 %
123 % To destroy an existing FIFO/stack:
124 % \begin{quote}
125 % \DescribeMacro{\FSDestroy}\verb|\FSDestroy{fifoStackName}|
126 % \end{quote}
127 % This macro destroys the FIFO/stack named \verb|fifoStackName|.
128 %
129 % \subsection{Stack based commands}
130 %
131 % To push a new value on \emph{top} of a FIFO/stack:
132 % \begin{quote}
133 % \DescribeMacro{\FSPush}\verb|\FSPush{fifoStackName}{value}|\newline
134 % \end{quote}
135 % Note that you \emph{can} use \verb|\FSTop| in the \verb|value| argument of the
136 % \verb|\FSPush| macro. See the qstest unit test for \verb|\FSPush| (below) for
137 % an example.
138 %
139 % To remove the value from the \emph{top} of a FIFO/stack:
140 % \begin{quote}
141 % \DescribeMacro{\FSPop}\verb|\FSPop{fifoStackName}|
142 % \end{quote}
143 %
144 % To get the value from the \emph{top} of the FIFO/stack:
145 % \begin{quote}
146 % \DescribeMacro{\FSTop}\verb|\FSTop{fifoStackName}|
147 % \end{quote}
148 %
149 % For use when debugging your use of the FIFO/stack:
150 % \begin{quote}
151 % \DescribeMacro{\FSShowTop}\verb|\FSShowTop{fifoStackName}|
152 % \end{quote}
153 % will \verb|\typeout| the current value on the \emph{top} of the FIFO/stack.
154 %
155 % \subsection{FIFO based commands}
156 %
157 % To add a new value to the \emph{bottom} of a FIFO/stack:
158 % \begin{quote}
159 % \DescribeMacro{\FSUnshift}\verb|\FSUnshift{fifoStackName}{value}|
160 % \end{quote}
161 % Note that you \emph{can} use \verb|\FSBottom| in the \verb|value| argument of
162 % the \verb|\FSUnshift| macro. See the qstest unit test for \verb|\FSUnshift|
163 % (below) for an example.
164 %
165 % To remove the value on the \emph{bottom} of a FIFO/stack:
166 % \begin{quote}
167 % \DescribeMacro{\FSShift}\verb|\FSShift{fifoStackName}|
168 % \end{quote}
169 %
170 % To get the value on the \emph{bottom} of a FIFO/stack:
171 % \begin{quote}
172 % \DescribeMacro{\FSBottom}\verb|\FSBottom{fifoStackName}|
173 % \end{quote}
174 %
175 % For use when debugging your use of the FIFO/stack:
176 % \begin{quote}
177 % \DescribeMacro{\FSShowBottom}\verb|\FSShowBottom{fifoStackName}|
178 % \end{quote}
179 % will \verb|\typeout| the current value on the \emph{bottom} of the FIFO/stack.
180 %
181 % \subsection{FIFO/stack size commands}
182 %
183 % To get the current size of the FIFO/stack:
184 % \begin{quote}
185 % \DescribeMacro{\FSSize}\verb|\FSSize{fifoStackName}|
186 % \end{quote}
187 %
188 % \subsection{TeXStudio CWL file}
189 %
190 % As a bonus for users of TeXStudio, the \verb|fifo-stack.zip| file also
191 % contains a \verb|fifo-stack.cwl| file which provides TeXStudio command
192 % expansion descriptions for each of the `public' \verb|fifo-stack| macros. To
193 % make use of these command expansions, simply place the \verb|fifo-stack.cwl|
194 % file into TeXStudio's local configuration directory (on most Linux
195 % distributions this can be found in \verb|~/.config/texstudio|).
196 %
197 % This \verb|fifo-stack.cwl| file is automatically generated from the macrocode
198 % lines which begin with the characters \verb|%txs|. This automatic generation
199 % is done by the \verb|cook texStyle| command defined by the sister project
200 % \href{https://github.com/diSimplex/diSimplexLaTeX}{diSimplexLaTeX}'s (ruby)
201 % cookbook.
202 %
203 % \subsection{\TeX\ and \LaTeX\ Dependencies}
204 %
205 % The \verb|fifo-stack| package depends upon both $\varepsilon$-\TeX, as well as
206 % the \verb|ifthen| package. $\varepsilon$-\TeX\ is required only for the two
207 % uses of \verb|\numexpr|. The \verb|ifthen| package is only required for the
208 % one use of \verb|\whiledo|. All three uses are listed in the index.
209 %
210 % The production of this documentation assumes you have the \verb|hyperref|
211 % package installed.
212 %
213 % The regression tests associated with this package depend upon the
214 % \verb|qstest|, \verb|ifthen|, and \verb|xifthen| packages.
215 %
216 % \section{Integration tests and example usage}
217 %
218 % We use the \href{http://www.ctan.org/pkg/qstest}{QSTest} package from
219 % \href{http://www.ctan.org}{CTAN} to provide both integration and unit tests of
220 % our FIFO/stack package.
221 %
222 % In this section we walk through a number of integration tests which also
223 % provide example uses of FIFO/Stacks. We provide unit tests of specific
224 % invariants in the code section below. These unit tests are associated
225 % with the section of code which implements a particular invariant.
226 %
227 % We begin by setting up the \LaTeX\ QSTest package to test the \verb|fifo-stack|
228 % package, and we will log everything. Note that we do not use a document class
229 % or begin/end a document, this is because there should not be any \emph{normal}
230 % output created. All \emph{results} are listed in the associated
231 % \verb|fifo-stack-test.lgout| file.
232 %
233 % \begin{macrocode}
234 %<*qstest>
235 \RequirePackage{qstest}
236 \RequirePackage{xifthen}
237 \IncludeTests{*}
238 \LogTests{lgout}{*}{*}
239 \RequirePackage{fifo-stack}
240 %</qstest>
241 % \end{macrocode}
242 %
243 % \subsection{Stack based examples}
244 %
245 % We now provide an example of standard use of just the stack based
246 % functionality. To do this we create a stack, push three things onto the stack
247 % and then pop all three things back off, all in a nice linear fashion.
248 %
249 % \begin{macrocode}
250 %<*qstest>
251 \begin{qstest}{Simple stack integration test}
252 {\FSCreate, \FSPush, \FSPop, \FSTop}
253
254 \FSCreate{testStack}{defaultValue}
255 \Expect*{\FSTop{testStack}}{defaultValue}
256 \FSPush{testStack}{firstValue}
257 \Expect*{\FSTop{testStack}}{firstValue}
258 \FSPush{testStack}{secondValue}
259 \Expect*{\FSTop{testStack}}{secondValue}
260 \FSPush{testStack}{thirdValue}
261 \Expect*{\FSTop{testStack}}{thirdValue}
262 \FSPop{testStack}
263 \Expect*{\FSTop{testStack}}{secondValue}
264 \FSPop{testStack}
265 \Expect*{\FSTop{testStack}}{firstValue}
266 \FSPop{testStack}
267 \Expect*{\FSTop{testStack}}{defaultValue}
268 \FSPop{testStack}
269 \Expect*{\FSTop{testStack}}{defaultValue}
270 \end{qstest}
271 %</qstest>
272 % \end{macrocode}
273 %
274 % We now look at using the stack in a non-linear order pushing, popping, then
275 % pushing and popping again.
276 %
277 % \begin{macrocode}
278 %<*qstest>
279 \begin{qstest}{Up down up down stack integration test}
280 {\FSCreate, \FSPush, \FSPop, \FSTop}
281
282 \FSCreate{testStackUDUD}{defaultValue}
283 \Expect*{\FSTop{testStackUDUD}}{defaultValue}
284 \FSPush{testStackUDUD}{firstValue}
285 \Expect*{\FSTop{testStackUDUD}}{firstValue}
286 \FSPush{testStackUDUD}{secondValue}
287 \Expect*{\FSTop{testStackUDUD}}{secondValue}
288 \FSPop{testStackUDUD}
289 \Expect*{\FSTop{testStackUDUD}}{firstValue}
290 \FSPush{testStackUDUD}{newSecondValue}
291 \Expect*{\FSTop{testStackUDUD}}{newSecondValue}
292 \end{qstest}
293 %</qstest>
294 % \end{macrocode}
295 %
296 % \subsection{FIFO/Stack based examples}
297 %
298 % This time we make use of \verb|\FSPush| to put items onto the FIFO and
299 % \verb|\FSShift| to take them off in a \emph{first in first off} order. At the
300 % end we shift past the top of the FIFO/Stack, and so we should get the default
301 % value again.
302 %
303 % \begin{macrocode}
304 %<*qstest>
305 \begin{qstest}{Simple FIFO integration test}
306 {\FSCreate, \FSPush, \FSShift, \FSTop, \FSBottom}
307
308 \FSCreate{testFifo}{defaultValue}
309 \Expect*{\FSTop{testFifo}}{defaultValue}
310 \Expect*{\FSBottom{testFifo}}{defaultValue}
311 \FSPush{testFifo}{firstValue}
312 \Expect*{\FSTop{testFifo}}{firstValue}
313 \Expect*{\FSBottom{testFifo}}{firstValue}
314 \FSPush{testFifo}{secondValue}
315 \Expect*{\FSTop{testFifo}}{secondValue}
316 \Expect*{\FSBottom{testFifo}}{firstValue}
317 \FSShift{testFifo}
318 \Expect*{\FSTop{testFifo}}{secondValue}
319 \Expect*{\FSBottom{testFifo}}{secondValue}
320 \FSPush{testFifo}{thirdValue}
321 \Expect*{\FSTop{testFifo}}{thirdValue}
322 \Expect*{\FSBottom{testFifo}}{secondValue}
323 \FSShift{testFifo}
324 \Expect*{\FSTop{testFifo}}{thirdValue}
325 \Expect*{\FSBottom{testFifo}}{thirdValue}
326 \FSShift{testFifo}
327 \Expect*{\FSTop{testFifo}}{defaultValue}
328 \Expect*{\FSBottom{testFifo}}{defaultValue}
329 \FSShift{testFifo}
330 \Expect*{\FSTop{testFifo}}{defaultValue}
331 \Expect*{\FSBottom{testFifo}}{defaultValue}
332 \end{qstest}
333 %</qstest>
334 % \end{macrocode}
335 %
336 % We now provide an example use of \verb|\FSUnshift| and \verb|\FSShift|.
337 %
338 % \begin{macrocode}
339 %<*qstest>
340 \begin{qstest}{Simple linear use of unshift/shift}
341 {\FSUnshift, \FSShift}
342
343 \FSCreate{testRStack}{defaultValue}
344 \Expect*{\FSBottom{testRStack}}{defaultValue}
345 \FSUnshift{testRStack}{firstValue}
346 \Expect*{\FSBottom{testRStack}}{firstValue}
347 \FSUnshift{testRStack}{secondValue}
348 \Expect*{\FSBottom{testRStack}}{secondValue}
349 \FSUnshift{testRStack}{thirdValue}
350 \Expect*{\FSBottom{testRStack}}{thirdValue}
351 \FSShift{testRStack}
352 \Expect*{\FSBottom{testRStack}}{secondValue}
353 \FSShift{testRStack}
354 \Expect*{\FSBottom{testRStack}}{firstValue}
355 \FSShift{testRStack}
356 \Expect*{\FSBottom{testRStack}}{defaultValue}
357 \FSShift{testRStack}
358 \Expect*{\FSBottom{testRStack}}{defaultValue}
359 \end{qstest}
360 %</qstest>
361 % \end{macrocode}
362 %
363 % Now we provide an example (non-linear) use of all of the \verb|\FSPush|,
364 % \verb|\FSPop|, \verb|\FSUnshift|, and \verb|\FSShift| macros
365 %
366 % \begin{macrocode}
367 %<*qstest>
368 \begin{qstest}{Full non-linear FIFO/stack integration test}
369 {\FSCreate, \FSPush, \FSPop, \FSUnshift, \FSShift, \FSTop, \FSBottom}
370
371 \FSCreate{testFS}{defaultValue}
372 \Expect*{\FSTop{testFS}}{defaultValue}
373 \Expect*{\FSBottom{testFS}}{defaultValue}
374 \FSPush{testFS}{value1}
375 \Expect*{\FSTop{testFS}}{value1}
376 \Expect*{\FSBottom{testFS}}{value1}
377 \FSUnshift{testFS}{value-1}
378 \Expect*{\FSTop{testFS}}{value1}
379 \Expect*{\FSBottom{testFS}}{value-1}
380 \FSShift{testFS}
381 \Expect*{\FSTop{testFS}}{value1}
382 \Expect*{\FSBottom{testFS}}{value1}
383 \FSPush{testFS}{value2}
384 \Expect*{\FSTop{testFS}}{value2}
385 \Expect*{\FSBottom{testFS}}{value1}
386 \FSUnshift{testFS}{value-1again}
387 \Expect*{\FSTop{testFS}}{value2}
388 \Expect*{\FSBottom{testFS}}{value-1again}
389 \FSUnshift{testFS}{value-2}
390 \Expect*{\FSTop{testFS}}{value2}
391 \Expect*{\FSBottom{testFS}}{value-2}
392 \FSPop{testFS}
393 \Expect*{\FSTop{testFS}}{value1}
394 \Expect*{\FSBottom{testFS}}{value-2}
395 \FSPop{testFS}
396 \Expect*{\FSTop{testFS}}{value-1again}
397 \Expect*{\FSBottom{testFS}}{value-2}
398 \FSShift{testFS}
399 \Expect*{\FSTop{testFS}}{value-1again}
400 \Expect*{\FSBottom{testFS}}{value-1again}
401 \FSPop{testFS}
402 \Expect*{\FSTop{testFS}}{defaultValue}
403 \Expect*{\FSBottom{testFS}}{defaultValue}
404 \FSPop{testFS}
405 \Expect*{\FSTop{testFS}}{defaultValue}
406 \Expect*{\FSBottom{testFS}}{defaultValue}
407 \FSShift{testFS}
408 \Expect*{\FSTop{testFS}}{defaultValue}
409 \Expect*{\FSBottom{testFS}}{defaultValue}
410 \end{qstest}
411 %</qstest>
412 % \end{macrocode}
413 %
414 % Finally we add an integration test of the full suite, including
415 % \verb|\FSClear|, \verb|\FSSize|, and \verb|\FSDestroy| macros
416 %
417 % \begin{macrocode}
418 %<*qstest>
419 \begin{qstest}{FSClear, FSSize, and FSDestroy test}
420 {\FSCreate, \FSPush, \FSPop, \FSUnshift, \FSShift, \FSTop,
421 \FSBottom, \FSClear, \FSDestroy, \FSSize}
422
423 \FSCreate{testFSC}{defaultValue}
424 \Expect*{\FSSize{testFSC}}{0}
425 \Expect*{\FSTop{testFSC}}{defaultValue}
426 \Expect*{\FSBottom{testFSC}}{defaultValue}
427 \FSPush{testFSC}{value1}
428 \Expect*{\FSSize{testFSC}}{1}
429 \Expect*{\FSTop{testFSC}}{value1}
430 \Expect*{\FSBottom{testFSC}}{value1}
431 \FSUnshift{testFSC}{value-1}
432 \Expect*{\FSSize{testFSC}}{2}
433 \Expect*{\FSTop{testFSC}}{value1}
434 \Expect*{\FSBottom{testFSC}}{value-1}
435 \FSPush{testFSC}{value2}
436 \Expect*{\FSSize{testFSC}}{3}
437 \Expect*{\FSTop{testFSC}}{value2}
438 \Expect*{\FSBottom{testFSC}}{value-1}
439 \FSUnshift{testFSC}{value-2}
440 \Expect*{\FSSize{testFSC}}{4}
441 \Expect*{\FSTop{testFSC}}{value2}
442 \Expect*{\FSBottom{testFSC}}{value-2}
443 \FSClear{testFSC}
444 \Expect*{\FSSize{testFSC}}{0}
445 \Expect*{\FSTop{testFSC}}{defaultValue}
446 \Expect*{\FSBottom{testFSC}}{defaultValue}
447 \FSPush{testFSC}{value1}
448 \Expect*{\FSSize{testFSC}}{1}
449 \Expect*{\FSTop{testFSC}}{value1}
450 \Expect*{\FSBottom{testFSC}}{value1}
451 \FSUnshift{testFSC}{value-1}
452 \Expect*{\FSSize{testFSC}}{2}
453 \Expect*{\FSTop{testFSC}}{value1}
454 \Expect*{\FSBottom{testFSC}}{value-1}
455 \FSPush{testFSC}{value2}
456 \Expect*{\FSSize{testFSC}}{3}
457 \Expect*{\FSTop{testFSC}}{value2}
458 \Expect*{\FSBottom{testFSC}}{value-1}
459 \FSUnshift{testFSC}{value-2}
460 \Expect*{\FSSize{testFSC}}{4}
461 \Expect*{\FSTop{testFSC}}{value2}
462 \Expect*{\FSBottom{testFSC}}{value-2}
463 \FSDestroy{testFSC}
464 \end{qstest}
465 %</qstest>
466 % \end{macrocode}
467 %
468 % \section{Code for the FIFO/stack package}
469 %
470 % \subsection{Identification}
471 %
472 % \begin{macrocode}
473 %<*package>
474 \ProvidesPackage{fifo-stack}[2014/03/24 v1.0 Multi-FIFO/stack system]
475 \RequirePackage{ifthen}
476 % \end{macrocode}
477 %
478 % \subsection{FIFO/stack creation and destruction macro definitions}
479 %
480 % In the following code, we use only three counters (in the \TeX\ meaning) we
481 % store the various values in macros, and use only the top, bottom or size
482 % counters when we need to do computations.
483 %
484 % \begin{macro}{\tmp@fifo@stack@top}
485 % \begin{macrocode}
486 \newcount\tmp@fifo@stack@top
487 % \end{macrocode}
488 % \end{macro}
489 %
490 % \begin{macro}{\tmp@fifo@stack@bottom}
491 % \begin{macrocode}
492 \newcount\tmp@fifo@stack@bottom
493 % \end{macrocode}
494 % \end{macro}
495 %
496 % \begin{macro}{\tmp@fifo@stack@size}
497 % \begin{macrocode}
498 \newcount\tmp@fifo@stack@size
499 % \end{macrocode}
500 % \end{macro}
501 %
502 % \begin{macro}{\fifo@stack@pointer}
503 %
504 % All items in a given FIFO/stack named \verb|fifoStackName| are stored in
505 % dynamically defined macros whose names consist of the \verb|fifoStackName|
506 % followed by \verb|@| followed by the value of the \verb|\fifo@stack@pointer|
507 % macro with either \verb|\tmp@fifo@stack@top| or \verb|\tmp@fifo@stack@bottom|
508 % counters as argument.
509 %
510 % We start by providing a unit test of the expected behaviour of the\\
511 % \verb|\fifo@stack@pointer| macro.
512 %
513 % \begin{macrocode}
514 %</package>
515 %<*qstest>
516 \begin{qstest}{Unit test of \fifo@stack@pointer}{\fifo@stack@pointer}
517 \makeatletter
518 \Expect*{\fifo@stack@pointer{1}}{ii}
519 \Expect*{\fifo@stack@pointer{0}}{i}
520 \Expect*{\fifo@stack@pointer{-1}}{@i}
521 \makeatother
522 \end{qstest}
523 %</qstest>
524 %<*package>
525 % \end{macrocode}
526 %
527 % Now the macrocode itself. Note the only two uses of the $\varepsilon$-\TeX\
528 % \verb|\numexpr| macro.
529 %
530 % \begin{macrocode}
531 \global\def\fifo@stack@pointer#1{%
532 \ifnum#1<0
533 @\expandafter\romannumeral\numexpr -1*#1 \relax
534 \else
535 \expandafter\romannumeral\numexpr #1+1 \relax
536 \fi
537 }
538 % \end{macrocode}
539 % \end{macro}
540 %
541 % \begin{macro}{\FSCreate}
542 %
543 % Creating a new FIFO/stack is, essentially, creating new counter-like top,
544 % bottom and size macros, initializing them to 0, 1 and 0 respectively, as well
545 % as creating macros for stack-top and stack-bottom evaluation (see next two
546 % macros below).
547 %
548 % \begin{macrocode}
549 %txs\FSCreate{fifoStackName}{defaultValue}#
550 \newcommand\FSCreate[2]{%
551 \expandafter\gdef\csname #1@fifo@stack@count@top\endcsname{0}%
552 \expandafter\gdef\csname #1@fifo@stack@count@bottom\endcsname{1}%
553 \expandafter\gdef\csname #1@fifo@stack@count@size\endcsname{0}%
554 \expandafter\do@fifo@stack@top@macro%
555 \csname #1@fifo@stack@count@top\endcsname{#1}{#2}%
556 \expandafter\do@fifo@stack@bottom@macro%
557 \csname #1@fifo@stack@count@bottom\endcsname{#1}{#2}%
558 }
559 % \end{macrocode}
560 % \end{macro}
561 %
562 % \begin{macro}{\do@fifo@stack@top@macro}
563 %
564 % This stack-top evaluation macro is required due to an ugly trick. During the
565 % push, we ``evaluate'' the value to push with an \verb|\edef|, because one
566 % might want to push something which contains the previous top of the stack (see
567 % the example package provided). If the \verb|\FSTop| or \verb|FSBottom| macros
568 % compute the real value on the top or bottom of the stack, then, the expanded
569 % definition in \verb|\FSPush| will contain more or less the \emph{content} of
570 % \verb|\FSTop| and not the value.
571 %
572 % Another way would be to have a \verb|\csname...\endcsname| pair within
573 % another one in an \verb|\ifx| condition, which doesn't work.
574 %
575 % \begin{macrocode}
576 \newcommand\do@fifo@stack@top@macro[3]{%
577 \expandafter\newcommand\expandafter*%
578 \csname fifo@stack@top@#2\endcsname{%
579 \expandafter\ifx\csname #2@\fifo@stack@pointer#1\endcsname\relax
580 #3%
581 \else
582 \csname #2@\fifo@stack@pointer#1\endcsname
583 \fi
584 }%
585 }
586 % \end{macrocode}
587 % \end{macro}
588 %
589 % \begin{macro}{\do@fifo@stack@bottom@macro}
590 %
591 % This is the stack-bottom macro defined for the same reasons as
592 % \verb|\do@fifo@stack@top@macro| (see above).
593 %
594 % \begin{macrocode}
595 \newcommand\do@fifo@stack@bottom@macro[3]{%
596 \expandafter\newcommand\expandafter*%
597 \csname fifo@stack@bottom@#2\endcsname{%
598 \expandafter\ifx\csname #2@\fifo@stack@pointer#1\endcsname\relax
599 #3%
600 \else
601 \csname #2@\fifo@stack@pointer#1\endcsname
602 \fi
603 }%
604 }
605 % \end{macrocode}
606 % \end{macro}
607 %
608 % \begin{macro}{\FSClear}
609 %
610 % While the size of the FIFO/stack is greater than zero, pop the FIFO/stack.
611 % Note the only use of the \verb|ifthen| package's \verb|\whiledo| macro.
612 %
613 % \begin{macrocode}
614 %txs\FSClear{fifoStackName}#
615 \newcommand{\FSClear}[1]{%
616 \whiledo{0 < \FSSize{#1}}{\FSPop{#1}}
617 }
618 % \end{macrocode}
619
620 % \end{macro}
621 %
622 % \begin{macro}{\FSDestroy}
623 %
624 % Clear the FIFO/stack and then undefine all of the supporting macros.
625 %
626 % We provide a unit test of the expected behaviour of the \verb|\FSDestroy|
627 % macro.
628 %
629 % \begin{macrocode}
630 %</package>
631 %<*qstest>
632 \begin{qstest}{Unit test of \FSdestroy}
633 {\FSCreate, \FSDestroy}
634
635 \FSCreate{testFSDestroy}{defaultValue}
636 \makeatletter
637 \ExpectIfThen{\isnamedefined{testFSDestroy@fifo@stack@count@top}}
638 \ExpectIfThen{\isnamedefined{testFSDestroy@fifo@stack@count@bottom}}
639 \ExpectIfThen{\isnamedefined{testFSDestroy@fifo@stack@count@size}}
640 \ExpectIfThen{\isnamedefined{fifo@stack@top@testFSDestroy}}
641 \ExpectIfThen{\isnamedefined{fifo@stack@bottom@testFSDestroy}}
642 \makeatother
643 \FSDestroy{testFSDestroy}
644 \makeatletter
645 \ExpectIfThen{\isundefined\testFSDestroy@fifo@stack@count@top}
646 \ExpectIfThen{\isundefined\testFSDestroy@fifo@stack@count@bottom}
647 \ExpectIfThen{\isundefined\testFSDestroy@fifo@stack@count@size}
648 \ExpectIfThen{\isundefined\fifo@stack@top@testFSDestroy}
649 \ExpectIfThen{\isundefined\fifo@stack@bottom@testFSDestroy}
650 \makeatother
651 \end{qstest}
652 %</qstest>
653 %<*package>
654 % \end{macrocode}
655 %
656 % And now the macrocode for \verb|\FSDestroy|.
657 %
658 % \begin{macrocode}
659 %txs\FSDestroy{fifoStackName}#
660 \newcommand{\FSDestroy}[1]{%
661 \FSClear{#1}
662 \expandafter\global\expandafter\let
663 \csname #1@fifo@stack@count@top\endcsname=
664 \fifo@stack@never@defined\relax
665 \expandafter\global\expandafter\let
666 \csname #1@fifo@stack@count@bottom\endcsname=
667 \fifo@stack@never@defined\relax
668 \expandafter\global\expandafter\let
669 \csname #1@fifo@stack@count@size\endcsname=
670 \fifo@stack@never@defined\relax
671 \expandafter\global\expandafter\let
672 \csname fifo@stack@top@#1\endcsname=
673 \fifo@stack@never@defined\relax
674 \expandafter\global\expandafter\let
675 \csname fifo@stack@bottom@#1\endcsname=
676 \fifo@stack@never@defined\relax
677 }
678 % \end{macrocode}
679 % \end{macro}
680 %
681 % \subsection{Stack based macro definitions}
682 %
683 % \begin{macro}{\FSTop}
684 % I'd rather remove the ``check'' code, but, well, it would suppose
685 % the end-user of the macro is a fair developer, which is not
686 % realistic.
687 %
688 % If the stack has been properly created, we call the top-stack evaluation
689 % macro.
690 %
691 % \begin{macrocode}
692 %txs\FSTop{fifoStackName}#
693 \newcommand\FSTop[1]{%
694 \ifx\csname #1@fifo@stack@count@top\endcsname\relax
695 \PackageError{fifo-stack}{Undefined FIFO/stack #1}%
696 {You should first create the FIFO/stack with \FSCreate}%
697 \else
698 \csname fifo@stack@top@#1\endcsname
699 \fi
700 }
701 % \end{macrocode}
702 % \end{macro}
703 %
704 % \begin{macro}{\FSPush}
705 % The \verb|\FSPush| macro is one of the most complex ones.
706 %
707 % We provide a unit test of the ability to use \verb|\FSTop| inside the value
708 % argument to a \verb|\FSPush| macro (which is the reason for the complexity of
709 % this macro).
710 %
711 % \begin{macrocode}
712 %</package>
713 %<*qstest>
714 \begin{qstest}{Unit test of \FSPush and \FSTop}
715 {\FSCreate, \FSPush, \FSTop}
716
717 \FSCreate{testFSPush}{defaultValue}
718 \Expect*{\FSTop{testFSPush}}{defaultValue}
719 \FSPush{testFSPush}{\FSTop{testFSPush}-with-additional-text}
720 \Expect*{\FSTop{testFSPush}}{defaultValue-with-additional-text}
721 \end{qstest}
722 %</qstest>
723 %<*package>
724 % \end{macrocode}
725 %
726 % And now the macrocode for \verb|\FSPush|. First, we check if the stack is
727 % properly defined.
728 %
729 % \begin{macrocode}
730 %txs\FSPush{fifoStackName}{value}#
731 \newcommand\FSPush[2]{%
732 \ifx\csname #1@fifo@stack@count@top\endcsname\relax
733 \PackageError{fifo-stack}{Undefined FIFO/stack #1}%
734 {You should first create the FIFO/stack with \FSCreate}%
735 \else
736 % \end{macrocode}
737 %
738 % We store the new top-value in a macro, just because one might do
739 % \begin{quote}
740 % \verb|\FSPush{stack}{\FSTop{stack}.ext}|
741 % \end{quote}
742 % in which case the expansion of
743 % the value to push is something rather tricky.
744 %
745 % Then, we step the top of the stack (put the top in the scratch
746 % counter, advance this counter, have the value back in the macro).
747 %
748 % We separately adjust the size macro. We do this since actually computing the
749 % value in the \verb|\FSSize| macro proved difficult.
750 %
751 % Only after that, the value to be pushed is stored in the corresponding
752 % slot.
753 % \begin{macrocode}
754 \edef\fifo@stack@newtop{#2}%
755 \tmp@fifo@stack@top\csname #1@fifo@stack@count@top\endcsname\relax
756 \global\advance\tmp@fifo@stack@top by 1\relax
757 \expandafter\xdef\csname #1@fifo@stack@count@top\endcsname
758 {\the\tmp@fifo@stack@top}%
759 \tmp@fifo@stack@size\csname #1@fifo@stack@count@size\endcsname\relax
760 \global\advance\tmp@fifo@stack@size by 1\relax
761 \expandafter\xdef\csname #1@fifo@stack@count@size\endcsname
762 {\the\tmp@fifo@stack@size}%
763 \expandafter\xdef\csname #1@\fifo@stack@pointer\tmp@fifo@stack@top\endcsname
764 {\fifo@stack@newtop}%
765 \fi
766 }
767 % \end{macrocode}
768 % \end{macro}
769 %
770 % \begin{macro}{\FSPop}
771 % The \verb|\FSPop| macro is simpler: if the stack is properly defined and
772 % the stack-top is greater than or equal to the stack-bottom, then we undefine
773 % the existing `top' macro and down-step the stack-top and stack-size.
774 % \begin{macrocode}
775 %txs\FSPop{fifoStackName}#
776 \newcommand\FSPop[1]{%
777 \ifx\csname #1@fifo@stack@count@top\endcsname\relax
778 \PackageError{fifo-stack}{Undefined FIFO/stack #1}%
779 {You should first create the FIFO/stack with \FSCreate}%
780 \else
781 \tmp@fifo@stack@top\csname #1@fifo@stack@count@top\endcsname\relax
782 \tmp@fifo@stack@bottom\csname #1@fifo@stack@count@bottom\endcsname\relax
783 \ifnum\tmp@fifo@stack@top<\tmp@fifo@stack@bottom\relax\else
784 \expandafter\global\expandafter\let
785 \csname #1@\fifo@stack@pointer\tmp@fifo@stack@top\endcsname=
786 \fifo@stack@never@defined\relax
787 \advance\tmp@fifo@stack@top by -1\relax
788 \expandafter\xdef\csname #1@fifo@stack@count@top\endcsname
789 {\the\tmp@fifo@stack@top}%
790 \tmp@fifo@stack@size\csname #1@fifo@stack@count@size\endcsname\relax
791 \global\advance\tmp@fifo@stack@size by -1\relax
792 \expandafter\xdef\csname #1@fifo@stack@count@size\endcsname
793 {\the\tmp@fifo@stack@size}%
794 \fi
795 \fi
796 }
797 % \end{macrocode}
798 % \end{macro}
799 %
800 % Now, a debug only macro.
801 % \begin{macro}{\FSShowTop}
802 % \begin{macrocode}
803 %txs\FSShowTop{fifoStackName}#
804 \newcommand\FSShowTop[1]{%
805 {\edef\fifo@stack@top{\FSTop{#1}}%
806 \typeout{The top of #1: \fifo@stack@top}}}
807 % \end{macrocode}
808 % \end{macro}
809 %
810 % \subsection{FIFO based macro definitions}
811 %
812 % \begin{macro}{\FSBottom}
813 % \begin{macrocode}
814 %txs\FSBottom{fifoStackName}#
815 \newcommand\FSBottom[1]{%
816 \ifx\csname #1@fifo@stack@count@bottom\endcsname\relax
817 \PackageError{fifo-stack}{Undefined FIFO/stack #1}%
818 {You should first create the FIFO/stack with \FSCreate}%
819 \else
820 \csname fifo@stack@bottom@#1\endcsname
821 \fi
822 }
823 % \end{macrocode}
824 % \end{macro}
825 %
826 % \begin{macro}{\FSUnshift}
827 % The \verb|\FSUnshift| macro, like the corresponding \verb|\FSPush| macro, is
828 % one of the most complex ones.
829 %
830 % % We provide a unit test of the ability to use \verb|\FSBottom| inside the value
831 % argument to a \verb|\FSUnshift| macro (which is the reason for the complexity of
832 % this macro).
833 %
834 % \begin{macrocode}
835 %</package>
836 %<*qstest>
837 \begin{qstest}{Unit test of \FSUnshift and \FSBottom}
838 {\FSCreate, \FSUnshift, \FSBottom}
839
840 \FSCreate{testFSUnshift}{defaultValue}
841 \Expect*{\FSBottom{testFSUnshift}}{defaultValue}
842 \FSUnshift{testFSUnshift}{\FSBottom{testFSUnshift}-with-additional-text}
843 \Expect*{\FSBottom{testFSUnshift}}{defaultValue-with-additional-text}
844 \end{qstest}
845 %</qstest>
846 %<*package>
847 % \end{macrocode}
848 %
849 % And now the macrocode for \verb|\FSUnshift|. First, we check if the stack is
850 % properly defined.
851 %
852 % \begin{macrocode}
853 %txs\FSUnshift{fifoStackName}{value}#
854 \newcommand\FSUnshift[2]{%
855 \ifx\csname #1@fifo@stack@count@bottom\endcsname\relax
856 \PackageError{fifo-stack}{Undefined FIFO/stack #1}%
857 {You should first create the FIFO/stack with \FSCreate}%
858 \else
859 % \end{macrocode}
860 %
861 % We store the new bottom-value in a macro, just because one might do
862 % \begin{quote}
863 % \verb|\FSUnshift{stack}{\FSBottom{stack}.ext}|
864 % \end{quote}
865 % in which case the expansion of
866 % the value to push is something rather tricky.
867 %
868 % Then, we step the bottom of the stack (put the bottom in the scratch
869 % counter, decrement this counter, have the value back in the macro).
870 %
871 % We separately adjust the size macro. We do this since actually computing the
872 % value in the \verb|\FSSize| macro proved difficult.
873 %
874 % Only after that, the value to be unshifted is stored in the corresponding
875 % slot.
876 % \begin{macrocode}
877 \edef\fifo@stack@newBottom{#2}%
878 \tmp@fifo@stack@bottom\csname #1@fifo@stack@count@bottom\endcsname\relax
879 \global\advance\tmp@fifo@stack@bottom by -1\relax
880 \expandafter\xdef\csname #1@fifo@stack@count@bottom\endcsname
881 {\the\tmp@fifo@stack@bottom}%
882 \tmp@fifo@stack@size\csname #1@fifo@stack@count@size\endcsname\relax
883 \global\advance\tmp@fifo@stack@size by 1\relax
884 \expandafter\xdef\csname #1@fifo@stack@count@size\endcsname
885 {\the\tmp@fifo@stack@size}%
886 \expandafter\xdef\csname #1@\fifo@stack@pointer\tmp@fifo@stack@bottom\endcsname
887 {\fifo@stack@newBottom}%
888 \fi
889 }
890 % \end{macrocode}
891 % \end{macro}
892 %
893 % \begin{macro}{\FSShift}
894 % The \verb|\FSShift| macro is fairly simple: if the stack is properly defined
895 % and the stack-top is greater than or equal to the stack-bottom, then we undefine
896 % the `bottom' macro and up-step the stack-bottom and adjust the stack-size.
897 % \begin{macrocode}
898 %txs\FSShift{fifoStackName}#
899 \newcommand\FSShift[1]{%
900 \ifx\csname #1@fifo@stack@count@bottom\endcsname\relax
901 \PackageError{fifo-stack}{Undefined FIFO/stack #1}%
902 {You should first create the FIFO/stack with \FSCreate}%
903 \else
904 \tmp@fifo@stack@top\csname #1@fifo@stack@count@top\endcsname\relax
905 \tmp@fifo@stack@bottom\csname #1@fifo@stack@count@bottom\endcsname\relax
906 \ifnum\tmp@fifo@stack@top<\tmp@fifo@stack@bottom\relax\else
907 \expandafter\global\expandafter\let
908 \csname #1@\fifo@stack@pointer\tmp@fifo@stack@bottom\endcsname=
909 \fifo@stack@never@defined\relax
910 \advance\tmp@fifo@stack@bottom by 1\relax
911 \expandafter\xdef\csname #1@fifo@stack@count@bottom\endcsname
912 {\the\tmp@fifo@stack@bottom}%
913 \tmp@fifo@stack@size\csname #1@fifo@stack@count@size\endcsname\relax
914 \global\advance\tmp@fifo@stack@size by -1\relax
915 \expandafter\xdef\csname #1@fifo@stack@count@size\endcsname
916 {\the\tmp@fifo@stack@size}%
917 \fi
918 \fi
919 }
920 % \end{macrocode}
921 % \end{macro}
922 %
923 % Again, a debug only macro for the FIFO usage.
924 % \begin{macro}{\FSShowBottom}
925 % \begin{macrocode}
926 %txs\FSShowBottom{fifoStackName}#
927 \newcommand\FSShowBottom[1]{%
928 {\edef\fifo@stack@bottom{\FSBottom{#1}}%
929 \typeout{The bottom of #1: \fifo@stack@bottom}}}
930 % \end{macrocode}
931 % \end{macro}
932 %
933 % \subsection{FIFO/stack length macro definition}
934 %
935 % \begin{macro}{\FSSize}
936 %
937 % We keep track of the changes to the stack-size in each of the \verb|\FSPush|,
938 % \verb|\FSPop|, \verb|\FSUnshift|, and \verb|\FSShift| macros, since actually
939 % computing the value in the \verb|\FSSize| macro (below) was returning spurious
940 % tokens.
941 %
942 % \begin{macrocode}
943 %txs\FSSize{fifoStackName}#
944 \newcommand\FSSize[1]{\csname #1@fifo@stack@count@size\endcsname}
945 % \end{macrocode}
946 % \end{macro}
947 %
948 % \subsection{Finishing off}
949 %
950 % \begin{macrocode}
951 %</package>
952 %<*qstest>
953 \LogClose{lgout}
954 \stop
955 %</qstest>
956 % \end{macrocode}
957 %