Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2021 Dennis Chen <[email protected]>
4 %
5 % This file may be distributed and/or modified under
6 % the conditions the LaTeX Project Public License (LPPL),
7 % either version 1.3 of this license or (at your option)
8 % any later version. The latest version of this license
9 % can be found in
10 % http://www.latex-project.org/lppl.txt
11 % and version 1.3 or later is part of all distributions of LaTeX
12 % version 2005/12/01 or later.
13 % \fi
14 %
15 % \iffalse
16 %<*package>
17
18 \NeedsTeXFormat{LaTeX2e}
19 \ProvidesPackage{macrolist}[2021/07/31 v2.1.0 Create lists of macros and perform operations on them]
20
21 \RequirePackage{pgffor}
22 %</package>
23
24 %<*driver>
25 \documentclass{ltxdoc}
26 \usepackage{macrolist}
27 \EnableCrossrefs
28 \CodelineIndex
29 \RecordChanges
30 \begin{document}
31 \DocInput{macrolist.dtx}
32 \PrintIndex
33 \PrintChanges
34 \end{document}
35 %</driver>
36 % \fi
37 %
38 % \changes{v2.0.0}{2021/07/29}{Add ``macro'' in front of each external command (to avoid conflicts with etoolbox)}
39 % \changes{v1.0.2}{2021/07/17}{Print changelog in documentation}
40 % \changes{v1.0.2}{2021/07/17}{Added comment markers to remove pars and fix spacing in listforeach}
41 % \changes{v1.0.1}{2021/07/16}{Make a couple of defs and lets global to prevent scoping issues}
42 % \changes{v1.0.1}{2021/07/16}{Add ``scope is always global'' to documentation}
43 % \changes{v1.0.1}{2021/07/16}{Fix date in initial version changes entry}
44 % \changes{v1.0.1}{2021/07/16}{Fix v. appearing in front of date in document title}
45 % \changes{v1.0.0}{2021/07/12}{Initial version}
46 %
47 % \GetFileInfo{macrolist.sty}
48 %
49 % \title{\textsf{macrolist} -- Create lists of macros and manipulate them}
50 % \author{Dennis Chen \\ [email protected]}
51 % \date{\fileversion, \filedate\thanks{\url{https://github/com/chennisden/macrolist}}}
52 %
53 % \maketitle
54 %
55 % \begin{abstract}
56 % The \textsf{macrolist} package allows you to create lists and manipulate them, with utilities such as |\macrolistforeach| and an implementation of arr.join() from Javascript. Contrary to the name of the package, non-macros and groups of macros can be put into an item of the list.
57 % \end{abstract}
58 %
59 % \section{Usage}
60 % The scope of lists is always global. This provides the most consistency and functionality for developers in places that are usually local (part of a group), such as environments and loops.
61 %
62 % \DescribeMacro{\macronewlist}
63 % To create a list, pass in |\macronewlist{listname}| to create a list with the name \textsf{listname}.
64 %
65 % The package checks that \textsf{listname} is not the name of another list, and will throw an error if another list \textsf{listname} has already been defined.
66 %
67 % \iffalse
68 \newcommand{\macronewlist}[1]{
69 \ifcsname c@macrolist@list@#1\endcsname
70 \PackageError{macrolist}{The list '#1' is already defined}{}
71 \else
72 \newcounter{macrolist@list@#1}
73 \setcounter{macrolist@list@#1}{0}
74 \fi
75 }
76 % \fi
77 %
78 % \changes{v1.1.0}{2021/07/22}{Add listexists}
79 % \DescribeMacro{\macrolistexists}
80 % Writing |\macrolistexists{listname}{true}{false}| will execute \textsf{true} if \textsf{listname} exists and \textsf{false} otherwise.
81 %
82 % \iffalse
83 \newcommand{\macrolistexists}[3]{\ifcsname c@macrolist@list@#1\endcsname#2\else#3\fi}
84 % \fi
85 %
86 % \DescribeMacro{\macrolistelement}
87 %
88 % To execute the \textsf{i}th element of \textsf{listname}, write |\macrolistelement{listname}{i}|. Note that \textit{lists are 1-indexed}, meaning the first element is numbered 1, the second element numbered 2, and so on.
89 %
90 % An error will be thrown if \textsf{listname} is not a defined list, if \textsf{i} is empty, or if \textsf{i} is greater than the size of the list.
91 %
92 % \iffalse
93 \newcommand{\macrolistelement}[2]{%
94 \macrolist@inbounds{#1}{#2}%
95 \csname macrolist@list@#1\the\numexpr #2\relax\endcsname%
96 }
97 % \fi
98 % \changes{}
99 % \changes{v1.2.1}{2021/07/25}{Fix behavior of listindexof and listcontains for empty lists}
100 % \changes{v1.2.0}{2021/07/23}{Add listindexof and listcontains}
101 % \DescribeMacro{\macrolistindexof}
102 %
103 % This works similar to \textsf{indexof} in almost any ordinary programming language. Write |\macrolistindexof{list}{element}| to get the index of where \textsf{element} first appears in \textsf{list}. If it never does, then the macro will expand to \textsf{0}.
104 %
105 % The command uses |\ifx| instead of |\if|; this means that if you have |\macro| as an element with the definition \textsf{this is a macro} (assuming that \textsf{this is a macro} is not an element itself), then |\macrolistindexof{listname}{this is a macro}| will expand to \textsf{0}.
106 %
107 % Because of the implementation of this macro, it can't actually be parsed as a number. (See the `Limitations' section for more information.)
108 % \iffalse
109 \newcommand{\macrolistindexof}[2]{%
110 \def\macrolist@listindex{0}%
111 \macrolist@exists{#1}%
112 \ifnum\macrolistsize{#1}>0\relax
113 \def\macrolist@el{#2}%
114 \macrolistforeach{#1}{\macrolist@listindexel}[\macrolistsize{#1}][1]{%
115 \ifx\macrolist@el\macrolist@listindexel
116 \xdef\macrolist@listindex{\macrolist@index}%
117 \fi
118 }%
119 \fi
120 \macrolist@listindex%
121 \let\macrolist@listindex\relax%
122 }
123 % \fi
124 %
125 % \DescribeMacro{\macrolistcontains}
126 % Writing |\macrolistcontains{listname}{element}{true branch}{false branch}| checks whether list \textsf{listname} contains \textsf{element}, executing \textsf{true branch} if it does and \textsf{false branch} if it does not.
127 %
128 % \iffalse
129 \newcommand{\macrolistcontains}[4]{%
130 \def\macrolist@listindex{0}%
131 \macrolist@exists{#1}%
132 \ifnum\macrolistsize{#1}>0\relax
133 \def\macrolist@el{#2}%
134 \macrolistforeach{#1}{\macrolist@listindexel}[\macrolistsize{#1}][1]{%
135 \ifx\macrolist@el\macrolist@listindexel
136 \xdef\macrolist@listindex{\macrolist@index}%
137 \fi
138 }%
139 \fi
140 \ifnum\macrolist@listindex>0\relax
141 #3%
142 \else
143 #4%
144 \fi
145 }
146 % \fi
147 %
148 % \DescribeMacro{\macrolistadd}
149 % To add something to the list \textsf{listname}, pass in |\macrolistadd{listname}[position]{element}|, where \textsf{position} is an optional argument. If nothing is passed in for \textsf{position}, then by default \textsf{element} will be added to the end of the list.
150 %
151 % \iffalse
152 \newcommand{\macrolistadd}[1]{
153 \macrolist@exists{#1}
154 \def\macrolist@currlist{#1}
155 \macrolist@listadd
156 }
157 %% We write \macrolistadd this way such that the optional argument will be positioned correctly
158 \newcommand{\macrolist@listadd}[2][]{
159 \stepcounter{macrolist@list@\macrolist@currlist}
160
161 \if\relax\detokenize{#1}\relax
162 \expandafter\gdef\csname macrolist@list@\macrolist@currlist\macrolistsize{\macrolist@currlist}\endcsname{#2}
163 \else
164 \expandafter\ifnum\csname themacrolist@list@\macrolist@currlist\endcsname=#1
165 \expandafter\gdef\csname macrolist@list@\macrolist@currlist\macrolistsize{\macrolist@currlist}\endcsname{#2}
166 \else
167 \macrolist@inbounds{\macrolist@currlist}{#1}
168 \foreach \macrolist@index in {\macrolistsize{\macrolist@currlist}, ...,\the\numexpr #1+1\relax} {
169 \global\expandafter\let\csname macrolist@list@\macrolist@currlist\macrolist@index\expandafter\endcsname\csname macrolist@list@\macrolist@currlist\the\numexpr\macrolist@index-1\relax\endcsname
170 }
171 \expandafter\gdef\csname macrolist@list@\macrolist@currlist#1\endcsname{#2}
172 \fi
173 \fi
174 }
175 % \fi
176 % \changes{v2.1.0}{2021/07/31}{Add macrolisteadd}
177 % \DescribeMacro{\macrolisteadd}
178 % To fully expand |element| before adding it to list |listname|, pass in |\macrolisteadd{listname}[position]{element}|. This behaves similarly to |\edef|.
179 %
180 % \iffalse
181 \newcommand{\macrolisteadd}[1]{
182 \macrolist@exists{#1}
183 \def\macrolist@currlist{#1}
184 \macrolist@listeadd
185 }
186 \newcommand{\macrolist@listeadd}[2][]{
187 \stepcounter{macrolist@list@\macrolist@currlist}
188
189 \if\relax\detokenize{#1}\relax
190 \expandafter\xdef\csname macrolist@list@\macrolist@currlist\macrolistsize{\macrolist@currlist}\endcsname{#2}
191 \else
192 \expandafter\ifnum\csname themacrolist@list@\macrolist@currlist\endcsname=#1
193 \expandafter\gdef\csname macrolist@list@\macrolist@currlist\macrolistsize{\macrolist@currlist}\endcsname{#2}
194 \else
195 \macrolist@inbounds{\macrolist@currlist}{#1}
196 \foreach \macrolist@index in {\macrolistsize{\macrolist@currlist}, ...,\the\numexpr #1+1\relax} {
197 \global\expandafter\let\csname macrolist@list@\macrolist@currlist\macrolist@index\expandafter\endcsname\csname macrolist@list@\macrolist@currlist\the\numexpr\macrolist@index-1\relax\endcsname
198 }
199 \expandafter\xdef\csname macrolist@list@\macrolist@currlist#1\endcsname{#2}
200 \fi
201 \fi
202 }
203 % \fi
204 % \DescribeMacro{\macrolistremove}
205 % To remove an element in a list, write |\macrolistremove{listname}{index}|.
206 %
207 % \iffalse
208 \newcommand{\macrolistremove}[2]{
209 \macrolist@inbounds{#1}{#2}
210
211 \ifnum\numexpr#2\relax=\macrolistsize{#1}
212 \else
213 \foreach \macrolist@index in {#2, ..., \the\numexpr\macrolistsize{#1}-1\relax} {
214 \global\expandafter\let\csname macrolist@list@#1\macrolist@index\expandafter\endcsname\csname macrolist@list@#1\the\numexpr\macrolist@index+1\endcsname
215 }
216 \fi
217
218 \global\expandafter\let\csname macrolist@list@#1\macrolistsize{#1}\endcsname\relax
219 \addtocounter{macrolist@list@#1}{-1}
220 }
221 % \fi
222 %
223 % \DescribeMacro{\macrolistremovelast}
224 % To remove the last element in a list, write |\macrolistremovelast{listname}|. This behaves like C++'s |pop_back|.
225 %
226 % \iffalse
227 \newcommand{\macrolistremovelast}[1]{
228 \macrolist@exists{#1}
229 \global\expandafter\let\csname macrolist@list@#1\macrolistsize{#1}\endcsname\relax
230 \addtocounter{macrolist@list@#1}{-1}
231 }
232 % \fi
233 %
234 % \DescribeMacro{\macrolistclear}
235 % To clear a list, write |\macrolistclear{listname}|.
236 %
237 % \iffalse
238 \newcommand{\macrolistclear}[2]{
239 \macrolist@inbounds{#1}{#2}
240
241 \foreach \macrolist@index in {1, ..., \macrolistsize{#1}} {
242 \global\expandafter\let\csname \macrolist@list@#1\macrolist@index\endcsname\relax
243 }
244
245 \setcounter{macrolist@list@#1}{0}
246 }
247 % \fi
248 %
249 % \DescribeMacro{\macrolistsize}
250 % To get the size of a list, write |\macrolistsize{listname}|.
251 %
252 % \iffalse
253 \newcommand*{\macrolistsize}[1]{%
254 \macrolist@exists{#1}%
255 \csname themacrolist@list@#1\endcsname
256 }
257 % \fi
258 %
259 % \DescribeMacro{\macrolistforeach}
260 % \changes{v1.1.1}{2021/07/23}{Fix foreach doc by removing incorrect begin}
261 % To write a for each loop, write
262 % \begin{verbatim}
263 %\macrolistforeach{listname}{\element}[begin][end]{action}
264 % \end{verbatim}
265 %
266 %
267 % Note that begin and end are optional arguments, and by default, they take the values \textsf{1} and |\macrolistsize{listname}|. If you pass in \textsf{begin}, you must also pass in \textsf{end}.
268 %
269 % \iffalse
270 \newcommand{\macrolistforeach}[2]
271 {%
272 \def\macrolist@foreachstart{0}% Reset
273 % This is used to make optional arguments line up correctly
274 %
275 \def\macrolist@start{1}%
276 \def\macrolist@end{\macrolistsize{#1}}%
277 \def\macrolist@listname{#1}%
278 \def\macrolist@element{#2}%
279 \macrolist@listforeachi
280 }
281
282 \newcommand{\macrolist@listforeachi}[1][]{%
283 \if\relax\detokenize{#1}\relax
284 \else
285 \def\macrolist@start{#1}%
286 \def\macrolist@foreachstart{1}%
287 \fi
288 \macrolist@listforeachii
289 }
290
291 \newcommand{\macrolist@listforeachii}[1][]{%
292 \if\relax\detokenize{#1}\relax
293 \ifnum\macrolist@foreachstart=1
294 \PackageError{macrolist}{You must either pass in both a starting and ending position or neither}{}
295 \fi
296 \else
297 \def\macrolist@end{#1}%
298 \fi
299 \macrolist@listforeachaction
300 }
301
302 \newcommand{\macrolist@listforeachaction}[1]{%
303 %
304 \macrolist@exists{\macrolist@listname}%
305 %
306 \ifnum\numexpr\macrolist@start\relax>\macrolistsize{\macrolist@listname}%
307 \PackageError{macrolist}{The starting index of the loop is out of the bounds of list '\macrolist@listname'}{}
308 \fi
309 %
310 \ifnum\numexpr\macrolist@end\relax>\macrolistsize{\macrolist@listname}
311 \PackageError{macrolist}{The ending index of the loop is out of the bounds of list '\macrolist@listname'}{}
312 \fi
313 %
314 \foreach \macrolist@index in {\the\numexpr\macrolist@start\relax, ..., \the\numexpr\macrolist@end\relax} {%
315 \expandafter\expandafter\expandafter\let\expandafter\expandafter\macrolist@element\csname macrolist@list@\macrolist@listname\macrolist@index\endcsname
316 #1%
317 }%
318 }
319 % \fi
320 %
321 % \DescribeMacro{\macrolistjoin}
322 % Executing |\macrolistjoin{listname}{joiner}| returns all of the elements separated by \textsf{joiner}. This behaves like Javascript's \textsf{arr.join()}.
323 %
324 % \iffalse
325 \newcommand{\macrolistjoin}[2]{%
326 \ifnum\macrolistsize{#1}>1
327 \macrolistforeach{#1}{\macrolist@joinelement}[1][\macrolistsize{#1}-1]{\macrolist@joinelement#2}%
328 \fi
329 \ifnum\macrolistsize{#1}>0
330 \macrolistelement{#1}{\macrolistsize{#1}}%
331 \fi
332 }
333 % \fi
334 %
335 % \section{Example}
336 % Here is the source code for a small document using \textsf{macrolist}.
337 %
338 % \begin{verbatim}
339 %\documentclass{article}
340 %\usepackage{macrolist}
341 %
342 %\begin{document}
343 %
344 %\macronewlist{mylist}
345 %\macrolistadd{mylist}{Some text}
346 %% List: Some text
347 %
348 %\newcommand\macro{This is a macro}
349 %
350 %\macrolistadd{mylist}{\macro}
351 %% List: Some text, \macro
352 %
353 %\macrolistelement{mylist}{1}
354 %% Prints out "Some text"
355 %
356 %\macrolistadd{mylist}[1]{Element inserted into beginning}
357 %% List: Element inserted into beginning, Some text, \macro
358 %
359 %\macrolistremove{mylist}{1}
360 %% List: Some text, \macro
361 %
362 %\macrolistforeach{mylist}{\element}{We're printing out \textbf{\element}. }
363 %% We're printing out \textbf{Some text}. We're printing out \textbf{\macro}.
364 %
365 %\macrolistjoin{mylist}{, }
366 %% Some text, \macro
367 %
368 %\end{document}
369 % \end{verbatim}
370 %
371 % \section{Limitations}
372 %
373 % The |\macrolistindexof| macro cannot be parsed as a number. This is because we have to compare each element of the list to the passed in element and requires storing the index in a macro, which requires some unexpandable macros. (This is why we do not directly use |\macrolistindexof| when defining |\macrolistcontains|.)
374 %
375 % \section{Implementation details}
376 %
377 % All internal macros are namespaced to prevent package conflicts.
378 %
379 % \begin{macro}{\macrolist@exists}
380 % One internal macro we use is |\macrolist@exists{listname}|, which checks that \textsf{listname} exists. It throws an error otherwise.
381 %
382 % \begin{macrocode}
383 \newcommand*{\macrolist@exists}[1]{%
384 \ifcsname c@macrolist@list@#1\endcsname
385 \else
386 \PackageError{macrolist}
387 {The first argument is not a defined list}
388 {Make sure you have defined the list before trying to operate on it.}
389 \fi
390 }
391 % \end{macrocode}
392 % \end{macro}
393 %
394 % \begin{macro}{\macrolist@inbounds}
395 % We use |\macrolist@inbounds{listname}{index}| to check that first, \textsf{listname} is a defined list using |\macrolist@exists|, and second, that \textsf{index} is within bounds. It throws an error otherwise.
396 % \begin{macrocode}
397 \newcommand*{\macrolist@inbounds}[2]{%
398 \macrolist@exists{#1}%
399 %
400 \if\relax\detokenize{#2}
401 \PackageError{macrolist}
402 {No number has been passed into the second argument of your command
403 }{Pass in a number to the second argument of your command.}
404 \fi
405 %
406 \ifnum\numexpr#2 \relax>\macrolistsize{#1}
407 \PackageError{macrolist}
408 {Index out of bounds}
409 {The number you have passed in to the second argument of your command\MessageBreak
410 is out of the bounds of list '#1'.}
411 \fi
412 }
413 % \end{macrocode}
414 % \end{macro}
415 %
416 % \Finale
417 \endinput