| 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 |