Debian Codegraph @

texmf-dist/source/latex/cals/lltokens.dtx

raw
1 % \subsection{List list of tokens}
2 %
3 % Two-dimensional arrays of tokens, or lists of lists of tokens.
4 %
5 %
6 % Format of the list:
7 %
8 % \begin{verbatim}
9 % {...tokens1...}{...tokens2...}...{...tokensN...}
10 % \end{verbatim}
11 %
12 % Token manipulation should not belong to the ``cals'' package,
13 % and the macros from this section have the prefix |llt@|
14 % instead of |cals@|. Probably it is better to use some CTAN
15 % package, but initially the llt-code was small and simple, so
16 % I did not want dependencies, and now I do not want to replace
17 % working code with something new.
18 %
19 % In comments to these functions, a parameter of type \textit{token list}
20 % is a macro which will be expanded once to get the tokens, and
21 % \textit{list list} is a macro which stores the two-dimensional array.
22 %
23 % An example of use:
24 % \begin{verbatim}
25 % \def\aaa{aaa}
26 % \def\bbb{bbb}
27 % \def\ccc{ccc}
28 % \def\lst{} % empty list
29 % \llt@cons\bbb\lst % \lst -> "{bbb}"
30 % \llt@snoc\lst\ccc % \lst -> "{bbb}{ccc}"
31 % \llt@cons\aaa\lst % \lst -> "{aaa}{bbb}{ccc}"
32 % \llt@decons\lst % \llt@car -> "aaa", \lst -> "{bbb}{ccc}"
33 % \llt@rot\lst % \llt@car -> "bbb", \lst -> "{ccc}{bbb}"
34 % \end{verbatim}
35 %
36 %
37
38 %
39 % \begin{macro}{\llt@cons}
40 % Prepends the token list \#1 to the list list \#2.
41 % Corrupts the token registers 0 and~2.
42 % \begin{macrocode}
43 \def\llt@cons#1#2{%
44 \toks0=\expandafter{#1}%
45 \toks2=\expandafter{#2}%
46 \edef#2{\noexpand{\the\toks0}\the\toks2 }%
47 }
48 % \end{macrocode}
49 % \end{macro}
50
51 %
52 % \begin{macro}{\llt@snoc}
53 % Appends the token list \#2 to the list list \#1 (note the order
54 % of parameters).
55 % Macro corrupts the token registers 0 and 2.
56 %
57 % \begin{macrocode}
58 \def\llt@snoc#1#2{%
59 \toks0=\expandafter{#1}%
60 \toks2=\expandafter{#2}%
61 \edef#1{\the\toks0 \noexpand{\the\toks2}}%
62 }
63 % \end{macrocode}
64 % \end{macro}
65
66 %
67 % \begin{macro}{\llt@car}
68 % A token list, set as a side-effect of the list deconstruction
69 % and rotation functions.
70 % \end{macro}
71
72 %
73 % \begin{macro}{\llt@decons}
74 % List deconstruction. The first item is removed from the list list \#1
75 % and its tokens are put to the token list |\llt@car|.
76 % Corrupts the token register 0.
77 % Undefined behaviour if the list list has no items.
78 %
79 % The actual work happens on the |\expandafter| line.
80 % It's hard to explain, let me show the macro expansion,
81 % I hope it's self-explaining.
82 %
83 % \begin{verbatim}
84 % \expandafter\llt@decons@open\lst} -->
85 % \llt@decons@open{aaa}{bbb}{ccc}{ddd}} -->
86 % \def\llt@car{aaa} \toks0=\llt@opengroup {bbb}{ccc}{ddd}} -->
87 % \def\llt@car{aaa} \toks0={{bbb}{ccc}{ddd}}
88 % \end{verbatim}
89 %
90 % Why I use |\let\llt@opengroup={| inside the definition?
91 % Only to balance the number of opening and closing brackets.
92 % Otherwise TeX will not compile the definition.
93 %
94 % Initially I tried to use the following helper:
95 %
96 % \begin{verbatim}
97 % \def\decons@helper#1#2\relax{%
98 % \def\llt@car{#1}%
99 % \def\list{#2}}
100 % \end{verbatim}
101 %
102 % If a call is |\decons@helper{aaa}{bbb}{ccc}\relax| then
103 % all is ok, the helper gets: \#1 is |aaa| and \#2 is
104 % |{bbb}{ccc}|.
105 %
106 % Unfortunately, if the list has two items and the call is
107 % |\decons@helper{aaa}{bbb}}\relax|, then the helper gets:
108 % \#1 is |aaa| and \#2 is |bbb| instead of |{bbb}|.
109 % The grouping tokens are lost, and we can't detect it.
110 %
111 % \begin{macrocode}
112 \def\llt@decons@open#1{%
113 \def\llt@car{#1}%
114 \toks0=\llt@opengroup
115 }
116
117 \def\llt@decons#1{%
118 \let\llt@opengroup={%
119 \expandafter\llt@decons@open#1}%
120 \edef#1{\the\toks0}%
121 }
122 % \end{macrocode}
123 % \end{macro}
124
125 %
126 % \begin{macro}{\llt@rot}
127 % Rotates the list list \#1. The first item becomes the last. Also,
128 % its tokens are saved to token list |\llt@car|.
129 % The second item becomes the first item, the third the second etc.
130 % Corrupts the token registers 0 and 2.
131 %
132 % \begin{macrocode}
133 \def\llt@rot#1{%
134 \ifx#1\empty
135 \let\llt@car=\relax
136 \else
137 \llt@decons#1%
138 \llt@snoc#1\llt@car%
139 \fi
140 }
141 % \end{macrocode}
142 % \end{macro}
143
144 %
145 % \begin{macro}{\llt@desnoc}
146 % Very unefficient list deconstruction. The last item is removed
147 % from the list list \#1 % and its tokens are put to the token
148 % list |\llt@car|. Corrupts the token registers 0 and 2.
149 % Undefined behaviour if the list list has no items.
150 %
151 % |\llt@desnocII| is used to hide |\if| from the loop.
152 % \begin{macrocode}
153 \def\llt@desnocII#1{
154 \ifx\empty#1%
155 \let\llt@tmp=n%
156 \else
157 \llt@snoc{\llt@newlist}{\llt@car}%
158 \let\llt@tmp=y%
159 \fi
160 }
161
162 \def\llt@desnoc#1{%
163 \def\llt@newlist{}%
164 \loop
165 \llt@decons{#1}%
166 \llt@desnocII{#1}%
167 \if y\llt@tmp \repeat
168 \let#1=\llt@newlist}
169 % \end{macrocode}
170 % \end{macro}