Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % !TEX program = pdfLaTeX
3
4 %<*internal>
5 \iffalse
6 %</internal>
7
8 %<*readme>
9 ----------------------------------------------------------------------
10 `counterz' --- 2023/06/05 Version 1.1.1
11
12 Copyright (C) 2023 by Christopher McClain
13 E-mail: [email protected]
14
15 Released under the LaTeX Project Public License v1.3c or later
16 See https://www.latex-project.org/lppl.txt
17 ----------------------------------------------------------------------
18
19 The `counterz' package provides additional tools for manipulating
20 counters. The package facilitates the use of stealth prefixes for
21 counter names in order to help distinguish between counters from
22 multiple input files. The package also provides a means to generate
23 random counters and save such counter values for future typesetting.
24 %</readme>
25
26 %<*internal>
27 \fi
28 \def\nameofplainTeX{plain}
29 \ifx\fmtname\nameofplainTeX\else
30 \expandafter\begingroup
31 \fi
32 %</internal>
33
34 %<*install>
35 \input docstrip.tex
36 \keepsilent
37 \askforoverwritefalse
38
39 \preamble
40 ----------------------------------------------------------------------
41 `counterz' --- 2023/06/05 Version 1.1.1 Additional tools for counters
42 E-mail: [email protected]
43 Released under the LaTeX Project Public License v1.3c or later
44 See https://www.latex-project.org/lppl.txt
45 ----------------------------------------------------------------------
46
47 \endpreamble
48 \postamble
49
50 Copyright (C) 2023 by Christopher McClain
51
52 This work may be distributed and/or modified under the
53 conditions of the LaTeX Project Public License (LPPL), either
54 version 1.3c of this license or (at your option) any later
55 version. The latest version of this license is in the file:
56
57 https://www.latex-project.org/lppl.txt
58
59 and version 1.3 or later is part of all distributions of
60 LaTeX version 2005/12/01 or later.
61
62 This work has the LPPL maintenance status `maintained'.
63
64 The Current Maintainer of this work is Christopher McClain.
65
66 This work consists of the file counterz.dtx
67 and the derived files counterz.ins,
68 counterz.pdf and
69 counterz.sty.
70
71 \endpostamble
72
73 \usedir{tex/latex/counterz}
74 \generate{
75 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
76 }
77
78 %</install>
79 %<install>\endbatchfile
80
81 %<*internal>
82 \usedir{source/latex/counterz}
83 \generate{
84 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
85 }
86 \nopreamble\nopostamble
87 \usedir{doc/latex/counterz}
88 \generate{
89 \file{README.txt}{\from{\jobname.dtx}{readme}}
90 }
91 \ifx\fmtname\nameofplainTeX
92 \expandafter\endbatchfile
93 \else
94 \expandafter\endgroup
95 \fi
96 %</internal>
97
98 %<*package>
99 \NeedsTeXFormat{LaTeX2e}
100 %</package>
101
102 %<*driver>
103 \documentclass{ltxdoc}
104 \usepackage{\jobname}
105 \usepackage[numbered]{hypdoc}
106 \EnableCrossrefs
107 \DoNotIndex{\addtocounter,\Alph,\alph,\arabic,\begingroup,\boolfalse,\booltrue,
108 \catcode,\endgroup,\fnsymbol,\gdef,\ifbool,\ifboolexpr,\ifnumequal,
109 \ifnumgreater,\ifnumless,\immediate,\jobname,\newcommand,
110 \newcounter,\newbool,\newwrite,\numexpr,\openout,\pdfuniformdeviate,
111 \providecounter,\ProvidesPackage,\relax,\renewcommand,
112 \RequirePackage,\Roman,\roman,\setcounter,\the,\unexpanded,\value,
113 \whileboolexpr,\write,\@ifnextchar,\ifltxcounter,\InputIfFileExists,
114 \m@k@gobbleendoptarg,\MessageBreak,\PackageError,\protect,\space,
115 \typein,\@typein}
116 \CodelineIndex
117 \RecordChanges
118 \begin{document}
119 \DocInput{\jobname.dtx}
120 \end{document}
121 %</driver>
122 %
123 % \fi
124 %
125 %\GetFileInfo{\jobname.sty}
126 %
127 %\title{^^A
128 % The \textsf{counterz} package\thanks{^^A
129 % This file describes version \fileversion, last revised \filedate.^^A
130 % }^^A
131 %}
132 %\author{^^A
133 % Christopher McClain\thanks{E-mail: [email protected]}^^A
134 %}
135 %\date{Released \filedate}
136 %
137 %\maketitle
138 %
139 %\changes{v1.0.0}{2023/05/19}{First public release}
140 %\changes{v1.1.0}{2023/05/30}{New and revised commands and error reports}
141 %\changes{v1.1.1}{2023/06/05}{Bug fixes}
142 %
143 %
144 %\begin{abstract}
145 % The \textsf{counterz} package provides additional tools for manipulating
146 % counters. The package facilitates the use of stealth prefixes for
147 % counter names in order to help distinguish between counters from
148 % multiple input files. The package also provides a means to generate
149 % random counters and save such counter values for future typesetting.
150 %\end{abstract}
151 %
152 %\tableofcontents
153 %
154 %\section{Introduction}
155 %
156 %\subsection{About}
157 %
158 % This project emerged from the author's frequent use of \LaTeX\ counters as
159 % traditional integer type variables when generating mathematics documents with
160 % random elements. While pdf\TeX\ primitives such as \cs{pdfuniformdeviate} may
161 % be used to generate random integers, these integer values will be randomized
162 % with every typesetting. The \textsf{counterz} package provides a way to save
163 % the values of counters. Another \textsf{.tex} file is created so that, if
164 % desired, it can be inputted upon a subsequent typesetting in order to
165 % initialize the counters with the previously generated values. A boolean
166 % variable and accompanying commands allow an author to toggle between reusing
167 % and rerandomizing counters.
168 %
169 % One of the consequences of preloading counter values in large projects with
170 % multiple source files is that one must take care to use distinct counter names
171 % throughout all of the different files. If the file \textsf{Main.tex} inputs
172 % \textsf{File1.tex} and \textsf{File2.tex}, and both input files define the
173 % counter \textit{mycounter}, then this could result in typesetting errors. One
174 % way to address this problem is to prefix every counter name with the file name
175 % or some other marker so that the counter names will actually be distinct. For
176 % example, \textit{File1mycounter} is distinct from \textit{File2mycounter}.
177 % Very long counter names, however, can make code difficult to read and hinder
178 % consistent application of this practice. The \textsf{counterz} package
179 % provides a way to stealthily define and recall such prefixes so that the
180 % shorter non-prefixed names can be used for the manipulation, recall, and
181 % typesetting of counters.
182 %
183 %\subsection{License}
184 %
185 % Copyright \copyright\ 2023 Christopher McClain. This software may be copied,
186 % distributed, and/or modified under the %terms of the
187 % \href{https://www.latex-project.org/lppl/}{LaTeX Project Public License},
188 % either version 1.3c of this license or any later version.
189 %
190 %\subsection{Installation}
191 %
192 % Run (pdf)\TeX{} on counterz.dtx to generate the file counterz.sty, and copy it
193 % to your local texmf directory. To generate both the package file counterz.sty
194 % and the documentation counterz.pdf, run (pdf)\LaTeX{} on counterz.dtx.
195 % Typesetting the documentation requires the package \textsf{hypdoc} which is
196 % included in \TeX\ distributions and at \href{http://www.ctan.org}
197 % {The Comprehensive TeX Archive Network}.
198 %
199 %\section{User Guide}
200 %
201 % To use this package, include the following line in the preamble of your
202 % document:
203 %
204 %\begin{verbatim}
205 %\usepackage{counterz}
206 %\end{verbatim}
207 %
208 % \noindent
209 % The package \textsf{counterz} loads the packages \textsf{etoolbox} and
210 % \textsf{makecmds}, both of which are included in \TeX\ distributions
211 % and at \href{http://www.ctan.org}{The Comprehensive TeX Archive Network}.
212 %
213 %\subsection{Counter Prefixes}
214 %
215 % Counter prefixes are stored in an internal macro whose default value is an
216 % empty string.
217 %\DescribeMacro{\setcounterprefix}
218 % The command \cs{setcounterprefix}\marg{prefix} is used to change this value.
219 % For example, to change the prefix to \textit{PurpleMonkey}, use
220 %
221 %\begin{verbatim}
222 %\setcounterprefix{PurpleMonkey}
223 %\end{verbatim}
224 %
225 % \noindent
226 % and to change it from \textit{PurpleMonkey} to \textit{Dishwasher}, use
227 %
228 %\begin{verbatim}
229 %\setcounterprefix{Dishwasher}
230 %\end{verbatim}
231 %
232 % \noindent
233 %\DescribeMacro{\clearcounterprefix}
234 % The command \cs{clearcounterprefix} returns the prefix to its empty default.
235 %
236 %\subsection{Manipulating Counters}
237 %
238 %\DescribeMacro{\xnewcounter}
239 % The command \cs{xnewcounter}\marg{countername} creates a counter with a
240 % prefixed name.
241 %\DescribeMacro{\xsetcounter}
242 % The command \cs{xsetcounter}\marg{countername}\marg{integer} assigns the
243 % specified value to the counter with the prefixed name. For example, suppose
244 % that the file \textsf{BoringFile1.tex} contains the following:
245 %
246 %\begin{verbatim}
247 %\xnewcounter{bestcounterever}
248 %\xsetcounter{bestcounterever}{100}
249 %\end{verbatim}
250 %
251 % \noindent
252 % and suppose that the file \textsf{BoringFile2.tex} contains the following:
253 %
254 %\begin{verbatim}
255 %\xnewcounter{bestcounterever}
256 %\xsetcounter{bestcounterever}{-29}
257 %\end{verbatim}
258 %
259 % \noindent
260 % and, finally, suppose that the file Main.tex contains (in part) the following:
261 %
262 %\begin{verbatim}
263 %\setcounterprefix{PurpleMonkey}
264 %\input{BoringFile1}
265 %\setcounterprefix{Dishwasher}
266 %\input{BoringFile2}
267 %\end{verbatim}
268 %
269 % \noindent
270 % Then typesetting \textsf{Main.tex} will create a counter
271 % \textit{PurpleMonkeybestcounterever} with the value 100 and a counter
272 % \textit{Dishwasherbestcounterever} with the value $-29$. By using commands
273 % \cs{xnewcounter} and \cs{xsetcounter} instead of \cs{newcounter} and
274 % \cs{setcounter}, \textsf{BoringFile1.tex} and \textsf{BoringFile2.tex}
275 % may be written independently without considering any counter name conflicts.
276 % The distinction between the counters is determined by the prefixes defined
277 % in the file \textsf{Main.tex}. By changing prefixes, \textsf{Main.tex} can
278 % even input the same file multiple times without conflict.
279 %
280 %\DescribeMacro{\xprovidecounter}
281 % The commands \cs{xprovidecounter}, \cs{xaddtocounter}, and \cs{xvalue} are
282 % likewise prefix versions of commands \cs{providecounter}, \cs{addtocounter},
283 %\DescribeMacro{\xaddtocounter}
284 % and \cs{value}, respectively. When the prefix is empty, the commands expand
285 %\DescribeMacro{\xvalue}
286 % like their standard counterparts. (Note: \cs{providecounter} defines a counter
287 % if it has not already been defined. See the documentation for the package
288 % \textsf{makecmds} for details.)
289 %
290 %\subsection{Conditional Statements}
291 %
292 %\DescribeMacro{\ifctrequal}
293 % The command \cs{ifctrequal}\marg{counter1}\marg{counter2}\marg{foo}\marg{bar}
294 % uses the command \cs{xvalue} to compare the values of the (prefixed) counters
295 % and then executes \meta{foo} if the values are equal and otherwise executes
296 % \meta{bar}. The commands
297 %\DescribeMacro{\ifctrless}
298 % \cs{ifctrless} and \cs{ifctrmore} work analogously, based on whether the value
299 % of prefixed \meta{counter1} is less than that of of prefixed \meta{counter2}
300 %\DescribeMacro{\ifctrmore}
301 % or more than that of prefixed \meta{counter2}, respectively. Consider the
302 % example code
303 %
304 %\begin{verbatim}
305 %\setcounterprefix{TigerTiger}
306 %\xnewcounter{Small}
307 %\xsetcounter{Small}{7}
308 %\xnewcounter{Large}
309 %\xsetcounter{Large}{11}
310 %\ifctrequal{Small}{Large}{January}{February}
311 %\ifctrless{Small}{Large}{March}{April}
312 %\ifctrmore{Small}{Large}{May}{June}
313 %\end{verbatim}
314 %
315 % \noindent
316 % which produces the output
317 %
318 % \bigskip
319 %\setcounterprefix{TigerTiger}
320 %\xnewcounter{Small}
321 %\xsetcounter{Small}{7}
322 %\xnewcounter{Large}
323 %\xsetcounter{Large}{11}
324 %\ifctrequal{Small}{Large}{January}{February}
325 %\ifctrless{Small}{Large}{March}{April}
326 %\ifctrmore{Small}{Large}{May}{June}
327 %
328 % \bigskip
329 % \noindent
330 % because the value of the counter \textit{TigerTigerSmall} is 7 which is less
331 % than 11, the value of the counter \textit{TigerTigerLarge}.
332 %
333 %\DescribeMacro{\ifctrzero}
334 % The command \cs{ifctrzero}\marg{counter}\marg{foo}\marg{bar} executes
335 % \meta{foo} if the value of the (prefixed) counter is zero and otherwise
336 % executes \meta{bar}. The commands
337 %\DescribeMacro{\ifctrneg}
338 % \cs{ifctrneg} and \cs{ifctrpos} work analogously based on whether the value
339 %\DescribeMacro{\ifctrpos}
340 % is negative or positive, respectively. The example code
341 %
342 %\begin{verbatim}
343 %\setcounterprefix{TigerTiger}
344 %\xprovidecounter{Small}
345 %\xsetcounter{Small}{7}
346 %\ifctrzero{Small}{January}{February}
347 %\ifctrneg{Small}{March}{April}
348 %\ifctrpos{Small}{May}{June}
349 %\end{verbatim}
350 %
351 % \noindent
352 % produces the output
353 %
354 % \bigskip
355 %\setcounterprefix{TigerTiger}
356 %\xprovidecounter{Small}
357 %\xsetcounter{Small}{7}
358 %\ifctrzero{Small}{January}{February}
359 %\ifctrneg{Small}{March}{April}
360 %\ifctrpos{Small}{May}{June}
361 %
362 % \bigskip
363 % \noindent
364 % because the value of the counter \textit{TigerTigerSmall} is 7 which is
365 % positive (and thus nonzero, as well).
366 %
367 %\subsection{Displaying Counters}
368 %
369 %\DescribeMacro{\xarabic}
370 % The command \cs{xarabic}\marg{counter} is simply a prefix version of the
371 % standard display command \cs{arabic}.
372 %\DescribeMacro{\xroman}
373 % The commands \cs{xroman}, \cs{xRoman}, \cs{xalph}, \cs{xAlph}, and
374 %\DescribeMacro{\xRoman}
375 % \cs{xfnsymbol} are likewise prefix versions of the standard display commands
376 %\DescribeMacro{\xalph}
377 % \cs{roman}, \cs{Roman}, \cs{alph}, \cs{Alph}, and \cs{fnsymbol}, inheriting
378 % the restrictions of their
379 %\DescribeMacro{\xAlph}
380 % parent commands.
381 %
382 %\DescribeMacro{\xfnsymbol}
383 % Note that the code
384 %
385 %\begin{verbatim}
386 %\setcounterprefix{Sneaky}
387 %\xprovidecounter{Pete}
388 %\xsetcounter{Pete}{42}
389 %\arabic{Pete}
390 %\end{verbatim}
391 %
392 % \noindent
393 % produces an error because the counter \textit{Pete} is not defined, but the
394 % code
395 %
396 %\begin{verbatim}
397 %\setcounterprefix{Sneaky}
398 %\xprovidecounter{Pete}
399 %\xsetcounter{Pete}{42}
400 %\xarabic{Pete}
401 %\end{verbatim}
402 %
403 % \noindent
404 % produces the output
405 %
406 % \bigskip
407 %\setcounterprefix{Sneaky}
408 %\xprovidecounter{Pete}
409 %\xsetcounter{Pete}{42}
410 %\xarabic{Pete}
411 %
412 % \bigskip
413 % \noindent
414 % which is the value of the counter \textit{SneakyPete}. The code
415 %
416 %\begin{verbatim}
417 %\setcounterprefix{Sneaky}
418 %\xprovidecounter{Pete}
419 %\xsetcounter{Pete}{42}
420 %\clearcounterprefix
421 %\xarabic{Pete}
422 %\end{verbatim}
423 %
424 % \noindent
425 % also generates error because the final line is trying to use the
426 % undefined counter \textit{Pete} after the prefix was returned to its
427 % default value.
428 %
429 % In addition to prefix versions of the standard display commands, the package
430 % \textsf{counterz} defines some variants of \cs{xarabic} that are useful in
431 % the display of mathematical expressions. For example, consider the following
432 % code:
433 %
434 %\begin{verbatim}
435 %\xprovidecounter{a}
436 %\xsetcounter{a}{5}
437 %\xprovidecounter{b}
438 %\xsetcounter{b}{0}
439 %\xprovidecounter{c}
440 %\xsetcounter{c}{-7}
441 %$\xarabic{a}+\xarabic{b}+\xarabic{c}$
442 %\end{verbatim}
443 %
444 % \noindent
445 % which produces
446 %
447 % \bigskip
448 %\xprovidecounter{a}
449 %\xsetcounter{a}{5}
450 %\xprovidecounter{b}
451 %\xsetcounter{b}{0}
452 %\xprovidecounter{c}
453 %\xsetcounter{c}{-7}
454 %$\xarabic{a}+\xarabic{b}+\xarabic{c}$
455 %
456 % \bigskip
457 % \noindent
458 % Using \cs{arabicx} causes the expression to contain the consecutive pair $+-$.
459 % The command \cs{xsigned}\marg{counter} is like \cs{xarabic} except that
460 %\DescribeMacro{\xsigned}
461 % nonnegative values are preceded by a plus sign ``+''. The code
462 %
463 %\begin{verbatim}
464 %$\xarabic{a}\xsigned{b}\xsigned{c}$
465 %\end{verbatim}
466 %
467 % \noindent
468 % produces
469 %
470 % \bigskip
471 %$\xarabic{a}\xsigned{b}\xsigned{c}$
472 %
473 % \bigskip
474 % \noindent
475 % If we wish to suppress the $0$, we can instead use the command
476 %\DescribeMacro{\xsignednz}
477 % \cs{xsignednz}\marg{counter} which is a nonzero version of \cs{xsigned} and,
478 % if desired or necessary, the command \cs{xarabicnz}\marg{counter} which is a
479 %\DescribeMacro{\xarabicnz}
480 % nonzero version of \cs{xarabic}. The code
481 %
482 %\begin{verbatim}
483 %$\xarabicnz{a}\xsignednz{b}\xsignednz{c}$
484 %\end{verbatim}
485 %
486 % \noindent
487 % produces
488 %
489 % \bigskip
490 %$\xarabicnz{a}\xsignednz{b}\xsignednz{c}$
491 %
492 % \bigskip
493 % \noindent
494 %\DescribeMacro{\xnegof}
495 % The command \cs{xnegof}\marg{counter} displays the negative of \meta{counter}.
496 % The command \cs{xnegofnz} does the same except that it suppresses the number
497 %\DescribeMacro{\xnegofnz}
498 % zero. The command \cs{xnegsigned} includes the appropriate signs of plus ``+''
499 %\DescribeMacro{\xnegsigned}
500 % and minus ``-'' (assigning a minus to zero in this case).
501 %\DescribeMacro{\xnegsignednz}
502 % Finally, the command \cs{xnegsignednz} does the same except that it suppresses
503 % the number zero., as demonstrated by the following code:
504 %
505 %\begin{verbatim}
506 %\xprovidecounter{d}
507 %\xsetcounter{d}{-2}
508 %
509 %$\xarabic{a}\xsigned{b}\xsigned{c}=\xarabic{d}$
510 %
511 %$\xnegof{d}=\xnegof{a}\xnegsigned{b}\xnegsigned{c}$
512 %
513 %$\xnegofnz{d}=\xnegofnz{a}\xnegsignednz{b}\xnegsignednz{c}$
514 %\end{verbatim}
515 %
516 % \noindent
517 % which produces
518 %
519 % \bigskip
520 %\xprovidecounter{d}
521 %\xsetcounter{d}{-2}
522 %
523 %$\xarabic{a}\xsigned{b}\xsigned{c}=\xarabic{d}$
524 %
525 %$\xnegof{d}=\xnegof{a}\xnegsigned{b}\xnegsigned{c}$
526 %
527 %$\xnegofnz{d}=\xnegofnz{a}\xnegsignednz{b}\xnegsignednz{c}$
528 %
529 % \bigskip
530 % The preceding commands for displaying values related to counters were created
531 % by using some other commands that we make available in case they prove useful.
532 %\DescribeMacro{\xabsof}
533 % The command \cs{xabsof}\marg{counter} prints the absolute value of
534 % \meta{counter}. The command \cs{xsignof}\marg{counter} prints a minus sign
535 %\DescribeMacro{\xsignof}
536 % ``-'' if \meta{counter} is negative and otherwise prints a plus sign ``+''.
537 % (Note that the latter case includes the value zero.) The command
538 %\DescribeMacro{\xnegsignof}
539 % \cs{xnegsignof}\marg{counter} prints a plus sign ``+'' if \meta{counter} is
540 % negative and otherwise prints a minus sign ``-''. (Note that the latter case
541 % includes the value zero.)
542 %
543 % Additional variants of these commands suppress certain output, as is
544 % conventional when using integers as coefficients in algebraic expressions.
545 % The command \cs{xabsofcoef}\marg{counter} prints the absolute value of
546 %\DescribeMacro{\xabsofcoef}
547 % \meta{counter} except that it suppresses the values of 1 and 0. The command
548 %\DescribeMacro{\xsignofcoef}
549 % \cs{xsignofcoef}\marg{counter} prints the sign of \meta{counter} if the value
550 % of \meta{counter} is nonzero. The command \cs{xnegsignofcoef}\marg{counter}
551 %\DescribeMacro{\xnegsignofcoef}
552 % prints the opposite sign of \meta{counter} if the value of \meta{counter} is
553 % nonzero. These commands are used to build versions of \cs{xarabic} and
554 % \cs{xsigned} specific to typesetting coefficients, as we now illustrate.
555 %
556 % Consider the following code
557 %
558 %\begin{verbatim}
559 %\xprovidecounter{a0}
560 %\xsetcounter{a0}{-10}
561 %\xprovidecounter{a1}
562 %\xsetcounter{a1}{1}
563 %\xprovidecounter{a2}
564 %\xsetcounter{a2}{-5}
565 %\xprovidecounter{a3}
566 %\xsetcounter{a3}{-1}
567 %\xprovidecounter{a4}
568 %\xsetcounter{a4}{0}
569 %\xprovidecounter{a5}
570 %\xsetcounter{a5}{11}
571 %$\xarabic{a5}x^5 + \xarabic{a4}x^4 + \xarabic{a3}x^3 + \xarabic{a2}x^2
572 % + \xarabic{a1}x + \xarabic{a0} = 42$
573 %\end{verbatim}
574 %
575 % \noindent
576 % and its output
577 %
578 % \bigskip
579 %\xprovidecounter{a0}
580 %\xsetcounter{a0}{-10}
581 %\xprovidecounter{a1}
582 %\xsetcounter{a1}{1}
583 %\xprovidecounter{a2}
584 %\xsetcounter{a2}{-5}
585 %\xprovidecounter{a3}
586 %\xsetcounter{a3}{-1}
587 %\xprovidecounter{a4}
588 %\xsetcounter{a4}{0}
589 %\xprovidecounter{a5}
590 %\xsetcounter{a5}{11}
591 %$\xarabic{a5}x^5 + \xarabic{a4}x^4 + \xarabic{a3}x^3 + \xarabic{a2}x^2
592 % + \xarabic{a1}x + \xarabic{a0} = 42$
593 %
594 % \bigskip
595 % \noindent
596 % We seek a better way to handle the coefficients, especially $1$ and $-1$. The
597 % command \cs{xcoef}\marg{counter} prints the value of \meta{counter} except
598 %\DescribeMacro{\xcoef}
599 % that it suppresses the values of 1, 0, and -1, printing a minus sign ``-'' in
600 % the latter case. The command \cs{xsignedcoef}\marg{counter} is like \cs{xcoef}
601 %\DescribeMacro{\xsignedcoef}
602 % except that positive values are preceded by a plus sign ``+''. We use these to
603 % write the code
604 %
605 %\begin{verbatim}
606 %$\xarabic{a5}x^5 + \xarabic{a4}x^4 + \xarabic{a3}x^3 + \xarabic{a2}x^2
607 % + \xarabic{a1}x + \xarabic{a0} = 42$
608 %
609 %$\xcoef{a5}\ifctrzero{a5}{}{x^5}
610 % \xsignedcoef{a4}\ifctrzero{a4}{}{x^4}
611 % \xsignedcoef{a3}\ifctrzero{a3}{}{x^3}
612 % \xsignedcoef{a2}\ifctrzero{a2}{}{x^2}
613 % \xsignedcoef{a1}\ifctrzero{a1}{}{x}
614 % \xsignednz{a0}
615 % = 42$
616 %\end{verbatim}
617 %
618 % \noindent
619 % whose output is
620 %
621 % \bigskip
622 %$\xarabic{a5}x^5 + \xarabic{a4}x^4 + \xarabic{a3}x^3 + \xarabic{a2}x^2
623 % + \xarabic{a1}x + \xarabic{a0} = 42$
624 %
625 %$\xcoef{a5}\ifctrzero{a5}{}{x^5}
626 % \xsignedcoef{a4}\ifctrzero{a4}{}{x^4}
627 % \xsignedcoef{a3}\ifctrzero{a3}{}{x^3}
628 % \xsignedcoef{a2}\ifctrzero{a2}{}{x^2}
629 % \xsignedcoef{a1}\ifctrzero{a1}{}{x}
630 % \xsignednz{a0}
631 % = 42$
632 %
633 % \bigskip
634 %\DescribeMacro{\xnegcoef}
635 % The command \cs{xnegcoef}\marg{counter} prints the negative of the value of
636 % \meta{counter} except that it suppresses the values of 1, 0, and -1, printing
637 % a ``-'' in the latter case. The command \cs{xnegsignedcoef}\marg{counter} is
638 %\DescribeMacro{\xnegsignedcoef}
639 % like \cs{xnegcoef} except that positive values are preceded by a plus sign
640 % ``+''. We use these to write the code
641 %
642 %\begin{verbatim}
643 %$\xcoef{a5}\ifctrzero{a5}{}{x^5}
644 % \xsignedcoef{a4}\ifctrzero{a4}{}{x^4}
645 % \xsignedcoef{a3}\ifctrzero{a3}{}{x^3}
646 % \xsignedcoef{a2}\ifctrzero{a2}{}{x^2}
647 % \xsignedcoef{a1}\ifctrzero{a1}{}{x}
648 % \xsignednz{a0}
649 % = 42$
650 %
651 %$\xcoef{a5}\ifctrzero{a5}{}{x^5}
652 % \xsignedcoef{a4}\ifctrzero{a4}{}{x^4}
653 % \xsignedcoef{a2}\ifctrzero{a2}{}{x^2}
654 % \xsignednz{a0}
655 % = \xnegcoef{a3}\ifctrzero{a3}{}{x^3}
656 % \xnegsignedcoef{a1}\ifctrzero{a1}{}{x}
657 % +42$
658 %\end{verbatim}
659 %
660 % \noindent
661 % whose output is
662 %
663 % \bigskip
664 %$\xcoef{a5}\ifctrzero{a5}{}{x^5}
665 % \xsignedcoef{a4}\ifctrzero{a4}{}{x^4}
666 % \xsignedcoef{a3}\ifctrzero{a3}{}{x^3}
667 % \xsignedcoef{a2}\ifctrzero{a2}{}{x^2}
668 % \xsignedcoef{a1}\ifctrzero{a1}{}{x}
669 % \xsignednz{a0}
670 % = 42$
671 %
672 %$\xcoef{a5}\ifctrzero{a5}{}{x^5}
673 % \xsignedcoef{a4}\ifctrzero{a4}{}{x^4}
674 % \xsignedcoef{a2}\ifctrzero{a2}{}{x^2}
675 % \xsignednz{a0}
676 % = \xnegcoef{a3}\ifctrzero{a3}{}{x^3}
677 % \xnegsignedcoef{a1}\ifctrzero{a1}{}{x}
678 % +42$
679 %
680 % \bigskip
681 % As the reader has probably already observed in the code above, these display
682 % commands appear to be less efficient than a manual adjustment of signs and
683 % numbers. For fixed, known values of counters, this assessment is correct. The
684 % real utility of these commands is not apparent until they are combined with
685 % randomly generated counter values.
686 %
687 %\subsection{Random Counters}
688 %
689 % In order to effectively manage the options of randomizing counter values or
690 %\DescribeMacro{\randomizectr}
691 % reusing counter values, the commands \cs{randomizectr} and \cs{norandomizectr}
692 % are used to toggle an internal boolean variable. The internal boolean
693 %\DescribeMacro{\norandomizectr}
694 % is initialized as TRUE when the \textsf{counterz} package is loaded. A
695 % conditional command \cs{ifrandomizectr}\marg{foo}\marg{bar} executes
696 %\DescribeMacro{\ifrandomizectr}
697 % \meta{foo} when the boolean is TRUE and otherwise executes \meta{bar}.
698 %
699 % We next define random versions of \cs{setcounter} and \cs{addtocounter}.
700 % These commands will only execute when the document is set to randomize.
701 % The command \cs{randsetcounter}\marg{counter}\marg{min}\marg{max} assigns
702 %\DescribeMacro{\randsetcounter}
703 % to \meta{counter} a random integer value between \meta{min} and \meta{max}.
704 %\DescribeMacro{\xrandsetcounter}
705 % The command \cs{xrandsetcounter} is a prefix version of \cs{randsetcounter}.
706 % Analogously, we define the command
707 %\DescribeMacro{\randaddtocounter}
708 % \cs{randaddtocounter}\marg{counter}\marg{min}\marg{max} which adds to
709 % \meta{counter} a random integer value between \meta{min} and \meta{max}.
710 %\DescribeMacro{\xrandaddtocounter}
711 % \cs{xrandaddtocounter} is a prefix version of \cs{randaddtocounter}.
712 % The following code produces an expression in the form $ax+b$, where $a$
713 % and $b$ are random integers between $-10$ and $10$:
714 %
715 %\begin{verbatim}
716 %\randomizectr
717 %\xprovidecounter{a}
718 %\xprovidecounter{b}
719 %\xrandsetcounter{a}{-10}{10}
720 %\xrandsetcounter{b}{-10}{10}
721 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$
722 %\end{verbatim}
723 %
724 % \noindent
725 % Organized in the following table are fifty instances of output that are
726 % randomly generated by the typesetting of this document:
727 %
728 % \bigskip
729 %\noindent
730 %\xprovidecounter{a}
731 %\xprovidecounter{b}
732 %\begin{tabular}{rrrrr}
733 %\xrandsetcounter{a}{-10}{10}
734 %\xrandsetcounter{b}{-10}{10}
735 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
736 %\xrandsetcounter{a}{-10}{10}
737 %\xrandsetcounter{b}{-10}{10}
738 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
739 %\xrandsetcounter{a}{-10}{10}
740 %\xrandsetcounter{b}{-10}{10}
741 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
742 %\xrandsetcounter{a}{-10}{10}
743 %\xrandsetcounter{b}{-10}{10}
744 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
745 %\xrandsetcounter{a}{-10}{10}
746 %\xrandsetcounter{b}{-10}{10}
747 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
748 %\xrandsetcounter{a}{-10}{10}
749 %\xrandsetcounter{b}{-10}{10}
750 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
751 %\xrandsetcounter{a}{-10}{10}
752 %\xrandsetcounter{b}{-10}{10}
753 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
754 %\xrandsetcounter{a}{-10}{10}
755 %\xrandsetcounter{b}{-10}{10}
756 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
757 %\xrandsetcounter{a}{-10}{10}
758 %\xrandsetcounter{b}{-10}{10}
759 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
760 %\xrandsetcounter{a}{-10}{10}
761 %\xrandsetcounter{b}{-10}{10}
762 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
763 %\xrandsetcounter{a}{-10}{10}
764 %\xrandsetcounter{b}{-10}{10}
765 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
766 %\xrandsetcounter{a}{-10}{10}
767 %\xrandsetcounter{b}{-10}{10}
768 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
769 %\xrandsetcounter{a}{-10}{10}
770 %\xrandsetcounter{b}{-10}{10}
771 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
772 %\xrandsetcounter{a}{-10}{10}
773 %\xrandsetcounter{b}{-10}{10}
774 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
775 %\xrandsetcounter{a}{-10}{10}
776 %\xrandsetcounter{b}{-10}{10}
777 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
778 %\xrandsetcounter{a}{-10}{10}
779 %\xrandsetcounter{b}{-10}{10}
780 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
781 %\xrandsetcounter{a}{-10}{10}
782 %\xrandsetcounter{b}{-10}{10}
783 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
784 %\xrandsetcounter{a}{-10}{10}
785 %\xrandsetcounter{b}{-10}{10}
786 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
787 %\xrandsetcounter{a}{-10}{10}
788 %\xrandsetcounter{b}{-10}{10}
789 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
790 %\xrandsetcounter{a}{-10}{10}
791 %\xrandsetcounter{b}{-10}{10}
792 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
793 %\xrandsetcounter{a}{-10}{10}
794 %\xrandsetcounter{b}{-10}{10}
795 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
796 %\xrandsetcounter{a}{-10}{10}
797 %\xrandsetcounter{b}{-10}{10}
798 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
799 %\xrandsetcounter{a}{-10}{10}
800 %\xrandsetcounter{b}{-10}{10}
801 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
802 %\xrandsetcounter{a}{-10}{10}
803 %\xrandsetcounter{b}{-10}{10}
804 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
805 %\xrandsetcounter{a}{-10}{10}
806 %\xrandsetcounter{b}{-10}{10}
807 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
808 %\xrandsetcounter{a}{-10}{10}
809 %\xrandsetcounter{b}{-10}{10}
810 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
811 %\xrandsetcounter{a}{-10}{10}
812 %\xrandsetcounter{b}{-10}{10}
813 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
814 %\xrandsetcounter{a}{-10}{10}
815 %\xrandsetcounter{b}{-10}{10}
816 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
817 %\xrandsetcounter{a}{-10}{10}
818 %\xrandsetcounter{b}{-10}{10}
819 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
820 %\xrandsetcounter{a}{-10}{10}
821 %\xrandsetcounter{b}{-10}{10}
822 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
823 %\xrandsetcounter{a}{-10}{10}
824 %\xrandsetcounter{b}{-10}{10}
825 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
826 %\xrandsetcounter{a}{-10}{10}
827 %\xrandsetcounter{b}{-10}{10}
828 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
829 %\xrandsetcounter{a}{-10}{10}
830 %\xrandsetcounter{b}{-10}{10}
831 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
832 %\xrandsetcounter{a}{-10}{10}
833 %\xrandsetcounter{b}{-10}{10}
834 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
835 %\xrandsetcounter{a}{-10}{10}
836 %\xrandsetcounter{b}{-10}{10}
837 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
838 %\xrandsetcounter{a}{-10}{10}
839 %\xrandsetcounter{b}{-10}{10}
840 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
841 %\xrandsetcounter{a}{-10}{10}
842 %\xrandsetcounter{b}{-10}{10}
843 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
844 %\xrandsetcounter{a}{-10}{10}
845 %\xrandsetcounter{b}{-10}{10}
846 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
847 %\xrandsetcounter{a}{-10}{10}
848 %\xrandsetcounter{b}{-10}{10}
849 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
850 %\xrandsetcounter{a}{-10}{10}
851 %\xrandsetcounter{b}{-10}{10}
852 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
853 %\xrandsetcounter{a}{-10}{10}
854 %\xrandsetcounter{b}{-10}{10}
855 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
856 %\xrandsetcounter{a}{-10}{10}
857 %\xrandsetcounter{b}{-10}{10}
858 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
859 %\xrandsetcounter{a}{-10}{10}
860 %\xrandsetcounter{b}{-10}{10}
861 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
862 %\xrandsetcounter{a}{-10}{10}
863 %\xrandsetcounter{b}{-10}{10}
864 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
865 %\xrandsetcounter{a}{-10}{10}
866 %\xrandsetcounter{b}{-10}{10}
867 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
868 %\xrandsetcounter{a}{-10}{10}
869 %\xrandsetcounter{b}{-10}{10}
870 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
871 %\xrandsetcounter{a}{-10}{10}
872 %\xrandsetcounter{b}{-10}{10}
873 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
874 %\xrandsetcounter{a}{-10}{10}
875 %\xrandsetcounter{b}{-10}{10}
876 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
877 %\xrandsetcounter{a}{-10}{10}
878 %\xrandsetcounter{b}{-10}{10}
879 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ &
880 %\xrandsetcounter{a}{-10}{10}
881 %\xrandsetcounter{b}{-10}{10}
882 %$\xcoef{a}\ifctrzero{a}{\xarabic{b}}{x \xsignednz{b}}$ \\
883 %\end{tabular}
884 %
885 % \bigskip
886 % If our document contains randomly generated counters, but we wish to typeset
887 % the document again without changing those values, then we need a way to save
888 %\DescribeMacro{\opencountersfile}
889 % them. The command \cs{opencountersfile} creates and opens the write stream to
890 % the file \textsf{\meta{jobname}.counters.tex} to store the necessary
891 % information. For example, if the document is
892 % named \textsf{Yellowdog.tex}, then the previously generated counters and their
893 % assigned values will be stored the file \textsf{Yellowdog.counters.tex}.
894 % The author only has to include this command once, prior to any commands used
895 % to save the counter values. Additional instances of \cs{opencountersfile} will
896 % report an error, as will trying to use the command when the document is set to
897 % not randomize (e.g. \cs{norandomizectr}). These error reports are designed to
898 % prevent the accidental overwriting of \textsf{\meta{jobname}.counters.tex}.
899 %
900 % After opening the write stream to \textsf{\meta{jobname}.counters.tex}, the
901 % command \cs{savecounter}\marg{counter} may be used to ``save'' the value of
902 %\DescribeMacro{\savecounter}
903 % \textit{counter} by writing to the file the relevant \cs{providecounter} and
904 % \cs{setcounter} commands. The command \cs{xsavecounter} is a prefix version of
905 %\DescribeMacro{\xsavecounter}
906 % \cs{savecounter}. When using \cs{xsavecounter}, the commands that are written
907 % to the file include the necessary counter prefixes. Consequently, an author
908 % can, if necessary or desired, manually search the file for the value assigned
909 % to any randomly generated counter.
910 %
911 % Once we have generated a file for storing counters, we need a way to recover
912 % those values during a subsequent typesetting. The command
913 %\DescribeMacro{\inputcountersfile}
914 % \cs{inputcountersfile} will input the necessary file, if it exists, and report
915 % an error if it does not. Keep in mind that inputting the file will override
916 % any previous assignments of those counters, so it is probably best to invoke
917 % this command near the beginning of a document. For example, after including an
918 % instance of either \cs{randomizectr} or \cs{norandomizectr}, a document named
919 % \textsf{Yellowdog.tex} might include the code
920 %
921 %\begin{verbatim}
922 %\ifrandomizectr{\opencountersfile}{\inputcountersfile}
923 %\end{verbatim}
924 %
925 % \noindent
926 % to determine whether to preload previously stored counter values or open the
927 % write stream in anticipation of randomly generating new counter values.
928 %
929 %\DescribeMacro{\promptrandomizectr}
930 % The command \cs{promptrandomizectr}\oarg{macro}\marg{message}\marg{string}
931 % offers an alternative to manually switching between the commands
932 % \cs{randomizectr} and \cs{norandomizectr} for different typesettings. The
933 % contents of \meta{message} are displayed in the terminal, awaiting a response
934 % from the user at the prompt \meta{macro}. If the optional argument is not used
935 % then the default prompt is \cs{@typein}. If the optional argument is given, it
936 % must be a macro name that includes the backslash. The user's response is
937 % stored as a string in \meta{macro} and compared to \meta{string}. If they are
938 % equal, then the command \cs{randomizectr} is executed. If they are not equal
939 % then \cs{norandomizectr} is executed.
940 %
941 % Consider the following example code:
942 %
943 %\begin{verbatim}
944 %\promptrandomizectr[\EnterResponse]{%
945 % ^^J Enter 1 to randomize.
946 % ^^J Enter 2 to not randomize.
947 %}{%
948 % 1%
949 %}%
950 %\ifrandomizectr{%
951 % \opencountersfile
952 %}{%
953 % \inputcountersfile
954 %}%
955 %\end{verbatim}
956 %
957 % \noindent
958 % which displays the following in the terminal:
959 %
960 %\begin{verbatim}
961 % Enter 1 to randomize.
962 % Enter 2 to not randomize.
963 %
964 %\EnterResponse=
965 %\end{verbatim}
966 %
967 % \noindent
968 % Notice that the first (optional) argument \cs{EnterResponse} begins with a
969 % backslash and is displayed with an equals sign ``='' at the prompt. Also note
970 % that the second argument contains two instances of the text \texttt{\^{}\^{}J}
971 % which is used to produce a line break in the terminal output. Next, note that
972 % the third argument \texttt{1} is immediately followed by a percent symbol
973 % \texttt{\%} to prevent extra space being included in the string. (If the
974 % \texttt{1} was immediately followed by a closing brace instead of a line break
975 % in the code, the percent symbol would not be used.) Finally, note that if the
976 % user types a \texttt{1} in the terminal and presses Enter, then the commands
977 % \cs{randomizectr} and \cs{opencountersfile} will be executed. If the user
978 % enters \textit{any other text} or simply presses Enter with no text, then the
979 % commands \cs{norandomizectr} and \cs{inputcountersfile} will be executed,
980 % despite the instructions to enter a \texttt{2} to achieve this outcome.
981 %
982 %\DescribeMacro{\randprovidecounter}
983 % The command \cs{randprovidecounter}\marg{counter}\marg{min}\marg{max}
984 % combines the four commands \cs{providecounter}, \cs{ifrandomizectr},
985 % \cs{randsetcounter}, and \cs{savecounter}. The command creates \meta{counter}
986 % if it has not already been defined and, if the document is
987 % randomized, assigns to \meta{counter} a random integer value between
988 % \meta{min} and \meta{max} and saves this value to the counters file. The
989 %\DescribeMacro{\randprovidecounternz}
990 % command \cs{randprovidecounternz} is like \cs{randprovidecounter} except
991 %\DescribeMacro{\xrandprovidecounter}
992 % that the generated value is nonzero. The commands \cs{xrandprovidecounter} and
993 %\DescribeMacro{\xrandprovidecounternz}
994 % \cs{xrandprovidecounternz} are prefix versions of \cs{randprovidecounter} and
995 % \cs{randprovidecounternz}, respectively. Suppose that \textsf{Neverending.tex}
996 % contains the code
997 %
998 %\begin{verbatim}
999 %\randomizectr
1000 %\ifrandomizectr{\opencountersfile}{}
1001 %\setcounterprefix{Southern}
1002 %\xrandprovidecounternz{Oracle}{-10}{10}
1003 %\xcoef{Oracle}x+42
1004 %\end{verbatim}
1005 %
1006 % \noindent
1007 % After typesetting once, the resulting document might display an expression
1008 % such as $-9x+42$ and print to \textsf{Neverending.counters.tex} the line
1009 %
1010 %\begin{verbatim}
1011 %\providecounter {SouthernOracle} \setcounter {SouthernOracle}{-9}
1012 %\end{verbatim}
1013 %
1014 % \noindent
1015 % After typesetting a second time, the resulting document might display $4x+42$
1016 % and print to \textsf{Neverending.counters.tex} the line
1017 %
1018 %\begin{verbatim}
1019 %\providecounter {SouthernOracle} \setcounter {SouthernOracle}{4}
1020 %\end{verbatim}
1021 %
1022 % \noindent
1023 % If, however, the command \cs{randomizectr} is replaced by \cs{norandomizectr},
1024 % then a third typesetting will leave both the displayed text and the counters
1025 % file unchanged.
1026 %
1027 %\StopEventually{^^A
1028 % \PrintChanges
1029 % \PrintIndex
1030 %}
1031 %
1032 %\section{Implementation}
1033 %
1034 % The \textsf{counterz} package loads the two packages \textsf{etoolbox} and
1035 % \textsf{makecmds} for the use of conditional tests (boolean and numerical)
1036 % and the macro \cs{providecounter}.
1037 %
1038 % \begin{macrocode}
1039 %<*package>
1040 \ProvidesPackage{counterz}[%
1041 2023/06/05 v1.1.1 Additional tools for counters
1042 ]%
1043 \RequirePackage{etoolbox,makecmds}
1044 % \end{macrocode}
1045 %
1046 %\subsection{Counter Prefixes}
1047 %
1048 %\begin{macro}{\@counterz@counterprefix}
1049 %\begin{macro}{\setcounterprefix}
1050 %\begin{macro}{\clearcounterprefix}
1051 %
1052 % The default expansion of \cs{@counterz@counterprefix} is null, but it can be
1053 % changed with the commands \cs{setcounterprefix} and \cs{clearcounterprefix}.
1054 %
1055 % \begin{macrocode}
1056 \newcommand{\@counterz@counterprefix}{}
1057 \newcommand{\setcounterprefix}[1]{%
1058 \renewcommand{\@counterz@counterprefix}{#1}
1059 }%
1060 \newcommand{\clearcounterprefix}{%
1061 \setcounterprefix{}
1062 }%
1063 % \end{macrocode}
1064 %
1065 %\end{macro}
1066 %\end{macro}
1067 %\end{macro}
1068 %
1069 %\subsection{Manipulating Counters}
1070 %
1071 %\begin{macro}{\xnewcounter}
1072 %\begin{macro}{\xprovidecounter}
1073 %\begin{macro}{\xsetcounter}
1074 %\begin{macro}{\xaddtocounter}
1075 %\begin{macro}{\xvalue}
1076 %
1077 % These commands are prefix versions of commands \cs{newcounter},
1078 % \cs{providecounter}, \cs{setcounter}, \cs{addtocounter}, and \cs{value},
1079 % respectively. The creation, modification, or use of the counters is carried
1080 % out on a prefixed version of the specified counter name. When
1081 % \cs{@counterz@counterprefix} is null, the commands expand like their standard
1082 % counterparts.
1083 %
1084 % \begin{macrocode}
1085 \newcommand{\xnewcounter}[1]{%
1086 \newcounter{\@counterz@counterprefix #1}
1087 }%
1088 \newcommand{\xprovidecounter}[1]{%
1089 \providecounter{\@counterz@counterprefix #1}
1090 }%
1091 \newcommand{\xsetcounter}[2]{%
1092 \setcounter{\@counterz@counterprefix #1}{#2}
1093 }%
1094 \newcommand{\xaddtocounter}[2]{%
1095 \addtocounter{\@counterz@counterprefix #1}{#2}
1096 }%
1097 \newcommand{\xvalue}[1]{%
1098 \value{\@counterz@counterprefix #1}
1099 }%
1100 % \end{macrocode}
1101 %
1102 %\end{macro}
1103 %\end{macro}
1104 %\end{macro}
1105 %\end{macro}
1106 %\end{macro}
1107 %
1108 %\subsection{Conditional Statements}
1109 %
1110 % The following commands provide if-then-else constructs analogous to those in
1111 % the package \textsf{etoolbox}. The notable difference is that the arguments
1112 % are counter names. The command \cs{xvalue} is used to determine the values of
1113 % the counters, so that the stored prefix is applied to the specified counter
1114 % names before execution.
1115 %
1116 %\begin{macro}{\ifctrequal}
1117 %
1118 % \cs{ifctrequal}\marg{counter1}\marg{counter2}\marg{foo}\marg{bar} executes
1119 % \meta{foo} if the value of \meta{counter1} is equal to the value of
1120 % \meta{counter2} and otherwise executes \meta{bar}.
1121 %
1122 % \begin{macrocode}
1123 \newcommand{\ifctrequal}[4]{%
1124 \ifnumequal{\xvalue{#1}}{\xvalue{#2}}{#3}{#4}
1125 }%
1126 % \end{macrocode}
1127 %
1128 %\end{macro}
1129 %
1130 %\begin{macro}{\ifctrless}
1131 %
1132 % \cs{ifctrless}\marg{counter1}\marg{counter2}\marg{foo}\marg{bar} executes
1133 % \meta{foo} if the value of \meta{counter1} is less than the value of
1134 % \meta{counter2} and otherwise executes \meta{bar}.
1135 %
1136 % \begin{macrocode}
1137 \newcommand{\ifctrless}[4]{%
1138 \ifnumless{\xvalue{#1}}{\xvalue{#2}}{#3}{#4}
1139 }%
1140 % \end{macrocode}
1141 %
1142 %\end{macro}
1143 %
1144 %\begin{macro}{\ifctrmore}
1145 %
1146 % \cs{ifctrmore}\marg{counter1}\marg{counter2}\marg{foo}\marg{bar} executes
1147 % \meta{foo} if the value of \meta{counter1} is more than the value of
1148 % \meta{counter2} and otherwise executes \meta{bar}.
1149 %
1150 % \begin{macrocode}
1151 \newcommand{\ifctrmore}[4]{%
1152 \ifnumless{\xvalue{#2}}{\xvalue{#1}}{#3}{#4}
1153 }%
1154 % \end{macrocode}
1155 %
1156 %\end{macro}
1157 %
1158 %\begin{macro}{\ifctrzero}
1159 %
1160 % \cs{ifctrzero}\marg{counter}\marg{foo}\marg{bar} executes \meta{foo} if
1161 % the value of \meta{counter} is zero and otherwise executes \meta{bar}.
1162 %
1163 % \begin{macrocode}
1164 \newcommand{\ifctrzero}[3]{%
1165 \ifnumequal{\xvalue{#1}}{0}{#2}{#3}
1166 }%
1167 % \end{macrocode}
1168 %
1169 %\end{macro}
1170 %
1171 %\begin{macro}{\ifctrneg}
1172 %
1173 % \cs{ifctrneg}\marg{counter}\marg{foo}\marg{bar} executes \meta{foo} if the
1174 % value of \meta{counter} is negative and otherwise executes \meta{bar}.
1175 %
1176 % \begin{macrocode}
1177 \newcommand{\ifctrneg}[3]{%
1178 \ifnumless{\xvalue{#1}}{0}{#2}{#3}
1179 }%
1180 % \end{macrocode}
1181 %
1182 %\end{macro}
1183 %
1184 %\begin{macro}{\ifctrpos}
1185 %
1186 % \cs{ifctrpos}\marg{counter}\marg{foo}\marg{bar} executes \meta{foo} if the
1187 % value of \meta{counter} is positive and otherwise executes \meta{bar}.
1188 %
1189 % \begin{macrocode}
1190 \newcommand{\ifctrpos}[3]{%
1191 \ifnumless{\xvalue{#1}}{1}{#3}{#2}
1192 }%
1193 % \end{macrocode}
1194 %
1195 %\end{macro}
1196 %
1197 %\subsection{Displaying Counters}
1198 %
1199 %\begin{macro}{\xarabic}
1200 %\begin{macro}{\xroman}
1201 %\begin{macro}{\xRoman}
1202 %\begin{macro}{\xalph}
1203 %\begin{macro}{\xAlph}
1204 %\begin{macro}{\xfnsymbol}
1205 %
1206 % These commands include prefix versions of the standard display commands.
1207 %
1208 % \begin{macrocode}
1209 \newcommand{\xarabic}[1]{\arabic{\@counterz@counterprefix #1}}
1210 \newcommand{\xroman}[1]{\roman{\@counterz@counterprefix #1}}
1211 \newcommand{\xRoman}[1]{\Roman{\@counterz@counterprefix #1}}
1212 \newcommand{\xalph}[1]{\alph{\@counterz@counterprefix #1}}
1213 \newcommand{\xAlph}[1]{\Alph{\@counterz@counterprefix #1}}
1214 \newcommand{\xfnsymbol}[1]{\fnsymbol{\@counterz@counterprefix #1}}
1215 % \end{macrocode}
1216 %
1217 %\end{macro}
1218 %\end{macro}
1219 %\end{macro}
1220 %\end{macro}
1221 %\end{macro}
1222 %\end{macro}
1223 % The following commands likewise apply the stored prefix to the counter name.
1224 % These commands are designed to aid in the typesetting of counter values within
1225 % algebraic expressions while observing particular conventions about the display
1226 % of numbers and their and their signs.
1227 %
1228 %\begin{macro}{\xabsof}
1229 %
1230 % \cs{xabsof}\marg{counter} prints the absolute value of \meta{counter}.
1231 %
1232 % \begin{macrocode}
1233 \newcommand{\xabsof}[1]{%
1234 \ifctrneg{#1}{%
1235 \the \numexpr 0 - \xvalue{#1} \relax%
1236 }{%
1237 \xarabic{#1}%
1238 }%
1239 }
1240 % \end{macrocode}
1241 %
1242 %\end{macro}
1243 %
1244 %\begin{macro}{\xsignof}
1245 %
1246 % \cs{xsignof}\marg{counter} prints a minus sign ``-'' if \meta{counter} is
1247 % negative and otherwise prints a plus sign ``+''. Note that the latter case
1248 % includes the value zero.
1249 %
1250 % \begin{macrocode}
1251 \newcommand{\xsignof}[1]{%
1252 \ifctrneg{#1}{-}{+}
1253 }%
1254 % \end{macrocode}
1255 %
1256 %\end{macro}
1257 %
1258 %\begin{macro}{\xnegsignof}
1259 %
1260 % \cs{xnegsignof}\marg{counter} prints a plus sign ``+'' if \meta{counter} is
1261 % negative and otherwise prints a minus sign ``-''. Note that the latter case
1262 % includes the value zero.
1263 %
1264 % \begin{macrocode}
1265 \newcommand{\xnegsignof}[1]{%
1266 \ifctrneg{#1}{+}{-}
1267 }%
1268 % \end{macrocode}
1269 %
1270 %\end{macro}
1271 %
1272 %\begin{macro}{\xsigned}
1273 %
1274 % \cs{xsigned}\marg{counter} prints the absolute value of \meta{counter},
1275 % preceded by a plus sign ``+'' or a minus sign ``-'' as defined by
1276 % \cs{xsignof}.
1277 %
1278 % \begin{macrocode}
1279 \newcommand{\xsigned}[1]{%
1280 \xsignof{#1} \xabsof{#1}
1281 }%
1282 % \end{macrocode}
1283 %
1284 %\end{macro}
1285 %
1286 %\begin{macro}{\xsignednz}
1287 %
1288 % \cs{xsignednz}\marg{counter} is like \cs{xsigned} but suppresses the number
1289 % zero.
1290 %
1291 % \begin{macrocode}
1292 \newcommand{\xsignednz}[1]{%
1293 \ifctrzero{#1}{}{\xsigned{#1}}
1294 }%
1295 % \end{macrocode}
1296 %
1297 %\end{macro}
1298 %
1299 %\begin{macro}{\xarabicnz}
1300 %
1301 % \cs{xarabicnz}\marg{counter} is like \cs{xarabic} but suppresses the number
1302 % zero.
1303 %
1304 % \begin{macrocode}
1305 \newcommand{\xarabicnz}[1]{%
1306 \ifctrzero{#1}{}{\xarabic{#1}}
1307 }%
1308 % \end{macrocode}
1309 %
1310 %\end{macro}
1311 %
1312 %\begin{macro}{\xnegsigned}
1313 %
1314 % \cs{xnegsigned}\marg{counter} prints the absolute value of \meta{counter},
1315 % preceded by a plus sign ``+'' or a minus sign ``-'' as defined by
1316 % \cs{xnegsignof}.
1317 %
1318 % \begin{macrocode}
1319 \newcommand{\xnegsigned}[1]{%
1320 \xnegsignof{#1} \xabsof{#1}
1321 }%
1322 % \end{macrocode}
1323 %
1324 %\end{macro}
1325 %
1326 %\begin{macro}{\xnegsignednz}
1327 %
1328 % \cs{xnegsignednz}\marg{counter} is like \cs{xnegsigned} but suppresses the
1329 % number zero.
1330 %
1331 % \begin{macrocode}
1332 \newcommand{\xnegsignednz}[1]{%
1333 \ifctrzero{#1}{}{\xnegsigned{#1}}
1334 }%
1335 % \end{macrocode}
1336 %
1337 %\end{macro}
1338 %
1339 %\begin{macro}{\xnegof}
1340 %
1341 % \cs{xnegof}\marg{counter} prints the negative of the value of \meta{counter}.
1342 %
1343 % \begin{macrocode}
1344 \newcommand{\xnegof}[1]{%
1345 \ifctrpos{#1}{-}{}\xabsof{#1}
1346 }%
1347 % \end{macrocode}
1348 %
1349 %\end{macro}
1350 %
1351 %\begin{macro}{\xnegofnz}
1352 %
1353 % \cs{xnegofnz}\marg{counter} is like \cs{xnegof} but suppresses the number
1354 % zero.
1355 %
1356 % \begin{macrocode}
1357 \newcommand{\xnegofnz}[1]{%
1358 \ifctrzero{#1}{}{\xnegof{#1}}
1359 }%
1360 % \end{macrocode}
1361 %
1362 %\end{macro}
1363 %
1364 %\begin{macro}{\xcoef}
1365 %
1366 % \cs{xcoef}\marg{counter} prints the value of \meta{counter} except that it
1367 % suppresses the values of 1, 0, and -1, printing a ``-'' in the latter case.
1368 %
1369 % \begin{macrocode}
1370 \newcommand{\xcoef}[1]{%
1371 \ifboolexpr{%
1372 test {\ifnumless{\xvalue{#1}}{-1}}
1373 or test {\ifnumgreater{\xvalue{#1}}{1}}
1374 }{%
1375 \xarabic{#1}
1376 }{%
1377 }%
1378 \ifnumequal{\xvalue{#1}}{-1}{-}{}
1379 }%
1380 % \end{macrocode}
1381 %
1382 %\end{macro}
1383 %
1384 %\begin{macro}{\xnegcoef}
1385 %
1386 % \cs{xnegcoef}\marg{counter} prints the value of \meta{counter} except that it
1387 % suppresses the values of 1, 0, and -1, printing a ``-'' in the former case.
1388 %
1389 % \begin{macrocode}
1390 \newcommand{\xnegcoef}[1]{%
1391 \ifboolexpr{%
1392 test {\ifnumless{\xvalue{#1}}{-1}}
1393 or test {\ifnumgreater{\xvalue{#1}}{1}}
1394 }{%
1395 \xnegof{#1}
1396 }{%
1397 }%
1398 \ifnumequal{\xvalue{#1}}{1}{-}{}
1399 }%
1400 % \end{macrocode}
1401 %
1402 %\end{macro}
1403 %
1404 %\begin{macro}{\xabsofcoef}
1405 %
1406 % \cs{xabsofcoef}\marg{counter} prints the absolute value of \meta{counter}
1407 % except that it suppresses the values of 1 and 0.
1408 %
1409 % \begin{macrocode}
1410 \newcommand{\xabsofcoef}[1]{%
1411 \ifboolexpr{%
1412 test {\ifnumless{\xvalue{#1}}{-1}}
1413 or test {\ifnumgreater{\xvalue{#1}}{1}}
1414 }{%
1415 \xabsof{#1}
1416 }{%
1417 }%
1418 }%
1419 % \end{macrocode}
1420 %
1421 %\end{macro}
1422 %
1423 %\begin{macro}{\xsignofcoef}
1424 %
1425 % \cs{xsignofcoef}\marg{counter} prints the sign of \meta{counter} if
1426 % \meta{counter} is nonzero.
1427 %
1428 % \begin{macrocode}
1429 \newcommand{\xsignofcoef}[1]{%
1430 \ifctrzero{#1}{}{\xsignof{#1}}
1431 }%
1432 % \end{macrocode}
1433 %
1434 %\end{macro}
1435 %
1436 %\begin{macro}{\xnegsignofcoef}
1437 %
1438 % \cs{xnegsignofcoef}\marg{counter} prints the opposite sign of \meta{counter}
1439 % if \meta{counter} is nonzero.
1440 %
1441 % \begin{macrocode}
1442 \newcommand{\xnegsignofcoef}[1]{%
1443 \ifctrzero{#1}{}{\xnegsignof{#1}}
1444 }%
1445 % \end{macrocode}
1446 %
1447 %\end{macro}
1448 %
1449 %\begin{macro}{\xsignedcoef}
1450 %
1451 % \cs{xsignedcoef}\marg{counter} is like \cs{xcoef} except that positive values
1452 % are preceded by a plus sign ``+''.
1453 %
1454 % \begin{macrocode}
1455 \newcommand{\xsignedcoef}[1]{%
1456 \xsignofcoef{#1} \xabsofcoef{#1}
1457 }%
1458 % \end{macrocode}
1459 %
1460 %\end{macro}
1461 %
1462 %\begin{macro}{\xnegsignedcoef}
1463 %
1464 % \cs{xnegsignedcoef}\marg{counter} is like \cs{xsignedcoef} except using the
1465 % opposite sign.
1466 %
1467 % \begin{macrocode}
1468 \newcommand{\xnegsignedcoef}[1]{%
1469 \xnegsignofcoef{#1} \xabsofcoef{#1}
1470 }%
1471 % \end{macrocode}
1472 %
1473 %\end{macro}
1474 %
1475 %\subsection{Random Counters}
1476 %
1477 %\begin{macro}{\randomizectr}
1478 %\begin{macro}{\norandomizectr}
1479 %
1480 % In order to assign a random value to a counter during one typesetting and
1481 % avoid overwriting this value with a random assignment during another
1482 % typesetting, the boolean \textit{@counterz@random} is used to distinguish
1483 % between the two typesetting options. The value of \textit{@counterz@random} may
1484 % be changed by the commands \cs{randomizectr} and \cs{norandomizectr}.
1485 %
1486 % \begin{macrocode}
1487 \newbool{@counterz@random}
1488 \booltrue{@counterz@random}
1489 \newcommand{\randomizectr}{\booltrue{@counterz@random}}
1490 \newcommand{\norandomizectr}{\boolfalse{@counterz@random}}
1491 % \end{macrocode}
1492 %
1493 %\end{macro}
1494 %\end{macro}
1495 %
1496 %\begin{macro}{\ifrandomizectr}
1497 %
1498 % \cs{ifrandomizectr}\marg{foo}\marg{bar} executes \meta{foo} if the boolean
1499 % \textit{@counterz@random} is TRUE and otherwise executes \meta{bar}.
1500 %
1501 % \begin{macrocode}
1502 \newcommand{\ifrandomizectr}[2]{%
1503 \ifbool{@counterz@random}{#1}{#2}
1504 }%
1505 % \end{macrocode}
1506 %
1507 %\end{macro}
1508 %
1509 %\begin{macro}{\promptrandomizectr}
1510 %\changes{v1.1.0}{2023/05/30}{new}
1511 %
1512 % \cs{promptrandomizectr}\oarg{command}\marg{message}\marg{string} writes
1513 % \meta{message} to the terminal and awaits a response from the user at the
1514 % prompt. The user's response is stored in \meta{command} and compared to the
1515 % text of \meta{string}. If they are equal, then \cs{randomizectr} is executed.
1516 % If they are not equal, then \cs{norandomizectr} is executed.
1517 %
1518 % \begin{macrocode}
1519 \newcommand{\promptrandomizectr}[3][\@typein]{%
1520 \typein[#1]{#2}
1521 \ifdefstring{#1}{#3}{%
1522 \randomizectr
1523 }{%
1524 \norandomizectr
1525 }%
1526 }%
1527 % \end{macrocode}
1528 %
1529 %\end{macro}
1530 %
1531 % The commands \cs{randsetcounter} and \cs{randaddtocounter} use the pdf\TeX\
1532 % primitive \cs{pdfuniformdeviate} to provide random versions of
1533 % \cs{setcounter} and \cs{addtocounter}. The commands \cs{xrandsetcounter} and
1534 % \cs{xrandaddtocounter} are prefix versions of \cs{randsetcounter} and
1535 % \cs{randaddtocounter}, respectively. Each of these four commands will generate
1536 % random counter values only when the boolean \textit{@counterz@random} is TRUE.
1537 %
1538 %\begin{macro}{\randsetcounter}
1539 %\changes{v1.1.0}{2023/05/30}{new}
1540 %\changes{v1.1.1}{2023/06/05}{bug fix}
1541 %\begin{macro}{\xrandsetcounter}
1542 %\changes{v1.1.0}{2023/05/30}{now based on a new \cs{randsetcounter}}
1543 %
1544 % \cs{randsetcounter}\marg{counter}\marg{min}\marg{max} assigns to
1545 % \meta{counter} a random integer value between \meta{min} and \meta{max},
1546 % if \textit{@counterz@random} is TRUE.
1547 %
1548 % \begin{macrocode}
1549 \newcommand{\randsetcounter}[3]{%
1550 \ifrandomizectr{%
1551 \setcounter{#1}{%
1552 \the \numexpr #2+\pdfuniformdeviate \numexpr #3-#2+1 \relax
1553 }%
1554 }{%
1555 % Do Nothing
1556 }%
1557 }%
1558 \newcommand{\xrandsetcounter}[3]{%
1559 \randsetcounter{\@counterz@counterprefix#1}{#2}{#3}
1560 }%
1561 % \end{macrocode}
1562 %
1563 %\end{macro}
1564 %\end{macro}
1565 %
1566 %\begin{macro}{\randaddtocounter}
1567 %\changes{v1.1.0}{2023/05/30}{new}
1568 %\changes{v1.1.1}{2023/06/05}{bug fix}
1569 %\begin{macro}{\xrandaddtocounter}
1570 %\changes{v1.1.0}{2023/05/30}{now based on a new \cs{randaddtocounter}}
1571 %
1572 % \cs{randaddtocounter}\marg{counter}\marg{min}\marg{max} adds to \meta{counter}
1573 % a random integer value between \meta{min} and \meta{max},
1574 % if \textit{@counterz@random} is TRUE.
1575 %
1576 % \begin{macrocode}
1577 \newcommand{\randaddtocounter}[3]{%
1578 \ifrandomizectr{%
1579 \addtocounter{#1}{%
1580 \the \numexpr #2+\pdfuniformdeviate \numexpr #3-#2+1 \relax
1581 }%
1582 }{%
1583 % Do Nothing
1584 }%
1585 }%
1586 \newcommand{\xrandaddtocounter}[3]{%
1587 \randaddtocounter{\@counterz@counterprefix#1}{#2}{#3}
1588 }%
1589 % \end{macrocode}
1590 %
1591 %\end{macro}
1592 %\end{macro}
1593 % The following commands are designed to provide a means by which authors can
1594 % generate random values for counters but also preserve those values for future
1595 % typesettings. This is accomplished by storing counters and their values in an
1596 % external file and then inputting the file before a subsequent typesetting.
1597 %
1598 %\begin{macro}{\opencountersfile}
1599 %\changes{v1.1.0}{2023/05/30}{new error reports}
1600 %
1601 % The command \cs{opencountersfile} creates and opens the write stream to the
1602 % file \textsf{\meta{jobname}.counters.tex}, referenced by the macro
1603 % \cs{countersfile}. If the file already exists, it is overwritten. For this
1604 % reason,
1605 %
1606 % \begin{macrocode}
1607 \newbool{@counterz@fileISopen}
1608 \boolfalse{@counterz@fileISopen}
1609 \newcommand{\opencountersfile}{%
1610 \ifbool{@counterz@fileISopen}{%
1611 \PackageError{counterz}{%
1612 The write stream is already open!
1613 \MessageBreak Process interrupted to prevent overwriting
1614 \MessageBreak \jobname.counters.tex
1615 }{%
1616 Be sure to include only one instance of
1617 \protect\opencountersfile.
1618 }%
1619 }{%
1620 \ifrandomizectr{%
1621 \newwrite\countersfile
1622 \immediate\openout\countersfile=\jobname.counters.tex
1623 \booltrue{@counterz@fileISopen}
1624 }{%
1625 \PackageError{counterz}{%
1626 \protect\opencountersfile\space requires
1627 \protect\randomizectr
1628 \MessageBreak Process interrupted to prevent overwriting
1629 \MessageBreak \jobname.counters.tex
1630 }{%
1631 \protect\opencountersfile\space is designed to open a file
1632 for saving newly randomized counters. See the Random
1633 Counters section of the counterz package documentation for
1634 details.
1635 }%
1636 }%
1637 }%
1638 }
1639 % \end{macrocode}
1640 %
1641 %\end{macro}
1642 %
1643 %\begin{macro}{\inputcountersfile}
1644 %\changes{v1.1.0}{2023/05/30}{new}
1645 %
1646 % The command \cs{inputcountersfile} inputs \textsf{\meta{jobname}.counters.tex}
1647 % if the file exists and reports a package error if the file does not exist.
1648 %
1649 % \begin{macrocode}
1650 \newcommand{\inputcountersfile}{%
1651 \InputIfFileExists{\jobname.counters}{%
1652 }{%
1653 \PackageError{counterz}{%
1654 The file \jobname.counters.tex does not exist.
1655 }{%
1656 See the Random Counters section of the counterz package
1657 documentation.
1658 }%
1659 }%
1660 }%
1661 % \end{macrocode}
1662 %
1663 %\end{macro}
1664 %
1665 %\begin{macro}{\@counterz@openbrace}
1666 %\begin{macro}{\@counterz@closebrace}
1667 %
1668 % The commands \cs{@counterz@openbrace} and \cs{@counterz@closebrace}
1669 % facilitate the writing of the brace delimiters to \cs{countersfile}.
1670 %
1671 % \begin{macrocode}
1672 \begingroup
1673 \catcode`<=1 \catcode`>=2
1674 \catcode`{=12 \catcode`}=12
1675 \gdef\@counterz@openbrace<{>
1676 \gdef\@counterz@closebrace<}>
1677 \endgroup
1678 % \end{macrocode}
1679 %
1680 %\end{macro}
1681 %\end{macro}
1682 %
1683 %\begin{macro}{\savecounter}
1684 %\changes{v1.1.0}{2023/05/30}{new}
1685 %\begin{macro}{\xsavecounter}
1686 %\changes{v1.1.0}{2023/05/30}{now based on a new \cs{savecounter}}
1687 %
1688 % \cs{savecounter}\marg{counter} writes \cs{providecounter} and \cs{setcounter}
1689 % commands to the file \textsf{\meta{jobname}.counters.tex} so that they may be
1690 % inputted as part of a future typesetting. The command reports a package error
1691 % if the write stream to \textsf{\meta{jobname}.counters.tex} is not open. The
1692 % command \cs{xsavecounter} is a prefix version of \cs{savecounter}.
1693 %
1694 %
1695 % \begin{macrocode}
1696 \newcommand{\savecounter}[1]{%
1697 \ifbool{@counterz@fileISopen}{%
1698 \immediate\write\countersfile{%
1699 \unexpanded{\providecounter}
1700 \@counterz@openbrace#1\@counterz@closebrace
1701 \unexpanded{\setcounter}
1702 \@counterz@openbrace#1\@counterz@closebrace
1703 \@counterz@openbrace\arabic{#1}\@counterz@closebrace
1704 }%
1705 }{%
1706 \PackageError{counterz}{%
1707 The write stream to the file \jobname.counters.tex must be
1708 opened before \protect\savecounter\space can be executed.
1709 }{%
1710 See \protect\opencountersfile\space and
1711 \protect\savecounter\space in the counterz package
1712 documentation.
1713 }%
1714 }%
1715 }%
1716
1717 \newcommand{\xsavecounter}[1]{%
1718 \savecounter{\@counterz@counterprefix#1}%
1719 }%
1720 % \end{macrocode}
1721 %
1722 %\end{macro}
1723 %\end{macro}
1724 %
1725 %\begin{macro}{\randprovidecounter}
1726 %\changes{v1.1.0}{2023/05/30}{new}
1727 %
1728 % \cs{randprovidecounter}\marg{counter}\marg{min}\marg{max} creates
1729 % \meta{counter} if it does not already exist, and if the boolean
1730 % \textit{@counterz@random} is TRUE then \meta{counter} is assigned a
1731 % random integer value between \meta{min} and \meta{max} and then saved.
1732 %
1733 % \begin{macrocode}
1734 \newcommand{\randprovidecounter}[3]{%
1735 \ifltxcounter{#1}{%
1736 \@ifnextchar]{%
1737 \m@k@gobbleendoptarg
1738 }{%
1739 }%
1740 }{%
1741 \newcounter{#1}
1742 \ifrandomizectr{%
1743 \randsetcounter{#1}{#2}{#3}
1744 \savecounter{#1}
1745 }{%
1746 }%
1747 }%
1748 }%
1749 % \end{macrocode}
1750 %
1751 %\end{macro}
1752 %
1753 %\begin{macro}{\xrandprovidecounter}
1754 %\changes{v1.1.0}{2023/05/30}{no longer randomizes if already defined;
1755 %now based on a new \cs{randprovidecounter}}
1756 %
1757 % \cs{xrandprovidecounter}\marg{counter}\marg{min}\marg{max} creates
1758 % \meta{counter} if it does not already exist, and if the boolean
1759 % \textit{@counterz@random} is TRUE then \meta{counter} is assigned a
1760 % random integer value between \meta{min} and \meta{max} and then saved.
1761 %
1762 % \begin{macrocode}
1763 \newcommand{\xrandprovidecounter}[3]{%
1764 \randprovidecounter{\@counterz@counterprefix#1}{#2}{#3}
1765 }%
1766 % \end{macrocode}
1767 %
1768 %\end{macro}
1769 %
1770 %\begin{macro}{\randprovidecounternz}
1771 %\changes{v1.1.0}{2023/05/30}{new}
1772 %
1773 % \cs{randprovidecounternz}\marg{counter}\marg{min}\marg{max} does the same
1774 % job as the command \cs{xrandprovidecounter} except that the value of
1775 % \meta{counter} is randomized until it is nonzero.
1776 %
1777 % \begin{macrocode}
1778 \newcommand{\randprovidecounternz}[3]{%
1779 \ifltxcounter{#1}{%
1780 \@ifnextchar]{%
1781 \m@k@gobbleendoptarg
1782 }{%
1783 }%
1784 }{%
1785 \newcounter{#1}
1786 \ifrandomizectr{%
1787 \setcounter{#1}{0}
1788 \whileboolexpr{test {\ifnumequal{\value{#1}}{0}}}{%
1789 \randsetcounter{#1}{#2}{#3}
1790 }%
1791 \savecounter{#1}
1792 }{%
1793 }%
1794 }%
1795 }%
1796 % \end{macrocode}
1797 %
1798 %\end{macro}%
1799 %
1800 %\begin{macro}{\xrandprovidecounternz}
1801 %\changes{v1.1.0}{2023/05/30}{no longer randomizes if already defined;
1802 %now based on a new \cs{randprovidecounternz}}
1803 %
1804 % \cs{xrandprovidecounternz}\marg{counter}\marg{min}\marg{max} does the same
1805 % job as the command \cs{xrandprovidecounter} except that the value of
1806 % \meta{counter} is randomized until it is nonzero.
1807 %
1808 % \begin{macrocode}
1809 \newcommand{\xrandprovidecounternz}[3]{%
1810 \randprovidecounternz{\@counterz@counterprefix#1}{#2}{#3}
1811 }%
1812 % \end{macrocode}
1813 %
1814 %\end{macro}%
1815 %
1816 % \begin{macrocode}
1817 %</package>
1818 % \end{macrocode}
1819 %\Finale