Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2016-2020 by Richard Grewe <[email protected]>
4 % -------------------------------------------------------
5 %
6 % Thie file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % https://www.latex-project.org/lppl.txt
11 % and version 1.3c or later is part of all distributions of LaTeX
12 % version 2008 or later.
13 %
14 % This file has the LPPL maintenance status "maintained".
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{keyvaltable.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{keyvaltable}
24 %<*package>
25 [2020/08/09 v2.3 Package for filling tables using key-value lists]
26 %</package>
27 %
28 %<*driver>
29 \documentclass[svgnames]{ltxdoc}
30 \usepackage{rgltxdoc}[2019/12/21 v1.3]
31 \usepackage{etoc}
32 \usepackage{amssymb}% \checkmark
33 \EnableCrossrefs
34 \CodelineIndex
35 \RecordChanges
36 \usepackage{xspace}
37 \newcommand\thispackage{\pkgname{keyvaltable}\xspace}
38 % the following packages are additional for the examples
39 \usepackage{xintexpr}
40 \usepackage{makecell,cellspace}
41 \usepackage{gensymb}% for \degree
42 \usepackage{tabularx,longtable,xltabular,tabu}
43 \usepackage{filecontents}
44 \usepackage{keyvaltable}
45 \usepackage{datatool,csvsimple}
46 \NewKeyValTable[
47 showhead=false,headformat={\bfseries\footnotesize},
48 rowbg=black!7!white..black!3!white,
49 showrules=false,
50 backend=tabu]{GoalApproach}{
51 id: align=r, default=(\alph{kvtRow}), head=\#;
52 goal: align=X[l];
53 approach: align={X[2,l]};
54 }
55 \newcommand\RecipePreset{%
56 \NewKeyValTable{Recipe}{amount:align=r;ingredient:align=l;step:align=X}}
57 %
58 \usepackage{fontawesome}
59 \makeatletter
60 \newenvironment{NiceText}[2]{%
61 \medskip\par\noindent
62 \rgltxdoc@inmargin{\smash{\textcolor{#1}{\large#2}}}{\quad}%
63 \ignorespaces}{\medskip\par\noindent}
64 \newenvironment{NiceNote}{\NiceText{DarkBlue}{\faInfoCircle}}{\endNiceText}
65 \newenvironment{NiceTipp}{\NiceText{DarkBlue}{\faLightbulbO}}{\endNiceText}
66 \newenvironment{NiceWarn}{\NiceText{DarkBlue}{\faWarning}}{\endNiceText}
67 % \end{macrocode}
68 \makeatother
69 %
70 \begin{filecontents*}{recipes.csv}
71 id,amount,ingredient,step
72 snowman,3,balls of snow,staple all 3 balls
73 snowman,1,carrot,stick into top ball
74 snowman,2,coffee beans,put diagonally above carrot
75 cherries,150g,ice cream,put into bowl
76 cherries,50g,cherries,heat up and add to bowl
77 \end{filecontents*}
78 %
79 \begin{document}
80 \DocInput{keyvaltable.dtx}
81 \PrintChanges
82 \PrintIndex
83 \end{document}
84 %</driver>
85 % \fi
86 %
87 % \CheckSum{0}
88 %
89 % \CharacterTable
90 % {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
91 % 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
92 % Digits \0\1\2\3\4\5\6\7\8\9
93 % Exclamation \! Double quote \" Hash (number) \#
94 % Dollar \$ Percent \% Ampersand \&
95 % Acute accent \' Left paren \( Right paren \)
96 % Asterisk \* Plus \+ Comma \,
97 % Minus \- Point \. Solidus \/
98 % Colon \: Semicolon \; Less than \<
99 % Equals \= Greater than \> Question mark \?
100 % Commercial at \@ Left bracket \[ Backslash \\
101 % Right bracket \] Circumflex \^ Underscore \_
102 % Grave accent \` Left brace \{ Vertical bar \|
103 % Right brace \} Tilde \~}
104 %
105 % \changes{v0.1}{2016/03/13}{Initial version}
106 % \changes{v0.3b}{2018/11/01}{Package author's name change}
107 %
108 % \GetFileInfo{keyvaltable.dtx}
109 %
110 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
111 %
112 %
113 % \title{The \thispackage package\thanks{This document
114 % corresponds to \thispackage~\fileversion, dated \filedate.
115 % The package is available online at
116 % \url{http://www.ctan.org/pkg/keyvaltable} and
117 % \url{https://github.com/Ri-Ga/keyvaltable}.}}
118 % \author{Richard Grewe \\ \texttt{[email protected]}}
119 %
120 % \maketitle
121 %
122 % \begin{abstract}\noindent
123 % The \thispackage package's main goal is to facilitate
124 % typesetting tables\ldots\medskip\\
125 % \begin{KeyValTable}{GoalApproach}
126 % \Row{
127 % goal={\ldots easily and yet still looking rather nicely},
128 % approach={through horizontal rules and alternating row background
129 % colors by default;}}
130 % \Row{
131 % goal={\ldots in a way that separates content from presentation},
132 % approach={by table rows that are specified as lists of key-value
133 % pairs, where the keys are column names and the corresponding
134 % values are the content of the cell in this row in the respective
135 % column;}}
136 % \Row{
137 % goal={\ldots with re-usable layout for tables of the same type},
138 % approach={through named table types, of which each has a list of
139 % columns as well as further properties such as the background
140 % colors of rows; each column, in turn, has a name as well as
141 % further properties such as the heading of the column and the
142 % alignment of the column's content.}}
143 % \end{KeyValTable}
144 % \end{abstract}
145 %
146 % \etocsetnexttocdepth{1}
147 % \etocmulticol[2]{\section*{Contents}}
148 % \clearpage
149 %
150 % \section{Basic Usage}\label{sec:basic}
151 %
152 % We start with a basic usage example. An explanation of the involved
153 % macros follows afterwards.\medskip
154 %
155 % \begin{LTXexample}[morekeywords={NewKeyValTable,Row,KeyValTable}]
156 % \NewKeyValTable{Recipe}{
157 % amount: align=r;
158 % ingredient: align=l;
159 % step: align=X;
160 % }
161 % \begin{KeyValTable}{Recipe}
162 % \Row{amount=150g, ingredient=ice cream,
163 % step=put into bowl}
164 % \Row{amount= 50g, ingredient=cherries,
165 % step=heat up and add to bowl}
166 % \end{KeyValTable}
167 % \end{LTXexample}
168 % The example code first defines a new table type, |Recipe|, along with
169 % the columns that belong to this type. There are three columns
170 % (|amount|, |ingredient|, and |step|), whose specifications are separated
171 % with semicolons. After the separating |:|, for each column, the macro
172 % configures the column alignment using the |align| key. The alignments
173 % |r| (right) and |l| (left) are the standard |tabular| alignments; the
174 % |X| alignment is provided by the \pkgname{tabularx} package (see the
175 % documentation there).
176 %
177 % After defining the table type, the example creates a table of
178 % the newly defined type. For this, the example uses the |KeyValTable|
179 % environment and the |\Row| macro, once for each row. The parameter
180 % |Recipe| of the |KeyValTable| identifies the type of the table.
181 % In the parameter of the |\Row| macro, the content of the individual
182 % cells can be specified by key-value pairs such as |amount=150g|, which
183 % puts ``150g'' into the |amount| column of the respective row.
184 %
185 % The example above already shows that producing a rather nice-looking
186 % table -- including alternating row colors as well as horizontal rules
187 % -- without further ado. How the \thispackage package can be
188 % used in the general case and how its visual appearance can be
189 % customized is subject of the remainder of this documentation.
190 %
191 % \begin{NiceTipp}
192 % To quickly sketch a table type, one can even omit properties
193 % of columns and just list their names, separated by semicolons, as the
194 % following example shows. All columns then get the default alignment:
195 % |l|.
196 % \end{NiceTipp}
197 % \begin{LTXexample}
198 % \NewKeyValTable{Recipe}{amount;ingredient;step}
199 % \begin{KeyValTable}{Recipe}
200 % \Row{amount=150g, ingredient=ice cream,
201 % step=put into bowl}
202 % \Row{amount= 50g, ingredient=cherries,
203 % step=heat up and add to bowl}
204 % \end{KeyValTable}
205 % \end{LTXexample}
206 %
207 %
208 % \section{Defining Table Types}
209 %
210 % As the example in \cref{sec:basic} shows,
211 % |\NewKeyValTable| defines a table type.
212 %
213 % \NiceDescribeMacro{\NewKeyValTable}{\oarg{options}\marg{tname}\marg{colspecs}\oarg{layout}}
214 % The macro defines a table type with name \meta{tname} whose columns
215 % are specified by \meta{colspecs}.
216 % The \meta{colspecs} parameter must be a semicolon-separated list.
217 % Each column specification is of the form
218 % \begin{center}
219 % \meta{colname}|:| \meta{property}|=|\meta{value}|,|
220 % \meta{property}|=|\meta{value}|,|\ldots
221 % \end{center}
222 % In such a specification, \meta{colname} represents the name of the
223 % column. The \meta{property}|=|\meta{value} pairs configure certain
224 % properties of the column. The \meta{property} can be one of the
225 % following:
226 %
227 % \NiceDescribeKey{align}{vals={l,c,r,p,X,\ldots}, init=l}
228 % This property specifies the alignment of content in the
229 % column. The \meta{value} can be set to any column alignment
230 % understood by table environments.\footnote{More complex values, for
231 % instance using the notation of the \pkgname{array} package for
232 % inserting material before or after a column, are permitted but not
233 % further tested. Use at your own risk.}
234 %
235 % \NiceDescribeKey{default}{vals=\vmeta{content}, init=\vmeta{empty}}
236 % This property specifies the default \meta{content} of a cell in this
237 % column, i.e., in case that a \cmd{\Row} does not provide content for
238 % the cell. Initially (i.e., if unset for a column), this is an
239 % empty string.
240 %
241 % \NiceDescribeKey{format}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
242 % This property specifies a formatting macro for content of the cell.
243 % The macro can take one argument and is provided with the content of
244 % the cell as its argument. Initially, the format is defined to take
245 % the content as is.\footnote{Prior to version~2.3 of \thispackage,
246 % the initial format setting was to put \cmd{\strut} before and after
247 % the content to yield a better vertical row spacing in some
248 % situations. See also \cref{sec:VertSpacing}.}
249 %
250 % \NiceDescribeKey{head}{vals=\vmeta{content}, init=\vmeta{colname}}
251 % This property specifies the \meta{content} of the column's header
252 % row. The initial value for this property is the name of the column.
253 %
254 % \NiceDescribeKey{hidden}{vals={true,false}, init=false, def=true}
255 % This property specifies whether a table column shall be displayed or
256 % not. The \meta{value} for this property can be |true| (to hide the
257 % cell) or |false| (to display the cell). Using |hidden| without
258 % \meta{value} is equivalent to specifying |hidden=true|.
259 %
260 % The following example shows all of the above column properties in
261 % action.
262 %
263 % \begin{LTXexample}[morekeywords={align,default,format,head,hidden}]
264 % \NewKeyValTable{ShoppingList}{
265 % what: head=article, format=\textbf;
266 % amount: align=r, default=1;
267 % why: hidden;
268 % }
269 % \begin{KeyValTable}{ShoppingList}
270 % \Row{what=melon}
271 % \Row{what=apples, amount=6}
272 % \Row{what=bicycle, why=Bob's birthday}
273 % \end{KeyValTable}
274 % \end{LTXexample}
275 %
276 % The \meta{options} and \meta{layout} parameters of |\NewKeyValTable|
277 % are described in \cref{sec:TableAppearance} and, respectively,
278 % \cref{sec:CustomHeaders} of this documentation.
279 %
280 %
281 % \section{Typesetting Tables}\label{sec:typesetting-tables}
282 %
283 % The \thispackage package offers three possibilities for typesetting
284 % tables.
285 % The first is in the traditional \hologo{LaTeX} form, in which there is
286 % an environment that encloses the individual row specifications.
287 % The second possibility is to specify rows throughout the document, bind
288 % them to a name, and finally typeset a table from all rows bound to
289 % the particular name.
290 % The third possibility is to source the row specifications from a
291 % file.
292 %
293 % \subsection{Specifying Rows in a Table Environment}
294 %
295 % The first possibility for typesetting a table using the
296 % \thispackage package, is via the |KeyValTable| environment.
297 % \cref{sec:basic} presents an example of this possibility.
298 %
299 % \NiceDescribeEnv{KeyValTable}{\oarg{options}\marg{tname}}
300 % The |KeyValTable| environment creates a table of type \meta{tname}.
301 % The type \meta{tname} must have been created using |\NewKeyValTable|
302 % before. The environment itself already produces a table with the
303 % columns specified for the table type, produces a header row and some
304 % horizontal lines, and sets up background colors of rows.
305 % The \meta{options} are described in \cref{sec:TableAppearance}.
306 %
307 % \NiceDescribeMacro{\Row}{\oarg{options}\marg{content}}
308 % A table row is produced by the |\Row| macro. The
309 % \meta{content} must be a comma-separated list of
310 % \meta{cname}|=|\meta{text} pairs. The \meta{cname} identifies a column
311 % that was registered for the table type \meta{tname}. The \meta{text}
312 % specifies the content of the cell in the respective column. Each
313 % column for which no \meta{text} is provided in \meta{content}, will
314 % result in a cell that is filled with the column's default value.
315 % The \meta{options} argument customizes row properties and is further
316 % explained in \cref{sec:RowOptions}.
317 %
318 %
319 % \subsection{Tables of Collected Rows}\label{sec:collected}
320 %
321 % The content of a table's rows might logically belong to locations that
322 % are scattered throughout a document, e.g., to individual sections of
323 % the document. In this situation, it can be convenient to have the rows
324 % specified close to the locations their contents belong to, instead of
325 % specified in the table environment.
326 %
327 % The following example illustrates the use of this feature for taking
328 % and collecting notes in a document:
329 % \begin{LTXexample}[width=0.475\hsize,morekeywords={NewCollectedTable,CollectRow,ShowCollectedTable}]
330 % \NewKeyValTable{Notes}{type; text}
331 % \NewCollectedTable{notes}{Notes}
332 %
333 % \subsection*{Notes}
334 % \ShowCollectedTable{notes}
335 %
336 % \section{Introduction}
337 % \CollectRow{notes}{type=remark, text=intro too long}
338 % Lorem ipsum dolor sit amet, \ldots
339 %
340 % \section{Analysis}
341 % \CollectRow{notes}{type=task, text=proofread Analysis}
342 % Lorem ipsum dolor sit amet, \ldots
343 % \end{LTXexample}
344 % See \cref{sec:referencing} on how to (automatically) include
345 % references to, e.g., section or page numbers in tables.
346 % The key macros (highlighted in bold font) used in the example are the
347 % following three.
348 %
349 % \NiceDescribeMacro{\NewCollectedTable}{\marg{cname}\marg{tname}}
350 % This macro defines the name \meta{cname} for a new collection of
351 % rows. The collection is associated with the table type \meta{tname}.
352 % This macro must be used before |\CollectRow| for a \meta{cname}.
353 %
354 % \NiceDescribeMacro{\CollectRow}{\oarg{options}\marg{cname}\marg{content}}
355 % This macro adds the row content \meta{content} and row options
356 % \meta{options} to the row collection \meta{cname}.
357 %
358 % \NiceDescribeMacro{\ShowCollectedTable}{\oarg{options}\marg{cname}}
359 % This macro typesets a table of the row collection \meta{cname}, with
360 % the table options \meta{options}.
361 % The table includes rows that are collected only afterwards in the
362 % document. For this, \hologo{LaTeX} must be run at least two times.
363 %
364 %
365 % \subsection{Sourcing Rows From a File}
366 %
367 % Rather than specifying the rows of a table inside a |KeyValTable|
368 % environment, the rows can also be sourced from a file.
369 % More concretely, this file must consist of the |\Row| macros that
370 % specify the content of the rows.
371 % For information on how to source rows from CSV files, see
372 % \cref{sec:CSV}.
373 %
374 % \NiceDescribeMacro{\ShowKeyValTableFile}{\oarg{options}\marg{tname}\marg{filename}}
375 % This macro produces a |KeyValTable| environment of type \meta{tname}
376 % whose content is taken from the file \meta{filename}.
377 % The \meta{options} specify the table options, which are directly
378 % passed to the options argument of the |KeyValTable| environment.
379 %
380 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={ShowKeyValTableFile}]
381 % \begin{filecontents}{snowman.kvt}
382 % \Row{amount=3, ingredient=balls of snow,
383 % step=staple all 3 balls}
384 % \Row{amount=1, ingredient=carrot,
385 % step=stick into top ball}
386 % \Row{amount=2, ingredient=coffee beans,
387 % step=put diagonally above carrot}
388 % \end{filecontents}
389 % \ShowKeyValTableFile{Recipe}{snowman.kvt}
390 % \end{LTXexample}
391 %
392 %
393 % \subsection{Tables of Collected Rows (Legacy Interface)}
394 %
395 % This section documents legacy functionality of \thispackage, that is
396 % now superseded by the functionality described in \cref{sec:collected}.
397 % The legacy functionality compares to the new functionality as follows:
398 % \begin{itemize}[noitemsep]
399 % \item Rows must be collected \emph{before} the place in the document
400 % where they are displayed in a table.
401 % \item For each table type, there can be only one collection of rows.
402 % After the collection has been typeset in a table the collection is
403 % emptied again.
404 % \item Row content is not written into the aux file. This might be
405 % relevant for very large tables.
406 % \end{itemize}
407 % The following macros and environments implement the functionality.
408 %
409 % \NiceDescribeMacro{\AddKeyValRow}{\marg{tname}\oarg{options}\marg{content}}
410 % A table row is produced by the
411 % |\AddKeyValRow| macro. The \meta{tname}
412 % identifies the table type and the \meta{content} provides the content
413 % of the cells in the row. The format of the \meta{content} is the same
414 % as for the |\Row| macro described in
415 % Section~\ref{sec:typesetting-tables}.
416 %
417 % \NiceDescribeMacro{\ShowKeyValTable}{\oarg{options}\marg{tname}}
418 % A table of all the rows defined via |\AddKeyValRow| can be displayed
419 % by the |\ShowKeyValTable| macro. The
420 % parameters have the same meaning as for the |KeyValTable| environment.
421 % This macro resets the list of rows for the specified table type.
422 %
423 % \NiceDescribeEnv{KeyValTableContent}{\marg{tname}}
424 % For simplifying the addition of rows, the
425 % |KeyValTableContent| environment can be used. In this
426 % environment, the |\Row| macro can be used just like in the
427 % |KeyValTable| environment. The only difference is that the
428 % |KeyValTableContent| environment does not cause the table to be
429 % displayed. For displaying the content collected in
430 % |KeyValTableContent| environments, the |\ShowKeyValTable| macro can be
431 % used.
432 %
433 % The following example demonstrates the use, based on the previously
434 % defined |Recipe| table type.
435 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={AddKeyValRow,KeyValTableContent,ShowKeyValTable}]
436 % \AddKeyValRow{Recipe}{amount=3,
437 % ingredient=balls of snow,
438 % step=staple all 3 balls}
439 % \begin{KeyValTableContent}{Recipe}
440 % \Row{amount=1, ingredient=carrot,
441 % step=stick into top ball}
442 % \Row{amount=2, ingredient=coffee beans,
443 % step=put diagonally above carrot}
444 % \end{KeyValTableContent}
445 % \ShowKeyValTable{Recipe}
446 % \end{LTXexample}
447 %
448 %
449 % \section{Row Numbering\,\&\,Labeling}\label{sec:row-numbering}
450 %
451 % The mechanism of default column values enables a simple means for
452 % automatic row numbering, labeling, and referencing document entities.
453 %
454 % \subsection{Row Numbering}
455 %
456 % For row numbering, one can use one of three row counters provided by
457 % the \thispackage package: |kvtRow|, |kvtTypeRow|, and |kvtTotalRow|.
458 % The counters are explained after the following example, which
459 % demonstrates the use for the case of the |kvtRow| counter.
460 %
461 % \begin{LTXexample}[morekeywords={thekvtRow,thekvtTypeRow}]
462 % \NewKeyValTable[headformat=\textbf]{Numbered}{
463 % line: align=r, head=\#,
464 % format=\textbf,
465 % default=\thekvtRow;
466 % text: align=l, head=Text}
467 % \begin{KeyValTable}{Numbered}
468 % \Row{text=First row}
469 % \Row{text=Second row}
470 % \end{KeyValTable}
471 % \end{LTXexample}
472 %
473 % \NiceDescribeCounter{kvtRow}{}
474 % The |kvtRow| counter counts the row in the \emph{current} table. The
475 % row number excludes the header row of the table. If the table spans
476 % multiple pages, the row number also excludes the repeated headings on
477 % subsequent pages.
478 %
479 % \NiceDescribeCounter{kvtTypeRow}{}
480 % The |kvtTypeRow| counter counts the rows in the current table and
481 % includes the number of rows of all previous tables of the same type.
482 %
483 % \NiceDescribeCounter{kvtTotalRow}{}
484 % The |kvtTotalRow| counter counts the rows in the current table and
485 % includes the number of rows of all previous tables produced using the
486 % \thispackage package.
487 %
488 % By default, all rows are counted by the aforementioned counters.
489 % However, this default can be changed.
490 %
491 % \NiceDescribeKey{uncounted}{vals={true,false}, init=false, def=true}
492 % This row option specifies whether the row shall not be counted
493 % (|true|) or shall be counted (|false|).
494 % If only |uncounted| is used without a value, this is equivalent to
495 % |uncounted=true|.
496 % The following example illustrates the option.
497 %
498 % \begin{LTXexample}[morekeywords={uncounted},
499 % morepreset={\NewKeyValTable[headformat=\textbf]{Numbered}{
500 % line: align=r,head=\#,format=\textbf,default=\thekvtRow;
501 % text: align=l,head=Text}}]
502 % \begin{KeyValTable}{Numbered}
503 % \Row{text=First row}
504 % \Row[uncounted]{line={--}, text=interlude}
505 % \Row{text=Second row}
506 % \end{KeyValTable}
507 % \end{LTXexample}
508 %
509 % By default, all counters start at value $1$. Through the following
510 % possibilities, this behavior can be changed.
511 %
512 % \NiceDescribeKey{resume}{vals={true,false}, init=false, def=true}\label{opt:resume}
513 % This option is available in |KeyValTable| environments. When this
514 % option is set to |true|, the value of the |kvtRow| counter is resumed
515 % from the previous |KeyValTable| environment. The other two counters
516 % are not affected by this option.
517 %
518 % \subsection{Row Labeling}
519 %
520 % Row numbering can easily be combined with row labeling.
521 % The following example shows how the |format| column property can be
522 % used for this purpose.
523 % \begin{LTXexample}[morekeywords={kvtLabel}]
524 % \NewKeyValTable{Labeled}{
525 % label: align=r, head=\textbf{\#},
526 % format=\kvtLabel{kvtRow};
527 % text: align=l, head=\textbf{Text}}
528 % \begin{KeyValTable}{Labeled}
529 % \Row{text=First row, label=first}
530 % \Row{text=After row \ref{first}}
531 % \end{KeyValTable}
532 % \end{LTXexample}
533 %
534 % \NiceDescribeMacro{\kvtLabel}{\oarg{labelopts}\marg{counter}\marg{label}}
535 % The |\kvtLabel| macro shows the current value of the \meta{counter} --
536 % in particular |kvtRow|, |kvtTypeRow|, and |kvtTotalRow| -- and sets
537 % the \meta{label} to the value of \meta{counter}. When using the macro
538 % with the |format| property, only the first argument (\meta{counter})
539 % must be provided, as the above example shows. The second argument
540 % (\meta{label}) is provided by the respective cell content.
541 %
542 % The |\kvtLabel| macro should work well with packages that change the
543 % referencing, like \pkgname{cleveref} or \pkgname{varioref}. When using a
544 % package that adds an optional argument to the |\label| command (like
545 % \pkgname{cleveref} does), the \meta{labelopts} can be used to pass an
546 % optional argument to |\label|. This feature is demonstrated in
547 % \cref{sec:package-cleveref}.
548 %
549 % \subsection{Referencing in Collected Rows}\label{sec:referencing}
550 %
551 % The previous sections show examples of referencing row numbers.
552 % In tables of collected rows, it may be desirable to reference the
553 % point in the document at which a row was collected.
554 % The example in \cref{sec:collected} illustrates such a situation.
555 % In the following, we augment that example by references to section and
556 % page numbers.
557 %
558 % \begin{LTXexample}[width=0.5\hsize,morekeywords={NewCollectedTable,CollectRow,ShowCollectedTable}]
559 % \NewKeyValTable{Notes2}{
560 % id: default=\thekvtRow.;
561 % type; text;
562 % where: default={\S\thesection\ (p.\@\thepage)};}
563 % \NewCollectedTable{notes2}{Notes2}
564 %
565 % \subsection*{Notes}
566 % \ShowCollectedTable{notes2}
567 %
568 % \section{Introduction}
569 % \CollectRow{notes2}{type=remark, text=intro too long}
570 % Lorem ipsum dolor sit amet, \ldots
571 %
572 % \section{Analysis}
573 % \CollectRow{notes2}{type=task, text=proofread!}
574 % Lorem ipsum dolor sit amet, \ldots
575 % \end{LTXexample}
576 %
577 % The above example demonstrates that the correct section number is
578 % referenced. Since the whole example is contained on a single page, the
579 % example does not demonstrate that the page number (|\thepage|) in the
580 % "where" column actually references the page in the document on which
581 % the |\CollectRow| takes place. Note that the correct page will be
582 % produced even when the |\CollectRow| is placed in a float, such as a
583 % figure or table.
584 % \begin{NiceWarn}
585 % \hologo{LaTeX} internally implements a special treatment of
586 % |\thepage| to make page references possible. For this reason, using
587 % something like |\arabic{page}| to produce the page number will
588 % presumably not work correctly.
589 % \end{NiceWarn}
590 %
591 % The \thispackage package
592 % \begin{itemize}[nosep]
593 % \item takes the values of row counters (like |\thekvtRow|) from the
594 % position of \emph{the row in the table}
595 % but
596 % \item takes the values of other counters such as the page counter and
597 % the section counter from the \emph{point in the document where
598 % \cmd{\CollectRow} is used}.
599 % \end{itemize}
600 % This takes into account that counter values can be obtained via
601 % \cmd{\the\meta{ctrname}} (like |\thekvtRow| or |\thepage|) as well as
602 % via macros like |\arabic|, |\roman| etc.
603 % The following macros allow for declaring additional counters and
604 % formatting macros to be taken into account by \thispackage.
605 %
606 % \NiceDescribeMacros{2}
607 % {\kvtDeclareTableMacros}{\marg{macro-list}}
608 % {\kvtDeclareTableCounters}{\marg{counter-list}}
609 % These macros take a comma-separated list of macros (respectively
610 % counters) and declares these as "table macros" ("table counters").
611 % A macro or counter declared this way is expanded only inside the table
612 % environment and not at the point where |\CollectRow| is used.
613 % The \thispackage already declares |\thekvtRow|, |\thekvtTypeRow|, and
614 % |\thekvtTotalRow| as table macros and declares |kvtRow|, |kvtTypeRow|,
615 % and |kvtTotalRow| as table counters.
616 %
617 % \NiceDescribeMacro{\kvtDeclareCtrFormatters}{\marg{macro-list}}
618 % This macro takes a comma-separated list of macros and declares them as
619 % macros for formatting counter values. Examples for such macros are
620 % |\arabic|, |\alph|, |\Alph|, |\roman|, |\Roman|, |\fnsymbol|, which
621 % \thispackage already declares.
622 % When other counter-formatting macros shall be used in the |default|
623 % value of a column, such as |\ordinal| of the \pkgname{fmtcount}
624 % package, they have to be passed to |\kvtDeclareCtrFormatters| first.
625 %
626 %
627 % \section{Changing the Appearance}
628 %
629 % The appearance (e.g., colors, rules) of a table can be changed at
630 % the level of the overall table as well as for individual rows,
631 % columns, and cells.
632 %
633 % \subsection{Table Appearance}\label{sec:TableAppearance}
634 %
635 % The appearance of a table can be configured through the \meta{options}
636 % parameters of
637 % \begin{itemize}[nosep]
638 % \item |KeyValTable|, |\ShowKeyValTable|, and |\ShowKeyValTableFile|
639 % (affecting the particular table),
640 % \item |\NewKeyValTable| (affecting all tables of the table type), and
641 % \item |\kvtSet| (affecting all tables).
642 % \end{itemize}
643 % In this list, the former take precedence over the latter. That is,
644 % table options override table type options and table type options
645 % override global options for all tables.
646 %
647 % In each case, \meta{options} must be specified as a comma-separated
648 % list of \meta{property}|=|\meta{value} pairs.
649 % The following \meta{property} keys can be configured.
650 %
651 % \NiceDescribeKeys{2}
652 % {backend}{vals={tabular,tabularx,longtable,xltabular,tabu,longtabu}}
653 % {shape}{vals={multipage,onepage}, init=multipage}
654 % The |backend| property specifies the table environment to be used for
655 % producing the table. A set of six environments is currently supported,
656 % including environments that can span multiple pages and environments
657 % whose columns can stretch/shrink to fill the available space ("|X|"
658 % columns).
659 % The |shape| property abstracts from the concrete environments.
660 % In case of |multipage|, the table may span multiple pages and
661 % depending on whether |X|-columns are used or not, an appropriate
662 % environment is selected. In case of |onepage|, the table does not
663 % split into multiple pages.
664 % See \cref{sec:AltTabEnv} for more details on the available shapes and
665 % backends.
666 % Only one of |shape| and |backend| can be specified. If both are
667 % specified, the property that is specified last wins.
668 %
669 % \NiceDescribeKey{width}{vals=\vmeta{dimension}, init=\cmd\linewidth}
670 % This property specifies the width of the table, if the selected
671 % |shape|/|backend| supports it (see \cref{sec:AltTabEnv}).
672 %
673 % \NiceDescribeKeys{2}
674 % {valign}{vals={t,c,b}, init=\vmeta{empty}}
675 % {halign}{vals={l,c,r}, init=\vmeta{empty}}
676 % These two properties specify the vertical and, respectively, horizontal
677 % alignment of the table, if the selected |shape|/|backend| supports it (see
678 % \cref{sec:AltTabEnv}).
679 %
680 % \NiceDescribeKey{showhead}{vals={true,false}, init=true}
681 % This property specifies whether the header row shall be shown. The
682 % \meta{value} must be a Boolean (i.e., |true| or |false|), where |true|
683 % specifies that the header row is shown and |false| specifies that the
684 % header row is not shown.
685 %
686 % \NiceDescribeKeys{2}
687 % {showrules}{vals={true,false}, init=true}
688 % {norules}{vals={true,false}, init=false, def=true}
689 % The |showrules| property specifies whether top and bottom rules as
690 % well as a rule below the header row are drawn (|true|) or not
691 % (|false|). The |norules| property serves the same purpose, but the
692 % value |true| hides the rules and the value |false| causes the rules to
693 % be drawn.
694 % Note that both properties only affect the rules that \thispackage
695 % produces automatically; rules manually added, e.g., via |\hline|,
696 % |\midrule|, or |\MidRule| (see Section~\ref{sec:rules}) are not
697 % affected by the properties.
698 %
699 % \NiceDescribeKey{headalign}{vals={\vmeta{empty} or \vmeta{coltype}}, init=\vmeta{empty}}
700 % This property specifies the alignment for header cells. If left
701 % empty, each header cell receives the same alignment as the respective
702 % column.
703 %
704 % \NiceDescribeKey{headbg}{vals=\vmeta{color}, init={black!14}}
705 % This property specifies the background color of the header rows. The
706 % \meta{color} must be a single color specification that is understood
707 % by the \pkgname{xcolor} package. The \meta{color} is passed directly
708 % to the \cs{rowcolor} macro. If \meta{color} is empty, then no
709 % background color is produced for the header row.
710 %
711 % \NiceDescribeKey{headformat}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
712 % This property specifies a format to be applied to all header cells.
713 % The value specified for the |headformat| key is used to format each
714 % header. The value can be a macro that takes once argument, through
715 % which it is provided the header (as specified in the column's |head|
716 % property). Initially, an "identity" macro is used, meaning that each
717 % |head| is taken without change.
718 %
719 % \NiceDescribeKey{rowbg}{vals=\vmeta{color}, init={white..black!10}}
720 % This property specifies the background colors of content rows. The
721 % \meta{value} for this property must be of the format
722 % \meta{oddcolor}|..|\meta{evencolor}. The first row after the header is
723 % colored with \meta{oddcolor}, the second row with \meta{evencolor},
724 % and so forth. Both colors must be understood by the \pkgname{xcolor}
725 % package. If \meta{color} is empty, then no background color is
726 % produced for content rows.
727 %
728 % \NiceDescribeKeys{2}
729 % {norowbg}{vals={true,false}, init=false, def=true}
730 % {nobg}{vals={true,false}, init=false, def=true}
731 % These properties are shorthands for |rowbg={}| (turning off
732 % background colors for content rows) and, respectively, for
733 % |rowbg={},headbg={}| (turning off background colors for header rows
734 % and for content rows). Using these options without a value is
735 % equivalent to using |true| for the value. For instance, |nobg| is
736 % equivalent to |nobg=true|.
737 %
738 % \vref{fig:TableOptionExamples} demonstrates the \meta{options} in
739 % examples.
740 % \begin{figure}
741 % \begin{LTXexample}[morekeywords={showhead,rowbg}]
742 % \kvtSet{format=\texttt}
743 % \NewKeyValTable[showhead=false,
744 % rowbg=blue!10..blue!15,
745 % ]{TabOptions}{opt; val}
746 % \begin{KeyValTable}{TabOptions}
747 % \Row{opt=showhead, val=false}
748 % \Row{opt=rowbg, val=blue!10..blue!15}
749 % \end{KeyValTable}
750 % \end{LTXexample}
751 % \begin{LTXexample}[morepreset={\kvtSet{format=\texttt}},morekeywords={showrules,headbg,headalign,headformat,halign,norowbg}]
752 % \NewKeyValTable[showrules=false,headbg=blue!25,
753 % headalign=c,headformat=\textbf,norowbg,
754 % halign=r,
755 % ]{TabOptions2}{opt; val}
756 % \begin{KeyValTable}{TabOptions2}
757 % \Row{opt=showrules, val=false}
758 % \Row{opt=headbg, val=blue!25}
759 % \Row{opt=headalign, val=c}
760 % \Row{opt=headformat, val=\string\textbf}
761 % \Row{opt=norowbg, val=true}
762 % \Row{opt=halign, val=r}
763 % \end{KeyValTable}
764 % \end{LTXexample}
765 % \begin{LTXexample}[morepreset={\kvtSet{format=\texttt}},morekeywords={nobg,norules,valign,shape,width}]
766 % \NewKeyValTable[valign=t,nobg,norules,
767 % shape=onepage,width=3cm,headformat=\textbf,
768 % ]{TabOptions3}{opt: align=X;}
769 % \begin{KeyValTable}{TabOptions3}
770 % \Row{opt=nobg}
771 % \Row{opt=norules}
772 % \end{KeyValTable}
773 % \begin{KeyValTable}{TabOptions3}
774 % \Row{opt={shape=onepage}}
775 % \Row{opt={valign=t}}
776 % \Row{opt={width=3cm}}
777 % \end{KeyValTable}
778 % \end{LTXexample}
779 % \caption{Examples for table options}
780 % \label{fig:TableOptionExamples}
781 % \end{figure}
782 %
783 % \subsubsection{Table Styles and Resumable Options}
784 %
785 % Rather than specifying properties for individual tables or table
786 % types, \thispackage also supports named \emph{table styles}.
787 %
788 % \NiceDescribeKey{style}{vals=\vmeta{list of style names}, init=\vmeta{empty}}
789 % Through this property of tables or table types, a list of styles can
790 % be applied to a single table or, respectively, a table type. Each
791 % style must have been defined with |\kvtNewTableStyle| before.
792 %
793 % \NiceDescribeMacro{\kvtNewTableStyle}{\marg{name}\marg{options}}
794 % This macro declares a new table style with the given \meta{name} and
795 % defines it to be equivalent to using the given \meta{options}.
796 % The \meta{name} must not already be defined.
797 %
798 % \NiceDescribeMacro{\kvtRenewTableStyle}{\marg{name}\marg{options}}
799 % This macro re-defines an existing table style \meta{name} with new
800 % \meta{options}.
801 %
802 % The following example demonstrates table styles for an individual
803 % table.
804 %
805 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={style,kvtNewTableStyle}]
806 % \kvtNewTableStyle{plain}{
807 % norules,nobg,headformat=\textbf}
808 % \begin{KeyValTable}[style=plain]{Recipe}
809 % \Row{amount=150g, ingredient=ice cream,
810 % step=put into bowl}
811 % \Row{amount= 50g, ingredient=cherries,
812 % step=heat up and add to bowl}
813 % \end{KeyValTable}
814 % \end{LTXexample}
815 %
816 % \begin{NiceNote}
817 % The \meta{options} in |\kvtNewTableStyle| can be left
818 % empty. In this case, the table style does not have any effect on the
819 % appearance of tables. However, the style can already be used for
820 % "tagging" tables and table types, while the final options for the
821 % style can be configured at a later point in time.
822 % \end{NiceNote}
823 %
824 % Even without table styles, the appearance of the previous
825 % |KeyValTable| can be used again through the following option.
826 % \NiceDescribeKey{resume*}{vals={true,false}, init=false, def=true}
827 % When set to |true|, this option makes the table use the options from
828 % the previous |KeyValTable| environment. This option also implies the
829 % |resume| option (see \vref{opt:resume}).
830
831 % If the previous environment also used |resume*|, then the options of
832 % its predecessor environment are used, and so forth.
833 % Note that this means that table options are not accumulated over
834 % subsequent uses of |resume*|.
835 % This behavior is the same as in the \pkgname{enumitem} package.
836 %
837 %
838 % \subsection{Column Appearance}
839 %
840 % Column appearance is configured through the parameters |align|,
841 % |head|, |format|, and |default| of columns in |\NewKeyValTable|.
842 %
843 %
844 % \subsection{Row Appearance}\label{sec:RowOptions}
845 %
846 % Through the \meta{options} argument of the
847 % |\Row|
848 % and the
849 % |\KeyValRow|
850 % macros, the appearance of rows can be configured.
851 % As with other option arguments of the \thispackage package, the
852 % options must be a comma-separated list of key-value pairs.
853 % The following options are supported.
854 %
855 % \NiceDescribeKey{hidden}{vals={true,false}, init=false, def=true}
856 % This property specifies whether the row shall be hidden (|true|) or
857 % not (|false|). If only |hidden| is used without a value, this is
858 % equivalent to |hidden=true|.
859 %
860 % \NiceDescribeKey{align}{vals={\vmeta{empty} or \vmeta{coltype}}, init=\vmeta{empty}}
861 % This property specifies the alignment of the cells in the row.
862 % If this property is not specified, the respective columns' alignment
863 % is used. The alignment applies to normal cells as well as to cells
864 % in column groups.\footnote{Note that the alignment does not override
865 % the alignment specified in any \cs{multicolumn} if it is assigned to
866 % a cell in the row.}
867 %
868 % \NiceDescribeKey{bg}{vals=\vmeta{color}, init=\vmeta{empty}}
869 % This property specifies the background color for the particular row.
870 % If this option is not specified (or set to an empty value
871 % explicitly), the background color is determined by the |rowbg|
872 % option of the table.
873 %
874 % \NiceDescribeKeys{3}
875 % {format}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
876 % {format*}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
877 % {format!}{vals=\vmeta{single argument macro}, init=\vmeta{none}}
878 % These properties specify formatting for all cells of the particular
879 % row. The difference between the three properties is how they
880 % interact with the column formats of the respective cells in the row.
881 % The |format| property is applied to the cell content \emph{before}
882 % the column format, and the |format*| property is applied
883 % \emph{after} the column format.
884 % The |format!| property overrides any column formats in the
885 % respective row and also renders the |format| and |format*|
886 % properties ineffective.
887 %
888 % \NiceDescribeKey{headlike}{vals={true,false}, init=false, def=true}
889 % This property, when used without a value or with value |true|,
890 % specifies that the row shall be formatted like a header row.
891 % Concretely, the alignment, background color, and format of the row's
892 % cells is then set to the values of the table's |headalign|,
893 % |headbg|, and |headformat| properties.
894 %
895 % \begin{NiceNote}
896 % Initial values for all row options can be set with
897 % |\kvtSet{Row/|\meta{option}|=|\meta{value}|}| (see also
898 % \cref{sec:kvtSet}).
899 % \end{NiceNote}
900 %
901 % The following example demonstrates some of the options.
902 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={hidden,above,bg,format}]
903 % \begin{KeyValTable}{Recipe}
904 % \Row{amount=150g, ingredient=ice cream,
905 % step=put into bowl}
906 % \Row{amount= 50g, ingredient=cherries,
907 % step=heat up and add to bowl}
908 % \Row[hidden]{amount=25g, ingredient=cream,
909 % step=decorate on top}
910 % \Row[above=1ex,bg=Gold,format=\textit]{
911 % step=serve with a smile}
912 % \end{KeyValTable}
913 % \end{LTXexample}
914 %
915 %
916 % \subsubsection{Vertical Row Size \& Spacing}\label{sec:VertSpacing}
917 %
918 % When rows are narrow or appear to be narrow, extra spacing above and
919 % below can be configured. There are (at least) three options for this.
920 %
921 % The first option is to use the following |\Row| options.
922 % \NiceDescribeKeys{3}
923 % {above}{vals=\vmeta{dimension}, init=\vmeta{empty}}
924 % {below}{vals=\vmeta{dimension}, init=\vmeta{empty}}
925 % {around}{vals=\vmeta{dimension}, init=\vmeta{empty}}
926 % These properties specify extra vertical space above and,
927 % respectively, below the row. The |around| property is a short-hand
928 % for setting both, |above| and |below|, to the same value.
929 % Note that the vertical space is currently not colored with the
930 % row's background color but with the page's background color.
931 % The argument, if provided, is directly passed to |\vspace|.
932 %
933 % The second option is to use the row |format| or a column's |format|
934 % property to insert |\strut| macros around cell content.
935 % For the |format|, the following macro exists.
936 %
937 % \NiceDescribeMacro{\kvtStrutted}{\oarg{inner}\marg{arg}}
938 % This macro places a |\strut| before \meta{arg} and a |\strut| after
939 % \meta{arg}. This has the effect that the first and last row of
940 % \meta{arg} obtain a "natural" height and depth even if their content
941 % is smaller.
942 % The second |\strut| is omitted when it would cause a new line to be
943 % produced.
944 % See \cref{sec:row-numbering} for an example.
945 %
946 % The third option is using the \pkgname{cellspace} package and its
947 % column alignments (e.g., |Sl| instead of |l|) along with the configurable dimensions |\cellspacetoplimit| and |\cellspacebottomlimit|.
948 % The following example shows the second and the third option.
949 %
950 % \begin{LTXexample}[morekeywords={cellspace,kvtStrutted,cellspacetoplimit}]
951 % \usepackage{cellspace}
952 % \setlength{\cellspacetoplimit}{3pt}
953 % \NewKeyValTable{VertSpacing}{
954 % normal;
955 % struts: format=\kvtStrutted;
956 % cellspace: align=Sl;
957 % }
958 % \begin{KeyValTable}{VertSpacing}
959 % \Row{normal=normal size}
960 % \Row{normal=\large Large}
961 % \Row{struts=\large Large}
962 % \Row{cellspace=\large Large}
963 % \end{KeyValTable}
964 % \end{LTXexample}
965 %
966 %
967 % \subsubsection{Row Styles}
968 %
969 % Rather than specifying properties for individual rows, \thispackage
970 % also supports named \emph{row styles}.
971 %
972 % \NiceDescribeKey{style}{vals=\vmeta{list of style names}, init=\vmeta{empty}}
973 % Through this property of rows, a list of styles can be applied to the
974 % row. Each style must have been defined with |\kvtNewRowStyle| before.
975 %
976 % \NiceDescribeMacro{\kvtNewRowStyle}{\marg{name}\marg{row-options}}
977 % This macro declares a new row style with the given \meta{name} and
978 % defines it to be equivalent to using the given \meta{row-options}.
979 % The \meta{name} must not already be defined.
980 %
981 % \NiceDescribeMacro{\kvtRenewRowStyle}{\marg{name}\marg{row-options}}
982 % This macro re-defines an existing row style \meta{name} with new
983 % \meta{row-options}.
984 %
985 % The following example produces the same output as the previous
986 % example, but uses row styles.
987 %
988 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={style,kvtNewRowStyle}]
989 % \kvtNewRowStyle{optional}{hidden}
990 % \kvtNewRowStyle{highlight}{above=1ex,bg=Gold}
991 % \begin{KeyValTable}{Recipe}
992 % \Row{amount=150g, ingredient=ice cream,
993 % step=put into bowl}
994 % \Row{amount= 50g, ingredient=cherries,
995 % step=heat up and add to bowl}
996 % \Row[style=optional]{amount=25g,
997 % ingredient=cream, step=decorate on top}
998 % \Row[style=highlight]{step=serve with a smile}
999 % \end{KeyValTable}
1000 % \end{LTXexample}
1001 %
1002 % \begin{NiceNote}
1003 % The \meta{row-options} in |\kvtNewRowStyle| can be left empty.
1004 % In this case, the row style does not have any effect on the appearance
1005 % of rows. However, the style can already be used for "tagging" rows and
1006 % the final options for the style can be configured at a later point in
1007 % time.
1008 % \end{NiceNote}
1009 %
1010 %
1011 % \subsubsection{Rules Between Rows}\label{sec:rules}
1012 %
1013 % For placing additional horizontal rules between rows, the
1014 % \thispackage package provides the following two macros that are
1015 % available in |KeyValTable| environments.
1016 %
1017 % \NiceDescribeMacro{\MidRule}{\oarg{width}}
1018 % This macro puts a horizontal rule over the full width of the table,
1019 % with line width \meta{width}. The macro puts the same vertical
1020 % spacing above and below the rule, just like |\midrule| of the
1021 % \pkgname{booktabs} package. The difference to |\midrule| is that row
1022 % colors (as specified by the |rowbg| property) are respected.
1023 % The following example demonstrates the use of |\MidRule|.
1024 %
1025 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={MidRule}]
1026 % \begin{KeyValTable}{Recipe}
1027 % \Row{amount=150g, ingredient=ice cream,
1028 % step=put into bowl}
1029 % \Row{amount= 50g, ingredient=cherries,
1030 % step=heat up and add to bowl}
1031 % \MidRule
1032 % \Row{step=serve with a smile}
1033 % \end{KeyValTable}
1034 % \end{LTXexample}
1035 %
1036 % \NiceDescribeMacro{\CMidRule}{\oarg{width}\marg{columns}}
1037 % This macro puts horizontal rules below each of the columns in the
1038 % comma-separated list \meta{columns}. This comma-separated list can
1039 % also contain names of column groups. The rules all have line width
1040 % \meta{width}. The outcome is similar to what a set of |\cmidrule|'s
1041 % would produce, except that row colors are respected and that column
1042 % indexes need not be counted.
1043 % The following example demonstrates the use of |\CMidRule|.
1044 %
1045 % \begin{LTXexample}[morekeywords={CMidRule}]
1046 % \NewKeyValTable[headformat=\textbf]{Prices}{
1047 % part; min: align=r; max: align=r}[
1048 % headers={min+max: head=price},
1049 % colgroups={price: span=min+max}]
1050 % \begin{KeyValTable}{Prices}
1051 % \Row{part=engine, min=2500\$, max=3000\$}
1052 % \Row{part=tires, min=500\$, max=700\$}
1053 % \CMidRule[2pt]{price}
1054 % \Row{part=$\Sigma$, min=3000\$, max=3700\$}
1055 % \end{KeyValTable}
1056 % \end{LTXexample}
1057 %
1058 % The following macros are provided for general use, in
1059 % normal table environments.
1060 % \newcommand\kvtparg[1]{\texttt{(}\meta{#1}\texttt{)}}%
1061 % \NiceDescribeMacros{4}
1062 % {\kvtRuleTop}{\oarg{width}\marg{color2}}
1063 % {\kvtRuleBottom}{\oarg{width}\marg{color1}}
1064 % {\kvtRuleMid}{\oarg{width}\marg{color1}\marg{color2}}
1065 % {\kvtRuleCMid}{\oarg{width}\kvtparg{trim}\marg{a-b}\marg{color1}\marg{color2}}
1066 % These macros are replacements for the macros |\toprule|,
1067 % |\bottomrule|, |\midrule|, and |\cmidrule| of the \pkgname{booktabs}
1068 % package, which do not integrate well with background colors of rows.
1069 % The arguments \meta{color1} and \meta{color2} take the background
1070 % color above and, respectively, below the rule.
1071 %
1072 % Note that while multiple |\cmidrule|s can follow each other and
1073 % produce rules at the same horizontal position, this is not possible
1074 % with |\kvtRuleCMid|. Instead, if multiple |\kvtRuleCMid|s are desired,
1075 % one can use the following macro:
1076 % \NiceDescribeMacro{\kvtRulesCMid}{\oarg{width}\marg{rlist}\marg{color1}\marg{color2}}
1077 % In this macro, \meta{rlist} is a comma-separated list of
1078 % "\kvtparg{trim}\marg{a-b}" pairs, where each \meta{trim} is optional.
1079 % Consider the \pkgname{booktabs} documentation for more information
1080 % about \meta{trim}.
1081 %
1082 %
1083 % \subsection{Cell Appearance}
1084 %
1085 % Individual cells can be formatted by using the respective
1086 % \hologo{LaTeX} code directly in the value of the cell.
1087 % One can disable the column's configured |format| for the cell by
1088 % using the starred column name in |\Row|.
1089 % The following example demonstrates starred column names.
1090 %
1091 % \begin{LTXexample}
1092 % \usepackage{url}\urlstyle{sf}
1093 % \NewKeyValTable{Links}{
1094 % service;
1095 % url: format=\url }
1096 % \begin{KeyValTable}{Links}
1097 % \Row{service=CTAN,
1098 % url=ctan.org/pkg/keyvaltable}
1099 % \Row{service=github,
1100 % url=github.com/Ri-Ga/keyvaltable}
1101 % \Row{service=Google Play, url*=none}
1102 % \end{KeyValTable}
1103 % \end{LTXexample}
1104 %
1105 % \subsection{Setting Global Defaults}\label{sec:kvtSet}
1106 %
1107 % \NiceDescribeMacro{\kvtSet}{\marg{options}}
1108 % The \thispackage package allows changing the default values
1109 % globally for the parameters of tables and columns. This can be done by
1110 % using the |\kvtSet| macro.
1111 %
1112 % \begin{LTXexample}[morekeywords={kvtSet}]
1113 % \kvtSet{headbg=red,default=?,align=r}
1114 % \NewKeyValTable{Defaults}{x; y}
1115 % \begin{KeyValTable}{Defaults}
1116 % \Row{x=1}
1117 % \Row{y=4}
1118 % \end{KeyValTable}
1119 % \end{LTXexample}
1120 %
1121 %
1122 % \section{Customizing the Layout}
1123 %
1124 % The \thispackage package provides some means for altering tables
1125 % beyond those described in the previous sections.
1126 % Those means are described in the following.
1127 %
1128 % \subsection{Custom Table Headers}\label{sec:CustomHeaders}
1129 %
1130 % By default, a table type defined by |\NewKeyValTable| includes a
1131 % single header row and each column of the table type has a header cell
1132 % in this row.
1133 % Through the optional \meta{layout} parameter of |\NewKeyValTable|,
1134 % one can define multiple header rows and can define header cells that
1135 % span multiple columns.
1136 %
1137 % The following two examples illustrate how the |headers| key in the
1138 % \meta{layout} parameter can be used for specifying custom
1139 % headers.\footnote{In \thispackage v1.0, the \meta{layout}
1140 % parameter specified \emph{only} the headers and did not use a
1141 % \texttt{headers} key for this. For compatibility, this can be enabled
1142 % with the \texttt{compat=1.0} package option.}
1143 % The first example produces a single header row in which two columns
1144 % are grouped with a single header, one column has a normal header, and
1145 % in which one column is not provided with a header.
1146 % \begin{LTXexample}
1147 % \NewKeyValTable{Headers1}{
1148 % id: align=r, default=\thekvtRow.;
1149 % amount: align=r; ingredient: align=l;
1150 % step: align=X;
1151 % }[headers={
1152 % amount+ingredient: head=\textbf{ingredient};
1153 % step: head=\textbf{step}, align=l;
1154 % }
1155 % ]
1156 % \begin{KeyValTable}{Headers1}
1157 % \Row{amount=150g, ingredient=ice cream,
1158 % step=put into bowl}
1159 % \Row{amount= 50g, ingredient=cherries,
1160 % step=heat up and add to bowl}
1161 % \end{KeyValTable}
1162 % \end{LTXexample}
1163 %
1164 % The second example shows how multiple header rows can be specified
1165 % and, particularly, how the normal column headers can be displayed
1166 % through the use of "|::|".
1167 % \begin{LTXexample}[width=0.5\hsize]
1168 % \NewKeyValTable[headformat=\textbf,headalign=c]
1169 % {Headers2}{
1170 % date: align=r, head=date;
1171 % Berlin/min: align=r, head=min;
1172 % Berlin/max: align=r, head=max;
1173 % Paris/min: align=r, head=min;
1174 % Paris/max: align=r, head=max;
1175 % }[headers={
1176 % Berlin/min+Berlin/max+Paris/min+Paris/max:
1177 % head=temperature\\
1178 % Paris/min+Paris/max: head=Paris, underline;
1179 % Berlin/min+Berlin/max: head=Berlin, underline\\
1180 % ::}]
1181 % \begin{KeyValTable}{Headers2}
1182 % \Row{date=01.01.1970,
1183 % Berlin/min=0\degree C, Berlin/max=...}
1184 % \end{KeyValTable}
1185 % \end{LTXexample}
1186 %
1187 % The syntax for a \meta{value} of the |headers| key in the
1188 % \meta{layout} parameter is as follows:
1189 % \begin{itemize}[noitemsep]
1190 % \item \meta{value} is a list, separated by "|\\|", where each
1191 % element in the list specifies the columns of a single header
1192 % \meta{row}.
1193 % \item Each \meta{row}, in turn, is also a
1194 % list. The elements of this list are separated by "|;|" (as in the
1195 % columns specification of |\NewKeyValTable|) and each element
1196 % specifies a header \meta{cell}.
1197 % \item Each \meta{cell} is of the form
1198 % \begin{center}
1199 % \meta{col}|+|\ldots|+|\meta{col}|:| \meta{property}|=|\meta{value}|,|
1200 % \meta{property}|=|\meta{value}|,|\ldots
1201 % \end{center}
1202 % where each \meta{col} is the name of a column.
1203 % The specified header cell then spans each of the listed columns.
1204 % The columns must be displayed consecutively, though not necessarily
1205 % in the same order in which they are specified in \meta{cell}.
1206 % \end{itemize}
1207 % The \meta{property}|=|\meta{value} pairs configure properties of the
1208 % header cell. Supported \meta{property} keys are the following.
1209 %
1210 % \NiceDescribeKey{align}{vals={\vmeta{alignment-letter},\vmeta{empty}}, init=c}
1211 % This property specifies the alignment of content in the header cell.
1212 % The \meta{value} can be set to any column alignment understood by
1213 % the underlying table environment used (see \cref{sec:AltTabEnv}).
1214 % This particularly includes |l|, |c|, |r|, and |p|, as well as |X|
1215 % for some of the table environments.
1216 % The initial value can be modified with
1217 % |\kvtSet{HeadCell/align=...}|.
1218 %
1219 % \NiceDescribeKey{head}{vals=\vmeta{text}, init=\vmeta{colspec}}
1220 % This property specifies the content of the header cell.
1221 % The initial value for this property is the column specification,
1222 % i.e., "\meta{col}|+|\ldots|+|\meta{col}".
1223 %
1224 % \NiceDescribeKey{underline}{vals={true,false}, init=false, def=true}
1225 % This property specifies whether the header cell shall be underlined,
1226 % to visually indicate that the columns in the header cell form a
1227 % logical group.
1228 %
1229 %
1230 % \subsection{Column Spanning}
1231 %
1232 % The \thispackage package supports column spanning via "column
1233 % groups". A column group is a collection of adjacent columns, has
1234 % its own name, and can be assigned a value just like "normal" columns
1235 % can be.
1236 % The following example demonstrates how column groups can be defined
1237 % and be used.
1238 %
1239 % \begin{LTXexample}[morekeywords={colgroups}]
1240 % \NewKeyValTable{AltRecipe}{
1241 % amount: align=r, format=\textbf;
1242 % ingredient: align=l;
1243 % step: align=X;
1244 % }[colgroups={
1245 % all: span=step+amount+ingredient
1246 % }]
1247 % \begin{KeyValTable}{AltRecipe}
1248 % \Row{amount=150g, ingredient=ice cream,
1249 % step=put into bowl}
1250 % \Row{amount= 50g, ingredient=cherries,
1251 % step=heat up and add to bowl}
1252 % \MidRule
1253 % \Row{all=serve with a smile}
1254 % \end{KeyValTable}
1255 % \end{LTXexample}
1256 %
1257 % As the example shows, column groups are defined through the
1258 % |colgroups| key of the second optional argument of |\NewKeyValTable|.
1259 % This key expects a semicolon-separated list of individual column
1260 % groups definitions.
1261 % Each such definition takes the same shape as a normal column
1262 % definition -- that is, first the name of the column group, then a
1263 % colon, and then a comma-separated list of column properties.
1264 % The properties that can be set are the following.
1265 %
1266 % \NiceDescribeKey{span}{vals=\vmeta{plus-separated columns}}
1267 % This property specifies which columns the column group shall span, as
1268 % a plus-separated list of column names. Some or all of the columns can
1269 % be hidden. All the displayed columns must be adjacent in the table,
1270 % though.
1271 %
1272 % \NiceDescribeKeys{2}
1273 % {align}{vals={\vmeta{alignment-letter},\vmeta{empty}}, init=c}
1274 % {format}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
1275 % These properties are analogous to the respective properties of normal
1276 % columns. The only difference is that the initial column alignment of
1277 % column groups is "|c|" while the alignment of normal columns is "|l|".
1278 %
1279 % \begin{NiceNote}
1280 % Initial values for all the |align| and |format| options can be
1281 % set with |\kvtSet|, via the |ColGroup/align| and, respectively
1282 % |ColGroup/format| keys (see also \cref{sec:kvtSet}).
1283 % \end{NiceNote}
1284 %
1285 %
1286 % \subsubsection{Manual Column Spanning}
1287 %
1288 % The |\multicolumn| macro can be used for the content of a cell.
1289 % The effect of this is that a number of subsequent cells are spanned
1290 % over with the content of the cell. The following example demonstrates
1291 % the use.
1292 % \begin{LTXexample}[width=0.475\hsize,morekeywords={multicolumn}]
1293 % \NewKeyValTable{MultiCol}{
1294 % col1: align=l;
1295 % col2: align=l;
1296 % col3: align=l;}
1297 % \begin{KeyValTable}{MultiCol}
1298 % \Row{col1=1, col2=\multicolumn{1}{r}{2}, col3=3}
1299 % \Row{col1=1, col2=\multicolumn{2}{c}{2+3}}
1300 % \Row{col1=\multicolumn{2}{c}{1+2}, col3=3}
1301 % \Row{col1=\multicolumn{3}{c}{1+2+3}}
1302 % \end{KeyValTable}
1303 % \end{LTXexample}
1304 % A word of warning:
1305 % The |\multicolumn| macro implicitly constrains the ordering of
1306 % columns. For instance, in the above example, switching columns 2 and 3
1307 % would lead to an error in the second row (because |col2| is the
1308 % rightmost column and therefore cannot span two columns) and also in
1309 % the third row (because |col1| spans two columns but the second, |col3|
1310 % is not empty). Thus, column spanning via |\multicolumn| should be used
1311 % with care.
1312 %
1313 %
1314 % \subsection{Captions}
1315 %
1316 % There are two ways to add captions to \pkgname{keyvaltable} tables:
1317 % The first way is to enclose the table in a |table| environment. This
1318 % is particularly suit for tables that do not span multiple pages, such
1319 % as those produced through the |onepage| shape or the backends
1320 % |tabular|, |tabularx|, and |tabu| (see \cref{sec:AltTabEnv}).
1321 %
1322 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={caption,label,ref}]
1323 % \begin{table}
1324 % \begin{KeyValTable}[shape=onepage]{Recipe}
1325 % \Row{amount=150g, ingredient=ice cream,
1326 % step=put into bowl}
1327 % \Row{amount= 50g, ingredient=cherries,
1328 % step=heat up and add to bowl}
1329 % \end{KeyValTable}
1330 % \caption{Cherries++}
1331 % \label{Cherries}
1332 % \end{table}
1333 % Table~\ref{Cherries} shows the recipe.
1334 % \end{LTXexample}
1335 %
1336 % The second way to add captions is through the |caption| option of
1337 % \pkgname{keyvaltable} tables. This option is available for the
1338 % "multipage" shape and, respectively, the table backends |longtable|,
1339 % |xltabular|, and |longtabu| (see \cref{sec:AltTabEnv}).
1340 %
1341 % \NiceDescribeKeys{4}
1342 % {caption}{vals=\vmeta{text}, init=\vmeta{none}}
1343 % {caption/lot}{vals=\vmeta{text}, init=\vmeta{none}}
1344 % {caption/alt}{vals=\vmeta{text}, init=\vmeta{none}}
1345 % {label}{vals=\vmeta{name}, init=\vmeta{none}}
1346 % These options set the caption and, respectively, label of a table.
1347 % Through the option |caption/lot|, the caption to be put into the list
1348 % of tables can be specified; if omitted, |caption| is used.
1349 % Through the option |caption/alt|, the alternative caption to be
1350 % displayed on those pages of multipage tables where the main caption is
1351 % not shown; if omitted, no caption is displayed on these pages.
1352 %
1353 % The position of the caption is determined by the following option.
1354 %
1355 % \NiceDescribeKey{captionpos}{vals={t,b}, init=b}
1356 % This option specifies the position of table captions. Value "|t|"
1357 % specifies that captions are at the top of (above) their tables; value
1358 % "|b|" specifies that captions are at the bottom of (below) their
1359 % tables.
1360 % Moreover, in case of "|t|" the main caption is on top of the
1361 % \emph{first} page of a table while in case of "|b|" the main caption
1362 % is at the bottom of the \emph{last} page of a table.
1363 %
1364 % The following example shows the options in action.
1365 %
1366 % \begin{LTXexample}[morepreset=\RecipePreset\setcounter{table}{0},morekeywords={caption,label,ref}]
1367 % \begin{KeyValTable}[captionpos=t,
1368 % caption=Cherries++, label=Cherries2]{Recipe}
1369 % \Row{amount=150g, ingredient=ice cream,
1370 % step=put into bowl}
1371 % \Row{amount= 50g, ingredient=cherries,
1372 % step=heat up and add to bowl}
1373 % \end{KeyValTable}
1374 % Table~\ref{Cherries2} shows the recipe.
1375 % \end{LTXexample}
1376 %
1377 %
1378 % \subsection{Alternative Table Environments}
1379 % \label{sec:AltTabEnv}
1380 % The \thispackage package internally uses traditional table
1381 % environments, such as |tabular|, for typesetting the actual tables.
1382 % Through the |shape| and |backend| properties of a table or table type,
1383 % the table environment used by for the table or, respectively, table
1384 % type can be changed.
1385 % \Vref{tab:TabEnv} compares the possible shapes/environments with
1386 % regards to
1387 % \begin{itemize}[nosep]
1388 % \item whether they support tables that span multiple pages,
1389 % \item whether they support |caption| and |label| options,
1390 % \item whether they support |X|-type (variable-width) columns,
1391 % \item whether their width can be specified (through the |width|
1392 % option), and
1393 % \item whether they support a vertical or horizontal alignment of the
1394 % table to be specified.
1395 % \end{itemize}
1396 % Finally, the table also lists the names of the packages that provide
1397 % the respective environments. The packages for the shapes |onepage| and
1398 % |multipage| are loaded automatically. All other packages must be
1399 % loaded via |\usepackage| when the respective shape or backend shall be
1400 % used.
1401 % \begin{table}\centering
1402 % \newcommand\RHead[1]{\rotatebox{90}{\small\varwidth{\linewidth}#1\endvarwidth}}%
1403 % \newcommand\YesNo[1]{\ifstrequal{#1}{yes}{\checkmark}{}}%
1404 % \NewKeyValTable[backend=tabular,headformat=\sffamily\textbf]{ShapeProps}{
1405 % shape: format=\small\texttt;
1406 % env: format=\small\texttt, head=backend;
1407 % multipage: align=c, head=\RHead{multipage}, format=\YesNo;
1408 % caption: align=c, head=\RHead{caption}, format=\YesNo;
1409 % Xcols: align=c, head=\RHead{\texttt{X} columns}, format=\YesNo;
1410 % width: align=c, head=\RHead{width}, format=\YesNo;
1411 % align: align=c, head=\RHead{align}, format=\textsf;
1412 % packages: align=l, format=\pkgnames}%
1413 % \begin{KeyValTable}{ShapeProps}
1414 % \Row{shape=onepage, env=tabular/tabularx, multipage=no, caption=no, Xcols=yes, width=yes, align=v, packages=tabularx}
1415 % \Row{shape=multipage, env=longtable/xltabular, multipage=yes, caption=yes, Xcols=yes, width=yes, align=h, packages={longtable, xltabular}}
1416 % \MidRule
1417 % \noalign{\footnotesize with package option |compat=1.0|:}
1418 % \Row{shape=onepage, env=tabu, multipage=no, caption=no, Xcols=yes, width=yes, align=v, packages=tabu}
1419 % \Row{shape=multipage, env=longtabu, multipage=yes, caption=yes, Xcols=yes, width=yes, align=h, packages={tabu, longtable}}
1420 % \MidRule
1421 % \Row{ env=tabular, multipage=no, caption=no, Xcols=no, width=no, align=v}
1422 % \Row{ env=tabularx, multipage=no, caption=no, Xcols=yes, width=yes, align=v, packages={tabularx}}
1423 % \Row{ env=longtable, multipage=yes, caption=yes, Xcols=no, width=no, align=h, packages={longtable}}
1424 % \Row{ env=xltabular, multipage=yes, caption=yes, Xcols=yes, width=yes, align=h, packages={xltabular}}
1425 % \Row{ env=tabu, multipage=no, caption=no, Xcols=yes, width=yes, align=v, packages={tabu}}
1426 % \Row{ env=longtabu, multipage=yes, caption=yes, Xcols=yes, width=yes, align=h, packages={tabu,longtable}}
1427 % \end{KeyValTable}
1428 % \caption{Comparison of table shapes and backends}
1429 % \label{tab:TabEnv}
1430 % \end{table}
1431 %
1432 % Examples can be found in \vref{fig:TableTypes}.
1433 % \begin{figure}[p]
1434 % \begin{LTXexample}[width=0.475\hsize,
1435 % morekeywords={tabular,longtable}]
1436 % \NewKeyValTable[showrules=false]{ShapeNoX}{
1437 % id: align=l, default=\thekvtTypeRow;
1438 % l: align=l; c: align=c; r: align=r;}[headers={
1439 % l+c+r: head=\textbf{\kvtTableOpt{shape} shape}\\ ::}]
1440 %
1441 % \begin{KeyValTable}[backend=tabular]{ShapeNoX}
1442 % \Row{l=left, c=center, r=right}
1443 % \Row{l=left-2, c=2-center-2, r=2-right}
1444 % \end{KeyValTable}\\
1445 % \begin{KeyValTable}[backend=longtable]{ShapeNoX}
1446 % \Row{l=left, c=center, r=right}
1447 % \Row{l=left-2, c=2-center-2, r=2-right}
1448 % \end{KeyValTable}
1449 % \end{LTXexample}
1450 %
1451 % \begin{LTXexample}[width=0.475\hsize,
1452 % morekeywords={tabularx,xltabular,tabu,longtabu}]
1453 % \NewKeyValTable[showrules=false]{ShapeWithX}{
1454 % id: align=l, default=\thekvtTypeRow;
1455 % l: align=l; X: align=X; r: align=r;}[headers={
1456 % l+X+r: head=\textbf{\kvtTableOpt{shape} shape}\\ ::}]
1457 %
1458 % \begin{KeyValTable}[backend=tabularx]{ShapeWithX}
1459 % \Row{l=left, X=expandable, r=right}
1460 % \Row{l=left-2, X=expandable-2, r=2-right}
1461 % \end{KeyValTable}\medskip\\
1462 % \begin{KeyValTable}[backend=xltabular]{ShapeWithX}
1463 % \Row{l=left, X=expandable, r=right}
1464 % \Row{l=left-2, X=expandable-2, r=2-right}
1465 % \end{KeyValTable}
1466 % \begin{KeyValTable}[backend=tabu]{ShapeWithX}
1467 % \Row{l=left, X=expandable, r=right}
1468 % \Row{l=left-2, X=expandable-2, r=2-right}
1469 % \end{KeyValTable}
1470 % \begin{KeyValTable}[backend=longtabu]{ShapeWithX}
1471 % \Row{l=left, X=expandable, r=right}
1472 % \Row{l=left-2, X=expandable-2, r=2-right}
1473 % \end{KeyValTable}
1474 % \end{LTXexample}
1475 % \caption{Examples for the backend option}
1476 % \label{fig:TableTypes}
1477 % \end{figure}
1478 %
1479 % ^^M The following \clearpage is a hack! It fixes the page breaking
1480 % ^^M that is messed up because of the longtable/xltabular/longtabu
1481 % ^^M in fig:TableTypes.
1482 % \clearpage
1483 % \section{Use with Other Packages}
1484 %
1485 % \subsection{Named References (\pkgname{cleveref})}\label{sec:package-cleveref}
1486 %
1487 % The |\kvtLabel| feature of the \thispackage package can be
1488 % used together with named references, as provided by the
1489 % \pkgname{cleveref} package. A name to a row label can be given by using
1490 % the optional first argument to the |\kvtLabel| formatting macro and
1491 % specifying the name to use using |\crefname|. The following example
1492 % uses ``row'' for the optional argument and ``line'' for the displayed
1493 % name of the reference.
1494 % \begin{LTXexample}
1495 % \usepackage{cleveref}
1496 % \crefname{row}{line}{lines}
1497 % \NewKeyValTable[headformat=\textbf]{NamedRef}{
1498 % label: align=r, head=Line,
1499 % format=\kvtLabel[row]{kvtRow};
1500 % text: align=l, head=Text}
1501 % \begin{KeyValTable}{NamedRef}
1502 % \Row{text=First row, label=one}
1503 % \Row{text=After \cref{one}}
1504 % \end{KeyValTable}
1505 % \end{LTXexample}
1506 %
1507 %
1508 % \subsection{Tables from CSV Files (\pkgname{datatool} and \pkgname{csvsimple})}\label{sec:CSV}
1509 %
1510 % The \thispackage package itself does not offer its own functionality
1511 % for generating tables from CSV files. However, together with existing
1512 % CSV packages, table content can be sourced from CSV files.
1513 % The remainder of this section shows how this can be achieved by
1514 % example. The following CSV file serves as the data file in the
1515 % examples. We use the same |Recipe| table type as previously.
1516 %
1517 % \lstinputlisting[caption=recipes.csv]{recipes.csv}
1518 %
1519 % \paragraph{\pkgname{datatool}}
1520 % The package provides a variety of macros for loading and also
1521 % displaying CSV database content. The following shows how the macros
1522 % |\DTLloaddb| and |\DTLforeach*| can be used, together with
1523 % |\AddKeyValRow| and |\ShowKeyValTable|.
1524 % The example also shows how a simple filter can be applied to the rows
1525 % via |\DTLforeach*|.
1526 %
1527 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={DTLloaddb,DTLforeach,expandonce}]
1528 % \usepackage{datatool}
1529 % \DTLloaddb{recipes}{recipes.csv}
1530 % \DTLforeach*[\equal{\Id}{snowman}]{recipes}
1531 % {\Id=id,
1532 % \Amount=amount,\Ingr=ingredient,\Step=step}
1533 % {\AddKeyValRow{Recipe}[expandonce]{
1534 % amount=\Amount,ingredient=\Ingr,step=\Step}}
1535 % \ShowKeyValTable{Recipe}
1536 % \end{LTXexample}
1537 %
1538 % Two aspects shall be noted.
1539 % Firstly, we use |\AddKeyValRow| rather than |KeyValTable|,
1540 % because |\DTLforeach*| interferes with how |KeyValTable| constructs
1541 % its rows and yields "misplaced |\noalign|" errors. We do not use
1542 % |\CollectRow| here, because it requires two runs and we do not need
1543 % the feature to show the table before the rows are specified.
1544 % Secondly, we use the row option |expandonce| to ensure that the macros
1545 % |\Amount|, |\Ingr|, and |\Step| are expanded (i.e., replaced by their
1546 % values). Without this option, all rows would only carry the three
1547 % macros and display the value that these macros have at the time of the
1548 % |\ShowKeyValTable|.
1549 %
1550 % \NiceDescribeKeys{2}
1551 % {expandonce}{vals={true,false}, init=false, def=true}
1552 % {expand}{vals={true,false}, init=false, def=true}
1553 % These row options can be used when programmatically constructing the
1554 % rows of a table, particularly with |KeyValTableContent| and
1555 % |\CollectRow|.
1556 % The |expandonce| option expands all the cell values
1557 % given to a row (default values not included) exactly once before
1558 % including it in the respective row.
1559 % The |expand| option fully expands the cell values, in |protect|'ed
1560 % mode (i.e., robust commands are not expanded).
1561 %
1562 %
1563 % \paragraph{\pkgname{csvsimple}}
1564 % For the sake of our example, using this package is very similar to
1565 % using \pkgname{datatool}.
1566 %
1567 % \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={csvreader,expand}]
1568 % \usepackage{csvsimple}
1569 % \csvreader[head to column names,
1570 % filter equal={\id}{cherries}]{recipes.csv}{}
1571 % {\AddKeyValRow{Recipe}[expand]{
1572 % amount=\amount,ingredient=\ingredient,
1573 % step=\step}}
1574 % \ShowKeyValTable{Recipe}
1575 % \end{LTXexample}
1576 %
1577 % Two differences are noteworthy here:
1578 % First, we can avoid specifying macro names for the columns through the
1579 % |head to column names|, which uses the column names as macro names.
1580 % Second, we have to use the |expand| option rather than |expandonce|
1581 % here, because \pkgname{csvsimple} apparently does not directly store
1582 % the column value in the respective macro.
1583 %
1584 %
1585 % \subsection{Computational Cells (\pkgname{xint})}
1586 %
1587 % The mechanism of cell formatting macros enables a simple means for
1588 % automatically computing formulas contained in a column. This can be
1589 % done, for instance using the \pkgname{xint} package and defining a
1590 % custom format macro (here |\Math|) that takes over the computation.
1591 % \begin{LTXexample}
1592 % \usepackage{xintexpr}
1593 % \newcommand\Math[1]{%
1594 % \xinttheexpr trunc(#1, 1)\relax}
1595 % \NewKeyValTable{Calculating}{
1596 % type; value: align=r,format=\Math}
1597 % \begin{KeyValTable}{Calculating}
1598 % \Row{type=simple, value=10+5.5}
1599 % \Row{type=advanced, value=0.2*(9+2^8)}
1600 % \end{KeyValTable}
1601 % \end{LTXexample}
1602 %
1603 %
1604 % \subsection{Cell Formatting (\pkgname{makecell})}
1605 %
1606 % The \thispackage package can be used together with the
1607 % \pkgname{makecell} package in at least two ways:
1608 % \begin{enumerate}[noitemsep]
1609 % \item formatting header cells using the |head| property of columns;
1610 % \item formatting content cells using the |format| property of columns.
1611 % \end{enumerate}
1612 % The following example gives an impression.
1613 % \begin{LTXexample}
1614 % \usepackage{makecell}
1615 % \renewcommand\theadfont{\bfseries}
1616 % \renewcommand\theadalign{lt}
1617 % \NewKeyValTable{Header}{
1618 % first: head=\thead{short};
1619 % second: head=\thead{two\\ lines};}
1620 % \begin{KeyValTable}{Header}
1621 % \Row{first=just a, second=test}
1622 % \end{KeyValTable}
1623 % \end{LTXexample}
1624 %
1625 %
1626 % \clearpage
1627 % \section{Related Packages}
1628 %
1629 % I'm not aware of any \LaTeX{} packages that pursue similar goals or
1630 % provide similar functionality. The following \LaTeX{} packages provide
1631 % loosely related functionalities to the \thispackage package.
1632 %
1633 % \begin{description}
1634 % \item[\pkgname{tablestyles}:]
1635 % This package simplifies typesetting tables with common and/or more
1636 % appealing appearances than default \hologo{LaTeX} tables.
1637 % This corresponds to what \thispackage supports with the various
1638 % coloring and formatting options to |\kvtSet|, |\NewKeyValTable|, and
1639 % individual tables.
1640 % The \pkgname{tablestyles} package builds on the default
1641 % \hologo{LaTeX} environments and syntax for typesetting tables (with
1642 % column alignments specified in an argument to the table environment,
1643 % and columns separated by |&| in the body of the environment).
1644 % \item[\pkgname{ctable}:]
1645 % This package focuses on typesetting tables with captions and notes.
1646 % With this package, the specification of table content is quite
1647 % close to normal |tabular| environments, except that the package's
1648 % table creation is done via a macro, |\ctable|.
1649 % \item[\pkgname{easytable}:]
1650 % This package provides an environment |TAB| which simplifies the
1651 % creation of tables with particular horizontal and vertical cell
1652 % alignments, rules around cells, and cell width distributions. In
1653 % that sense, the package aims at simpler table creation, like
1654 % \thispackage. However, the package does not pursue
1655 % separation of content from presentation or re-use of table layouts.
1656 % \item[\pkgname{tabularkv}:]
1657 % Despite the similarity in the name, this package pursues a different
1658 % purpose. Namely, this package provides means for specifying table
1659 % options such as width and height through an optional key-value
1660 % argument to the |tabularkv| environment. This package does not use
1661 % a key-value like specification for the content of tables.
1662 % \end{description}
1663 %
1664 % \section{Future Work}
1665 %
1666 % \begin{itemize}
1667 % \item support for different headers on the first page vs.\@ on
1668 % subsequent pages of a multipage table; support configurable spacing
1669 % between and above/below header rows
1670 % \item support for more flexibility with regards to specifying
1671 % distinct captions on first/middle/last page of the table.
1672 % \item improved row coloring that makes sure that the alternation
1673 % re-starts on continued pages of a table that spans several pages
1674 % \item rerun detection for recorded rows (possibly via
1675 % \pkgname{rerunfilecheck})
1676 % \item nesting of |KeyValTable| environments (this is so far not tested
1677 % by the package author and might not work or work only to a limited
1678 % extent)
1679 % \end{itemize}
1680 %
1681 % \clearpage
1682 %
1683 % \StopEventually{}
1684 %\iffalse
1685 %<*package>
1686 %\fi
1687 %
1688 % \section{Implementation}
1689 % \etocsetnexttocdepth{2}
1690 % \etoclocalmulticol[2]{\subsection*{Content}}
1691 %
1692 % \subsection{Package Dependencies}
1693 %
1694 % We use \pkgname{etoolbox} for some convenience macros that make the
1695 % code more easily maintainable and use \pkgname{xkeyval} for options
1696 % in key--value form. The \pkgname{trimspaces} package is used once for
1697 % trimming spaces before a string comparison.
1698 % \begin{macrocode}
1699 \RequirePackage{etoolbox}
1700 \RequirePackage{xkeyval}
1701 \RequirePackage{trimspaces}
1702 % \end{macrocode}
1703 % We use \pkgname{booktabs} for nice horizontal lines,
1704 % \pkgname{colortbl} for row coloring, and \pkgname{xcolor} for color
1705 % names. To avoid package option clashes with \pkgname{xcolor}, we
1706 % load it at the end of the preamble..
1707 % \changes{v2.3}{2020/06/13}{Delayed loading of \pkgname{xcolor}}
1708 % \begin{macrocode}
1709 \RequirePackage{colortbl}
1710 \AtBeginDocument{\@ifpackageloaded{xcolor}{}{\RequirePackage{xcolor}}}
1711 \RequirePackage{booktabs}
1712 % \end{macrocode}
1713 %
1714 % \subsection{Auxiliary Code}
1715 %
1716 % \subsubsection{List Parsing}
1717 %
1718 % \begin{macro}{\kvt@DeclareTrimListParser}
1719 % The |\kvt@DeclareTrimListParser|(|*|)\marg{command}\marg{separator}
1720 % macro is equivalent to \pkgname{etoolbox}'s |\DeclareListParser|,
1721 % except that the \meta{command} is defined such that it will remove
1722 % trailing spaces from list elements before passing the list elements to
1723 % the processing macro (i.e., to |\do| or the user-provided macro).
1724 % Note: With |\DeclareListParser|, \meta{command} is defined to only
1725 % remove leading spaces but not trailing ones.
1726 % This implementation relies on the internals of
1727 % \pkgname{etoolbox} and works with v2.4 of the package, at least.
1728 % \begin{macrocode}
1729 \newcommand\kvt@DeclareTrimListParser{%
1730 \@ifstar{\kvt@DeclareTrimListParser@i{*}}
1731 {\kvt@DeclareTrimListParser@i{}}}
1732 \newcommand\kvt@DeclareTrimListParser@i[3]{%
1733 \DeclareListParser#1{#2}{#3}\expandafter
1734 \patchcmd\csname etb@lst@\expandafter\@gobble\string#2\endcsname
1735 {\etb@listitem}{\kvt@etb@listitem}{}
1736 {\kvt@warn{Failed to patch a command defined by the etoolbox
1737 package, possibly because etoolbox internals have changed.
1738 You might encounter superfluous spaces.}}}
1739 % \end{macrocode}
1740 % The cascade of |\expandafter| below ensures that first the trimming
1741 % macro is expanded and afterwards the outer |\unexpanded| of the
1742 % timming macro's expansion is expanded, which by definition of the
1743 % "noexp" trimming macro fully expands the macro's logic.
1744 % The auxiliary macro below is only for switching the two arguments such
1745 % that the expansion control can be applied to the second argument.
1746 % \begin{macrocode}
1747 \newcommand\kvt@etb@listitem[2]{%
1748 \expandafter\expandafter\expandafter\kvt@etb@listitem@i
1749 \expandafter\expandafter\expandafter{\trim@post@space@noexp{#2}}{#1}}
1750 \newcommand\kvt@etb@listitem@i[2]{\etb@listitem{#2}{#1}}
1751 % \end{macrocode}
1752 % \end{macro}
1753 %
1754 % \begin{macro}{\kvt@dossvlist}
1755 % The |\kvt@dossvlist|\marg{list} macro parses a semicolon-separated
1756 % list and runs |\do|\meta{item} for every element of the list.
1757 % \begin{macrocode}
1758 \DeclareListParser{\kvt@dossvlist}{;}
1759 % \end{macrocode}
1760 % \end{macro}
1761 %
1762 % \begin{macro}{\kvt@forpsvlist}
1763 % The |\kvt@forpsvlist|\marg{handler}\marg{list} parses a `+'-separated list.
1764 % \begin{macrocode}
1765 \kvt@DeclareTrimListParser*{\kvt@forpsvlist}{+}
1766 % \end{macrocode}
1767 % \end{macro}
1768 %
1769 % \begin{macro}{\kvt@dobrklist}
1770 % The |\kvt@dobrklist|\marg{list} parses a `|\\|'-separated list.
1771 % \begin{macrocode}
1772 \kvt@DeclareTrimListParser{\kvt@dobrklist}{\\}
1773 % \end{macrocode}
1774 % \end{macro}
1775 %
1776 % \subsubsection{Errors and Warnings}
1777 %
1778 % \begin{macro}{\kvt@error}
1779 % \begin{macro}{\kvt@warn}
1780 % These macros produce error and warning messages.
1781 % \begin{macrocode}
1782 \newcommand\kvt@error[2]{\PackageError{keyvaltable}{#1}{#2}}
1783 \newcommand\kvt@warn[1]{\PackageWarning{keyvaltable}{#1}}
1784 % \end{macrocode}
1785 % \end{macro}
1786 % \end{macro}
1787 %
1788 % \subsubsection{Setting Keys}
1789 %
1790 % \begin{macro}{\kvt@setkeys}
1791 % \begin{macro}{\kvt@setcmdkeys}
1792 % \begin{macro}{\kvt@setcskeys}
1793 % The |\kvt@setkeys|\marg{keys}\marg{fam} macro abbreviates
1794 % |\setkeys[kvt]|\meta{fam}\meta{keys} (note the reverse order of
1795 % arguments).
1796 % The |\kvt@setcmdkeys|\marg{keycmd}\marg{fam} and
1797 % |\kvt@setcskeys|\marg{keycs}\marg{fam} abbreviate the cases where
1798 % \meta{keys} are stored in macro \meta{keycmd} or, respectively,
1799 % stored in a macro with name \meta{keycs}.
1800 % \begin{macrocode}
1801 \newcommand\kvt@setkeys[2]{\setkeys[kvt]{#2}{#1}}
1802 \newcommand\kvt@setcmdkeys[2]{%
1803 \expandafter\kvt@setkeys\expandafter{#1}{#2}}
1804 \newcommand\kvt@setcskeys[2]{%
1805 \expandafter\kvt@setcmdkeys\expandafter{\csname #1\endcsname}{#2}}
1806 % \end{macrocode}
1807 % \end{macro}
1808 % \end{macro}
1809 % \end{macro}
1810 %
1811 % \begin{macro}{\kvt@setkeys@nopresets}
1812 % The
1813 % |\kvt@setkeys@nopresets|\marg{keys}\marg{family} macro
1814 % expands to a |\kvt@setkeys| in which no presets are active.
1815 % \begin{macrocode}
1816 \newcommand\kvt@setkeys@nopresets[2]{%
1817 \kvt@xkv@disablepreset[kvt]{#2}{\kvt@setkeys{#1}{#2}}}
1818 % \end{macrocode}
1819 % \end{macro}
1820 %
1821 % \begin{macro}{\kvt@colsetkeys}
1822 % \begin{macro}{\kvt@colsetcmdkeys}
1823 % \begin{macro}{\kvt@colsetcskeys}
1824 % The |\kvt@colsetkeys|\marg{fam}\marg{keys} macro abbreviates
1825 % |\setkeys[KeyValTable]| with the same arguments.
1826 % The |\kvt@colsetcmdkeys|\marg{famcmd}\marg{keys} and
1827 % |\kvt@colsetcskeys|\marg{famcs}\marg{keys} abbreviate the cases where
1828 % \meta{fam} is stored in macro \meta{famcmd} or, respectively,
1829 % stored in a macro with name \meta{famcs}.
1830 % \begin{macrocode}
1831 \newcommand\kvt@colsetkeys[2]{\setkeys[KeyValTable]{#1}{#2}}
1832 \newcommand\kvt@colsetcmdkeys[2]{%
1833 \expandafter\kvt@colsetkeys\expandafter{#1}{#2}}
1834 \newcommand\kvt@colsetcskeys[2]{%
1835 \expandafter\kvt@colsetcmdkeys\expandafter{\csname #1\endcsname}{#2}}
1836 % \end{macrocode}
1837 % \end{macro}
1838 % \end{macro}
1839 % \end{macro}
1840 %
1841 % \begin{macro}{\kvtStrutted}
1842 % The |\kvtStrutted|\oarg{inner}\marg{arg} macro prefixes and suffixes
1843 % the argument \meta{arg} with a |\strut|. When used for formatting
1844 % cell content, this makes sure that there is some vertical space
1845 % between the content of a cell and the top and bottom of the row.
1846 % The optional \oarg{inner} argument, if provided, should be a macro
1847 % that takes one argument. In this case, instead of \meta{arg},
1848 % \meta{inner}|{|\meta{arg}|}| is prefixed and sufficed with |\strut|.
1849 % \changes{v0.3}{2016/06/06}{Fix for cells with vertical material}
1850 % \changes{v2.0}{2019/03/22}{Added optional argument}
1851 % \begin{macrocode}
1852 \newcommand\kvtStrutted[2][\@firstofone]{%
1853 \strut#1{#2}\ifhmode\expandafter\strut\fi}
1854 % \end{macrocode}
1855 % \end{macro}
1856 %
1857 %
1858 % \subsection{Setting Options}
1859 %
1860 % \begin{macro}{\kvtSet}
1861 % The |\kvtSet|\marg{options} set the default options, which apply
1862 % to all tables typeset with the package.
1863 % \begin{macrocode}
1864 \newcommand\kvtSet[1]{%
1865 \kvt@setkeys{#1}{global,Table,Column}%
1866 \ifdefvoid\kvt@@presetqueue{}
1867 {\kvt@@presetqueue\undef\kvt@@presetqueue}}
1868 % \end{macrocode}
1869 % \end{macro}
1870 %
1871 % \begin{macro}{\kvt@lazypreset}
1872 % The |\kvt@@lazypreset|\marg{family}\marg{head keys} macro collects a
1873 % request for pre-setting \meta{head keys} in family
1874 % key \meta{family}. Using this macro, one can avoid causing problems
1875 % with using \pkgname{xkeyval}'s |\presetkeys| inside the \meta{function}
1876 % defined for a key (e.g., via |\define@key|). The collected requests
1877 % can be performed by expanding the |\kvt@@presetqueue| macro.
1878 % \begin{macrocode}
1879 \newcommand\kvt@lazypreset[2]{%
1880 \appto\kvt@@presetqueue{\presetkeys[kvt]{#1}{#2}{}}}
1881 % \end{macrocode}
1882 % \end{macro}
1883 %
1884 % \begin{macro}{\kvt@keysetter}
1885 % The
1886 % |\kvt@keysetter|\marg{macro}\marg{fam}\marg{key}\marg{value}\marg{func}
1887 % macro is an auxiliary macro that can be used inside the "func"
1888 % argument of |\[email protected]| macros.
1889 % If \meta{macro} is not defined, |\kvt@keysetter| expands to an
1890 % instance of |\kvt@lazypreset| in order to set a global default.
1891 % Otherwise, |\kvt@keysetter| expands to \meta{func}, which is supposed
1892 % to set a key for the specific context referenced by \meta{macro}.
1893 % \begin{macrocode}
1894 \newcommand\kvt@keysetter[5]{%
1895 \ifdefvoid{#1}
1896 {\kvt@lazypreset{#2}{#3=#4}}
1897 {#5}}
1898 % \end{macrocode}
1899 % \end{macro}
1900 %
1901 % \begin{macro}{\kvtTableOpt}
1902 % The |\kvtTableOpt|\marg{optname} macro, inside a |KeyValTable|
1903 % environment, expands to the value of the table option \meta{optname}.
1904 % \begin{macrocode}
1905 \newcommand\kvtTableOpt[1]{\csname cmdkvt@Table@#1\endcsname}
1906 % \end{macrocode}
1907 % \end{macro}
1908 %
1909 % \subsubsection{Table Options}
1910 %
1911 % The following code defines the possible table options.
1912 %
1913 % \changes{v0.2}{2016/05/21}{Added ``shape'' table option}
1914 % \changes{v2.0}{2019/05/11}{Added table options "caption" and "label"}
1915 % \changes{v2.1}{2020/01/18}{Added ``valign'' and ``halign'' table options}
1916 % \changes{v2.2}{2020/02/24}{Added ``style'' table option}
1917 % \changes{v2.2}{2020/02/27}{added option "backend"}
1918 % \changes{v2.2}{2020/03/08}{added option "captionpos"}
1919 % \begin{macrocode}
1920 \define@cmdkey[kvt]{Table}{rowbg}{}
1921 \define@cmdkey[kvt]{Table}{headbg}{}
1922 \define@cmdkey[kvt]{Table}{headalign}{}
1923 \define@cmdkey[kvt]{Table}{headformat}{}
1924 \define@cmdkey[kvt]{Table}{width}{}
1925 \define@boolkey[kvt]{Table}{showhead}{}
1926 \define@boolkey[kvt]{Table}{showrules}{}
1927 \define@choicekey[kvt]{Table}{captionpos}{t,b}
1928 {\csdef{cmdkvt@Table@captionpos}{#1}}
1929 \define@choicekey[kvt]{Table}{valign}{t,c,b}
1930 {\csdef{cmdkvt@Table@valign}{#1}}
1931 \define@choicekey[kvt]{Table}{halign}{l,c,r}
1932 {\csdef{cmdkvt@Table@halign}{#1}}
1933 \define@key[kvt]{Table}{style}{\kvt@UseTableStyles{#1}}
1934 % \end{macrocode}
1935 % The following options only abbreviate options defined above.
1936 % \changes{v2.1}{2020/01/14}{added abbreviation option "norules"}
1937 % \begin{macrocode}
1938 \define@boolkey[kvt]{Table}{norowbg}[true]{%
1939 \kvt@setkeys{rowbg={}}{Table}}
1940 \define@boolkey[kvt]{Table}{nobg}[true]{%
1941 \kvt@setkeys{rowbg={},headbg={}}{Table}}
1942 \define@boolkey[kvt]{Table}{norules}[true]{%
1943 \ifbool{#1}
1944 {\kvt@setkeys{showrules=false}{Table}}
1945 {\kvt@setkeys{showrules=true}{Table}}}
1946 \define@key[kvt]{Table}{backend}{\ifinlist{#1}{\kvt@@tablebackends}
1947 {\csdef{cmdkvt@Table@shape}{#1}}
1948 {\kvt@error{Table backend '#1' not known}
1949 {Check for misspellings in '#1'}}}
1950 \define@key[kvt]{Table}{shape}{\ifinlist{#1}{\kvt@@tableshapes}
1951 {\csdef{cmdkvt@Table@shape}{#1}}
1952 {\ifinlist{#1}{\kvt@@tablebackends}
1953 {\kvt@warn{Using a backend ('#1') as shape is deprecated.
1954 Use the 'backend' option instead.}%
1955 \csdef{cmdkvt@Table@shape}{#1}}
1956 {\kvt@error{Table shape '#1' not known}
1957 {Check for misspellings in '#1'}}}}
1958 % \end{macrocode}
1959 %
1960 % The following table options only apply to individual |KeyValTable|
1961 % environments and cannot be set with |\NewKeyValTable| or |\kvtSet|.
1962 % \changes{v2.2}{2020/02/23}{added table options "resume" and "resume*"}
1963 % \changes{v2.2}{2020/03/12}{added options "caption/lot" and "caption/alt"}
1964 % \begin{macrocode}
1965 \define@cmdkey[kvt]{TableEnv}{caption}{}
1966 \define@cmdkey[kvt]{TableEnv}{caption/lot}{}
1967 \define@cmdkey[kvt]{TableEnv}{caption/alt}{}
1968 \define@cmdkey[kvt]{TableEnv}{label}{}
1969 \define@boolkey[kvt]{TableEnv}{resume}[true]{%
1970 \ifbool{#1}{\ifundef\kvt@@rowcountlast
1971 {\kvt@error{No previous table whose counter could be resumed.}
1972 {Check whether the "resume" is intentional and whether a
1973 previously existing predecessor table has disappeared.}}{}}{}}
1974 \define@boolkey[kvt]{TableEnv}{resume*}[true]{%
1975 \ifbool{#1}
1976 % \end{macrocode}
1977 % The |\kvt@@lastenvopt| macro holds the previous |KeyValTable|'s
1978 % options. Beyond these options, |resume*| automatically also sets
1979 % |resume|.
1980 % \begin{macrocode}
1981 {\ifundef\kvt@@lastenvopt
1982 {\kvt@error{No previous table whose options could be resume*'d.}
1983 {Check whether the "resume*" is intentional and whether a
1984 previously existing predecessor table has disappeared.}}{}%
1985 \kvt@setcmdkeys\kvt@@lastenvopt{Table}%
1986 \kvt@setkeys{resume}{TableEnv}}
1987 {}}
1988 % \end{macrocode}
1989 %
1990 %
1991 % \subsubsection{Column Options}
1992 %
1993 % The following code defines the possible column options.
1994 %
1995 % \changes{v1.0}{2018/12/30}{Enabled default ``true'' for ``hidden''}
1996 % \begin{macrocode}
1997 \define@key[kvt]{Column}{default}{\kvt@colkeysetter{default}{#1}}
1998 \define@key[kvt]{Column}{format}{\kvt@colkeysetter{format}{#1}}
1999 \define@key[kvt]{Column}{align}{\kvt@colkeysetter{align}{#1}}
2000 \define@key[kvt]{Column}{head}{\kvt@colkeysetter{head}{#1}}
2001 \define@boolkey[kvt]{Column}{hidden}[true]{%
2002 \kvt@colkeysetter{hidden}{#1}}
2003 % \end{macrocode}
2004 %
2005 % \begin{macro}{\kvt@colkeysetter}
2006 % The |\kvt@colkeysetter|\marg{key}\marg{value} specializes
2007 % |\kvt@keysetter| for column options.
2008 % \begin{macrocode}
2009 \newcommand\kvt@colkeysetter[2]{%
2010 \kvt@keysetter{\kvt@@column}{Column}{#1}{#2}{%
2011 \csdef{kvt@col@#1@\kvt@@column}{#2}}}
2012 % \end{macrocode}
2013 % \end{macro}
2014 %
2015 % \begin{macro}{\kvt@def@globalopt}
2016 % \begin{macro}{\kvt@def@globalopts}
2017 % The |\kvt@def@globalopt|\marg{family}{key} macro creates the option key
2018 % "\meta{family}/\meta{key}". When used in |\kvtSet|, this key sets the preset
2019 % value for the \meta{key} in \meta{family}.
2020 % The |\kvt@def@globalopts|\marg{family}{keys} macro extends the former
2021 % macro to comma-separated lists of \meta{keys} within a single
2022 % \meta{family}.
2023 % \begin{macrocode}
2024 \newcommand\kvt@def@globalopt[2]{%
2025 \define@key[kvt]{global}{#1/#2}{\kvt@lazypreset{#1}{#2={##1}}}}
2026 \newcommand\kvt@def@globalopts[2]{%
2027 \forcsvlist{\kvt@def@globalopt{#1}}{#2}}
2028 % \end{macrocode}
2029 % \end{macro}
2030 % \end{macro}
2031 %
2032 % \begin{macrocode}
2033 \define@cmdkey[kvt]{ColGroup}{span}{%
2034 \csgdef{kvt@colgrp@span@\kvt@@tname @\kvt@@colgrp}{#1}}
2035 \define@cmdkey[kvt]{ColGroup}{align}{%
2036 \csgdef{kvt@colgrp@align@\kvt@@tname @\kvt@@colgrp}{#1}}
2037 \define@cmdkey[kvt]{ColGroup}{format}{%
2038 \csgdef{kvt@colgrp@format@\kvt@@tname @\kvt@@colgrp}{#1}}
2039 \kvt@def@globalopts{ColGroup}{align, format}
2040 % \end{macrocode}
2041 %
2042 %
2043 % \subsubsection{Layout Customization Options}
2044 %
2045 % The following defines the option keys for the second optional argument
2046 % to |\NewKeyValTable|. These options intentionally do not support
2047 % setting global defaults via |\kvtSet|.
2048 % \begin{macrocode}
2049 \define@cmdkey[kvt]{Layout}{headers}{%
2050 \expandafter\kvt@parseheadrows\expandafter{\kvt@@tname}{#1}}
2051 \define@cmdkey[kvt]{Layout}{colgroups}{%
2052 \expandafter\kvt@parsecolgroups\expandafter{\kvt@@tname}{#1}}
2053 % \end{macrocode}
2054 %
2055 % The following defines the options for header cells.
2056 % \begin{macrocode}
2057 \define@key[kvt]{HeadCell}{head}{%
2058 \csdef{kvt@@hdcell@head@\kvt@@hdcell}{#1}}
2059 \define@key[kvt]{HeadCell}{align}{%
2060 \csdef{kvt@@hdcell@align@\kvt@@hdcell}{#1}}
2061 \define@boolkey[kvt]{HeadCell}{underline}[true]{%
2062 \csdef{kvt@@hdcell@underline@\kvt@@hdcell}{#1}}
2063 \kvt@def@globalopts{HeadCell}{align}
2064 % \end{macrocode}
2065 %
2066 %
2067 % \subsubsection{Row Options}
2068 %
2069 % The following block declares the known row options.
2070 % Note that these are not enabled for |\kvtSet|.
2071 % \changes{v2.0}{2019/05/11}{added row options "expand" and "expandonce"}
2072 % \changes{v2.0}{2019/05/11}{added row options "nobg" and "norowbg"}
2073 % \changes{v2.0}{2019/05/11}{added row option "style"}
2074 % \changes{v2.0}{2019/05/11}{added row option "uncounted"}
2075 % \changes{v2.1}{2020/02/15}{added row options "format", "format*",
2076 % "format!", "align", and "headlike"}
2077 % \begin{macrocode}
2078 \define@cmdkey[kvt]{Row}{bg}{}
2079 \define@cmdkey[kvt]{Row}{format}{}
2080 \define@cmdkey[kvt]{Row}{format*}{}
2081 \define@cmdkey[kvt]{Row}{format!}{}
2082 \define@cmdkey[kvt]{Row}{align}{}
2083 \define@boolkey[kvt]{Row}{headlike}[true]{%
2084 \ifbool{#1}{%
2085 \edef\kvt@@opts{%
2086 bg={\expandonce\cmdkvt@Table@headbg},%
2087 format!={\expandonce\cmdkvt@Table@headformat},%
2088 align={\expandonce\cmdkvt@Table@headalign}}%
2089 \expandafter\kvt@setkeys@nopresets\expandafter{\kvt@@opts}{Row}%
2090 }{}}
2091 \define@boolkey[kvt]{Row}{hidden}[true]{}
2092 \define@cmdkey[kvt]{Row}{below}{}
2093 \define@cmdkey[kvt]{Row}{above}{}
2094 \define@key[kvt]{Row}{around}{%
2095 \kvt@setkeys@nopresets{below={#1},above={#1}}{Row}}
2096 \define@key[kvt]{Row}{style}{\kvt@UseRowStyles{#1}}
2097 \define@boolkey[kvt]{Row}{uncounted}[true]{}
2098 \define@boolkey[kvt]{Row}{expand}[true]{}
2099 \define@boolkey[kvt]{Row}{expandonce}[true]{}
2100 % \end{macrocode}
2101 % The following specifies which row options can be specified globally,
2102 % i.e. via a |Row/option| key. Not contained in the list are the
2103 % |format| options and the |headlike| option, as setting these globally
2104 % appears strange.
2105 % \begin{macrocode}
2106 \kvt@def@globalopts{Row}{
2107 bg,hidden,below,above,around,style,uncounted,
2108 expand,expandonce}
2109 % \end{macrocode}
2110 %
2111 %
2112 % \subsubsection{Option Defaults}
2113 %
2114 % The following sets the default values for the options. This is done
2115 % only after the package is otherwise completely processed, to ensure
2116 % that all features are already defined/registered at that point.
2117 % \changes{v2.3}{2020/07/30}{Removed \cmd{\kvtStrutted} from default format}
2118 % \begin{macrocode}
2119 \AtEndOfPackage{\kvtSet{%
2120 rowbg=white..black!10,
2121 headbg=black!14,
2122 showhead=true,
2123 showrules=true,
2124 headformat=\@firstofone,
2125 headalign=,
2126 shape=multipage,
2127 width=\linewidth,
2128 captionpos=b,
2129 % \end{macrocode}
2130 % Column options
2131 % \begin{macrocode}
2132 default=,
2133 format=\@firstofone,
2134 align=l,
2135 head=,
2136 hidden=false,
2137 Row/bg={},
2138 Row/hidden=false,
2139 Row/above={},
2140 Row/below={},
2141 Row/uncounted=false,
2142 Row/expand=false,
2143 Row/expandonce=false,
2144 ColGroup/align=c,
2145 ColGroup/format=\@firstofone,
2146 HeadCell/align=c,
2147 }}
2148 % \end{macrocode}
2149 %
2150 %
2151 % \subsection{Declaring Key-Value Tables}
2152 %
2153 % \begin{macro}{\NewKeyValTable}
2154 % The
2155 % |\NewKeyValTable|\oarg{options}\marg{tname}\marg{colspecs}\oarg{layout}
2156 % declares a new key-value table type, identified by the given
2157 % \meta{tname}. The columns of the table type are specified by
2158 % \meta{colspecs}. The optional \meta{options}, if given, override the
2159 % default table options for tables of type \meta{tname}.
2160 % \changes{v0.2}{2016/05/21}{Added table-type options}
2161 % \changes{v1.0}{2019/02/03}{Added optional headers argument}
2162 % \changes{v2.0}{2019/04/28}{Changed headers argument to layout argument}
2163 % \begin{macrocode}
2164 \newcommand\NewKeyValTable[3][]{%
2165 \@ifnextchar[%]
2166 {\kvt@NewKeyValTable{#1}{#2}{#3}}%
2167 {\kvt@NewKeyValTable{#1}{#2}{#3}[]}}
2168 % \end{macrocode}
2169 % The
2170 % |\kvt@NewKeyValTable|\marg{options}\marg{tname}\marg{colspecs}\oarg{layout}
2171 % macro is an auxiliary macro used for parsing the fourth, optional
2172 % argument of |\NewKeyValTable|.
2173 % \begin{macrocode}
2174 \def\kvt@NewKeyValTable#1#2#3[#4]{%
2175 % \end{macrocode}
2176 % Before doing anything, check whether \meta{tname} has already been
2177 % defined.
2178 % \begin{macrocode}
2179 \ifinlist{#2}{\kvt@alltables}
2180 {\kvt@error{Table type with name '#2' already defined}
2181 {Check '#2' for typos and check other uses of
2182 \string\NewKeyValTable}}{}%
2183 % \end{macrocode}
2184 % First initialize the ``variables''.
2185 % \begin{macrocode}
2186 \csdef{kvt@options@#2}{#1}%
2187 \csdef{kvt@headings@#2}{}%
2188 % \end{macrocode}
2189 % The following adds a zero-width column to the left of every table.
2190 % This column serves the purpose of "holding" the code that
2191 % \thispackage uses for formatting a row (e.g., parsing |\Row|
2192 % arguments). This code is partly not expandable.
2193 % The reason for not putting this code into the first actual colum of
2194 % tables is that this code would prevent |\multicolumn| to be used in
2195 % the first column.
2196 % \changes{v1.0}{2019/02/03}{Added zero-width column for \cs{multicolumn}}
2197 % \changes{v2.1}{2020/02/16}{Removed zero-width column again}
2198 % \begin{macrocode}
2199 \csdef{kvt@alignments@#2}{}%
2200 \csdef{kvt@allcolumns@#2}{}%
2201 \csdef{kvt@displaycols@#2}{}%
2202 \csdef{kvt@ndisplaycols@#2}{0}%
2203 \csdef{kvt@rowcount@#2}{0}%
2204 \csdef{kvt@rows@#2}{}%
2205 \csdef{kvt@headings@#2}{\kvt@defaultheader}%
2206 \listadd\kvt@alltables{#2}%
2207 % \end{macrocode}
2208 % Now parse \meta{colspecs}, a semicolon-separated list of individual
2209 % column specifications, and add the columns to the table. Each
2210 % |\do|\marg{colspec} takes the specification for a single column.
2211 % \begin{macrocode}
2212 \def\do##1{%
2213 \kvt@parsecolspec{#2}##1::\@undefined}%
2214 \kvt@dossvlist{#3}%
2215 % \end{macrocode}
2216 % By default, a single header row is constructed.
2217 % \begin{macrocode}
2218 \csdef{kvt@headrowcount@#2}{1}%
2219 % \end{macrocode}
2220 % The following terminates the argument list of |\kvt@defaultheader|.
2221 % \begin{macrocode}
2222 \csappto{kvt@headings@#2}{{\@nil}}%
2223 % \end{macrocode}
2224 % Finally, parse \meta{layout}.
2225 % \begin{macrocode}
2226 \kvt@parselayout{#4}{#2}%
2227 }
2228 % \end{macrocode}
2229 % \end{macro}
2230 %
2231 % \begin{macro}{\kvt@parsecolspec}
2232 % The
2233 % |\kvt@parsecolspec|\marg{tname}\meta{cname}|:|\meta{config}|:|\meta{empty}|\@undefined|
2234 % takes a configuration \meta{config} for a column \meta{cname} in table
2235 % \meta{tname} and adds the column with the configuration to the table.
2236 % \begin{macrocode}
2237 \def\kvt@parsecolspec#1#2:#3:#4\@undefined{%
2238 % \end{macrocode}
2239 % Catch syntax errors first.
2240 % \begin{macrocode}
2241 \kvt@checkcolspecempty{#4}{column}{#2}%
2242 \def\kvt@@column{#2}%
2243 \trim@spaces@in\kvt@@column
2244 \expandafter\kvt@parsecolspec@i\expandafter{\kvt@@column}{#1}{#3}}
2245 \newcommand\kvt@parsecolspec@i[3]{\kvt@parsecolspec@ii{#2}{#1}{#3}}
2246 \newcommand\kvt@parsecolspec@ii[3]{%
2247 \def\kvt@@column{#1@#2}%
2248 % \end{macrocode}
2249 % Check and record the column name first.
2250 % \begin{macrocode}
2251 \ifinlistcs{#2}{kvt@allcolumns@#1}
2252 {\kvt@error{Column name '#2' declared more than once in table type
2253 '#1'}{Check '#2' for typos; column names declared so far:%
2254 \forlistcsloop{ }{kvt@allcolumns@#1}}}{}%
2255 \listcsadd{kvt@allcolumns@#1}{#2}%
2256 \kvt@setkeys{#3}{Column}%
2257 % \end{macrocode}
2258 % The following stores the column's properties. The column is only added
2259 % if the |hidden| option is not set to |true|.
2260 % \begin{macrocode}
2261 \ifcsstring{kvt@col@hidden@#1@#2}{true}{}{%
2262 \cseappto{kvt@alignments@#1}{\csexpandonce{kvt@col@align@#1@#2}}%
2263 % \end{macrocode}
2264 % Append the column heading to \cs{kvt@headings@\meta{tname}}, which
2265 % collects arguments to |\kvt@defaultheader|. Hence, the appended tokens
2266 % are enclosed in curly braces. If no |head| is specified for the
2267 % column, \meta{cname} is used for the column header. Otherwise, the
2268 % |head| value is used.
2269 % \begin{macrocode}
2270 \ifcsvoid{kvt@col@head@#1@#2}%
2271 {\csappto{kvt@headings@#1}{{#2}}}%
2272 {\cseappto{kvt@headings@#1}{{\csexpandonce{kvt@col@head@#1@#2}}}}%
2273 \listcsadd{kvt@displaycols@#1}{#2}%
2274 \csedef{kvt@ndisplaycols@#1}{%
2275 \the\numexpr\csuse{kvt@ndisplaycols@#1}+1\relax}%
2276 }%
2277 % \end{macrocode}
2278 % The following creates the column key that can be used by the row
2279 % macros to set the content of the column's content in that row.
2280 % The starred variant of the key disables the column's |format| for the
2281 % cell.
2282 % \begin{macrocode}
2283 \define@cmdkey[KeyValTable]{#1}{#2}[]{}%
2284 \define@key[KeyValTable]{#1}{#2*}{%
2285 \csdef{cmdKeyValTable@#1@#2}{##1}%
2286 \csdef{kvt@@noformat@#1@#2}{1}}%
2287 \presetkeys[KeyValTable]{#1}{#2}{}%
2288 % \end{macrocode}
2289 % The |\kvt@parsecolspec| macro is not necessarily enclosed in a group.
2290 % To avoid leaking a local |\kvt@@column| value to the outer (global)
2291 % scope, we explicitly undefine it.
2292 % \begin{macrocode}
2293 \undef\kvt@@column}
2294 % \end{macrocode}
2295 % \end{macro}
2296 %
2297 %
2298 % \begin{macro}{\kvt@defaultheader}
2299 % The |\kvt@defaultheader|\marg{head1}\ldots\marg{headn}|\@nil| macro,
2300 % takes $n$ header cell titles, \meta{head1} to \meta{headn} and formats
2301 % them based on the |headformat| and |headalign| options.
2302 % More precisely, when fully expanded, |\kvt@defaultheader| yields
2303 % "\meta{rowcolor}\meta{fmthead1}| & |\ldots| & |\meta{fmtheadn}|\tabularnewline|".
2304 % In the above, \meta{rowcolor}=|\rowcolor{|\meta{headbg}|}|.
2305 % \begin{macrocode}
2306 \newcommand\kvt@defaultheader{%
2307 \noexpand\kvt@rowcolorornot{\cmdkvt@Table@headbg}%
2308 \kvt@defaultheader@i{}}
2309 \newcommand\kvt@defaultheader@i[2]{%
2310 \kvt@ifnil{#2}{\noexpand\tabularnewline}{%
2311 \unexpanded{#1}%
2312 \ifdefvoid\cmdkvt@Table@headalign
2313 {\expandonce\cmdkvt@Table@headformat{\unexpanded{#2}}}
2314 {\noexpand\multicolumn{1}{\expandonce\cmdkvt@Table@headalign}
2315 {\expandonce\cmdkvt@Table@headformat{\unexpanded{#2}}}}%
2316 \kvt@defaultheader@i{&}}}
2317 % \end{macrocode}
2318 % \begin{macro}{\kvt@ifnil}
2319 % The |\kvt@ifnil|\marg{val}\marg{iftrue}\marg{iffalse} macro expands to
2320 % \meta{iftrue} if \meta{val} is |\@nil|, and expands to \meta{iffalse}
2321 % otherwise.
2322 % Fixme: The |\relax| in the following is not fully ideal as it is not
2323 % swallowed by the |\ifx| and therefore remains in the macro's
2324 % expansion.
2325 % \begin{macrocode}
2326 \newcommand\kvt@ifnil[1]{%
2327 \ifx\@nil#1\relax
2328 \expandafter\@firstoftwo\else
2329 \expandafter\@secondoftwo\fi}
2330 % \end{macrocode}
2331 % \end{macro}
2332 % \end{macro}
2333 %
2334 % \begin{macro}{\kvt@alltables}
2335 % The |\kvt@alltables| is an \pkgname{etoolbox} list containing the names
2336 % of all tables declared by |\NewKeyValTable|.
2337 % \begin{macrocode}
2338 \newcommand\kvt@alltables{}
2339 % \end{macrocode}
2340 % \end{macro}
2341 %
2342 %
2343 % \subsection{Custom Layout Parameters}
2344 %
2345 % \begin{macro}{\kvt@parselayout}
2346 % The |\kvt@parselayout|\marg{layout-opts}\marg{tname} macro parses the
2347 % layout options, \meta{layout-opts}, for table type \meta{tname},
2348 % \begin{macrocode}
2349 \newcommand\kvt@parselayout[2]{%
2350 \def\kvt@@tname{#2}%
2351 % \end{macrocode}
2352 % Now parse the \meta{layout-opts}. The keys are defined such that their
2353 % handlers already do the parsing.
2354 % \begin{macrocode}
2355 \kvt@setkeys{#1}{Layout}%
2356 \undef\kvt@@tname}
2357 % \end{macrocode}
2358 % \end{macro}
2359 %
2360 % \begin{macro}{\kvt@parsecolgroups}
2361 % The |\kvt@parsecolgroups|\marg{tname}\marg{spec} macro parses the
2362 % specification, \meta{spec}, of column groups for table type
2363 % \meta{tname}.
2364 % \begin{macrocode}
2365 \newcommand\kvt@parsecolgroups[2]{%
2366 \begingroup
2367 % \end{macrocode}
2368 % |\kvt@@result| collects the parsing outcome code that shall escape the
2369 % group started above.
2370 % \begin{macrocode}
2371 \def\kvt@@result{}%
2372 \def\do##1{\kvt@parsecolgroup{#1}##1::\@undefined}%
2373 \kvt@dossvlist{#2}%
2374 \expandafter\endgroup\kvt@@result}
2375 % \end{macrocode}
2376 % The
2377 % |\kvt@parsecolgroup|\marg{tname}\marg{cgname}\marg{cgopts}\marg{empty}
2378 % macro parses a single column group, \meta{cgname} with options
2379 % \meta{cgopts}.
2380 % \begin{macrocode}
2381 \def\kvt@parsecolgroup#1#2:#3:#4\@undefined{%
2382 % \end{macrocode}
2383 % Catch syntax errors first.
2384 % \begin{macrocode}
2385 \kvt@checkcolspecempty{#4}{column group}{#2}%
2386 % \end{macrocode}
2387 % Next, check for a valid \meta{cgname}.
2388 % \begin{macrocode}
2389 \ifinlistcs{#2}{kvt@allcolumns@#1}{\kvt@error
2390 {Name `#2' cannot be used for a column group in table type `#1',
2391 as it is already used for a column}
2392 {Check the \string\NewKeyValTable{#1} for
2393 the names of known columns and check `#2' for a typo.}}{}%
2394 \ifinlistcs{#2}{kvt@grpcolkeys@#1}{\kvt@error
2395 {Name `#2' is used twice in table type `#1'}
2396 {Check the \string\NewKeyValTable{#1} for typos in the names of
2397 columns groups.}}{}%
2398 \def\kvt@@colgrp{#2}%
2399 \kvt@setkeys{#3}{ColGroup}%
2400 \kvt@checkcolgroupcs{kvt@colgrp@span@#1@#2}{#1}{#2}%
2401 % \end{macrocode}
2402 % Store the result of |\kvt@checkcolgroupcs| for later use.
2403 % \begin{macrocode}
2404 \csxdef{kvt@colgrp@first@#1@#2}{\kvt@@colgrp@first}%
2405 \csxdef{kvt@colgrp@count@#1@#2}{\kvt@@colgrp@n}%
2406 % \end{macrocode}
2407 % The following defines the |\Row| key for \meta{cgname}, as an
2408 % abbreviation for setting the value of the first displayed column of
2409 % \meta{cgname} (|\kvt@@colgrp@first| to a |\multicolumn| that spans the
2410 % "right" number of columns).
2411 % \begin{macrocode}
2412 \eappto\kvt@@result{%
2413 \noexpand\define@cmdkey[KeyValTable]{#1}{#2}{%
2414 % \end{macrocode}
2415 % The following |\ifdefvoid| check ensures that if \meta{cgname} is a
2416 % hidden column group (i.e., a column group of which all spanned columns
2417 % are hidden), then setting \meta{cgname} to a value has no effect.
2418 % \begin{macrocode}
2419 \ifdefvoid\kvt@@colgrp@first{}{%
2420 % \end{macrocode}
2421 % The "abbreviation" is implemented via |\setkeys|. The letter normally
2422 % employs the defined |\presetkeys|, but we disable this through
2423 % |\kvt@xkv@disablepreset| to avoid that column keys that are set before
2424 % a colgroup key are overwritten by their preset values.
2425 % \begin{macrocode}
2426 \noexpand\kvt@xkv@disablepreset[KeyValTable]{#1}{%
2427 \noexpand\setkeys[KeyValTable]{#1}{%
2428 % \end{macrocode}
2429 % Notice the "*" after |\kvt@@colgrp@first|,
2430 % which disables the first column's default formatting to replace it by
2431 % the formatting of \meta{cgname}.
2432 % \begin{macrocode}
2433 \expandonce\kvt@@colgrp@first=\noexpand\kvt@@@colgroup
2434 {\unexpanded{#2}}%
2435 {\expandonce\kvt@@colgrp@n}%
2436 {\csexpandonce{kvt@colgrp@align@#1@#2}}%
2437 {\unexpanded{##1}}}}%
2438 }%
2439 }}%
2440 \listcsadd{kvt@grpcolkeys@#1}{#2}}
2441 % \end{macrocode}
2442 % \end{macro}
2443 %
2444 % \begin{macro}{\kvt@checkcolspecempty}
2445 % The |\kvt@checkcolspecempty|\marg{empty}\marg{type}\marg{name}
2446 % macro checks the \meta{empty} parameter of a parsing macro for a
2447 % colon-separated key-value pair.
2448 % If \meta{empty} is empty, this corresponds to the valid case that only
2449 % the name of a column group was provided and no properties. If
2450 % \meta{empty} equals ":", then a name and properties were provided. In
2451 % all other cases, superfluous colons were found.
2452 % \begin{macrocode}
2453 \newcommand\kvt@checkcolspecempty[3]{%
2454 \ifstrempty{#1}{}{\ifstrequal{#1}{:}{}{\kvt@error
2455 {Too many ':' in definition of #2 '#3'}
2456 {Check whether there is an accidental ':' that should actually be
2457 a ',' or ';'.}}}}
2458 % \end{macrocode}
2459 % \end{macro}
2460 %
2461 % \begin{macro}{\kvt@checkcolgroup}
2462 % The |\kvt@checkcolgroup|\marg{span-psv}\marg{tname}\marg{cgname} macro
2463 % performs some checks on \meta{span-psv} as a specification of which
2464 % columns shall be spanned by a group column of name \meta{cgname}.
2465 % The checks are
2466 % \begin{itemize}
2467 % \item whether all column names are indeed columns of \meta{tname},
2468 % \item whether each column appears at most once in the column group,
2469 % and
2470 % \item whether the (displayed) columns from \meta{span-psv} appear
2471 % consecutively in \meta{tname}.
2472 % \end{itemize}
2473 % The macro returns the number of spanned (displayed!) columns in
2474 % |\kvt@@colgrp@n| and the name of the first column in
2475 % |\kvt@@colgrp@first|.
2476 %
2477 % Fixme: There can probably be some code sharing with
2478 % |\kvt@parseheadrow| and |\kvt@parsecolgroup|.
2479 % \begin{macrocode}
2480 \newcommand\kvt@checkcolgroup[3]{%
2481 % \end{macrocode}
2482 % First, check individual colums in \meta{span-psv} and transfer them
2483 % into a "map", |kvt@@incolgrp@| that simply records which column names
2484 % occur in \meta{span-psv}.
2485 % \begin{macrocode}
2486 \def\kvt@@psvdo##1{%
2487 \ifinlistcs{##1}{kvt@allcolumns@#2}{}{\kvt@error
2488 {Column `##1' referenced in column group `#3' not known
2489 in table type `#2'}
2490 {Check the \string\NewKeyValTable{#2} for
2491 the names of known columns and check `##1' for a typo.}}%
2492 \ifcsvoid{kvt@@incolgrp@##1}{}{\kvt@error
2493 {Column `##1' used more than once in column group `#3' of table
2494 type `#2'}
2495 {Check `##1' for a typo.}}%
2496 \csdef{kvt@@incolgrp@##1}{#2}%
2497 }\kvt@forpsvlist{\kvt@@psvdo}{#1}%
2498 % \end{macrocode}
2499 % The following two macros are the "return values".
2500 % \begin{macrocode}
2501 \def\kvt@@colgrp@n{0}%
2502 \let\kvt@@colgrp@first\relax
2503 % \end{macrocode}
2504 % Second, iterate over the displayed columns of \meta{tname} to check
2505 % whether the columns in \meta{span-psv} are consecutive.
2506 % For this, use |\kvt@@status| to track
2507 % whether no column of \meta{span-psv} has yet been visited (value 0,
2508 % the initial value),
2509 % whether the current column is part of \meta{span-psv} (value 1), and
2510 % whether columns of \meta{span-psv} have been visited but the current
2511 % column is not part of \meta{span-psv} (value 2).
2512 % \begin{macrocode}
2513 \def\kvt@@status{0}%
2514 % \end{macrocode}
2515 % |\kvt@@coldo|\marg{column} is applied to each displayed column, in
2516 % order.
2517 % \begin{macrocode}
2518 \def\kvt@@coldo##1{%
2519 \ifcsvoid{kvt@@incolgrp@##1}
2520 % \end{macrocode}
2521 % If \meta{column} is \emph{not} in \meta{span-psv}, then change
2522 % |\kvt@@status| from 1 to 2, but do not change it when it is 0 or 2.
2523 % \begin{macrocode}
2524 {\expandafter\ifcase\kvt@@status \or
2525 \def\kvt@@status{2}\fi}%
2526 % \end{macrocode}
2527 % If \meta{column} is in \meta{span-psv}, then change |\kvt@@status|
2528 % from 0 to 1 and record \meta{column} as |\kvt@@colgrp@first|; if
2529 % |\kvt@@status| is previously 2, then the columns in \meta{span-psv}
2530 % would not be consecutively displayed and, hence, an error is raised.
2531 % \begin{macrocode}
2532 {\expandafter\ifcase\kvt@@status
2533 \def\kvt@@status{1}\def\kvt@@colgrp@first{##1}%
2534 \or\or
2535 \kvt@error{Column group `\kvt@@colgrp' must consist of only
2536 consecutive columns, but it is not}%
2537 {Compare `\string\kvt@@curgrp' to the column ordering as
2538 specified in `\string\NewKeyValTable{#1}'}%
2539 \fi
2540 \edef\kvt@@colgrp@n{\the\numexpr\kvt@@colgrp@n+1\relax}%
2541 % \end{macrocode}
2542 % Since this macro is not encapsulated in a group (in order to return
2543 % |\kvt@@colgrp@n| and |\kvt@@colgrp@first|), we finally prevent the
2544 % local \cs{kvt@@incolgrp@\meta{column}} from leaking outside this
2545 % macro.
2546 % \begin{macrocode}
2547 \csundef{kvt@@incolgrp@##1}}%
2548 }\forlistcsloop{\kvt@@coldo}{kvt@displaycols@#2}}
2549 % \end{macrocode}
2550 % \end{macro}
2551 %
2552 % \begin{macro}{\kvt@checkcolgroupcs}
2553 % The |\kvt@checkcolgroupcs|\marg{span-psv-cs}\marg{tname}\marg{cgname}
2554 % macro is the same as |\kvt@checkcolgroup| except that it takes a
2555 % control sequence name as its first argument rather than a
2556 % plus-separated list directly.
2557 % \begin{macrocode}
2558 \newcommand\kvt@checkcolgroupcs[3]{%
2559 \expandafter\expandafter\expandafter
2560 \kvt@checkcolgroup
2561 \expandafter\expandafter\expandafter{\csname #1\endcsname}{#2}{#3}}
2562 % \end{macrocode}
2563 % \end{macro}
2564 %
2565 % \begin{macro}{\kvt@parseheadrows}
2566 % The |\kvt@parseheadrows|\marg{tname}\marg{headers}
2567 % macro parses the values of the |headers| key in the \meta{layout}
2568 % argument of |\NewKeyValTable|. The values are |\\|-separated lists of
2569 % header rows, and the rows are semicolon-separated lists of header
2570 % cells. Each header cell can span zero, one, or more visible columns.
2571 % If the |headers| key is not set (or empty), then the default header
2572 % (based on the column specification alone) is used, as set by
2573 % |\kvt@NewKeyValTable|.
2574 % \begin{macrocode}
2575 \newcommand\kvt@parseheadrows[2]{%
2576 \ifstrempty{#2}{}{\kvt@parseheadrows@i{#2}{#1}}}
2577 \newcommand\kvt@parseheadrows@i[2]{%
2578 \csdef{kvt@@custheadrows@#2}{}%
2579 \csdef{kvt@headrowcount@#2}{0}%
2580 \begingroup
2581 \def\kvt@@parseheadrows{}%
2582 % \end{macrocode}
2583 % Now loop over \meta{headers} to split \meta{headers} by |\\|.
2584 % Append each item, which specifies a single header row, to
2585 % |\kvt@@parseheadrows| for subsequent parsing by |\kvt@parseheadrow|.
2586 % If an item equals the special sequence "|::|", then the original
2587 % header for the columns is added as header row.
2588 % \begin{macrocode}
2589 \def\do##1{%
2590 \ifstrequal{##1}{::}
2591 {\appto\kvt@@parseheadrows{%
2592 \cseappto{kvt@@custheadrows@#2}{%
2593 \csexpandonce{kvt@headings@#2}}}}
2594 {\appto\kvt@@parseheadrows{\kvt@parseheadrow{#2}{##1}}}%
2595 % \end{macrocode}
2596 % Increment the header row counter for each |\\|-separated item of
2597 % \meta{headers}.
2598 % \begin{macrocode}
2599 \appto\kvt@@parseheadrows{\csedef{kvt@headrowcount@#2}{%
2600 \the\numexpr\csuse{kvt@headrowcount@#2}+1\relax}}%
2601 }\kvt@dobrklist{#1}%
2602 % \end{macrocode}
2603 % Finally, escape the inner group and overwrite the headings
2604 % with the result of the parsing.
2605 % \begin{macrocode}
2606 \expandafter\endgroup\kvt@@parseheadrows
2607 \csletcs{kvt@headings@#2}{kvt@@custheadrows@#2}}
2608 % \end{macrocode}
2609 % \end{macro}
2610 %
2611 % \begin{macro}{\kvt@parseheadrow}
2612 % The |\kvt@parseheadrow|\marg{tname}\marg{colspec} macro parses a
2613 % single header row and appends the resulting table code to
2614 % \cs{kvt@@custheadrows@\meta{tname}}.
2615 % \begin{macrocode}
2616 \newcommand\kvt@parseheadrow[2]{%
2617 \begingroup
2618 % \end{macrocode}
2619 % First parse \meta{colspec}, populating the
2620 % \cs{kvt@@hdcellof@\meta{colname}} macros that associate each column
2621 % with the header cell to which the column belongs (in this row).
2622 % \begin{macrocode}
2623 \def\do##1{\kvt@parsehdcolspec{#1}##1::\@undefined}%
2624 \kvt@dossvlist{#2}%
2625 % \end{macrocode}
2626 % Initialize variables for the subsequent loop.
2627 % The |\kvt@@tmpgrphd| macro collects the code for the cells of the
2628 % current header row.
2629 % The |\kvt@@tmpunderline| macro collects the rules (|\cmidrule|-like)
2630 % from header cells, in an \pkgname{etoolbox} list.
2631 % The |\kvt@@span| counter specifies how many columns the current cell
2632 % shall span.
2633 % Finally, |\kvt@@curhd| and |\kvt@@lasthd| hold the name of the
2634 % header cell in which the current column and, respectively, previous
2635 % column are in. Each of the two macros is undefined if there is no
2636 % such header cell.
2637 % \begin{macrocode}
2638 \let\kvt@@tmpgrphd\@empty
2639 \let\kvt@@tmpunderlines\@empty
2640 \letcs\kvt@@tmpncols{kvt@ndisplaycols@#1}%
2641 \kvt@@span\z@ \kvt@@coln\@ne
2642 \undef\kvt@@curhd \undef\kvt@@lasthd
2643 \kvt@def@atseconduse\kvt@@switchcol{\appto\kvt@@tmpgrphd{&}}%
2644 % \end{macrocode}
2645 % Next, loop over all displayed columns, stored in
2646 % \cs{kvt@displaycols@\meta{tname}}. The following |\do|\marg{colname}
2647 % macro collects (spanned) columns as specified in \meta{colspec}, in the
2648 % ordering in which the table's columns are displayed. The spanned
2649 % columns are stored in |\kvt@@tmpgrphd|.
2650 % \begin{macrocode}
2651 \def\do##1{\letcs\kvt@@curhd{kvt@@hdcellof@##1}%
2652 \ifdefequal\kvt@@curhd\kvt@@lasthd
2653 % \end{macrocode}
2654 % If the header cell has not changed, simply increase the spanning
2655 % counter.
2656 % \begin{macrocode}
2657 {\advance\kvt@@span\@ne}%
2658 % \end{macrocode}
2659 % Otherwise, i.e., if the header cell has changed, then conclude the
2660 % previous column (if there was one) and reset the span to 1 (to count
2661 % for the column in |\kvt@@curhd|) and set |\kvt@@lasthd| to the
2662 % current one.
2663 % \begin{macrocode}
2664 {\ifnum\kvt@@span>\z@ \expandafter\kvt@concludehdcolumn\fi
2665 \ifdefvoid\kvt@@curhd{}{\ifcsdef{kvt@@hdcelldone@\kvt@@curhd}{%
2666 \kvt@error{Header cell `\kvt@@curhd' must consist of only
2667 consecutive columns, but it is not}%
2668 {Compare `\string\kvt@@curhd' to the column ordering as
2669 specified in `\string\NewKeyValTable{#1}'}}{}}%
2670 \advance\kvt@@coln\kvt@@span\relax
2671 \kvt@@span\@ne \let\kvt@@lasthd\kvt@@curhd}%
2672 }\dolistcsloop{kvt@displaycols@#1}%
2673 \kvt@concludehdcolumn
2674 % \end{macrocode}
2675 % Finally, conclude the whole header row and append the row to the
2676 % overall list of rows, stored in \cs{kvt@@custheadrows@\meta{tname}},
2677 % while ending the current \hologo{TeX} group.
2678 % \begin{macrocode}
2679 \appto\kvt@@tmpgrphd{\tabularnewline}%
2680 \ifdefempty\kvt@@tmpunderlines{}{%
2681 \eappto\kvt@@tmpgrphd{%
2682 \noexpand\kvtRule@cmid{\noexpand\cmidrulewidth}
2683 {\expandonce\kvt@@tmpunderlines}
2684 {\expandonce\cmdkvt@Table@headbg}
2685 {\expandonce\cmdkvt@Table@headbg}}}%
2686 \edef\do{\noexpand\csappto{kvt@@custheadrows@#1}{%
2687 \unexpanded{\noexpand\kvt@rowcolorornot{\cmdkvt@Table@headbg}}%
2688 \noexpand\unexpanded{\expandonce{\kvt@@tmpgrphd}}}}%
2689 \expandafter\endgroup\do}
2690 % \end{macrocode}
2691 % \end{macro}
2692 %
2693 % \begin{macro}{\kvt@rowcolorornot}
2694 % The |\kvt@rowcolorornot|\marg{color} expands to
2695 % |\rowcolor|\marg{color} if \meta{color} is nonempty and does have no
2696 % effect if \meta{color} is empty.
2697 % \begin{macro}{\kvt@rowcolorcmdornot}
2698 % The |\kvt@rowcolorcmdornot|\marg{cmd} expands to
2699 % |\rowcolor|\marg{color}, where \meta{color} is the (one-time)
2700 % expansion of \meta{cmd}, if \meta{cmd} is a defined macro whose
2701 % expansion is nonempty; its expansion is empty otherwise.
2702 % \begin{macrocode}
2703 \newcommand\kvt@rowcolorornot[1]{\ifstrempty{#1}{}{\rowcolor{#1}}}
2704 \newcommand\kvt@rowcolorcmdornot[1]{\ifdefvoid{#1}{}{%
2705 \expandafter\rowcolor\expandafter{#1}}}
2706 % \end{macrocode}
2707 % \end{macro}
2708 % \end{macro}
2709 %
2710 % \begin{macro}{\kvt@@bodyrow}
2711 % The counter |\kvt@@bodyrow| is used internally in |KeyValTable|
2712 % environments for keeping track of rows for the background-coloring.
2713 % The difference between this counter and |\kvtRow| is that the former
2714 % also counts |uncounted| rows and is unaffected by the |resume| option.
2715 % The counter only counts rows produced by |\Row| and its corresponding
2716 % collecting counterparts. Header rows as well as manually inserted
2717 % rows, including those produced by macros like |\midrule| in a
2718 % |longtable| environment, are not counted (as opposed by the internal
2719 % counter of |\rowcolors|).
2720 % \begin{macrocode}
2721 \newcount\kvt@@bodyrow
2722 % \end{macrocode}
2723 % \end{macro}
2724 %
2725 % \begin{macro}{\kvt@@span}
2726 % The counter |\kvt@@span| is used temporarily in macros for counting
2727 % how many columns are spanned by column groups.
2728 % The counter |\kvt@@coln| is used temporarily in macros for counting
2729 % column indexes.
2730 % \begin{macrocode}
2731 \newcount\kvt@@span
2732 \newcount\kvt@@coln
2733 % \end{macrocode}
2734 % \end{macro}
2735 %
2736 % \begin{macro}{\kvt@concludehdcolumn}
2737 % The |\kvt@concludehdcolumn| macro appends a cell, potentially spanning
2738 % multiple columns, to the row under construction (which is in
2739 % |\kvt@@tmpgrphd|).
2740 % \begin{macrocode}
2741 \newcommand\kvt@concludehdcolumn{%
2742 \kvt@@switchcol
2743 \ifdefvoid\kvt@@lasthd{}{%
2744 \eappto\kvt@@tmpgrphd{\noexpand\multicolumn
2745 {\the\kvt@@span}
2746 {\csexpandonce{kvt@@hdcell@align@\kvt@@lasthd}}
2747 {\noexpand\cmdkvt@Table@headformat
2748 {\csexpandonce{kvt@@hdcell@head@\kvt@@lasthd}}}}%
2749 % \end{macrocode}
2750 % The following adds a pair of trim and spanned columns to
2751 % |\kvt@@tmpunderlines| for later drawing all the horizontal rules that
2752 % underline column groups.
2753 % A rule is trimmed left if it's not the first column and
2754 % a rule is trimmed right if it's not the last column.
2755 % \begin{macrocode}
2756 \ifcsstring{kvt@@hdcell@underline@\kvt@@lasthd}{true}
2757 {\listeadd\kvt@@tmpunderlines{%
2758 {\ifnumgreater{\kvt@@coln}{1}{l}{}%
2759 \ifnumless{\kvt@@coln+\kvt@@span-1}{\kvt@@tmpncols}{r}{}}%
2760 {\the\kvt@@coln-\the\numexpr\kvt@@coln+\kvt@@span-1\relax}}}{}%
2761 % \end{macrocode}
2762 % Mark the header cell as already used and concluded, such that another
2763 % use of the same header cell can be detected and raise an error.
2764 % \begin{macrocode}
2765 \cslet{kvt@@hdcelldone@\kvt@@lasthd}{\@ne}}}
2766 % \end{macrocode}
2767 % \end{macro}
2768 %
2769 % \begin{macro}{\kvt@parsehdcolspec}
2770 % The |\kvt@parsehdcolspec|\marg{tname}\meta{cname}|:|\meta{config}|:|\meta{empty}|\@undefined|
2771 % macro parses a single header cell (resp. column group), \meta{cname}.
2772 % For a header cell, \meta{cname} can consist of multiple,
2773 % "+"-separated column names.
2774 % \begin{macrocode}
2775 \def\kvt@parsehdcolspec#1#2:#3:#4\@undefined{%
2776 % \end{macrocode}
2777 % Catch syntax errors first.
2778 % \begin{macrocode}
2779 \kvt@checkcolspecempty{#4}{header cell}{#2}%
2780 % \end{macrocode}
2781 % Next, link the individual columns of a header cell to the cell.
2782 % In this, ensure that no column is contained in more than one header
2783 % cell.
2784 % \begin{macrocode}
2785 \def\kvt@@colreg##1{%
2786 \ifinlistcs{##1}{kvt@allcolumns@#1}{}
2787 {\kvt@error{Column `##1', referenced in header cell `#2', not
2788 known in table type `#1'}{Check the \string\NewKeyValTable{#1}
2789 for the names of known columns and check `##1' for a typo.}}%
2790 \ifcsmacro{kvt@@hdcellof@##1}
2791 {\kvt@error{Column `##1' used in more than one header cell}
2792 {Check the fourth, optional argument of \string\NewKeyValTable
2793 and eliminate multiple occurrences of column `##1'.}}
2794 {\csdef{kvt@@hdcellof@##1}{#2}}%
2795 }\kvt@forpsvlist{\kvt@@colreg}{#2}%
2796 % \end{macrocode}
2797 % Now parse the \meta{config} of the header cell.
2798 % \begin{macrocode}
2799 \def\kvt@@hdcell{#2}%
2800 \kvt@setkeys{#3}{HeadCell}}
2801 % \end{macrocode}
2802 % \end{macro}
2803 %
2804 %
2805 % \subsection{Row Numbering and Labeling}
2806 %
2807 % The following counters simplify row numbering in key-value tables.
2808 % One can use a table-local counter (|kvtRow|), a table-type local
2809 % counter (|kvtTypeRow|), and a global counter (|kvtTotalRow|).
2810 %
2811 % \begin{macro}{kvtRow}
2812 % The |kvtRow| counter can be used by cells to get the current row
2813 % number. This row number (in contrast to |taburow|) does not count
2814 % table headers. That is, |kvtRow| provides the current \emph{content}
2815 % row number, even in tables that are spread over multiple pages.
2816 % \begin{macrocode}
2817 \newcounter{kvtRow}
2818 % \end{macrocode}
2819 % \end{macro}
2820 % \begin{macro}{kvtTypeRow}
2821 % The |kvtTypeRow| counter can be used by cells to get the current row
2822 % number, including all previous rows of tables of the same type. This
2823 % counter works together with the \cs{kvt@rowcount@\meta{tname}} macro,
2824 % which keeps track of the individual row counts of the \meta{tname}
2825 % type.
2826 % \begin{macrocode}
2827 \newcounter{kvtTypeRow}
2828 % \end{macrocode}
2829 % \end{macro}
2830 % \begin{macro}{kvtTotalRow}
2831 % The |kvtTotalRow| counter can be used by cells to get the current row
2832 % number, including all previous |KeyValTable| tables.
2833 % \begin{macrocode}
2834 \newcounter{kvtTotalRow}
2835 \setcounter{kvtTotalRow}{0}
2836 % \end{macrocode}
2837 % \end{macro}
2838 %
2839 % \begin{macro}{\kvtLabel}
2840 % The |\kvtLabel|\oarg{labelopts}\marg{counter}\marg{label} macro sets
2841 % a label, named \meta{label}, for the current value of the \LaTeX{}
2842 % counter named \meta{counter}.
2843 % \changes{v0.2}{2016/05/22}{Added macro for row labeling}
2844 % \changes{v0.3}{2016/06/09}{Robustified for use with, e.g., \pkgname{cleveref}}
2845 % \begin{macrocode}
2846 \newcommand\kvtLabel[3][]{%
2847 % \end{macrocode}
2848 % The following imitates a |\refstepcounter| in the sense of setting the
2849 % current label, but it does not touch the \meta{counter} (in case
2850 % someone added some custom hooks to them).
2851 % \begin{macrocode}
2852 \setcounter{kvt@LabelCtr}{\value{#2}}%
2853 \addtocounter{kvt@LabelCtr}{-1}%
2854 \refstepcounter{kvt@LabelCtr}%
2855 % \end{macrocode}
2856 % Next, define the \meta{label} (if provided) and show the value of
2857 % \meta{counter}.
2858 % \begin{macrocode}
2859 \ifstrempty{#3}{}{%
2860 \ifstrempty{#1}{\label{#3}}{\label[#1]{#3}}}%
2861 \csuse{the#2}}
2862 % \end{macrocode}
2863 % \end{macro}
2864 % \begin{macro}{kvt@LabelCtr}
2865 % The |kvt@LabelCtr| counter is an auxiliary counter for setting labels,
2866 % used by |\kvtLabel|.
2867 % \begin{macrocode}
2868 \newcounter{kvt@LabelCtr}
2869 % \end{macrocode}
2870 % \end{macro}
2871 %
2872 %
2873 % \subsection{Rules}
2874 %
2875 % This section exists because drawing rules with proper spacing and
2876 % proper consideration of row background colors requires some effort.
2877 % \changes{v2.3}{2020/08/09}{Made rules aware of row background colors}
2878 %
2879 % \begin{macro}{\kvt@RuleTop}
2880 % The |\kvt@RuleTop| macro produces a |\kvtRuleTop| rule that fits with
2881 % the header background color or, if no headers are shown, the
2882 % alternating row background colors.
2883 % \begin{macrocode}
2884 \newcommand\kvt@RuleTop{\noalign{%
2885 \edef\kvt@@do{\noexpand\kvtRuleTop{\ifbool{kvt@Table@showhead}
2886 {\expandonce\cmdkvt@Table@headbg}{\expandonce\kvt@@bgcolor@odd}}}%
2887 \expandafter}\kvt@@do}
2888 % \end{macrocode}
2889 % \end{macro}
2890 %
2891 % \begin{macro}{\kvt@RuleBottom}
2892 % The |\kvt@RuleBottom| macro produces a |\kvtRuleBottom| rule that fits
2893 % with the alternating row background colors.
2894 % \begin{macrocode}
2895 \newcommand\kvt@RuleBottom{\noalign{%
2896 \edef\kvt@@do{\noexpand\kvtRuleBottom{\ifnumodd{\the\kvt@@bodyrow}
2897 {\expandonce\kvt@@bgcolor@odd}{\expandonce\kvt@@bgcolor@even}}}%
2898 \expandafter}\kvt@@do}
2899 % \end{macrocode}
2900 % \end{macro}
2901 %
2902 % \begin{macro}{\kvt@RuleMid}
2903 % The |\kvt@RuleMid|\oarg{wd} macro produces a |\kvtRuleMid| rule that
2904 % fits with the alternating row background colors.
2905 % \begin{macrocode}
2906 \newcommand\kvt@RuleMid{\noalign{\ifnum0=`}\fi
2907 \@ifnextchar[{\kvt@RuleMid@i}{\kvt@RuleMid@i[\lightrulewidth]}}
2908 \long\def\kvt@RuleMid@i[#1]{%
2909 \edef\kvt@@do{\unexpanded{\ifnum0=`{\fi}\kvtRuleMid[{#1}]}%
2910 \ifnumodd{\the\kvt@@bodyrow}
2911 {{\expandonce\kvt@@bgcolor@odd}{\expandonce\kvt@@bgcolor@even}}
2912 {{\expandonce\kvt@@bgcolor@even}{\expandonce\kvt@@bgcolor@odd}}}%
2913 \kvt@@do}
2914 % \end{macrocode}
2915 % \end{macro}
2916 %
2917 % \begin{macro}{\kvt@RuleSubHead}
2918 % The |\kvt@RuleSubHead| macro is very similar to |\kvt@RuleMid|.
2919 % The latter is to be placed between body rows of a table.
2920 % The former is to be placed between the header row(s) and the body
2921 % rows.
2922 % \begin{macrocode}
2923 \newcommand\kvt@RuleSubHead{\noalign{%
2924 \edef\kvt@@do{\noexpand\kvtRuleMid
2925 {\expandonce\cmdkvt@Table@headbg}{\expandonce\kvt@@bgcolor@odd}}%
2926 \expandafter}\kvt@@do}
2927 % \end{macrocode}
2928 % \end{macro}
2929 %
2930 % \begin{macro}{\kvt@RuleCMid}
2931 % The |\kvt@RuleCMid|\marg{tname}\oarg{wd}\marg{cglist} macro draws a
2932 % set of horizontal rules for a given comma-separated list of names of
2933 % columns and/or column groups, \meta{cglist}.
2934 % \begin{macrocode}
2935 \newcommand\kvt@RuleCMid[1]{\noalign{\ifnum0=`}\fi
2936 \@ifnextchar[{\kvt@RuleCMid@i{#1}}
2937 {\kvt@RuleCMid@i{#1}[\cmidrulewidth]}}
2938 \long\def\kvt@RuleCMid@i#1[#2]#3{%
2939 \let\kvt@@rules\@empty
2940 \def\kvt@@do##1{%
2941 \ifcsdef{kvt@colgrp@first@#1@##1}
2942 {\kvt@RuleCMid@cg{#1}{##1}}
2943 {\kvt@RuleCMid@cc{#1}{##1}{1}}}%
2944 \forcsvlist\kvt@@do{#3}%
2945 % \end{macrocode}
2946 % The above collected the second argument of |\kvtRule@cmid| in
2947 % |\kvt@@rules|. The remaining lines now add the remaining arguments.
2948 % \begin{macrocode}
2949 \edef\kvt@@rules{\unexpanded{\ifnum0=`{\fi}\kvtRule@cmid}%
2950 {\unexpanded{#2}}%
2951 {\expandonce\kvt@@rules}
2952 \ifnumodd{\the\kvt@@bodyrow}
2953 {{\expandonce\kvt@@bgcolor@odd}{\expandonce\kvt@@bgcolor@even}}
2954 {{\expandonce\kvt@@bgcolor@even}{\expandonce\kvt@@bgcolor@odd}}}%
2955 \kvt@@rules}
2956 % \end{macrocode}
2957 % The |\kvt@RuleCMid@cg|\marg{tname}\marg{colgrp} macro
2958 % takes the first column of \meta{colgrp} and column count of this
2959 % column group and passes them on to |\kvt@RuleCMid@c|.
2960 % \begin{macrocode}
2961 \newcommand\kvt@RuleCMid@cg[2]{\bgroup%
2962 \edef\kvt@@do{\egroup
2963 \unexpanded{\kvt@RuleCMid@c{#1}}%
2964 {\csuse{kvt@colgrp@first@#1@#2}}
2965 {\csuse{kvt@colgrp@count@#1@#2}}}%
2966 \kvt@@do}
2967 % \end{macrocode}
2968 % The |\kvt@RuleCMid@c|\marg{tname}\marg{cname}\marg{count}
2969 % macro determines the index $a$ of column \meta{cname} and adds a rule
2970 % from this column to $a+\meta{count}-1$.
2971 % The |\kvt@RuleCMid@cc| macro takes the same arguments but additionally
2972 % checks whether \meta{cname} is a valid column name.
2973 % \begin{macrocode}
2974 \newcommand\kvt@RuleCMid@cc[3]{%
2975 \ifinlistcs{#2}{kvt@allcolumns@#1}
2976 {\ifinlistcs{#2}{kvt@displaycols@#1}
2977 {\kvt@RuleCMid@c{#1}{#2}{#3}}
2978 % \end{macrocode}
2979 % Rules below known but hidden columns are silently skipped by the below
2980 % line.
2981 % \begin{macrocode}
2982 {}}
2983 {\kvt@error
2984 {Column or column group `#2' for `\string\CMidRule'
2985 not known in table type `#1'}
2986 {Check the \string\NewKeyValTable{#1} for
2987 the names of known columns and check `#2' for a typo.}}}
2988 \newcommand\kvt@RuleCMid@c[3]{%
2989 % \end{macrocode}
2990 % Find index of column \meta{cname} and store it in |\@tempcnta|.
2991 % Fixme: Column indexes could also be precomputed.
2992 % \begin{macrocode}
2993 \@tempcnta\z@
2994 \def\do##1{\advance\@tempcnta\@ne
2995 \ifstrequal{#2}{##1}{\listbreak}{}}%
2996 \dolistcsloop{kvt@displaycols@#1}%
2997 % \end{macrocode}
2998 % Now add new rule pair (trim and columns) to the list stored in
2999 % |\kvt@@rules|.
3000 % \begin{macrocode}
3001 \listeadd\kvt@@rules{%
3002 {\ifnumgreater{\@tempcnta}{1}{l}{}%
3003 \ifnumless{\@tempcnta+#3-1}{\csuse{kvt@ndisplaycols@#1}}{r}{}}%
3004 {\the\@tempcnta-\the\numexpr\@tempcnta+#3-1\relax}}}
3005 % \end{macrocode}
3006 % \end{macro}
3007 %
3008 % \paragraph{Candidate for separate package.}
3009 % The following macros are independent of the remaining \thispackage
3010 % macros and could be factored out into their own small macro package
3011 % (|kvtrule|?) as a solution to reoccurring questions about row colors
3012 % with \pkgname{booktabs} (e.g.,
3013 % \url{https://tex.stackexchange.com/questions/177202/booktabs-and-row-color}).
3014 %
3015 % The macros below act as alternatives to rule macros of the
3016 % \pkgname{booktabs} package.
3017 % The \pkgname{booktabs} rule macros draw horizontal rules with some
3018 % spacing above and below the rule. Their spacing does not take into
3019 % account row colors.
3020 % The replacement macro allow specifying the row color above
3021 % (\meta{c-above}) and below (\meta{c-below}) of rule.
3022 %
3023 % \begin{macro}{\kvtRuleTop}
3024 % The |\kvtRuleTop|\oarg{wd}\marg{c-below} macro acts as a replacement
3025 % macro for \pkgname{booktabs}'s |\toprule|\oarg{wd} macro.
3026 % \begin{macrocode}
3027 \newcommand\kvtRuleTop{\noalign{\ifnum0=`}\fi
3028 \@ifnextchar[{\kvtRuleTop@i}{\kvtRuleTop@i[\heavyrulewidth]}}
3029 \long\def\kvtRuleTop@i[#1]#2{\ifnum0=`{\fi}%
3030 \specialrule{#1}{\abovetopsep}{0pt}%
3031 \kvtRule@ColorRule{#2}{2\belowrulesep}{0pt}{-\belowrulesep}}
3032 % \end{macrocode}
3033 % \end{macro}
3034 %
3035 % \begin{macro}{\kvtRuleBottom}
3036 % The |\kvtRuleBottom|\oarg{wd}\marg{c-above} macro acts as a
3037 % replacement for \pkgname{booktabs}'s |\bottomrule|\oarg{wd} macro.
3038 % \begin{macrocode}
3039 \newcommand\kvtRuleBottom{\noalign{\ifnum0=`}\fi
3040 \@ifnextchar[{\kvtRuleBottom@i}{\kvtRuleBottom@i[\heavyrulewidth]}}
3041 \long\def\kvtRuleBottom@i[#1]#2{\ifnum0=`{\fi}%
3042 \kvtRule@ColorRule{#2}{\aboverulesep}{0pt}{0pt}%
3043 \specialrule{#1}{0pt}{\belowbottomsep}}
3044 % \end{macrocode}
3045 % \end{macro}
3046 %
3047 % \begin{macro}{\kvtRuleMid}
3048 % The |\kvtRuleMid|\oarg{wd}\marg{c-above}\marg{c-below} macro acts as a
3049 % replacement for \pkgname{booktabs}'s |\midrule|\oarg{wd} macro.
3050 % \begin{macrocode}
3051 \newcommand\kvtRuleMid{\noalign{\ifnum0=`}\fi
3052 \@ifnextchar[{\kvtRuleMid@i}{\kvtRuleMid@i[\lightrulewidth]}}
3053 \long\def\kvtRuleMid@i[#1]#2#3{\ifnum0=`{\fi}%
3054 \kvtRule@ColorRule{#2}{\aboverulesep}{0pt}{0pt}%
3055 \specialrule{#1}{0pt}{0pt}%
3056 % \end{macrocode}
3057 % For some reason, without the doubling of |\belowrulesep| below,
3058 % there is a white space below the |\specialrule|. (Fixme?)
3059 % \begin{macrocode}
3060 \kvtRule@ColorRule{#3}{2\belowrulesep}{0pt}{-\belowrulesep}}
3061 % \end{macrocode}
3062 % \end{macro}
3063 %
3064 % \begin{macro}{\kvtRuleCMid}
3065 % The
3066 % |\kvtRuleCMid|\oarg{wd}|(|\meta{trim}|)|\marg{a-b}\marg{c-above}\marg{c-below}
3067 % macro acts as a replacement for \pkgname{booktabs}'s
3068 % |\cmidrule|\oarg{wd}|(|\meta{trim}|)|\marg{a-b} macro.
3069 % \begin{macrocode}
3070 \newcommand\kvtRuleCMid{\noalign{\ifnum0=`}\fi
3071 \@ifnextchar[{\kvtRuleCMid@i}{\kvtRuleCMid@i[\cmidrulewidth]}}
3072 \long\def\kvtRuleCMid@i[#1]{%
3073 \@ifnextchar({\kvtRuleCMid@ii{#1}}{\kvtRuleCMid@ii{#1}()}}
3074 \long\def\kvtRuleCMid@ii#1(#2)#3{\ifnum0=`{\fi}%
3075 \kvtRule@cmid{#1}{{#2}{#3}}}
3076 % \end{macrocode}
3077 % The
3078 % |\kvtRule@cmid|\marg{wd}\marg{r-list}\marg{c-above}\marg{c-below}
3079 % macro does the actual work.
3080 % The \meta{r-list} parameter is a \pkgname{etoolbox} list of pairs
3081 % "\marg{trim}\marg{a-b}".
3082 % \begin{macrocode}
3083 \newcommand\kvtRule@cmid[4]{%
3084 % \end{macrocode}
3085 % The "\meta{wd}/2" (i.e., |#1/2|) occurring twice below "splits" the
3086 % later rule vertically into the upper half (on \meta{c-above}
3087 % background) and the lower half (on \meta{c-below} background).
3088 % \begin{macrocode}
3089 \kvtRule@ColorRule{#3}
3090 {\the\dimexpr\aboverulesep+#1/2\relax}
3091 {0pt}
3092 {\the\dimexpr-#1/2\relax}%
3093 % \end{macrocode}
3094 % Draw the "below" color already here such that the rule can be drawn in
3095 % the middle on top of the "above" and "below" color.
3096 % \begin{macrocode}
3097 \kvtRule@ColorRule{#4}
3098 {\the\dimexpr\belowrulesep+#1/2\relax}{0pt}
3099 {\the\dimexpr-\belowrulesep-#1\relax}%
3100 % \end{macrocode}
3101 % Now collect the rules to be drawn in a single macro |\kvt@@rules|.
3102 % \begin{macrocode}
3103 \noalign{%
3104 \let\kvt@@rules\@empty%
3105 \def\kvt@@do##1{\appto\kvt@@rules{\kvtRule@cmid@i{#1}##1}}%
3106 \forlistloop\kvt@@do{#2}%
3107 \expandafter}%
3108 \kvt@@rules
3109 % \end{macrocode}
3110 % In the spacing below, cancel out the negative spacing from
3111 % |\kvtRule@cmid@i|.
3112 % \begin{macrocode}
3113 \noalign{\vskip\dimexpr\belowrulesep+#1\relax}}
3114 % \end{macrocode}
3115 %
3116 % The |\kvtRule@cmid@i|\marg{wd}\marg{trim}\marg{a-b} macro produces a
3117 % single |\cmidrule|-like rule from a set of such rules. The arguments
3118 % are the same as for |\cmidrule|.
3119 % \begin{macrocode}
3120 \newcommand\kvtRule@cmid@i[3]{%
3121 % \end{macrocode}
3122 % The following three lines locally inject zero |\aboverulesep| into
3123 % |\cmidrule|. Due to grouping within |\@cmidrule|, this is not possible
3124 % for |\belowrulesep|; hence, we have to fix |\belowrulesep| in the
3125 % |\vskip| later in this macro.
3126 % Note that the |\noalign| started below is ended within |\@cmidrule|.
3127 % \begin{macrocode}
3128 \noalign{\ifnum0=`}\fi
3129 \aboverulesep=0pt\relax
3130 \@cmidrule[#1](#2){#3}%
3131 % \end{macrocode}
3132 % The imitates the code from |\xcmidrule| for when further |\cmidrule|s
3133 % follow. It additionally cancels out the superfluous |\belowrulesep| as
3134 % described before.
3135 % \begin{macrocode}
3136 \noalign{%
3137 \vskip-\dimexpr #1+\belowrulesep\relax
3138 \global\@lastruleclass\@ne}}
3139 % \end{macrocode}
3140 % \end{macro}
3141 %
3142 % \begin{macro}{\kvtRulesCMid}
3143 % The |\kvtRulesCMid|\oarg{width}\marg{r-list}\marg{color1}\marg{color2}
3144 % macro is the user interface for |\kvtRule@cmid| with multiple rules.
3145 % Here, \meta{r-list} is a comma-separated list of optional trim (in
3146 % parentheses) and column range -- and the code below essentially just
3147 % transforms this syntax into the syntax expected by |\kvtRule@cmid|.
3148 % \begin{macrocode}
3149 \newcommand\kvtRulesCMid{\noalign{\ifnum0=`}\fi
3150 \@ifnextchar[{\kvtRulesCMid@i}{\kvtRulesCMid@i[\cmidrulewidth]}}
3151 \long\def\kvtRulesCMid@i[#1]#2#3#4{%
3152 \let\kvt@@rules\@empty
3153 \forcsvlist\kvtRulesCMid@ii{#2}%
3154 \ifnum0=`{\fi\expandafter}\expandafter
3155 \kvtRulesCMid@v\expandafter{\kvt@@rules}{#1}{#3}{#4}}
3156 \newcommand\kvtRulesCMid@ii[1]{\kvtRulesCMid@iii#1\@undefined}
3157 \newcommand\kvtRulesCMid@iii{%
3158 \@ifnextchar({\kvtRulesCMid@iv}{\kvtRulesCMid@iv()}}
3159 \long\def\kvtRulesCMid@iv(#1)#2\@undefined{%
3160 \listadd\kvt@@rules{{#1}{#2}}}
3161 \newcommand\kvtRulesCMid@v[4]{\kvtRule@cmid{#2}{#1}{#3}{#4}}
3162 % \end{macrocode}
3163 % \end{macro}
3164 %
3165 % \begin{macro}{\kvtRule@ColorRule}
3166 % The |\kvtRule@ColorRule|\marg{color}\marg{wd}\marg{above}\marg{below}
3167 % macro draws a full-width horizontal table rule of width \meta{wd} in
3168 % color \meta{color} and spacing \meta{above} above and \meta{below}
3169 % below the rule.
3170 % If \meta{color} is empty, the current background color is used.
3171 % \begin{macrocode}
3172 \newcommand\kvtRule@ColorRule[4]{%
3173 \ifstrempty{#1}
3174 {\noalign{\expandafter\vskip\the\dimexpr #2+#3+#4\relax}}
3175 {\kvtRule@SaveRuleColor
3176 \arrayrulecolor{#1}%
3177 \specialrule{#2}{#3}{#4}%
3178 \kvtRule@RestoreRuleColor}}
3179 % \end{macrocode}
3180 % \end{macro}
3181 %
3182 % \begin{macro}{\kvtRule@SaveRuleColor}
3183 % \begin{macro}{\kvtRule@RestoreRuleColor}
3184 % These macros save and, respectively, restore the current rule color,
3185 % as provided by the \pkgname{colortbl} package in |\CT@arc@|.
3186 % \begin{macrocode}
3187 \newcommand\kvtRule@SaveRuleColor{%
3188 \noalign{\global\let\kvt@@ctarc\CT@arc@}}
3189 \newcommand\kvtRule@RestoreRuleColor{%
3190 \noalign{\global\let\CT@arc@\kvt@@ctarc}}
3191 % \end{macrocode}
3192 % \end{macro}
3193 % \end{macro}
3194 %
3195 %
3196 % \subsection{Key-Value Table Content}
3197 %
3198 % \begin{environment}{KeyValTable}
3199 % The |KeyValTable|\oarg{options}\marg{tname} environment encloses a new
3200 % table whose type is identified by the given \meta{tname}. Table options
3201 % can be overridden by providing \meta{options}.
3202 % \begin{macrocode}
3203 \newenvironment{KeyValTable}[2][]{%
3204 % \end{macrocode}
3205 % \begin{macro}{\Row}
3206 % The |\Row|\oarg{options}\marg{content} macro is made available locally
3207 % in the |KeyValTable| environment.
3208 % \begin{macrocode}
3209 \def\Row{\kvt@AddKeyValRow
3210 {\noalign\bgroup}{\expandafter\egroup\kvt@@row}{#2}}%
3211 \def\MidRule{\kvt@RuleMid}%
3212 \def\CMidRule{\kvt@RuleCMid{#2}}%
3213 % \end{macrocode}
3214 % \end{macro}
3215 % \begin{macrocode}
3216 \kvt@SetOptions{#2}{#1}%
3217 % \end{macrocode}
3218 % Save \meta{options} globally for a potential "|resume*|" option in the
3219 % immediately following |KeyValTable| environment.
3220 % If |resume*| is specified for the current environment, then the
3221 % previous options are not replaced. That is, |resume*| resumes the
3222 % options from the previous non-resuming environment.
3223 % \begin{macrocode}
3224 \ifbool{kvt@TableEnv@resume*}{}
3225 {\gdef\kvt@@lastenvopt{#1}}%
3226 \csuse{kvt@StartTable@\cmdkvt@Table@shape}{#2}%
3227 }{%
3228 \csuse{kvt@EndTable@\cmdkvt@Table@shape}}
3229 % \end{macrocode}
3230 % \end{environment}
3231 %
3232 % \begin{macro}{\kvt@SetOptions}
3233 % The |\kvt@SetOptions|\marg{tname}\marg{options} macro sets the
3234 % specific table options in the current environment, based on the
3235 % options for table type \meta{tname} and the specific \meta{options}.
3236 % \begin{macrocode}
3237 \newcommand\kvt@SetOptions[2]{\expandafter
3238 \kvt@SetOptions@i\expandafter{\csname kvt@options@#1\endcsname}{#2}}
3239 % \end{macrocode}
3240 % The auxiliary macro |\kvt@SetOptions@i|\marg{optcmd}\marg{options}
3241 % first sets the options in the expansion of \meta{optcmd} and then the
3242 % \meta{options}.
3243 % \begin{macrocode}
3244 \newcommand\kvt@SetOptions@i[2]{\expandafter
3245 \kvt@setkeys\expandafter{#1,#2}{Table,TableEnv}}
3246 % \end{macrocode}
3247 % \end{macro}
3248 %
3249 %
3250 % \subsubsection{Table Environment Properties}
3251 %
3252 % The following code maintains properties about known table
3253 % environments. This code does not depend on other code of the
3254 % \thispackage package but is only used by \thispackage.
3255 %
3256 % The following properties can be maintained about table environments.
3257 % \begin{macrocode}
3258 \define@boolkey[metatbl]{EnvProp}{isLong}{\metatbl@boolprop{isLong}{#1}}
3259 \define@boolkey[metatbl]{EnvProp}{isTabu}{\metatbl@boolprop{isTabu}{#1}}
3260 \define@boolkey[metatbl]{EnvProp}{hasWidth}{%
3261 \metatbl@boolprop{hasWidth}{#1}}
3262 \define@boolkey[metatbl]{EnvProp}{hasCaption}{%
3263 \metatbl@boolprop{hasCaption}{#1}}
3264 \define@boolkey[metatbl]{EnvProp}{canVAlign}{%
3265 \metatbl@boolprop{canVAlign}{#1}}
3266 \define@boolkey[metatbl]{EnvProp}{canHAlign}{%
3267 \metatbl@boolprop{canHAlign}{#1}}
3268 \define@cmdkey[metatbl]{EnvProp}{packages}{\metatbl@setprop{pkg}{#1}}
3269 % \end{macrocode}
3270 % The |atEnd| property shall be set to \hologo{TeX} code with one
3271 % argument (i.e., using the positional argument |#1|) that adds its
3272 % argument to the end of the active table environment's final content.
3273 % Finding such code is not obvious for table environments that collect
3274 % the content of the environment, like |tabularx| does, for instance.
3275 % \begin{macrocode}
3276 \define@key[metatbl]{EnvProp}{atEnd}{\metatbl@setprop[1]{atEnd}{#1}}
3277 % \end{macrocode}
3278 %
3279 % \begin{macro}{\metatblRegisterEnv}
3280 % The |\metatblRegisterEnv|\marg{env-name}\marg{properties} macro
3281 % registers a table environment with name \meta{env-name} and sets its
3282 % properties according to \meta{properties}, a comma-separated key-value
3283 % list.
3284 % \begin{macrocode}
3285 \newrobustcmd\metatblRegisterEnv[2]{%
3286 \edef\metatbl@@envname{#1}%
3287 \csdef{metatbl@@registered@#1}{true}%
3288 \setkeys[metatbl]{EnvProp}{#2}}
3289 % \end{macrocode}
3290 % \end{macro}
3291 %
3292 % \begin{macro}{\metatbl@setprop}
3293 % The |\metatbl@setprop|\oarg{n}\marg{key}\marg{value}
3294 % macro defines a macro with \meta{n} arguments ($0$ by default) for the
3295 % environment stored in |\metatbl@@envname| and the given
3296 % \meta{key}. This macro then expands to \meta{value}.
3297 % \begin{macrocode}
3298 \newcommand\metatbl@setprop[3][0]{%
3299 \expandafter\newcommand
3300 \csname metatbl@EnvProp@#2@\metatbl@@envname\endcsname[#1]{#3}}
3301 % \end{macrocode}
3302 % \end{macro}
3303 %
3304 % \begin{macro}{\metatbl@boolprop}
3305 % The |\metatbl@boolprop|\marg{prop}\marg{value} macro stores the
3306 % Boolean value \meta{value} in a property \meta{prop} for the
3307 % environment stored in |\metatbl@@envname|.
3308 % \begin{macrocode}
3309 \newcommand\metatbl@boolprop[2]{%
3310 \providebool{metatbl@EnvProp@#1@\metatbl@@envname}%
3311 \setbool{metatbl@EnvProp@#1@\metatbl@@envname}{#2}}
3312 % \end{macrocode}
3313 % \end{macro}
3314 %
3315 % \begin{macro}{\metatblRegistered}
3316 % \begin{macro}{\metatblIsLong}
3317 % \begin{macro}{\metatblIsTabu}
3318 % \begin{macro}{\metatblHasWidth}
3319 % \begin{macro}{\metatblHasCaption}
3320 % \begin{macro}{\metatblCanVAlign}
3321 % \begin{macro}{\metatblCanHAlign}
3322 % The following macros all expect the three arguments
3323 % \marg{env-name}\marg{iftrue}\marg{iffalse}.
3324 % The macro
3325 % |\metatblRegistered|
3326 % expands to \meta{iftrue} if \meta{env-name} has been registered via
3327 % |\metatblRegisterEnv| and expands to \meta{iffalse} otherwise.
3328 % The remaining macros expand to \meta{iftrue}, if the respective
3329 % property has been set to |true| in when \meta{env-name} was registered
3330 % via |\metatblRegisterEnv|, and expand to \meta{iffalse} otherwise.
3331 % \begin{macrocode}
3332 \newcommand\metatblRegistered[1]{\ifcsdef{metatbl@@registered@#1}}
3333 \newcommand\metatblIsLong[1]{\ifbool{metatbl@EnvProp@isLong@#1}}
3334 \newcommand\metatblIsTabu[1]{\ifbool{metatbl@EnvProp@isTabu@#1}}
3335 \newcommand\metatblHasWidth[1]{\ifbool{metatbl@EnvProp@hasWidth@#1}}
3336 \newcommand\metatblHasCaption[1]{\ifbool{metatbl@EnvProp@hasCaption@#1}}
3337 \newcommand\metatblCanVAlign[1]{\ifbool{metatbl@EnvProp@canVAlign@#1}}
3338 \newcommand\metatblCanHAlign[1]{\ifbool{metatbl@EnvProp@canHAlign@#1}}
3339 % \end{macrocode}
3340 % \end{macro}
3341 % \end{macro}
3342 % \end{macro}
3343 % \end{macro}
3344 % \end{macro}
3345 % \end{macro}
3346 % \end{macro}
3347 %
3348 % \begin{macro}{\metatblUsePackage}
3349 % \begin{macro}{\metatblRequire}
3350 % Macros |\metatblUsePackage|\marg{env-names} and
3351 % |\metatblRequire|\marg{env-names} load the packages required
3352 % for typesetting |KeyValTable| tables based on the table environments
3353 % listed in \meta{env-names}.
3354 % The former aims more at normal document use, the second at use by
3355 % package developers.
3356 % \begin{macrocode}
3357 \newcommand\metatblUsePackage[1]{%
3358 \def\do##1{%
3359 \metatbl@csnamearg\usepackage{metatbl@EnvProp@pkg@##1}}%
3360 \docsvlist{#1}}
3361 \newcommand\metatblRequire[1]{%
3362 \def\do##1{%
3363 \metatbl@csnamearg\RequirePackage{metatbl@EnvProp@pkg@##1}}%
3364 \docsvlist{#1}}
3365 % \end{macrocode}
3366 % \end{macro}
3367 % \end{macro}
3368 %
3369 % \begin{macro}{\metatblAtEnd}
3370 % The |\metatblAtEnd|\marg{env-name}\marg{code} macro registers
3371 % \meta{code} for addition at the end of tables based on the
3372 % \meta{env-name} environment.
3373 % \begin{macrocode}
3374 \newcommand\metatblAtEnd[2]{%
3375 \csname metatbl@EnvProp@atEnd@#1\endcsname{#2}}
3376 % \end{macrocode}
3377 % \end{macro}
3378 %
3379 % \begin{macro}{\metatbl@csnamearg}
3380 % The auxiliary macro
3381 % |\metatbl@csnamearg|\marg{command}\marg{csname}
3382 % passes the expansion of the macro with name \meta{csname} as the first
3383 % argument to \meta{command}.
3384 % \begin{macrocode}
3385 \newcommand\metatbl@csnamearg[2]{%
3386 \expandafter\expandafter\expandafter#1%
3387 \expandafter\expandafter\expandafter{\csname#2\endcsname}}
3388 % \end{macrocode}
3389 % \end{macro}
3390 %
3391 % The following are the properties of some basic table environments.
3392 % \begin{macrocode}
3393 \metatblRegisterEnv{tabular}{%
3394 isLong=false, hasWidth=false, isTabu=false, hasCaption=false,
3395 canVAlign=true, canHAlign=false,
3396 packages={},
3397 atEnd={\preto\endtabular{#1}},
3398 }
3399 \metatblRegisterEnv{tabularx}{%
3400 isLong=false, hasWidth=true, isTabu=false, hasCaption=false,
3401 canVAlign=true, canHAlign=false,
3402 packages=tabularx,
3403 atEnd={%
3404 % \end{macrocode}
3405 % Of the following two lines, the latter is for the case that the
3406 % \pkgname{xltabular} package is loaded, and the former is for the case
3407 % that the package is not loaded.
3408 % \begin{macrocode}
3409 \preto\TX@endtabularx{\toks@\expandafter{\the\toks@#1}}%
3410 \preto\XLT@i@TX@endtabularx{\toks@\expandafter{\the\toks@#1}}},
3411 }
3412 \metatblRegisterEnv{longtable}{%
3413 isLong=true, hasWidth=false, isTabu=false, hasCaption=true,
3414 canVAlign=false, canHAlign=true,
3415 packages={longtable},
3416 atEnd={\preto\endlongtable{#1}},
3417 }
3418 \metatblRegisterEnv{xltabular}{%
3419 isLong=true, hasWidth=true, isTabu=false, hasCaption=true,
3420 canVAlign=false, canHAlign=true,
3421 packages=xltabular,
3422 atEnd={\preto\XLT@ii@TX@endtabularx{\toks@\expandafter{\the\toks@#1}}},
3423 }
3424 \metatblRegisterEnv{tabu}{%
3425 isLong=false, hasWidth=true, isTabu=true, hasCaption=false,
3426 canVAlign=true, canHAlign=false,
3427 packages={tabu},
3428 % \end{macrocode}
3429 % The following is not a mistake: |tabu| does
3430 % |\def\endtabu{\endtabular}| at the beginning of a |tabu| environment.
3431 % \begin{macrocode}
3432 atEnd={\preto\endtabular{#1}},
3433 }
3434 \metatblRegisterEnv{longtabu}{%
3435 isLong=true, hasWidth=true, isTabu=true, hasCaption=true,
3436 canVAlign=false, canHAlign=true,
3437 packages={tabu,longtable},
3438 % \end{macrocode}
3439 % The following is not a mistake: |tabu| does
3440 % |\def\endlongtabu{\endlongtable}| at the beginning of a |longtabu|
3441 % environment.
3442 % \begin{macrocode}
3443 atEnd={\preto\endlongtable{#1}},
3444 }
3445 % \end{macrocode}
3446 %
3447 % \begin{macro}{\metatbl@ifhasXcolumns}
3448 % The |\metatbl@ifhasXcolumns|\marg{preamble}\marg{iftrue}\marg{iffalse}
3449 % takes a \meta{preamble} (the argument of a |tabular| environment that
3450 % specifies the columns of the table) and checks, whether this preamble
3451 % contains an "|X|" column. If such a column is contained, the macro
3452 % expands to \meta{iftrue}. Otherwise, it expands to \meta{iffalse}.
3453 % \begin{macrocode}
3454 \newrobustcmd\metatbl@ifhasXcolumns[1]{%
3455 \begingroup
3456 % \end{macrocode}
3457 % The |\metatbl@@branch| macro is used at the end of the macro to select
3458 % \meta{iftrue} or \meta{iffalse} for expansion. Initially, the macro is
3459 % defined to select \meta{iffalse}.
3460 % \begin{macrocode}
3461 \def\metatbl@@branch{\@secondoftwo}%
3462 % \end{macrocode}
3463 % The code uses the |\@mkpream| macro of the \pkgname{array} package to
3464 % create an |\halign| preamble from the |tabular| \meta{preamble}.
3465 % The result of |\@mkpream| is in |\@preamble| afterwards, but this
3466 % result is not used, but rather discarded at the |\endgroup| below.
3467 % Rather, we hook into |\@mkpream| via |\NC@rewrite@X|, which is used
3468 % when an |X| column was encountered in \meta{preamble}.\footnote{This
3469 % hooking into \cmd{\@mkpream} is inspired by how |tabularx| replaces |X|
3470 % columns by |p| columns as part of its measuring.}
3471 % When an |X| column is encountered, |\metatbl@@branch| is redefined to
3472 % expand to \meta{iftrue} in the end.
3473 % \begin{macrocode}
3474 \def\NC@rewrite@X{\def\metatbl@@branch{\@firstoftwo}\NC@find l}%
3475 \@mkpream{#1}%
3476 \expandafter\endgroup\metatbl@@branch}
3477 % \end{macrocode}
3478 % \end{macro}
3479 %
3480 %
3481 % \subsubsection{Table Environment Code}
3482 %
3483 % \begin{macro}{\kvt@StartTabularlike}
3484 % The
3485 % |\kvt@StartTabularlike|\marg{env}\marg{tname}
3486 % macro begins a table environment for the given table type \meta{tname}.
3487 % The \meta{env} parameter specifies the concrete environment name.
3488 % \begin{macrocode}
3489 \newcommand\kvt@StartTabularlike[2]{%
3490 % \end{macrocode}
3491 % \changes{v1.0}{2019/02/18}{Implemented \texttt{showrules} option}
3492 % \begin{macrocode}
3493 \metatblAtEnd{#1}{\kvt@@endhook}%
3494 \let\kvt@@endhook\@empty
3495 \let\kvt@@prehook\@empty
3496 \ifbool{kvt@Table@showrules}
3497 {\def\kvt@@rule##1{\csuse{kvt@Rule##1}}}
3498 {\def\kvt@@rule##1{}}%
3499 \appto\kvt@@prehook{\kvt@@rule{Top}}%
3500 \appto\kvt@@endhook{\kvt@@rule{Bottom}}%
3501 % \end{macrocode}
3502 % The following saves the row counter value for the table type globally,
3503 % such that subsequent tables of the same \meta{tname} can start counting
3504 % from there. Moreover, it save the local row counter for the case that
3505 % the next table uses the "|resume|" option.
3506 % \begin{macrocode}
3507 \appto\kvt@@endhook{\noalign{%
3508 \csxdef{kvt@rowcount@#2}{\thekvtTypeRow}%
3509 \csxdef{kvt@@rowcountlast}{\thekvtRow}}}%
3510 % \end{macrocode}
3511 % Adding caption and label.
3512 % \begin{macrocode}
3513 \ifdefvoid\cmdkvt@TableEnv@caption
3514 {\let\kvt@@caption@main\@empty
3515 \let\kvt@@caption@alt\@empty}
3516 {\metatblHasCaption{#1}
3517 {\edef\kvt@@caption@main{%
3518 \csexpandonce{kvt@caption@\cmdkvt@Table@captionpos}%
3519 \ifcsvoid{cmdkvt@TableEnv@caption/lot}{}
3520 {[{\csexpandonce{cmdkvt@TableEnv@caption/lot}}]}%
3521 {\expandonce\cmdkvt@TableEnv@caption
3522 \ifdefvoid\cmdkvt@TableEnv@label{}{%
3523 \noexpand\label{\expandonce\cmdkvt@TableEnv@label}}}%
3524 \noexpand\\}%
3525 \ifcsvoid{cmdkvt@TableEnv@caption/alt}
3526 {\def\kvt@@caption@alt{}}
3527 {\edef\kvt@@caption@alt{%
3528 \csexpandonce{kvt@caption@\cmdkvt@Table@captionpos}[]%
3529 {\csexpandonce{cmdkvt@TableEnv@caption/alt}}%
3530 \noexpand\\}}%
3531 }{\kvt@error
3532 {Caption lost, table backend '#1' does not support captions}
3533 {Consider placing the KeyValTable environment inside a 'table'
3534 environment and use the \string\caption\space macro inside.}}}%
3535 \ifdefstring{\cmdkvt@Table@captionpos}{t}
3536 {\let\kvt@@caption@headmain\kvt@@caption@main
3537 \let\kvt@@caption@footmain\@empty
3538 \let\kvt@@caption@headalt\kvt@@caption@alt
3539 \let\kvt@@caption@footalt\@empty}
3540 {\let\kvt@@caption@footmain\kvt@@caption@main
3541 \let\kvt@@caption@headmain\@empty
3542 \let\kvt@@caption@footalt\kvt@@caption@alt
3543 \let\kvt@@caption@headalt\@empty}%
3544 \ifbool{kvt@Table@showhead}
3545 {\eappto\kvt@@prehook{\csuse{kvt@headings@#2}%
3546 \noexpand\kvt@@rule{SubHead}}}
3547 {}%
3548 % \end{macrocode}
3549 % The following lines perform some checks before the table environment
3550 % is started.
3551 % \begin{macrocode}
3552 \ifdefvoid{\cmdkvt@Table@valign}{}{\metatblCanVAlign{#1}{}
3553 {\undef{\cmdkvt@Table@valign}%
3554 \kvt@warn{Table environment '#1' of table '#2'
3555 does not support the vertical alignment option (valign).
3556 Ignoring the option}}}%
3557 \ifdefvoid{\cmdkvt@Table@halign}{}{\metatblCanHAlign{#1}{}
3558 {\undef{\cmdkvt@Table@halign}%
3559 \kvt@warn{Table environment '#1' of table '#2'
3560 does not support the horizontal alignment option (halign).
3561 Ignoring the option}}}%
3562 % \end{macrocode}
3563 % Initializing the row counters. The global counter |kvtTotalRow| needs
3564 % no local initialization.
3565 % \begin{macrocode}
3566 \global\kvt@@bodyrow=0\relax
3567 \ifbool{kvt@TableEnv@resume}
3568 {\setcounter{kvtRow}{\csuse{kvt@@rowcountlast}}}
3569 {\setcounter{kvtRow}{0}}%
3570 \setcounter{kvtTypeRow}{\csuse{kvt@rowcount@#2}}%
3571 % \end{macrocode}
3572 % Initialize the background colors for the body rows.
3573 % \begin{macrocode}
3574 \expandafter\kvt@setrowcolors\expandafter{\cmdkvt@Table@rowbg}%
3575 % \end{macrocode}
3576 % In |\kvt@@do|, the start code for the environment, including the
3577 % header rows, is gathered, with expansion to fill in all the table
3578 % settings and options.
3579 % \changes{v0.3}{2016/06/05}{Added \texttt{showhead} option}
3580 % \changes{v1.0}{2019/03/09}{Added \texttt{width} option}
3581 % \changes{v2.1}{2020/01/19}{Added \texttt{valign} and \texttt{halign} options}
3582 % \begin{macrocode}
3583 \begingroup\edef\kvt@@do{\endgroup
3584 \expandafter\noexpand\csname #1\endcsname
3585 % \end{macrocode}
3586 % As background on the positions of the parameters below, here is the
3587 % syntax for beginning the supported environments:
3588 % \begin{itemize}[nosep]
3589 % \item|\begin{tabular}|\oarg{valign}\marg{preamble}
3590 % \item|\begin{tabularx}|\marg{width}\oarg{valign}\marg{preamble}
3591 % \item|\begin{longtable}|\oarg{halign}\marg{preamble}
3592 % \item|\begin{xltabular}|\oarg{halign}\marg{width}\marg{preamble}
3593 % \item|\begin{tabu}| to \meta{width}\oarg{valign}\marg{preamble}
3594 % \item|\begin{longtabu}| to \meta{width}\oarg{halign}\marg{preamble}
3595 % \end{itemize}
3596 % The above cases are covered in the following lines.
3597 % \begin{macrocode}
3598 \ifdefvoid{\cmdkvt@Table@halign}{}
3599 {\metatblIsTabu{#1}{}{[\cmdkvt@Table@halign]}}%
3600 \metatblHasWidth{#1}
3601 {\metatblIsTabu{#1}
3602 {to \expandonce\cmdkvt@Table@width}
3603 {{\expandonce\cmdkvt@Table@width}}}
3604 {}%
3605 \ifdefvoid{\cmdkvt@Table@valign}{}{[\cmdkvt@Table@valign]}%
3606 \ifdefvoid{\cmdkvt@Table@halign}{}
3607 {\metatblIsTabu{#1}{[\cmdkvt@Table@halign]}{}}%
3608 {\csexpandonce{kvt@alignments@#2}}%
3609 % \end{macrocode}
3610 % The remainder below already starts the content of the table
3611 % environment. It also sets the header and footer for multipage tables.
3612 % \begin{macrocode}
3613 \expandonce\kvt@@caption@headmain
3614 \expandonce\kvt@@prehook
3615 \metatblIsLong{#1}{%
3616 \noexpand\endfirsthead
3617 \expandonce\kvt@@caption@headalt
3618 \expandonce\kvt@@prehook
3619 \noexpand\endhead}{}%
3620 \expandonce\kvt@@caption@footmain
3621 \metatblIsLong{#1}{%
3622 \noexpand\endlastfoot
3623 \expandonce\kvt@@caption@footalt
3624 \noexpand\endfoot}{}%
3625 }\kvt@@do}
3626 % \end{macrocode}
3627 % \end{macro}
3628 %
3629 % \begin{macro}{\kvt@caption@b}
3630 % \begin{macro}{\kvt@caption@t}
3631 % The |\kvt@caption@b| and |\kvt@caption@t| macros behave like
3632 % |\caption| but add extra behavior depending on whether the caption is
3633 % displayed above (|\kvt@caption@t|) or below (|\kvt@caption@b|) the
3634 % table. Currently, |\kvt@caption@b| only fixes the spacing between the
3635 % table and the caption.
3636 % \begin{macrocode}
3637 \newcommand\kvt@caption@t{\caption}
3638 \newcommand\kvt@caption@b{%
3639 % \end{macrocode}
3640 % Fixme: The following |\baselineskip| before the caption compensates
3641 % that \pkgname{longtable} adds a |\baselineskip| below the caption (in
3642 % its macro |\LT@makecaption|) but not above. The \pkgname{ltcaption}
3643 % package replaces the hard-coded |\baselineskip| by |\LTcapskip| but
3644 % also only puts it below the caption. The code below could at least be
3645 % improved to use |\LTcapskip| if it is available.
3646 % \begin{macrocode}
3647 \noalign{\parbox{0pt}{\vskip\baselineskip}}%
3648 \caption}
3649 % \end{macrocode}
3650 % \end{macro}
3651 % \end{macro}
3652 %
3653 % \begin{macro}{\kvt@setrowcolors}
3654 % The |\kvt@setrowcolors|\marg{colors} sets up row
3655 % colors using the |\rowcolors| macro of \pkgname{xcolor}.
3656 % The \marg{colors} parameter expects arguments of the form
3657 % "\meta{color1}|..|\meta{color2}" (the syntax used for the |rowbg|
3658 % option. The row colors then alternate between \meta{color1} and
3659 % \meta{color2}, starting with \meta{color1} in the first row.
3660 % If \meta{colors} is empty, then no row colors are setup.
3661 % \begin{macrocode}
3662 \newcommand\kvt@setrowcolors[1]{%
3663 \ifstrempty{#1}{\kvt@setrowcolors@ii{}{}}
3664 {\kvt@setrowcolors@i#1\@nil}}
3665 \def\kvt@setrowcolors@i#1..#2\@nil{%
3666 \kvt@setrowcolors@ii{#1}{#2}}
3667 \newcommand\kvt@setrowcolors@ii[2]{%
3668 \def\kvt@@bgcolor@odd{#1}%
3669 \def\kvt@@bgcolor@even{#2}}
3670 % \end{macrocode}
3671 % \end{macro}
3672 %
3673 % \begin{macro}{\kvt@userowcolors}
3674 % The |\kvt@userowcolors| macro macro expands to
3675 % |\rowcolor|\marg{color}, where \meta{color} is the background color
3676 % set via |\kvt@setrowcolors| for odd, respectively even rows, based on
3677 % |\kvt@@bodyrow|.
3678 % \begin{macrocode}
3679 \newcommand\kvt@userowcolors{\ifnumodd{\the\kvt@@bodyrow}
3680 {\kvt@rowcolorcmdornot{\kvt@@bgcolor@odd}}
3681 {\kvt@rowcolorcmdornot{\kvt@@bgcolor@even}}}
3682 % \end{macrocode}
3683 % \end{macro}
3684 %
3685 % \begin{macro}{\kvt@RegisterBackend}
3686 % \begin{macro}{\kvt@RegisterShape}
3687 % The |\kvt@RegisterBackend|\marg{env} macro registers the table
3688 % environment \meta{env} as a table backend for use by \thispackage.
3689 % The |\kvt@RegisterShape|\marg{name}\marg{nonX-env}\marg{X-env}
3690 % registers a shape with the given \meta{name} and associates it with
3691 % the environment \meta{nonX-env} when the shape is used for a table
3692 % without |X| columns and with environment \meta{X-env} otherwise.
3693 % \begin{macrocode}
3694 \newcommand\kvt@RegisterBackend[1]{%
3695 \ifinlist{#1}{\kvt@@tablebackends}
3696 {\kvt@error{Backend '#1' already registered}
3697 {Internal error. Check use of \string\kvt@RegisterBackend.}}
3698 {\kvt@CheckMetatblEnv{#1}%
3699 \listadd{\kvt@@tablebackends}{#1}%
3700 \kvt@DefineStdTabEnv{#1}{#1}}}
3701 \newcommand\kvt@RegisterShape[3]{%
3702 \ifinlist{#1}{\kvt@@tableshapes}
3703 {\kvt@error{Shape '#1' already registered}
3704 {Internal error. Check use of \string\kvt@RegisterShape.}}
3705 {\kvt@CheckMetatblEnv{#2}\kvt@CheckMetatblEnv{#3}%
3706 \listadd{\kvt@@tableshapes}{#1}%
3707 \ifstrequal{#2}{#3}
3708 {\kvt@DefineStdTabEnv{#1}{#2}}
3709 {\kvt@DefineDualTabEnv{#1}{#2}{#3}}}}
3710 \newcommand\kvt@CheckMetatblEnv[1]{\metatblRegistered{#1}{}
3711 {\kvt@error{Environment '#1' not supported by keyvaltable}
3712 {Check \string\metatblRegisterEnv\space for how to make it
3713 supported.}}}
3714 % \end{macrocode}
3715 % \end{macro}
3716 % \end{macro}
3717 % \begin{macro}{\kvt@RegisterBackend}
3718 % \begin{macro}{\kvt@RegisterShape}
3719 % The macros |\kvt@@tablebackends| and |\kvt@@tableshapes| hold
3720 % \pkgname{etoolbox} lists of registered names of table backends and
3721 % table shapes.
3722 % \begin{macrocode}
3723 \newcommand\kvt@@tablebackends{}
3724 \newcommand\kvt@@tableshapes{}
3725 % \end{macrocode}
3726 % \end{macro}
3727 % \end{macro}
3728 %
3729 % \begin{macro}{\kvt@DefineStdTabEnv}
3730 % The |\kvt@DefineStdTabEnv|\marg{shape}\marg{env}
3731 % macro defines the macros needed for the given \meta{shape} value.
3732 % If \meta{shape} is omitted, \meta{env} (the name of the environment to
3733 % use for the shape) is used as \meta{shape} value.
3734 % \begin{macrocode}
3735 \newcommand\kvt@DefineStdTabEnv[2]{%
3736 \csdef{kvt@StartTable@#1}##1{%
3737 \kvt@StartTabularlike{#2}{##1}}%
3738 \csedef{kvt@EndTable@#1}{%
3739 \expandafter\noexpand\csname end#2\endcsname}}
3740 % \end{macrocode}
3741 % \end{macro}
3742 %
3743 % \begin{macro}{\kvt@DefineDualTabEnv}
3744 % The |\kvt@DefineDualTabEnv|\marg{shape}\marg{nonX-env}\marg{X-env}
3745 % macro defines the macros for the given \meta{shape} name.
3746 % The macros are defined in a way such that the table environment
3747 % \meta{nonX-env} is used for typesetting tables that do not use |X|
3748 % columns and that table environment \meta{X-env} is used for
3749 % typesetting tables that do use |X| columns.
3750 % \begin{macrocode}
3751 \newcommand\kvt@DefineDualTabEnv[3]{%
3752 \expandafter\newcommand\csname kvt@StartTable@#1\endcsname[1]{%
3753 \kvt@ifhasXcolumns{##1}
3754 {\csedef{kvt@EndTable@#1}{%
3755 \expandafter\noexpand\csname end#3\endcsname}%
3756 \kvt@StartTabularlike{#3}{##1}%
3757 }{\csedef{kvt@EndTable@#1}{%
3758 \expandafter\noexpand\csname end#2\endcsname}%
3759 \kvt@StartTabularlike{#2}{##1}}}}
3760 % \end{macrocode}
3761 % \end{macro}
3762 %
3763 % \begin{macro}{\kvt@ifhasXcolumns}
3764 % The |\kvt@ifhasXcolumns|\marg{tname}\marg{iftrue}\marg{iffalse}
3765 % takes a table type \meta{tname} and checks whether the table type
3766 % contains an "|X|" column. If such a column is contained, the macro
3767 % expands to \meta{iftrue}. Otherwise, it expands to \meta{iffalse}.
3768 % \begin{macrocode}
3769 \newcommand\kvt@ifhasXcolumns[1]{%
3770 \expandafter\expandafter\expandafter\metatbl@ifhasXcolumns
3771 \expandafter\expandafter\expandafter{%
3772 \csname kvt@alignments@#1\endcsname}}
3773 % \end{macrocode}
3774 % \end{macro}
3775 %
3776 % The following lines define the macros for the various table
3777 % environments.
3778 % \begin{macrocode}
3779 \kvt@RegisterBackend{tabular}
3780 \kvt@RegisterBackend{longtable}
3781 \kvt@RegisterBackend{tabularx}
3782 \kvt@RegisterBackend{xltabular}
3783 \kvt@RegisterBackend{tabu}
3784 \kvt@RegisterBackend{longtabu}
3785 % \end{macrocode}
3786 %
3787 %
3788 % \subsubsection{Environment-Independent Parts}
3789 %
3790 % \begin{macro}{\kvt@AddKeyValRow}
3791 % The
3792 % |\kvt@AddKeyValRow|\marg{pre}\marg{post}\marg{tname}\oarg{options}\marg{content}
3793 % macro composes a row for the table of type \meta{tname} from the given
3794 % \meta{content} and \meta{options}. The \meta{content} is a
3795 % key-value list that specifies the content of the individual cells in
3796 % the row. The result is returned in macro |\kvt@@row|.
3797 % The arguments \meta{pre} and \meta{post} are expanded at the very
3798 % beginning, resp.\@ end of the macro.
3799 % They allow to control grouping (|\begingroup| and |\endgroup|) as well
3800 % as table placement via |\noalign|.
3801 % \changes{v1.0}{2019/03/17}{Added \oarg{options}}
3802 % \begin{macrocode}
3803 \newcommand\kvt@AddKeyValRow[3]{%
3804 #1%
3805 % \end{macrocode}
3806 % It's essential that \meta{pre} above comes even before |\@ifnextchar|
3807 % and, therefore, cannot be moved into |\kvt@AddKeyValRow@i|:
3808 % The |\@ifnextchar| is not fully expandable and therefore any
3809 % |\noalign| (in \meta{pre}) following |\@ifnextchar| would lead to
3810 % "misplaced |\noalign|" errors.
3811 % \begin{macrocode}
3812 \@ifnextchar[%]
3813 {\kvt@AddKeyValRow@i{#2}{#3}}
3814 {\kvt@AddKeyValRow@i{#2}{#3}[]}}
3815 % \end{macrocode}
3816 % \end{macro}
3817 % \begin{macro}{\kvt@AddKeyValRow@i}
3818 % The
3819 % |\kvt@AddKeyValRow@i|\marg{post}\marg{tname}\oarg{options}\marg{content}
3820 % macro parses \meta{options} and evaluates the |hidden| option.
3821 % \begin{macrocode}
3822 \def\kvt@AddKeyValRow@i#1#2[#3]#4{%
3823 \kvt@setkeys{#3}{Row}%
3824 \ifbool{kvt@Row@hidden}
3825 {\let\kvt@@row\@empty #1}
3826 {\kvt@AddKeyValRow@ii{#1}{#2}{#4}}}
3827 % \end{macrocode}
3828 % \end{macro}
3829 % \begin{macro}{\kvt@AddKeyValRow@ii}
3830 % The
3831 % |\kvt@AddKeyValRow@ii|\marg{post}\marg{tname}\marg{content}
3832 % macro mainly processes \meta{content} as well as \meta{options}
3833 % that have already been parsed by |\kvt@AddKeyValRow@i|.
3834 % \begin{macrocode}
3835 \def\kvt@AddKeyValRow@ii#1#2#3{%
3836 \setkeys[KeyValTable]{#2}{#3}%
3837 % \end{macrocode}
3838 % Initialize and first add the |\noalign| material to the row.
3839 % \begin{macrocode}
3840 \def\kvt@@row{}%
3841 \ifdefvoid\cmdkvt@Row@above{}{%
3842 \eappto\kvt@@row{\noexpand\noalign{\noexpand\vspace{%
3843 \expandonce\cmdkvt@Row@above}}}}%
3844 \appto\kvt@@row{\noalign{\global\advance\kvt@@bodyrow\@ne}}%
3845 \ifbool{kvt@Row@uncounted}{}{%
3846 \appto\kvt@@row{\noalign{\kvt@stepcounters}}}%
3847 \ifdefvoid\cmdkvt@Row@bg
3848 {\appto\kvt@@row{\kvt@userowcolors}}
3849 {\eappto\kvt@@row{\noexpand\rowcolor{\expandonce\cmdkvt@Row@bg}}}%
3850 % \end{macrocode}
3851 % If a row alignment is specified, a default |\multicolumn| display is
3852 % enabled for the row's cells.
3853 % \begin{macrocode}
3854 \ifdefvoid\cmdkvt@Row@align
3855 {\def\kvt@@rowmkmulticolumn{\kvt@unicolumn}}
3856 {\edef\kvt@@rowmkmulticolumn{%
3857 \noexpand\kvt@multicolumn{1}{\expandonce\cmdkvt@Row@align}}}%
3858 % \end{macrocode}
3859 % The following defines a macro
3860 % |\kvt@@cellfmtbuilder|\marg{cmd}\marg{csname}.
3861 % This macro defines the macro \meta{cmd}\marg{cell} to format the cell
3862 % content, \meta{cell}, based on the column format \meta{csname} and the
3863 % row formatting options.
3864 % Through this "builder" macro, the row format options need only be
3865 % considered once and the column format options can then be included
3866 % when the displayed columns are iterated over.
3867 % \begin{macrocode}
3868 \ifcsvoid{cmdkvt@Row@format!}
3869 {\edef\kvt@@cellfmtbuilder##1##2{%
3870 \noexpand\edef##1####1{%
3871 \noexpand\kvt@expandonce@onearg\noexpand\kvt@@mkmulticolumn
3872 {\ifcsvoid{cmdkvt@Row@format*}{\@firstofone}
3873 {\noexpand\unexpanded{\csexpandonce{cmdkvt@Row@format*}}}%
3874 {\noexpand\csexpandonce{##2}{%
3875 \ifdefvoid\cmdkvt@Row@format{\@firstofone}
3876 {\noexpand\unexpanded{\expandonce\cmdkvt@Row@format}}%
3877 {####1}}}}}}}%
3878 {\edef\kvt@@cellfmtbuilder##1##2{%
3879 \noexpand\edef##1####1{%
3880 \noexpand\kvt@expandonce@onearg\noexpand\kvt@@mkmulticolumn{%
3881 \noexpand\unexpanded{\csexpandonce{cmdkvt@Row@format!}}%
3882 {####1}}}}}%
3883 % \end{macrocode}
3884 % The following loop uses |\do|\marg{cname} to append the content of
3885 % all displayed columns (in the given format and using the given default
3886 % value), where each column value is in
3887 % \cs{cmdKeyValTable@\meta{tname}@\meta{cname}}.
3888 % Note that currently the default value is formatted using the given
3889 % format macro -- a design decision.
3890 % \changes{v1.0}{2019/02/03}{Added \cs{multicolumn} support}
3891 % \begin{macrocode}
3892 \kvt@@span=0\relax
3893 \kvt@def@atseconduse\kvt@@switchcol{\appto\kvt@@row{&}}%
3894 \def\do##1{%
3895 % \end{macrocode}
3896 % First, check whether a column-spanning cell is active
3897 % ($\cs{kvt@@span}>0$). If this is the case, ensure that if the raw cell
3898 % content in the current column is empty, then the column is simply
3899 % ignored and otherwise an error is produced.
3900 % \begin{macrocode}
3901 \ifnumgreater\kvt@@span{0}
3902 {\advance\kvt@@span\m@ne
3903 \ifcsvoid{cmdKeyValTable@#2@##1}{}
3904 {\ifdefvoid\kvt@@curcgname
3905 {\kvt@error{Column '##1' nonempty inside a
3906 \string\multicolumn}{}}
3907 {\kvt@error{Column '##1' nonempty inside column group
3908 '\kvt@@curcgname'}{}}}}
3909 {\kvt@@switchcol
3910 % \end{macrocode}
3911 % Initialize the multicolumn display to the row's default.
3912 % \begin{macrocode}
3913 \let\kvt@@mkmulticolumn\kvt@@rowmkmulticolumn
3914 \letcs\kvt@@curcolformat{kvt@col@format@#2@##1}%
3915 % \end{macrocode}
3916 % First recover the cell content (either the specified value for the row
3917 % or, if no value is specified for the row, the cell's default value)
3918 % without formatting.
3919 % \begin{macrocode}
3920 \ifcsvoid{cmdKeyValTable@#2@##1}
3921 {\letcs\kvt@@cell{kvt@col@default@#2@##1}}
3922 {\letcs\kvt@@cell{cmdKeyValTable@#2@##1}%
3923 % \end{macrocode}
3924 % Unless the default cell value is used, first check for a multicolumn
3925 % value. Default cell values should not need this. The check is done
3926 % before the expansion code afterwards, in order for applying the
3927 % expansion to the code in the cell value rather than to the multicolumn
3928 % code.
3929 % \begin{macrocode}
3930 \expandafter\kvt@CheckMulticolumn\expandafter{\kvt@@cell}{#2}%
3931 % \end{macrocode}
3932 % Apply expansion control options, but only to manually supplied cell
3933 % values, not to default values.
3934 % \begin{macrocode}
3935 \ifbool{kvt@Row@expandonce}
3936 {\expandafter\let\expandafter\kvt@@cell\kvt@@cell}{}%
3937 \ifbool{kvt@Row@expand}
3938 {\protected@edef\kvt@@cell{\kvt@@cell}}{}}%
3939 % \end{macrocode}
3940 % Separately also already create the content -- with formatting unless
3941 % the user explicitly requested no cell formatting.
3942 % \begin{macrocode}
3943 \ifcsvoid{kvt@@noformat@#2@##1}
3944 {\kvt@@cellfmtbuilder\kvt@@formatter{kvt@@curcolformat}}%
3945 {\let\kvt@@formatter\kvt@unicolumn}%
3946 \csundef{kvt@@noformat@#2@##1}%
3947 \edef\kvt@@fmtcell{\expandafter\expandonce\expandafter{%
3948 \expandafter\kvt@@formatter\expandafter{%
3949 \kvt@@cell}}}%
3950 % \end{macrocode}
3951 % Finally, append the cell to the row.
3952 % \begin{macrocode}
3953 \expandafter\appto\expandafter\kvt@@row\expandafter{%
3954 \kvt@@fmtcell}}%
3955 }\dolistcsloop{kvt@displaycols@#2}%
3956 \undef\kvt@@cellfmtbuilder
3957 % \end{macrocode}
3958 % Finally, add the concluding newline for the row as well as
3959 % the vertical space after the row, if requested.
3960 % \begin{macrocode}
3961 \appto\kvt@@row{\tabularnewline}%
3962 \ifdefvoid\cmdkvt@Row@below{}{%
3963 \eappto\kvt@@row{\noexpand\noalign{\noexpand\vspace{%
3964 \expandonce\cmdkvt@Row@below}}}}%
3965 % \end{macrocode}
3966 % At the very end of the expansion text, put \meta{post}.
3967 % \begin{macrocode}
3968 #1}
3969 % \end{macrocode}
3970 % \end{macro}
3971 %
3972 % \begin{macro}{\kvt@def@atseconduse}
3973 % The |\kvt@def@atseconduse|\marg{cmd}\marg{code} defines the macro
3974 % \meta{cmd} to expand to \meta{code} but only from its second use
3975 % onwards. At its first use, \meta{cmd} only redefines itself to
3976 % \meta{code} but does not do anything else.
3977 % \begin{macrocode}
3978 \newcommand\kvt@def@atseconduse[2]{\def#1{\def#1{#2}}}
3979 % \end{macrocode}
3980 % \end{macro}
3981 %
3982 % \begin{macro}{\kvt@expandonce@onearg}
3983 % The |\kvt@expandonce@onearg|\marg{cmd}\marg{arg} macro expands to
3984 % \meta{arg} if \meta{cmd} is empty and expands to an |\expandonce| on
3985 % \meta{cmd} with \meta{arg} as argument otherwise.
3986 % This macro is for an |\edef| context in which an empty \meta{cmd}
3987 % should not leave any parentheses around the \meta{arg}.
3988 % \begin{macrocode}
3989 \newcommand\kvt@expandonce@onearg[2]{%
3990 \ifdefequal{#1}{\@empty}{#2}{\expandonce{#1}{#2}}}
3991 % \end{macrocode}
3992 % Note that the alternative of avoiding the conditional (|\ifdefequal|)
3993 % in the above code and using |\@firstofone| instead of |\@empty| for a
3994 % noop in \meta{cmd} does not work:
3995 % \begin{itemize}[nosep]
3996 % \item Using `|\expandonce|\marg{cmd}\marg{arg}' would, by definition
3997 % of |\expandonce|, expand to
3998 % `|\unexpanded\expandafter{\@firstofone}|' and produces the error
3999 % `Argument of |\@firstofone| has an extra |}|'.
4000 % \item Using `|\expandonce{|\meta{cmd}\marg{arg}|}|' would expand to
4001 % `|\unexpanded|\marg{arg}' and, thus, prevent expansion of
4002 % \meta{arg}.
4003 % \end{itemize}
4004 % \end{macro}
4005 %
4006 % \begin{macro}{\kvt@stepcounters}
4007 % The |\kvt@stepcounters|\oarg{delta} macro increments all row counters
4008 % by \meta{delta}. If \meta{delta} is omitted, \meta{delta}=1.
4009 % \begin{macrocode}
4010 \newcommand\kvt@stepcounters[1][1]{%
4011 \addtocounter{kvtRow}{#1}%
4012 \addtocounter{kvtTypeRow}{#1}%
4013 \addtocounter{kvtTotalRow}{#1}}
4014 % \end{macrocode}
4015 % \end{macro}
4016 %
4017 % \begin{macro}{\kvt@CheckMulticolumn}
4018 % The
4019 % |\kvt@CheckMulticolumn|\marg{content}\marg{tname} macro
4020 % checks whether a cell's \meta{content} in a table of type \meta{tname}
4021 % spans multiple columns in one of two ways:
4022 % \begin{enumerate}[nosep]
4023 % \item \meta{content} = |\multicolumn|\marg{n}\marg{align}\marg{content} or
4024 % \item \meta{content} = |\kvt@@@colgroup|\marg{cgname}\marg{n}\marg{align}\marg{content}
4025 % \end{enumerate}
4026 % The first way corresponds to the case that a user of the package
4027 % explicitly assigns a |\multicolumn| expression to a cell in a row.
4028 % The second way is generated by the package when a user assigns a
4029 % normal cell value to a column group key.
4030 % \begin{macrocode}
4031 \newcommand\kvt@CheckMulticolumn[2]{%
4032 % \end{macrocode}
4033 % For parsing \meta{content}, the macro uses |\kvt@CheckMulticolumn@i|
4034 % and adds 5 |\relax| after \meta{content} for the case that
4035 % \meta{content} is empty or too short.
4036 % \begin{macrocode}
4037 \kvt@CheckMulticolumn@i{#2}#1%
4038 \relax\relax\relax\relax\relax\kvt@@undefined}
4039 % \end{macrocode}
4040 % \end{macro}
4041 %
4042 % \begin{macro}{\kvt@CheckMulticolumn@i}
4043 % The
4044 % |\kvt@CheckMulticolumn@i|\marg{tname}\marg{c1}$\cdots$\marg{c5}\marg{ign}|\@undefined|
4045 % macro checks \meta{content} when split into \meta{c1}$\cdots$\meta{c5}
4046 % for one of the two multicolumn cases listed in the description of
4047 % |\kvt@CheckMulticolumn|.
4048 % \begin{macrocode}
4049 \def\kvt@CheckMulticolumn@i#1#2#3#4#5#6#7\kvt@@undefined{%
4050 \ifdefmacro{#2}{%
4051 % \end{macrocode}
4052 % First case: \meta{c1}=|\multicolumn|. In this case, we have
4053 % \meta{c2}=\meta{n}, \meta{c3}=\meta{align}, and
4054 % \meta{c4}=\meta{content}.
4055 % \begin{macrocode}
4056 \ifx#2\multicolumn
4057 \kvt@SetMulticolumn{#4}{#3}{#5}%
4058 \let\kvt@@curcgname\@empty
4059 % \end{macrocode}
4060 % Second case: \meta{c1}=|\kvt@@@colgroup|. In this case, we have
4061 % \meta{c3}=\meta{n}, \meta{c4}=\meta{align}, and
4062 % \meta{c5}=\meta{content}. Moreover, \meta{c2} holds \meta{cgname}.
4063 % \begin{macrocode}
4064 \else\ifx#2\kvt@@@colgroup
4065 \letcs\kvt@@curcolformat{kvt@colgrp@format@#1@#3}%
4066 \def\kvt@@curcgname{#3}%
4067 % \end{macrocode}
4068 % If a row alignment is defined, it overrides the alignment of the
4069 % column group:
4070 % \begin{macrocode}
4071 \ifdefvoid\cmdkvt@Row@align
4072 {\kvt@SetMulticolumn{#5}{#4}{#6}}
4073 {\expandafter
4074 \kvt@SetMulticolumn\expandafter{\cmdkvt@Row@align}{#4}{#6}}%
4075 \fi\fi}{}}
4076 % \end{macrocode}
4077 % \end{macro}
4078 %
4079 % \begin{macro}{\kvt@@@colgroup}
4080 % The |\kvt@@@colgroup| macro is not used as an actual macro but only as
4081 % an identifier for |\kvt@CheckMulticolumn@i|.
4082 % \begin{macrocode}
4083 \newcommand\kvt@@@colgroup{kvt@@@colgroup}
4084 % \end{macrocode}
4085 % \end{macro}
4086 %
4087 % \begin{macro}{\kvt@SetMulticolumn}
4088 % The |\kvt@SetMulticolumn|\marg{align}\marg{n}\marg{content} records
4089 % that \meta{n} cells, starting from the current cell, belong to a
4090 % multicolumn cell with alignment \meta{align} and the given
4091 % \meta{content}.
4092 % \begin{macrocode}
4093 \newcommand\kvt@SetMulticolumn[3]{%
4094 % \end{macrocode}
4095 % First, record \meta{n} in |\kvt@@span|. The subtraction of $-1$ is
4096 % already in preparation for the next column, in which one spanning has
4097 % already been reduced.
4098 % \begin{macrocode}
4099 \kvt@@span=#2\relax \advance\kvt@@span\m@ne
4100 % \end{macrocode}
4101 % Next, unwrap the cell's \meta{content} to |\kvt@@cell| and record the
4102 % |\kvt@@mkmulticolumn| for re-wrapping the content later, after all
4103 % cell formatting has been applied.
4104 % \begin{macrocode}
4105 \def\kvt@@cell{#3}%
4106 \def\kvt@@mkmulticolumn{\kvt@multicolumn{#2}{#1}}}
4107 % \end{macrocode}
4108 % \end{macro}
4109 %
4110 % \begin{macro}{\kvt@unicolumn}
4111 % \begin{macro}{\kvt@multicolumn}
4112 % The |\kvt@unicolumn|\marg{content} macro is the central macro for
4113 % creating a "normal" (non-multicolumn) cell holding the given
4114 % \meta{content}.
4115 % Analogously, the macro
4116 % |\kvt@multicolumn|\marg{align}\marg{n}\marg{content}
4117 % is the central macro for creating a multi-column cell with
4118 % \meta{content}.
4119 % The two macros are only meant to improve code legibility and to
4120 % simplify certain future modifications.
4121 % \begin{macrocode}
4122 \newcommand\kvt@unicolumn[1]{#1}
4123 \newcommand\kvt@multicolumn[3]{\multicolumn{#1}{#2}{#3}}
4124 % \end{macrocode}
4125 % \end{macro}
4126 % \end{macro}
4127 %
4128 % \subsubsection{Table and Row Styles}
4129 %
4130 % The following are the user macros.
4131 %
4132 % \begin{macro}{\kvtNewRowStyle}
4133 % \changes{v2.0}{2019/03/25}{Added the macro}
4134 % \begin{macro}{\kvtRenewRowStyle}
4135 % \changes{v2.0}{2019/03/25}{Added the macro}
4136 % The |\kvtNewRowStyle|\marg{name}\marg{row-options} macro declares
4137 % \meta{name} as a row style and defines it to be equivalent to
4138 % specifying \meta{row-options} directly in the optional argument of
4139 % |\Row|. The macro fails if \meta{name} is already declared as a row
4140 % style.
4141 % \begin{macrocode}
4142 \newcommand\kvtNewRowStyle{\kvt@NewStyle{row}{\kvtRenewRowStyle}}
4143 % \end{macrocode}
4144 % The |\kvtRenewRowStyle|\marg{name}\marg{row-options} macro re-defines
4145 % an already existing row style with new \meta{row-options}.
4146 % \begin{macrocode}
4147 \newcommand\kvtRenewRowStyle{\kvt@RenewStyle{row}{\kvtNewRowStyle}}
4148 % \end{macrocode}
4149 % \end{macro}
4150 % \end{macro}
4151 %
4152 % \begin{macro}{\kvtNewTableStyle}
4153 % \changes{v2.2}{2020/02/24}{Added the macro}
4154 % \begin{macro}{\kvtRenewTableStyle}
4155 % \changes{v2.2}{2020/02/24}{Added the macro}
4156 % The |\kvtNewTableStyle|\marg{name}\marg{options} macro declares
4157 % \meta{name} as a table style and defines it to be equivalent to
4158 % specifying \meta{options} directly in the optional argument of
4159 % a |KeyValTable| environment or of a |\NewKeyValTable|. The macro fails
4160 % if \meta{name} is already declared as a table style.
4161 % \begin{macrocode}
4162 \newcommand\kvtNewTableStyle{\kvt@NewStyle{table}{\kvtRenewTableStyle}}
4163 % \end{macrocode}
4164 % The |\kvtRenewTableStyle|\marg{name}\marg{options} macro re-defines
4165 % an already existing table style with new \meta{options}.
4166 % \begin{macrocode}
4167 \newcommand\kvtRenewTableStyle{\kvt@RenewStyle{table}{\kvtNewTableStyle}}
4168 % \end{macrocode}
4169 % \end{macro}
4170 % \end{macro}
4171 %
4172 % The following are the internal macros that the style code shares.
4173 %
4174 % \begin{macro}{\kvt@NewStyle}
4175 % \begin{macro}{\kvt@RenewStyle}
4176 % The |\kvt@NewStyle|\marg{type}\marg{renewcmd}\marg{name}\marg{options}
4177 % macro defines a new style, \meta{name}, for \meta{type} (|table| or
4178 % |row|) to correspond to \meta{options}.
4179 % Analogously,
4180 % |\kvt@RenewStyle|\marg{type}\marg{newcmd}\marg{name}\marg{options}
4181 % macro re-defines a style.
4182 % \begin{macrocode}
4183 \newcommand\kvt@NewStyle[4]{%
4184 \ifcsundef{kvt@@#1style@#3}
4185 {\csdef{kvt@@#1style@#3}{#4}}
4186 {\kvt@error{The #1 style '#3' is already defined}{Use
4187 \string#2\space to change an existing style.}}}
4188 \newcommand\kvt@RenewStyle[4]{%
4189 \ifcsundef{kvt@@#1style@#3}
4190 {\kvt@error{A #1 style '#3' is not defined}
4191 {Use \string#2\space to define a new #1 style.}}
4192 {\csdef{kvt@@#1style@#3}{#4}}}
4193 % \end{macrocode}
4194 % \end{macro}
4195 % \end{macro}
4196 %
4197 % \begin{macro}{\kvt@UseRowStyles}
4198 % \begin{macro}{\kvt@UseTableStyles}
4199 % \changes{v2.2}{2020/02/24}{Added the macro}
4200 % The |\kvt@UseRowStyles|\marg{styles} and
4201 % |\kvt@UseTableStyles|\marg{styles} macros set the keys for the given,
4202 % comma-separated list of \meta{styles}.
4203 % \begin{macrocode}
4204 \newcommand\kvt@UseRowStyles[1]{%
4205 \kvt@UseStyles{row}{Row}{\kvt@NewRowStyle}{#1}}
4206 \newcommand\kvt@UseTableStyles[1]{%
4207 \kvt@UseStyles{table}{Table}{\kvt@NewTableStyle}{#1}}
4208 % \end{macrocode}
4209 % \end{macro}
4210 % \end{macro}
4211 %
4212 % \begin{macro}{\kvt@UseStyle}
4213 % The |\kvt@UseStyle|\marg{type}\marg{fam}\marg{newcmd}\marg{style}
4214 % macro sets the keys for type \meta{type} based on the \meta{options}
4215 % stored for the given \meta{style}.
4216 % The \meta{fam} identifies the
4217 % \pkgname{xkeyval} family for \meta{type} and \meta{newcmd} is the
4218 % macro for defining new \meta{type} styles.
4219 % \begin{macrocode}
4220 \newcommand\kvt@UseStyle[4]{%
4221 \ifcsundef{kvt@@#1style@#4}
4222 {\kvt@error{A #1 style '#4' is not defined}
4223 {Use \string#3\space to define a new #1 style.}}
4224 {\kvt@setcskeys{kvt@@#1style@#4}{#2}}}
4225 % \end{macrocode}
4226 % \end{macro}
4227 %
4228 % \begin{macro}{\kvt@UseStyles}
4229 % The |\kvt@UseStyles|\marg{type}\marg{fam}\marg{newcmd}\marg{styles}
4230 % macro sets the \meta{type} keys based on the \meta{options} for all
4231 % styles in the comma-separated list \meta{styles}.
4232 % The \meta{fam} identifies the
4233 % \pkgname{xkeyval} family for \meta{type} and \meta{newcmd} is the
4234 % macro for defining new \meta{type} styles.
4235 % \begin{macrocode}
4236 \newcommand\kvt@UseStyles[4]{%
4237 % \end{macrocode}
4238 % We use |\kvt@xkv@disablepreset| to eliminate undesired effects that
4239 % would otherwise be caused by preset values for keys.
4240 % For an example of such side-effect, consider a style "|vis|" that is
4241 % defined as "|hidden=false|". Then,
4242 % |\Row[bg=red,style=vis]{...}|
4243 % causes a
4244 % |\setkeys[kvt]{Row}{hidden=false}|
4245 % to be processed inside the |\setkeys[kvt]{Row}{bg=red,style=vis}|,
4246 % after the |bg=red| is processed.
4247 % The former
4248 % |\setkeys| would then again employ the presets for |Row| (e.g., from a
4249 % |\kvtSet{Row/bg=blue}|) and undesirably overwrite the |bg=red|.
4250 % \begin{macrocode}
4251 \kvt@xkv@disablepreset[kvt]{#2}{%
4252 \forcsvlist{\kvt@UseStyle{#1}{#2}{#3}}{#4}}}
4253 % \end{macrocode}
4254 % \end{macro}
4255 %
4256 % \begin{macro}{\kvt@xkv@disablepreset}
4257 % The |\kvt@xkv@disablepreset|\oarg{prefix}\marg{family}\marg{code}
4258 % disables head presets and tail presets for \meta{family} during the
4259 % expansion of \meta{code}.
4260 % \begin{macrocode}
4261 \newcommand\kvt@xkv@disablepreset[3][KV]{%
4262 \ifnumgreater{\XKV@depth}{1}
4263 {#3}
4264 {\kvt@xkv@savepreset{#1}{#2}{h}%
4265 \kvt@xkv@savepreset{#1}{#2}{t}%
4266 #3%
4267 \kvt@xkv@restorepreset{#1}{#2}{h}%
4268 \kvt@xkv@restorepreset{#1}{#2}{t}}}
4269 % \end{macrocode}
4270 % \end{macro}
4271 % \begin{macro}{\kvt@xkv@savepreset}
4272 % \begin{macro}{\kvt@xkv@restorepreset}
4273 % The auxiliary macro
4274 % |\kvt@xkv@savepreset|\marg{prefix}\marg{family}\marg{h/t}
4275 % saves and unsets the preset keys (head keys for \meta{h/t}=h and tail
4276 % keys otherwise) for \meta{family}. The macro
4277 % |\kvt@xkv@restorepreset|\marg{prefix}\marg{family}\marg{h/t}
4278 % restores the preset keys saved via |\kvt@xkv@savepreset|.
4279 % \begin{macrocode}
4280 \newcommand\kvt@xkv@savepreset[3]{%
4281 \csletcs{kvt@@saved@preset#3}{XKV@#1@#2@preset#3}%
4282 \csundef{XKV@#1@#2@preset#3}}
4283 \newcommand\kvt@xkv@restorepreset[3]{%
4284 \csletcs{XKV@#1@#2@preset#3}{kvt@@saved@preset#3}}
4285 % \end{macrocode}
4286 % \end{macro}
4287 % \end{macro}
4288 %
4289 % \subsection{Collecting Key-Value Table Content}
4290 %
4291 % \begin{macro}{\NewCollectedTable}
4292 % The |\NewCollectedTable|\marg{cname}\marg{tname} macro registers a new
4293 % table for recorded rows under name \meta{cname} for table type
4294 % \meta{tname}. The macro can only be used when
4295 % \meta{cname} is not already defined. It's function is not more than
4296 % memorizing \meta{tname} for \meta{cname}.
4297 % \changes{v2.0}{2019/04/10}{Added the macro}
4298 % \begin{macrocode}
4299 \newcommand\NewCollectedTable[2]{%
4300 \ifcsvoid{kvt@@tnameof@#1}
4301 {\csgdef{kvt@@tnameof@#1}{#2}}
4302 {\kvt@error{Name '#1' for a row collection is already defined}
4303 {Check for other \string\NewCollectedTable{#1}.}}}
4304 % \end{macrocode}
4305 % \end{macro}
4306 %
4307 % \begin{macro}{\CollectRow}
4308 % The |\CollectRow|\oarg{options}\marg{cname}\marg{content} writes a
4309 % |\kvt@RecordedRow| entry to the aux file, protecting fragile parts of
4310 % \meta{content} through |\protected@write|.
4311 % \changes{v2.0}{2019/04/09}{Added the macro}
4312 % \begin{macrocode}
4313 \newcommand\CollectRow[3][]{%
4314 \ifcsvoid{kvt@@tnameof@#2}
4315 {\kvt@error{No row collection with name '#2' defined}
4316 {Use \string\NewCollectedTable in the preamble to define it.}}
4317 {%
4318 % \end{macrocode}
4319 % First check in a local group whether the passed \meta{content} and
4320 % \meta{options} are of a proper syntax.
4321 % \begin{macrocode}
4322 \begingroup
4323 \kvt@setkeys{#1}{Row}%
4324 \kvt@colsetcskeys{kvt@@tnameof@#2}{#3}%
4325 \endgroup
4326 % \end{macrocode}
4327 % Next, write to |\@auxout|.
4328 % \begin{macrocode}
4329 \kvt@protected@write\@auxout{\string\kvt@RecordedRow{#1}{#2}{%
4330 % \end{macrocode}
4331 % In the following, the columns' default values are explicitly added to
4332 % the row. This ensures that defaults are expanded (via the |\write|) at
4333 % the point at which a row is recorded rather than when the row is
4334 % displayed. This allows using |\thepage| as the default value for a
4335 % column with the intuitively expected outcome.
4336 % \begin{macrocode}
4337 \kvt@coldefaults{#2}%
4338 #3}}%
4339 }}
4340 % \end{macrocode}
4341 % \end{macro}
4342 %
4343 % \begin{macro}{\kvt@protected@write}
4344 % The |\kvt@protected@write|\marg{file}\marg{content} macro writes
4345 % \meta{content} to \meta{file}. The write ensures that \meta{content}
4346 % is written in a particularly protected form that
4347 % \begin{enumerate}[noitemsep]
4348 % \item protects ordinarily |\protect|'ed parts via |\protected@write|;
4349 % \begin{macrocode}
4350 \newcommand\kvt@protected@write[2]{\protected@write{#1}
4351 % \end{macrocode}
4352 % \item protects table macros -- like |\thekvtRow| --, which are stored
4353 % in the \pkgname{etoolbox} list |\kvt@@writeprotected@cmds|, by
4354 % defining them to expand to their own name -- delaying the actual
4355 % expansion until when the file's contents is expanded;
4356 % \begin{macrocode}
4357 {\def\do##1{\def##1{\string##1}}%
4358 \dolistloop{\kvt@@writeprotected@cmds}%
4359 % \end{macrocode}
4360 % \item protects table counters like |kvtRow| by adapting the
4361 % counter-formatting macros to treat table counters differently from
4362 % other counters.
4363 % \begin{macrocode}
4364 \forlistloop{\kvt@writeprotect@fmt}{\kvt@@numberformatters}}
4365 {#2}}
4366 % \end{macrocode}
4367 % \end{enumerate}
4368 % \end{macro}
4369 %
4370 % \begin{macro}{\kvt@writeprotect@fmt}
4371 % The |\kvt@writeprotect@fmt|\marg{fmt-csname} macro takes the name of a
4372 % counter-formatting macro (e.g., the name "arabic" for the macro|\arabic|)
4373 % and redefines it such that counters declared via
4374 % |\kvtDeclareTableCounters| are not expanded while all other counters
4375 % are treated normally.
4376 % \begin{macrocode}
4377 \newcommand\kvt@writeprotect@fmt[1]{%
4378 % \end{macrocode}
4379 % First, save a copy of \meta{fmt-csname} and then redefine
4380 % \meta{fmt-csname}.
4381 % \begin{macrocode}
4382 \csletcs{kvt@@fmt@#1}{#1}%
4383 \csdef{#1}##1{%
4384 % \end{macrocode}
4385 % The |kvt@@c@##1| in the following condition is a csname that is
4386 % defined by |\kvtDeclareTableCounters| if |##1| (the counter to be
4387 % formatted) has been declared as a table counter. If the macro is
4388 % defined, then \meta{fmt-csname} expands to its name with its argument.
4389 % Otherwise, the saved copy of \meta{fmt-csname} is expanded, producing
4390 % the actual counter value.
4391 % \begin{macrocode}
4392 \ifcsdef{kvt@@c@##1}
4393 {\expandafter\string\csname#1\endcsname{##1}}
4394 {\csname kvt@@fmt@#1\endcsname{##1}}}}
4395 % \end{macrocode}
4396 % \end{macro}
4397 %
4398 % \begin{macro}{\kvtDeclareTableMacros}
4399 % The |\kvtDeclareTableMacros|\marg{macro-list} macro declares all
4400 % the macros in \meta{macro-list} to be "table macros", i.e.,
4401 % macros that should be expanded inside the |KeyValTable| environment
4402 % rather than in a |\CollectRow|.
4403 % The macro records the \meta{macro-list} by appending its elements to
4404 % |\kvt@@writeprotected@cmds|. The actual expansion control is performed
4405 % by |\kvt@protected@write|.
4406 % \begin{macrocode}
4407 \newcommand\kvtDeclareTableMacros[1]{%
4408 \forcsvlist{\listadd\kvt@@writeprotected@cmds}{#1}}
4409 % \end{macrocode}
4410 % \end{macro}
4411 % \begin{macro}{\kvt@@writeprotected@cmds}
4412 % Initially empty \pkgname{etoolbox} list of table macros.
4413 % \begin{macrocode}
4414 \newcommand\kvt@@writeprotected@cmds{}
4415 % \end{macrocode}
4416 % \end{macro}
4417 %
4418 % \begin{macro}{\kvtDeclareTableCounters}
4419 % The |\kvtDeclareTableCounters|\marg{counter-list} macro declares all
4420 % the counters in \meta{counter-list} to be "table counters", i.e.,
4421 % counters that should be expanded inside the |KeyValTable| environment
4422 % rather than in a |\CollectRow|.
4423 % The macro only marks the counters by defining
4424 % \cs{kvt@@c@\meta{counter}}. The actual expansion control is performed
4425 % by |\kvt@writeprotect@fmt|.
4426 % \begin{macrocode}
4427 \newcommand\kvtDeclareTableCounters[1]{%
4428 \def\do##1{\cslet{kvt@@c@##1}\@ne}%
4429 \docsvlist{#1}}
4430 % \end{macrocode}
4431 % \end{macro}
4432 %
4433 % \begin{macro}{\kvtDeclareCtrFormatters}
4434 % The |\kvtDeclareCtrFormatters|\marg{macro-list} macro declares all the
4435 % macros in \meta{macro-list} to be counter-formatting macros, i.e.,
4436 % macros that take a \hologo{LaTeX} counter as their argument and format
4437 % the counter's value, e.g., arabic, alphabetic, or as a roman number.
4438 % The macro records the \meta{macro-list} by appending the csnames of
4439 % its elements to |\kvt@@numberformatters|. The actual expansion
4440 % control for the macros in \meta{macro-list} is performed by
4441 % |\kvt@writeprotect@fmt|.
4442 % \begin{macrocode}
4443 \newcommand\kvtDeclareCtrFormatters[1]{%
4444 \def\do##1{\listeadd\kvt@@numberformatters{%
4445 \expandafter\@gobble\string##1}}%
4446 \docsvlist{#1}}
4447 % \end{macrocode}
4448 % \end{macro}
4449 % \begin{macro}{\kvt@@writeprotected@cmds}
4450 % Initially empty \pkgname{etoolbox} list of counter-formatting macros.
4451 % \begin{macrocode}
4452 \newcommand\kvt@@numberformatters{}
4453 % \end{macrocode}
4454 % \end{macro}
4455 %
4456 % The following registers the row counter macros as well as the row
4457 % counters themselves as macros/counters that shall only be expanded
4458 % inside the respective table.
4459 % \begin{macrocode}
4460 \kvtDeclareTableMacros{\thekvtRow,\thekvtTypeRow,\thekvtTotalRow}
4461 \kvtDeclareTableCounters{kvtRow,kvtTypeRow,kvtTotalRow}
4462 % \end{macrocode}
4463 % The following registers macros that format counter values. This
4464 % registering is necessary such that |\kvt@writeprotect@fmt| can protect
4465 % table counters from expansion.
4466 % \begin{macrocode}
4467 \kvtDeclareCtrFormatters{\arabic,\alph,\Alph,\roman,\Roman,\fnsymbol}
4468 % \end{macrocode}
4469 %
4470 % \begin{macro}{\kvt@coldefault}
4471 % \begin{macro}{\kvt@coldefaults}
4472 % \begin{macro}{\kvt@coldefaults@i}
4473 % The |\kvt@coldefault|\marg{tname}\marg{cname} macro expands to
4474 % "\meta{cname}|={|\meta{default}|},|", where \meta{default} is the
4475 % default value of column \meta{cname} in table type \meta{tname}. If
4476 % \meta{default} is empty, then the macro expands to the empty string.
4477 % The |\kvt@coldefaults@i|\marg{tname} macro expands to the
4478 % comma-separated list of the |\kvt@coldefault| for all \emph{displayed}
4479 % columns of table type \meta{tname}.
4480 % Finally, the |\kvt@coldefaults|\marg{cname} macro expands to
4481 % |\kvt@coldefaults| for the table type assigned to \meta{cname} via
4482 % |\NewCollectedTable|.
4483 % \begin{macrocode}
4484 \newcommand\kvt@coldefaults[1]{%
4485 \kvt@coldefaults@i{\csuse{kvt@@tnameof@#1}}}
4486 \newcommand\kvt@coldefaults@i[1]{%
4487 \forlistcsloop{\kvt@coldefault{#1}}{kvt@displaycols@#1}}
4488 \newcommand\kvt@coldefault[2]{\ifcsvoid{kvt@col@default@#1@#2}{}{%
4489 #2={\csuse{kvt@col@default@#1@#2}},}}
4490 % \end{macrocode}
4491 % \end{macro}
4492 % \end{macro}
4493 % \end{macro}
4494 %
4495 % \begin{macro}{\kvt@RecordedRow}
4496 % The |\kvt@RecordedRow|\marg{options}\marg{cname}\marg{content}
4497 % appends a |\Row| with \meta{options} and \meta{content} to a global
4498 % macro for \meta{cname}.
4499 % \begin{macrocode}
4500 \newcommand\kvt@RecordedRow[3]{%
4501 \csgappto{kvt@@rowsof@#2}{\Row[{#1}]{#3}}}
4502 % \end{macrocode}
4503 % \end{macro}
4504 %
4505 % \begin{macro}{\ShowCollectedTable}
4506 % The |\ShowCollectedTable|\oarg{options}\marg{cname}
4507 % produces a |KeyValTable| table for the rows stored under the given
4508 % \meta{cname}, table options \meta{options}.
4509 % \changes{v2.0}{2019/04/09}{Added the macro}
4510 % \begin{macrocode}
4511 \newcommand\ShowCollectedTable[2][]{%
4512 \ifcsvoid{kvt@@tnameof@#2}
4513 {\kvt@error{No row collection with name '#2' defined}
4514 {Use \string\NewCollectedTable in the preamble to define it.}}
4515 {\ifcsvoid{kvt@@rowsof@#2}
4516 {\kvt@warn{No row data available for name '#2'.
4517 A LaTeX rerun might be needed^^M
4518 for the row data to be available}%
4519 \kvt@tableofcname{#2}{#1}{???\tabularnewline}}%
4520 {\kvt@tableofcname{#2}{#1}{\csuse{kvt@@rowsof@#2}}}}}
4521 % \end{macrocode}
4522 % \end{macro}
4523 %
4524 % \begin{macro}{\kvt@tableof}
4525 % \begin{macro}{\kvt@tableofcname}
4526 % \begin{macro}{\kvt@tableofcname@i}
4527 % The |\kvt@tableof|\marg{tname}\marg{options}\marg{content} expands to
4528 % a |KeyValTable| environment for table type \meta{tname} with
4529 % \meta{options} and environment body \meta{content}.
4530 % The |\kvt@tableofcname|\marg{cname}\marg{options}\marg{content}
4531 % expands to a |\kvt@tableof| where \meta{tname} is the table type
4532 % assigned to \meta{cname}.
4533 % Finally, |\kvt@tableofcname@i| is an auxiliary macro for expansion
4534 % control.
4535 % \begin{macrocode}
4536 \newcommand\kvt@tableof[3]{%
4537 \begin{KeyValTable}[{#2}]{#1}%
4538 #3%
4539 \end{KeyValTable}}
4540 \newcommand\kvt@tableofcname[1]{\expandafter
4541 \kvt@tableofcname@i\expandafter{\csname kvt@@tnameof@#1\endcsname}}
4542 \newcommand\kvt@tableofcname@i[1]{\expandafter
4543 \kvt@tableof\expandafter{#1}}
4544 % \end{macrocode}
4545 % \end{macro}
4546 % \end{macro}
4547 % \end{macro}
4548 %
4549 % \subsubsection{Table Content from Files}
4550 %
4551 % \begin{macro}{\ShowKeyValTableFile}
4552 % The |\ShowKeyValTableFile|\oarg{options}\marg{tname}\marg{filename}
4553 % loads the content of the file with name \meta{filename} and places it
4554 % inside the body of a |KeyValTable| environment of type \meta{tname} with
4555 % the given \meta{options}. That is, the filename should contain the rows
4556 % of the table.
4557 % \changes{v2.0}{2019/03/25}{Added the macro}
4558 % \begin{macrocode}
4559 \newcommand\ShowKeyValTableFile[3][]{%
4560 \IfFileExists{#3}
4561 {\begin{KeyValTable}[{#1}]{#2}\@@input#3 \end{KeyValTable}}%
4562 {\kvt@error{No KeyValTable file '#3'}
4563 {Check whether the file really exists or whether there is a
4564 typo in the argument '#3'}}}
4565 % \end{macrocode}
4566 % \end{macro}
4567 %
4568 % \subsubsection{Legacy Variant}
4569 %
4570 % \begin{macro}{\ShowKeyValTable}
4571 % The |\ShowKeyValTable|\oarg{options}\marg{tname} macro shows a table
4572 % of type \meta{tname} with given \meta{options}. The rows must have
4573 % been collected using |\Row| in |KeyValTableContent| environments or
4574 % using |\AddKeyValRow|.
4575 % \begin{macrocode}
4576 \newcommand\ShowKeyValTable[2][]{%
4577 \begin{KeyValTable}[#1]{#2}%
4578 \csuse{kvt@rows@#2}%
4579 \end{KeyValTable}%
4580 \csdef{kvt@rows@#2}{}}
4581 % \end{macrocode}
4582 % \end{macro}
4583 %
4584 % \begin{macro}{\AddKeyValRow}
4585 % The |\AddKeyValRow|\marg{tname}\oarg{options}\marg{content} adds a row
4586 % with a given \meta{content} to the existing content for the next table
4587 % of type \meta{tname} that is displayed with |\ShowKeyValTable|. The
4588 % \meta{content} and \meta{options} parameters are the same as with
4589 % |\kvt@AddKeyValRow|.
4590 % The resulting row (|\kvt@@row|) is globally appended to
4591 % \cs{kvt@rows@\meta{tname}}.
4592 % \begin{macrocode}
4593 \newcommand\AddKeyValRow[1]{%
4594 \kvt@AddKeyValRow
4595 {\begingroup}
4596 {\csxappto{kvt@rows@#1}{\expandonce{\kvt@@row}}\endgroup}
4597 {#1}}
4598 % \end{macrocode}
4599 % \end{macro}
4600 %
4601 % \begin{environment}{KeyValTableContent}
4602 % The |KeyValTableContent|\marg{tname} environment acts as a container
4603 % in which rows can be specified without automatically being displayed.
4604 % In this environment, rows can be specified via the
4605 % |\Row|\marg{content} macro, which is supposedly shorter than using
4606 % |\AddKeyValRow|\meta{tname}\meta{content}.
4607 % \begin{macrocode}
4608 \newenvironment{KeyValTableContent}[1]{%
4609 \def\Row{\AddKeyValRow{#1}}}{}%
4610 % \end{macrocode}
4611 % \end{environment}
4612 %
4613 %
4614 % \subsection{Package Options}
4615 %
4616 % The following option allows specifying a version for (hopefully)
4617 % compatibility with the respective old version.
4618 % \changes{v2.0}{2019/05/11}{added package option "compat"}
4619 % \begin{macrocode}
4620 \define@cmdkey[kvt]{PackageOptions}[kvt@@pkg@]{compat}{}
4621 % \end{macrocode}
4622 %
4623 % Next, set default package options and process them.
4624 % \begin{macrocode}
4625 \ExecuteOptionsX[kvt]<PackageOptions>{%
4626 compat=2.0,
4627 }
4628 \ProcessOptionsX[kvt]<PackageOptions>\relax
4629 % \end{macrocode}
4630 %
4631 %
4632 % \subsection{Compatibility}
4633 %
4634 % \begin{macro}{\kvt@NewCompat}
4635 % The
4636 % |\kvt@IfVersion|\marg{relation}\marg{version}\marg{iftrue}\marg{iffalse}
4637 % macro expands to \meta{iftrue} if the requested package version is in
4638 % the given \meta{relation} ($<$, $<$, or $=$) to \meta{version}.
4639 % Otherwise, the macro expands to \meta{iffalse}.
4640 % Package versions are requested via the |compat| package option. If no
4641 % version is explicitly requested, the newest version is implicitly
4642 % assumed to be requested.
4643 % \meta{code} as
4644 % \begin{macrocode}
4645 \newcommand\kvt@IfVersion[2]{%
4646 \ifdimcomp{\kvt@@pkg@compat pt}{#1}{#2pt}}
4647 % \end{macrocode}
4648 % \end{macro}
4649 %
4650 % Before v2.0, \pkgname{tabu} was the default table environment.
4651 % \begin{macrocode}
4652 \kvt@IfVersion{<}{2.0}{%
4653 \metatblRequire{tabu,longtabu}
4654 \kvt@RegisterShape{onepage}{tabu}{tabu}
4655 \kvt@RegisterShape{multipage}{longtabu}{longtabu}
4656 }{%
4657 \metatblRequire{tabularx,longtable,xltabular}
4658 \kvt@RegisterShape{onepage}{tabular}{tabularx}
4659 \kvt@RegisterShape{multipage}{longtable}{xltabular}
4660 }
4661 % \end{macrocode}
4662 %
4663 % Before v2.0, the second optional argument of |\NewKeyValTable|
4664 % specified the header rows only. Only afterwards, that argument
4665 % received a key-value syntax.
4666 % \begin{macrocode}
4667 \kvt@IfVersion{<}{2.0}{%
4668 \renewcommand\kvt@parselayout[2]{\kvt@parseheadrows{#2}{#1}}%
4669 }{}
4670 % \end{macrocode}
4671 %
4672 %\iffalse
4673 %</package>
4674 %\fi
4675 % \Finale
4676 \endinput