Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % getitems.dtx
4 % Copyright 2016 by Anders O.F. Hendrickson ([email protected])
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is 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 %
14 % This work has the LPPL maintenance status `maintained'.
15 %
16 % The Current Maintainer of this work is Anders O.F. Hendrickson.
17 %
18 % This work consists of the files moodle.dtx and moodle.ins
19 % and the derived files moodle.sty and getitems.sty.
20 %
21 % \fi
22 %
23 % \iffalse
24 %<*driver>
25 \ProvidesFile{getitems.dtx}
26 %</driver>
27 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
28 %<package>\ProvidesPackage{getitems}
29 %<*package>
30 [2016/01/11 v1.0 gather items from a list]
31 %</package>
32 %
33 %<*driver>
34 \documentclass{ltxdoc}
35 \usepackage{getitems}
36 \usepackage{fancyvrb}
37 \usepackage{amssymb}
38 \usepackage{xcolor}
39 \EnableCrossrefs
40 \CodelineIndex
41 \RecordChanges
42 \begin{document}
43 \DocInput{getitems.dtx}
44 \PrintChanges
45 %\PrintIndex
46 \end{document}
47 %</driver>
48 % \fi
49 %
50 % \CheckSum{212}
51 %
52 % \CharacterTable
53 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
54 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
55 % Digits \0\1\2\3\4\5\6\7\8\9
56 % Exclamation \! Double quote \" Hash (number) \#
57 % Dollar \$ Percent \% Ampersand \&
58 % Acute accent \' Left paren \( Right paren \)
59 % Asterisk \* Plus \+ Comma \,
60 % Minus \- Point \. Solidus \/
61 % Colon \: Semicolon \; Less than \<
62 % Equals \= Greater than \> Question mark \?
63 % Commercial at \@ Left bracket \[ Backslash \\
64 % Right bracket \] Circumflex \^ Underscore \_
65 % Grave accent \` Left brace \{ Vertical bar \|
66 % Right brace \} Tilde \~}
67 %
68 %
69 % \changes{v1.0}{2016/01/11}{Initial version}
70 %
71 % \GetFileInfo{getitems.sty}
72 %
73 % \DoNotIndex{\newcommand,\newenvironment,\def}
74 %
75 %
76 % \title{The \textsf{getitems} package: \\
77 % gathering {\tt\string\item}'s from a list-like environment\thanks{This document
78 % corresponds to \textsf{getitems.sty}~\fileversion, dated \filedate.}}
79 % \author{Anders Hendrickson\\ St.~Norbert College, De~Pere, WI, USA \\ \texttt{[email protected]}}
80 %
81 %
82 % \maketitle
83 %
84 % \section{Overview}
85 %
86 % The |enumerate| and |itemize| environments of \LaTeX\ organize their contents
87 % through the use of the |\item| command. Each entry in these lists is prefaced
88 % with the command |\item|, making for very compact and easily readable source
89 % code. Package designers may find it useful to use the same syntax for
90 % their custom environments. The \textsf{getitems} package makes
91 % it easy to code such environments by parsing a string of tokens, separating them
92 % by the occurrence of |\item|'s, and saving the contents as macros.
93 % Nested environments are handled correctly.
94 %
95 % Moreover, some typesetting tasks naturally consist of a ``header'' followed by
96 % several related items; one example would be a multiple-choice question on a
97 % school examination. This package saves any \TeX\ tokens appearing before the
98 % first |\item| as the zeroth item for special handling.
99 %
100 % \section{Usage}
101 %
102 % \DescribeMacro{\gatheritems}
103 % To parse a string of text, such as the body of an environment,
104 % call
105 % \begin{center}
106 % |\gatheritems|\marg{text to parse}.
107 % \end{center}
108 % This will scan through the \meta{text to parse}, dividing it at each |\item|
109 % while respecting \TeX\ groupings and nested environments,
110 % and store the divided portions of text into memory.
111 %
112 % \DescribeMacro{numgathereditems}
113 % The total number of items in the parsed text is stored in the \LaTeX\ counter
114 % |numgathereditems|.
115 %
116 % \DescribeMacro{\gathereditem}
117 % To retrieve a stored item, you may call |\gathereditem|\marg{item number};
118 % the \meta{item number} should expand to an arabic representation of a nonnegative integer.
119 % Any tokens occurring before the first |\item| may be retrieved with
120 % |\gathereditem{0}|.
121 %
122 % \DescribeMacro{\loopthroughitemswithcommand}
123 % Once the items are gathered, it will probably be necessary to loop through
124 % all of them.
125 % Of course a package author can do so manually, but |getitems| provides a
126 % built-in way to do so by calling |\loopthroughitemswithcommand|\marg{macro}.
127 % The \meta{macro} must be a control sequence taking exactly one argument;
128 % it will be called successively with the item text.
129 % For example,
130 % \begin{quote}
131 % \begin{tabular}{p{3in}p{1.5in}}
132 % \begin{minipage}{3in}
133 % \begin{Verbatim}[gobble=6]
134 % \gatheritems{%
135 % Zero
136 % \item One
137 % \item Two
138 % \item Three
139 % }
140 % \loopthroughitemswithcommand{\fbox}
141 % \end{Verbatim}
142 % \end{minipage}
143 % &
144 % \begin{minipage}{1.5in}
145 % \gatheritems{%
146 % Zero
147 % \item One
148 % \item Two
149 % \item Three
150 % }
151 % \loopthroughitemswithcommand{\fbox}
152 % \end{minipage}
153 % \end{tabular}
154 % \end{quote}
155 % The result is the same as processing |\fbox{One}|, then |\fbox{Two}|, and finally |\fbox{Three}|.
156 % Note that |\loopthroughitemswithcommand| deliberately ignores the zeroth entry, which occurs
157 % before the first |\item|.
158 %
159 % \DescribeMacro{currentitemnumber}
160 % Typically the package author will create a custom macro to process each item.
161 % This macro may make use of the index of the loop, which is stored in the
162 % \LaTeX\ counter |currentitemnumber|.
163 % \DescribeMacro{\ifgatherbeginningofloop}
164 % A conditional |\ifgatherbeginningofloop| is also available,
165 % which only evaluates as true when
166 % processing the first item; it is thus functionally equivalent to
167 % |\ifnum1=\c@currentitemnumber|.
168 % The custom macro may take advantage of this to run special code for the first item only.
169 %
170 %
171 % \section{Example}
172 % An example using |getitems| to create a custom environment may be informative.
173 % We use the |\NewEnviron| command from the |environ| package
174 % (automatically loaded by |getitems|) to define a |question| environment;
175 % the body between the |\begin{question}| and |\end{question}| is available as |\BODY|.
176 % \medskip
177 %
178 % \par \noindent
179 % \begin{tabular}{p{3in}p{1.5in}}
180 % \begin{minipage}{3in}
181 % \small
182 % \begin{Verbatim}[gobble=6]
183 % \def\doitem#1{\item #1\hfill $\Box$}%
184 % \NewEnviron{question}{%
185 % \expandafter\gatheritems\expandafter{\BODY}%
186 % \gathereditem{0}%
187 % \begin{itemize}
188 % \loopthroughitemswithcommand{\doitem}
189 % \end{itemize}
190 % }
191 % \begin{question}
192 % Who proved the unsolvability of the quintic?
193 % \item Abel
194 % \item Galois
195 % \item Lie
196 % \end{question}
197 % \end{Verbatim}
198 % \end{minipage}
199 % &
200 % \begin{minipage}{1.5in}
201 % \def\doitem#1{\item #1\hfill $\Box$}%
202 % \NewEnviron{question}{%
203 % \expandafter\gatheritems\expandafter{\BODY}%
204 % \gathereditem{0}%
205 % \begin{itemize}
206 % \loopthroughitemswithcommand{\doitem}
207 % \end{itemize}
208 % }
209 % \begin{question}
210 % Who proved the unsolvability of the quintic?
211 % Check the appropriate box.
212 % \item Abel
213 % \item Galois
214 % \item Lie
215 % \end{question}
216 % \end{minipage}
217 % \end{tabular}
218 % \medskip
219 %
220 %
221 % This second example shows that nested environments are handled as expected.
222 % \medskip
223 %
224 % \par \noindent
225 % \begin{tabular}{p{3in}p{2in}}
226 % \begin{minipage}{3in}
227 % \small
228 % \begin{Verbatim}[gobble=6]
229 % \def\doitem#1{\item[$\Box$]
230 % \fbox{\parbox[t]{1.75in}{#1}}}%
231 % \NewEnviron{question}{%
232 % \expandafter\gatheritems\expandafter{\BODY}%
233 % \gathereditem{0}%
234 % \begin{itemize}
235 % \loopthroughitemswithcommand{\doitem}
236 % \end{itemize}
237 % }
238 % \begin{question}
239 % Who proved the unsolvability of the quintic?
240 % Check the appropriate box.
241 % \item Abel
242 % \begin{itemize}
243 % \item Born August 5, 1802
244 % \item Died April 6, 1829
245 % \end{itemize}
246 % \item Galois
247 % \begin{itemize}
248 % \item Born October 25, 1811
249 % \item Died May 31, 1832
250 % \end{itemize}
251 % \item Lie
252 % \begin{itemize}
253 % \item Born December 17, 1842
254 % \item Died February 18, 1899
255 % \end{itemize}
256 % \end{question}
257 % \end{Verbatim}
258 % \end{minipage}
259 % &
260 % \begin{minipage}{2.5in}
261 % \def\doitem#1{\item[$\Box$] \fbox{\parbox[t]{1.75in}{#1}}}%
262 % \NewEnviron{question}{%
263 % \expandafter\gatheritems\expandafter{\BODY}%
264 % \gathereditem{0}%
265 % \begin{itemize}
266 % \loopthroughitemswithcommand{\doitem}
267 % \end{itemize}
268 % }
269 % \begin{question}
270 % Who proved the unsolvability of the quintic?
271 % Check the appropriate box.
272 % \item Abel
273 % \begin{itemize}
274 % \item Born August 5, 1802
275 % \item Died April 6, 1829
276 % \end{itemize}
277 % \item Galois
278 % \begin{itemize}
279 % \item Born October 25, 1811
280 % \item Died May 31, 1832
281 % \end{itemize}
282 % \item Lie
283 % \begin{itemize}
284 % \item Born December 17, 1842
285 % \item Died February 18, 1899
286 % \end{itemize}
287 % \end{question}
288 % \end{minipage}
289 % \end{tabular}
290 %
291 %
292 % \StopEventually{}
293 %
294 % \section{Implementation}
295 %
296 % We need the |trimspaces| package to remove excess spaces
297 % from the items we find.
298 % Although the |environ| package is not used by |getitems| itself,
299 % it will almost certainly be needed.
300 % \begin{macrocode}
301 \RequirePackage{environ}
302 \RequirePackage{trimspaces}
303 \let\xa=\expandafter
304 % \end{macrocode}
305 % \begin{macro}{\gathereditem}
306 % The $k$th item found will be stored in the macro |\getitems@item@|\meta{k};
307 % the user can access it through the |\gathereditem| macro.
308 % \begin{macrocode}
309 \def\gathereditem#1{\csname getitems@item@#1\endcsname}
310 % \end{macrocode}
311 % \end{macro}
312 %
313 % \begin{macro}{numgathereditems}
314 % We define the \LaTeX\ counter |numgathereditems|.
315 % \begin{macrocode}
316 \newcounter{numgathereditems}
317 % \end{macrocode}
318 % \end{macro}
319 %
320 % \begin{macro}{\gatheritems}
321 % The main control sequence of this package is |\gatheritems|.
322 % The na\"ive strategy is to use the delimiter mechanism of \TeX\ to
323 % split the text at the first occurrence of the token ``|\item|.''
324 % We add |\getitems@relax| before,
325 % and ``|\item\getitems@terminalitem|'' after, the text to help us
326 % detect empty items and prevent
327 % errors after we have found all the genuine |\item|'s.
328 % \begin{macrocode}
329 \long\def\gatheritems#1{%
330 \setcounter{getitems@begindepth}{0}%
331 \setcounter{numgathereditems}{0}%
332 \xa\long\xa\gdef\csname getitems@item@0\endcsname{}%
333 \gatheritems@int\getitems@relax#1\item\getitems@terminalitem\getitems@endgatheritems
334 \xa\let\xa\gatheredheader\xa=\csname getitems@item@0\endcsname
335 }
336 % \end{macrocode}
337 % \end{macro}
338 % The trouble with the na\"ive strategy is that it won't handle nested
339 % environments correctly. To do that, we need to keep track of how deeply
340 % nested we are with the macro |\getitems@trackbegindepth|, defined below.
341 % That macro stores its results in the \LaTeX\ counter |getitems@begindepth|;
342 % a value of 0 indicates the top-level within the argument of |\gatheritems|.
343 % \begin{macrocode}
344 \def\@getitems@terminalitem{\getitems@terminalitem}%
345 \def\@dummy@relax{\getitems@relax}%
346 \long\def\gatheritems@int#1\item#2\getitems@endgatheritems{%
347 \getitems@trackbegindepth{#1}%
348 \ifnum\c@getitems@begindepth=0\relax
349 % \end{macrocode}
350 % At this point we have gathered a complete |\item|; we have not stopped
351 % accidentally at a sub|\item|. The original |\item| might have had no content,
352 % in which case |#1| will be simply ``|\getitems@relax|'', and we do nothing;
353 % otherwise we strip off the |\getitems@relax| and store those tokens in
354 % |\getitems@item@|\meta{numgathereditems}.
355 % \begin{macrocode}
356 \def\getitems@test@i{#1}%
357 \ifx\getitems@test@i\@dummy@relax
358 \relax
359 \else
360 \xa\xa\xa\g@addto@macro
361 \xa\xa\csname getitems@item@\the\c@numgathereditems\endcsname
362 \xa{\getitems@stripfirsttokenfrom#1\getitems@endstrip}%
363 \fi
364 % \end{macrocode}
365 % Now we test whether we have reached the end of the text to be parsed.
366 % This is the case if |#2| is simply |\getitems@terminalitem|,
367 % and we stop the recursion.
368 % Otherwise there is at least one more |\item| to process, so we increment |numgathereditems|,
369 % prepare |\getitems@item@|\meta{k+1},
370 % and prepare to recurse.
371 % \begin{macrocode}
372 \def\getitems@test@ii{#2}%
373 \ifx\getitems@test@ii\@getitems@terminalitem
374 \let\getitems@next=\relax
375 \else
376 \stepcounter{numgathereditems}%
377 \xa\gdef\csname getitems@item@\the\c@numgathereditems\endcsname{}%
378 \def\getitems@next{\gatheritems@int\getitems@relax#2\getitems@endgatheritems}%
379 \fi
380 \else
381 % \end{macrocode}
382 % We are now in the case where |getitems@begindepth|${}\neq 0$.
383 % This essentially means that the text in |#1| has more |\begin|'s than |\end|'s,
384 % so we have not read a complete |\item|; we stopped at an ``|\item|'' token
385 % within a sub-environment.
386 % We save the text gathered so far to |\getitems@item@|\meta{k},
387 % including the |\item| we parsed by mistake,
388 % and then call |\gatheritems@int| again to sweep up more tokens.
389 % \begin{macrocode}
390 \xa\xa\xa\g@addto@macro
391 \xa\xa\csname getitems@item@\the\c@numgathereditems\endcsname
392 \xa{\getitems@stripfirsttokenfrom#1\getitems@endstrip}%
393 \xa\g@addto@macro\csname getitems@item@\the\c@numgathereditems\endcsname{\item}%
394 \def\getitems@next{\gatheritems@int\getitems@relax#2\getitems@endgatheritems}%
395 \fi
396 \getitems@next
397 }
398 % \end{macrocode}
399 % This next macro is used by |\gatheritems@int| to strip off a
400 % dummy |\getitems@relax| token from the beginning of its first parameter.
401 % \begin{macrocode}
402 \long\def\getitems@stripfirsttokenfrom#1#2\getitems@endstrip{#2}
403 % \end{macrocode}
404 % Here is the code used to track the depth of nesting of |\begin|'s in a text.
405 % \begin{macrocode}
406 \newcounter{getitems@begindepth}
407 \long\def\getitems@trackbegindepth#1{%
408 \getitems@trackbegindepth@int#1\getitems@terminalbegindepth\getitems@endtrackbegindepth
409 }
410 \def\@getitems@begin{\begin}%
411 \def\@getitems@end{\end}%
412 \def\@getitems@terminalbegindepth{\getitems@terminalbegindepth}%
413 \long\def\getitems@trackbegindepth@int#1#2\getitems@endtrackbegindepth{%
414 \def\getitems@test@i{#1}%
415 \ifx\getitems@test@i\@getitems@begin
416 \advance\c@getitems@begindepth by 1\relax
417 \else
418 \ifx\getitems@test@i\@getitems@end
419 \advance\c@getitems@begindepth by -1\relax
420 \fi
421 \fi
422 \def\getitems@test@ii{#2}%
423 \trim@spaces@in\getitems@test@ii
424 \ifx\getitems@test@ii\@getitems@terminalbegindepth
425 \let\getitems@trackbegindepth@next=\relax
426 \else
427 \def\getitems@trackbegindepth@next{%
428 \getitems@trackbegindepth@int#2\getitems@endtrackbegindepth}%
429 \fi
430 \getitems@trackbegindepth@next
431 }
432 % \end{macrocode}
433 % \begin{macro}{\loopthroughitemswithcommand}
434 % Finally, we define the user-level command to loop through
435 % the gathered items from 1 through |numgathereditems|.
436 % \begin{macrocode}
437 \newif\ifgatherbeginningofloop
438 \newcounter{currentitemnumber}
439 \def\loopthroughitemswithcommand#1{%
440 \setcounter{currentitemnumber}{1}%
441 \gatherbeginningoflooptrue
442 \loopthroughitemswithcommand@int{#1}%
443 }
444
445 \def\loopthroughitemswithcommand@int#1{%
446 \ifnum\c@currentitemnumber>\c@numgathereditems\relax
447 \let\getitems@loop@next=\relax%
448 \else
449 \xa\xa\xa#1\xa\xa\xa{\csname getitems@item@\the\c@currentitemnumber\endcsname}%
450 \def\getitems@loop@next{\loopthroughitemswithcommand@int{#1}}%
451 \stepcounter{currentitemnumber}%
452 \fi
453 \gatherbeginningofloopfalse
454 \getitems@loop@next
455 }
456 % \end{macrocode}
457 % \end{macro}
458 %
459 % \Finale
460 \endinput