Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<=*COPYRIGHT>
3 %% Copyright (c) 2009-2025 by Martin Scharrer <[email protected]>
4 %% ----------------------------------------------------------------------
5 %% This work may be distributed and/or modified under the
6 %% conditions of the LaTeX Project Public License, either version 1.3
7 %% of this license or (at your option) any later version.
8 %% The latest version of this license is in
9 %% http://www.latex-project.org/lppl.txt
10 %% and version 1.3 or later is part of all distributions of LaTeX
11 %% version 2005/12/01 or later.
12 %%
13 %% This work has the LPPL maintenance status `maintained'.
14 %%
15 %% The Current Maintainer of this work is Martin Scharrer.
16 %%
17 %% This work consists of the files collcell.dtx and collcell.ins
18 %% and the derived filebase collcell.sty.
19 %%
20 %<=/COPYRIGHT>
21 % \fi
22 %
23 % \iffalse
24 %<*driver>
25 \ProvidesFile{collcell.dtx}[%
26 %<=*DATE>
27 2025/02/21
28 %<=/DATE>
29 %<=*VERSION>
30 v0.6
31 %<=/VERSION>
32 DTX file for collcell]
33 \documentclass{ydoc}[2011/03/19]
34 \GetFileInfo{collcell.dtx}
35 \usepackage[robustcr]{collcell}[\filedate]
36 \usepackage{tikz-timing}
37 \lstset{language=[latex]tex,basicstyle=\ttfamily}
38
39 \EnableCrossrefs
40 %\CodelineIndex
41 \RecordChanges
42 %\OnlyDescription
43 \begin{document}
44 \DocInput{\jobname.dtx}
45 \PrintChanges
46 %\newpage\PrintIndex
47 \end{document}
48 %</driver>
49 % \fi
50 %
51 % \CheckSum{358}
52 %
53 % \CharacterTable
54 % {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
55 % 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
56 % Digits \0\1\2\3\4\5\6\7\8\9
57 % Exclamation \! Double quote \" Hash (number) \#
58 % Dollar \$ Percent \% Ampersand \&
59 % Acute accent \' Left paren \( Right paren \)
60 % Asterisk \* Plus \+ Comma \,
61 % Minus \- Point \. Solidus \/
62 % Colon \: Semicolon \; Less than \<
63 % Equals \= Greater than \> Question mark \?
64 % Commercial at \@ Left bracket \[ Backslash \\
65 % Right bracket \] Circumflex \^ Underscore \_
66 % Grave accent \` Left brace \{ Vertical bar \|
67 % Right brace \} Tilde \~}
68 %
69 %
70 % \changes{v0.0}{2009/08/13}{Created package}
71 % \changes{v0.1}{2011/02/04}{First released version}
72 % \changes{v0.1a}{2011/02/05}{Fixed unwanted spaces. Fixed misspelled macros in example.}
73 % \changes{v0.5}{2011/02/27}{Fixed several bugs and limitations. (Complete list to be inserted)}
74 % \changes{v0.6}{2025/02/21}{Add support for \textonly@unskip. Support nesting of environments in cells.}
75 %
76 % \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\DeclareRobustCommand}
77 %
78 % \GetFileInfo{\jobname.dtx}
79 % \author{Martin Scharrer}
80 % \email{[email protected]}
81 % \maketitle
82 %
83 % \begin{abstract}
84 % This package provides macros which collect the cell content of a tabular
85 % and provide it to a macro as argument. It was inspired by the |\collect@body|
86 % macro defined by the \pkg{amsmath} or the \pkg{environ} package, which can be used
87 % to collect the body of an environment. Special care is taken to remove all aligning
88 % macros inserted by tabular from the cell content. The macros also work in the last
89 % column of a tabular. They do not support verbatim material inside the cells, except of a
90 % special almost-verbatim version of \verb+\verb+.
91 %
92 % This package is relatively new and might still not work in all possible situations which can arise
93 % in a tabular. The implementation might change in future versions. Please do not hesitate to contact the
94 % author about any issue and suggestions.
95 % \end{abstract}
96 %
97 % \section{Usage}
98 % This package provides the macros \Macro\collectcell and \Macro\endcollectcell
99 % which are supposed to be used with the |>{ }| and |<{ }| tabular column declarations of
100 % the \pkg{array} package. This can be done either in the argument of tabular or using
101 % \Macro\newcolumntype.
102 %
103 % The following code defines a `|E|' column which passes the contents of its cell
104 % to \Macro\usermacro as an argument. The macro can the process the content as usual.
105 %
106 % \par\bigskip
107 % \noindent
108 % |% Preamble:|\\
109 % |\usepackage{array}|\\
110 % |\usepackage{collcell}|\\
111 % |% Preamble or document:|\\
112 % |\newcolumntype{E}{>{\collectcell\usermacro}c<{\endcollectcell}}|\\
113 % ||\\
114 % |% Document:|\\
115 % |\begin{tabular}{lE}|\\
116 % | A & Example \\ % Same as \usermacro{Example} |\\
117 % | B & Text \\ % Same as \usermacro{Text} |\\
118 % |\end{tabular}|\\
119 % \par\medskip
120 %
121 % For example \Macro\usermacro could be \Macro\fbox and wrap the cell content in a frame box.
122 % More complicated macros are also supported as long they take one argument. This package
123 % was originally programmed to be used with the \Macro\tikztiming macro of the \pkg{tikz-timing} package.
124 % This macro takes some complex user input and draws a timing diagram from it
125 %
126 % Note that if such a cell contains a tabular environment by itself, the environment must be wrapped
127 % in braces `|{ }|' to ensure proper operation.
128 %
129 % \subsection{Options}
130 %
131 % The~\opt*{verb} and~\opt*{noverb} options enable or disable (default) the definition of a special almost-verbatim version of \verb+\verb+.
132 % At the moment the one defined by the \pkg{tabularx} package is used, which is therefore loaded when this feature is enabled.
133 % Future versions of \pkg{collcell} might provide this macro in a different way, so the visual result might be different.
134 % The \pkg{tabularx} should be loaded explicitly if it is used.
135 % This version of \verb+\verb+ will read the content first normally, i.e. non-verbatim, and then print the included tokens in a verbatim format.
136 % The content must include a balanced number of |{ }| and must not be end with |\|. Macros inside the content will be followed by a space.
137 % See the manual of \pkg{tabularx} (page 8 in the version from 1999/01/07) for a more detailed description.
138 %
139 % The~\opt*{robustcr} and \opt*{norobustcr} options enable (default) or disable the redefinition of |\\| to a robust version, i.e. this macro
140 % will be prefixed with eTeX's |\protected| to ensure that it isn't expanded by the underlying |\halign|. If this feature disabled the
141 % last cell of a tabular must not be empty or only hold empty macros (like |\empty|).
142 %
143 % \subsection{Limitations}
144 %
145 % \DescribeMacro\ccunskip
146 % The macro |\unskip| should not be included inside the cell directly, but only inside a |{ }| group or a macro.
147 % Otherwise it will be taken as part of the internal cell code and ignored. Leading spaces will however be removed.
148 % This macro can be used as a replacement of |\unskip| inside the cells.
149 %
150 % \DescribeMacro\cci
151 % The content of every cell is expanded by TeX itself until the first non-expandable token (macro, character, \ldots) is found. This happens to check if a |\noalign| follows
152 % with e.g.\ is used inside |\hrule| and other rule drawing macros. There is nothing what \pkg{collcell} could do about this.
153 % If this expansion is unwanted the non-expandable token \Macro\cci should be placed at the beginning of the cell. This macro will be ignored (discarded) by \pkg{collcell} and
154 % will not be provided to the user macro (|cci| = collect cell; ignore).
155 %
156 % \clearpage
157 % \section{Tests and Examples}
158 %
159 % \begin{example}
160 % \caption{Framebox, texttiming, expanded tokens, sub-tabular}
161 % \begin{examplecode}
162 % \makeatletter
163 % \newcommand*\Meaning[1]
164 % {\def\CODE{#1}\texttt{\expandafter\strip@prefix\meaning\CODE}}%
165 % \newcolumntype{F}{>{\collectcell\fbox}l<{\endcollectcell}}%
166 % \newcolumntype{M}{>{\collectcell\Meaning}l<{\endcollectcell}}%
167 % \newcolumntype{T}{>{\collectcell\texttiming}l<{\endcollectcell}}%
168 % \begin{tabular}{@{}F@{}|@{}M@{}|@{}T@{}}
169 % A & B & HLDZ 2{HZLZ} \\
170 % A & \empty\relax Z5D{TEST}Z & Z5D{TEST}Z \\
171 % A & \cci\empty Z5D{TEST}Z & Z5D{TEST}Z \\
172 % {\begin{tabular}{cFc} a & b & c \end{tabular}} &
173 % \relax\begin{quote}AA\end{quote} & $5+5${C} \\
174 % A & B \ccunskip B & 3{ttz} \\
175 % \end{tabular}%
176 % \end{examplecode}
177 % \end{example}
178 %
179 % \makeatletter
180 % \newcommand*\Meaning[1]{\def\CODE{#1}\texttt{\expandafter\strip@prefix\meaning\CODE}}%
181 % \newcolumntype{M}{>{\collectcell\Meaning}l<{\endcollectcell}}%
182 % \newcolumntype{F}{>{\collectcell\fbox}l<{\endcollectcell}}%
183 % \makeatother
184 %
185 % \begin{example}
186 % \caption{Multicolumn, expanded row macro}
187 % \begin{examplecode}
188 % \def\abc{ \empty A & \empty B & \empty C }
189 % \begin{tabular}{MMM}
190 % \multicolumn{2}{M}{\empty Multi} & \empty single \\
191 % \abc \\
192 % \end{tabular}
193 % \end{examplecode}
194 % \end{example}
195 %
196 % \begin{example}
197 % \caption{Empty cells, missing `\texttt{\textbackslash\textbackslash}' at end}
198 % \begin{examplecode}
199 % \begin{tabular}{|F|F|F|}
200 % \\
201 % A & \\
202 % A & B \\
203 % A & B & \\
204 % A & B & C \\
205 % & \\
206 % & B \\
207 % & B & \\
208 % & B & C \\
209 % & & \\
210 % & & C \\
211 % A & B & C
212 % \end{tabular}
213 % \end{examplecode}
214 % \end{example}
215 %
216 % \StopEventually{}
217 % \clearpage
218 %
219 % \section{Implementation}
220 %
221 % \iffalse
222 %<*collcell.sty>
223 % \fi
224 % \begin{macrocode}
225 %<!COPYRIGHT>
226 \ProvidesPackage{collcell}[%
227 %<!DATE>
228 %<!VERSION>
229 %<*DRIVER>
230 2099/01/01 develop
231 %</DRIVER>
232 Collect the content of a tabular cell]
233 % \end{macrocode}
234 %
235 % \begin{macrocode}
236 \RequirePackage{array}
237 \def\collcell@beforeuser{\ignorespaces}
238 \def\collcell@afteruser{\unskip}
239
240 \newif\if@collcell@verb
241 \newif\if@collcell@robustcr
242 \@collcell@robustcrtrue
243 % \end{macrocode}
244 %
245 % \subsection{Options}
246 % \begin{macrocode}
247 \DeclareOption{verb}{\@collcell@verbtrue}
248 \DeclareOption{noverb}{\@collcell@verbfalse}
249 \DeclareOption{robustcr}{\@collcell@robustcrtrue}%
250 \DeclareOption{norobustcr}{\@collcell@robustcrfalse}%
251 \ProcessOptions\relax
252 \if@collcell@verb
253 \RequirePackage{tabularx}
254 \def\collcell@beforeuser{%
255 \let\collcell@savedverb\verb
256 \let\verb\TX@verb
257 \let\TX@vwarn\collcell@vwarn
258 \ignorespaces
259 }%
260 \def\collcell@afteruser{\unskip\let\verb\collcell@savedverb}%
261 \def\collcell@vwarn{%
262 \PackageWarning{collcell}{\noexpand\verb may be unreliable inside a collected cell}%
263 }%
264 \fi
265 \if@collcell@robustcr
266 \RequirePackage{etoolbox}
267 \robustify\@arraycr
268 \fi
269 % \end{macrocode}
270 %
271 % \subsection{Collect cell content}
272 % \begin{macrocode}
273 \let\collect@cell@toks\@temptokena
274 \newcount\collect@cell@count
275 % \end{macrocode}
276 %
277 % \begin{macro}{\collectcell}[2]{user macro(s)}{ignored tokens, possible empty}
278 % \begin{macrocode}
279 \newenvironment{collectcell}{}{}
280 \def\collectcell#1#2\ignorespaces{%
281 \begingroup
282 \collect@cell@count\z@
283 \collect@cell@toks{}%
284 \let\collect@cell@spaces\empty
285 \def\collect@cell@end{%
286 \expandafter\endgroup
287 \expandafter\collcell@beforeuser
288 \expandafter\ccell@swap\expandafter{\the\collect@cell@toks}{#1}%
289 \collcell@afteruser
290 }%
291 \collect@cell@look#2%
292 }
293 % \end{macrocode}
294 % \end{macro}
295 %
296 % \begin{macro}{\ccell@swap}
297 % Swaps the two arguments. The second one (user macro(s)) is added without braces.
298 % \begin{macrocode}
299 \def\ccell@swap#1#2{#2{#1}}
300 % \end{macrocode}
301 % \end{macro}
302 %
303 % \begin{macro}{\endcollectcell}
304 % Holds unique signature which will expand to nothing.
305 % \begin{macrocode}
306 \def\endcollectcell{\@gobble{endcollectcell}}
307 % \end{macrocode}
308 % \end{macro}
309 %
310 %
311 % \begin{macro}{\collect@cell@look}
312 % Looks ahead to the next token and call the next macro to handle it.
313 % \begin{macrocode}
314 \def\collect@cell@look{%
315 \futurelet\collect@cell@lettoken\collect@cell@look@
316 }
317 % \end{macrocode}
318 % \end{macro}
319 %
320 % \begin{macro}{\collect@cell@eatspace}
321 % Eats a following space and call the 'look' macro again.
322 % \begin{macrocode}
323 \@firstofone{\def\collect@cell@eatspace} {\collect@cell@look}
324 % \end{macrocode}
325 % \end{macro}
326 %
327 % \begin{macro}{\collect@cell@look@}
328 % Handles special tokens which should not be read as argument.
329 % All other are handled by \Macro\collect@cell@arg.
330 % \begin{macrocode}
331 \def\collect@cell@look@{%
332 \cc@case
333 \@sptoken{%
334 \edef\collect@cell@spaces{\collect@cell@spaces\space}%
335 \collect@cell@eatspace
336 }%
337 \bgroup{\collect@cell@group}%
338 \default{\collect@cell@arg}%
339 \endcc@case
340 }
341 % \end{macrocode}
342 % \end{macro}
343 %
344 % \begin{macro}{\collect@cell@group}
345 % Tests if the previous discovered |begin-group character {| token was a |\bgroup| or a |{|.
346 % In the first case the command sequence is simply added but in the second case the surrounding
347 % braces must be added again.
348 % The use of |\unexpanded| allows |#| in the cells, e.g. for in-cell macro definitions.
349 % \begin{macrocode}
350 \def\collect@cell@group#1{%
351 \begingroup
352 \edef\@tempa{\unexpanded{#1}}%
353 \def\@tempb{\bgroup}%
354 \ifx\@tempa\@tempb
355 \endgroup
356 \collect@cell@addarg{#1}%
357 \else
358 \endgroup
359 \collect@cell@addarg{{#1}}%
360 \fi
361 \collect@cell@look
362 }
363 % \end{macrocode}
364 % \end{macro}
365 %
366 % \begin{macro}{\collect@cell@addarg}
367 % Adds the given argument to the token list.
368 % \begin{macrocode}
369 \def\collect@cell@addarg#1{%
370 \expandafter\expandafter\expandafter\collect@cell@toks
371 \expandafter\expandafter\expandafter
372 {\expandafter\the\expandafter\collect@cell@toks\collect@cell@spaces#1}%
373 \let\collect@cell@spaces\empty
374 }
375 % \end{macrocode}
376 % \end{macro}
377 %
378 % \begin{macro}{\collect@cell@addcc}
379 % This macro is called when another |\collectcell| is found in the preamble
380 % (at the moment also inside the cell). The argument of it is placed into the
381 % token register and all following tokens are placed in an own token list which content
382 % is then added with surrounding braces in the outer token list once the |\endcollectcell|
383 % is found. TeX scoping mechanism is used for this so only one token register is required.
384 % \begin{macrocode}
385 \def\collect@cell@addcc#1{%
386 \collect@cell@addarg{#1}%
387 \begingroup
388 \collect@cell@toks{}%
389 \collect@cell@look
390 }
391 % \end{macrocode}
392 % \end{macro}
393 %
394 % \begin{macro}{\collect@cell@checkcsname}
395 % For support of |\end{tabularx}| without trailing |\\|.
396 % \begin{macrocode}
397 \def\collect@cell@checkcsname#1\endcsname{%
398 \begingroup
399 \expandafter\ccell@swap\expandafter
400 {\expandafter,\@currenvir,endtabular,endtabular*,array,tabularx,}%
401 {\in@{,#1,}}%
402 \ifin@
403 \endgroup
404 \expandafter\@firstoftwo
405 \else
406 \endgroup
407 \expandafter\@secondoftwo
408 \fi
409 {\collect@cell@cr\tabularnewline\csname#1\endcsname}%
410 {\collect@cell@addarg{\csname#1\endcsname}\collect@cell@look}%
411 }
412 % \end{macrocode}
413 % \end{macro}
414 %
415 % \begin{macro}{\collect@cell@checkend}[1]{The argument of an \string\end~macro}
416 % Reads the argument of |\end| and checks if it is identical to the current environment (|tabular|, |array|, |tabularx|, ...).
417 % If so the collecting of token is ended, otherwise the |\end| and its argument are added to the
418 % \begin{macrocode}
419 \def\collect@cell@checkend#1{%
420 \begingroup
421 \def\@tempa{#1}%
422 \ifx\@tempa\@currenvir
423 \endgroup
424 \expandafter\@firstoftwo
425 \else
426 \endgroup
427 \expandafter\@secondoftwo
428 \fi
429 {\collect@cell@cr\tabularnewline\end{#1}}%
430 {\collect@cell@addarg{\end{#1}}\collect@cell@look}%
431 }
432 % \end{macrocode}
433 % \end{macro}
434 %
435 % \begin{macro}{\cc@iftoken}
436 % Compares the |\collect@cell@lettoken| with the token given as argument.
437 % \begin{macrocode}
438 \def\cc@iftoken#1{%
439 \ifx#1\collect@cell@lettoken
440 \expandafter\@firstoftwo
441 \else
442 \expandafter\@secondoftwo
443 \fi
444 }
445 % \end{macrocode}
446 % \end{macro}
447 %
448 % \begin{macro}{\cc@case}
449 % Case statement over |\collect@cell@lettoken|.
450 % \begin{macrocode}
451 \def\cc@case{%
452 \begingroup
453 \let\default= \collect@cell@lettoken
454 \cc@@case
455 }
456 \def\cc@@case#1{%
457 \ifx#1\collect@cell@lettoken
458 \expandafter\cc@@truecase
459 \else
460 \expandafter\cc@@falsecase
461 \fi
462 }
463 \def\cc@@truecase#1#2\endcc@case{\endgroup#1}
464 \def\cc@@falsecase#1{\cc@@case}
465 % \end{macrocode}
466 % \end{macro}
467 %
468 % \begin{macro}{\collcell@unskip}
469 % Wrapper around |\unskip| to protect it from the eyes of the token scanner.
470 % It is protected to avoid trouble if the user wrongly uses it at the beginning of the cell.
471 % The macro is first defined using |\newcommand| to warn the user about name collisions.
472 % \begin{macrocode}
473 \newcommand*\ccunskip{}
474 \protected\def\ccunskip{\unskip}
475 % \end{macrocode}
476 % \end{macro}
477 %
478 % \begin{macro}{\cci}
479 % Protected empty macro usable to stop the expansion of tokens at the beginning of the
480 % cell. It is ignored (gobbled) by the token scanner.
481 % The macro is first defined using |\newcommand| to warn the user about name collisions.
482 % \begin{macrocode}
483 \newcommand*\cci{}
484 \protected\def\cci{}
485 % \end{macrocode}
486 % \end{macro}
487 %
488 % \begin{macro}{\collect@cell@cr}
489 % Redefines the table line/row end macro |\cr| so that
490 % token collection is restarted after the real |\cr| is expanded
491 % and the end material defined by `<{}` is inserted.
492 %
493 % This redefinition must be done around some \emph{dirty tricks}
494 % otherwise the |\cr| will be wrongly taken as end of the
495 % row.
496 %
497 % Because the redefinition is done just at the end of a cell inside the group
498 % opened by |collcell| it will only be locally.
499 % \begin{macrocode}
500 \def\collect@cell@cr{%
501 \iffalse{\fi
502 \let\collcell@realcr\cr
503 \def\cr{%
504 \collect@cell@look
505 \collcell@realcr
506 }%
507 \iffalse}\fi
508 }
509 % \end{macrocode}
510 % \end{macro}
511 %
512 % \begin{macro}{\collect@cell@arg}
513 % \begin{macro}{\collect@cell@grab}
514 % \begin{macro}{\l@collect@cell@env@cnt}
515 % Handles the arguments.
516 % The first token of the argument is still in the |lettoken| macro which is compared
517 % against a list of possible end tokens.
518 % Then either the cell end is handled or the argument is added to the token register
519 % and the rest of the cell is processed.
520 % \begin{macrocode}
521 \def\collect@cell@arg#1{%
522 \cc@case
523 \tabularnewline{\ifnum\l@collect@cell@env@cnt=0 %
524 \expandafter\collect@cell@cr
525 \else
526 \expandafter\collect@cell@grab
527 \fi
528 #1%
529 }%
530 \begin{\advance\l@collect@cell@env@cnt by 1 %
531 \collect@cell@grab\begin}%
532 \end{\advance\l@collect@cell@env@cnt by -1 %
533 \collect@cell@checkend}%
534 \end{\collect@cell@checkend}%
535 \csname{\collect@cell@checkcsname}%
536 \unskip{%
537 \let\collect@cell@spaces\empty
538 %\collect@cell@addarg{#1}% do not include the \unskip
539 \collect@cell@look%
540 }%
541 \textonly@unskip{%
542 \let\collect@cell@spaces\empty
543 \collect@cell@look%
544 }%
545 \@sharp{%
546 \expandafter\collect@cell@addarg\expandafter{#1}%
547 \collect@cell@look
548 }%
549 \collectcell{%
550 \advance\collect@cell@count by \@ne
551 \collect@cell@addcc%
552 }%
553 \endcollectcell{%
554 \ifnum\collect@cell@count=\z@
555 \expandafter\collect@cell@end
556 \else
557 \expandafter\endgroup
558 \expandafter\collect@cell@addarg\expandafter
559 {\expandafter{\the\collect@cell@toks}}%
560 \advance\collect@cell@count by \m@ne%
561 \expandafter\collect@cell@look
562 \fi
563 }%
564 \cci{%
565 \collect@cell@look
566 }%
567 \default{%
568 \expandafter\ccell@swap\expandafter
569 {\csname endtabular*\endcsname\endtabular\endarray}{\in@{#1}}%
570 \ifin@
571 \expandafter\@firstoftwo
572 \else
573 \expandafter\@secondoftwo
574 \fi
575 {\collect@cell@cr\tabularnewline#1}%
576 {%
577 \collect@cell@addarg{#1}%
578 \collect@cell@look
579 }%
580 }%
581 \endcc@case
582 }
583 \long\def\collect@cell@grab#1{%
584 \collect@cell@addarg{#1}%
585 \collect@cell@look
586 }
587 \newcount\l@collect@cell@env@cnt
588 % \end{macrocode}
589 % \end{macro}
590 % \end{macro}
591 % \end{macro}
592 %
593 % \iffalse
594 %</collcell.sty>
595 % \fi
596 %
597 % \Finale
598 % \endinput
599