summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tabularray/tabularray.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/tabularray/tabularray.tex')
-rw-r--r--Master/texmf-dist/doc/latex/tabularray/tabularray.tex264
1 files changed, 252 insertions, 12 deletions
diff --git a/Master/texmf-dist/doc/latex/tabularray/tabularray.tex b/Master/texmf-dist/doc/latex/tabularray/tabularray.tex
index 95416b6d468..94c9421016b 100644
--- a/Master/texmf-dist/doc/latex/tabularray/tabularray.tex
+++ b/Master/texmf-dist/doc/latex/tabularray/tabularray.tex
@@ -1,7 +1,7 @@
% -*- coding: utf-8 -*-
% !TEX program = lualatex
\documentclass[oneside]{book}
-\newcommand*{\myversion}{2022A}
+\newcommand*{\myversion}{2022B}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
\usepackage[a4paper,margin=2.5cm]{geometry}
@@ -18,7 +18,7 @@
\usepackage[firstpage=true]{background}
\backgroundsetup{contents={}}
-\UseTblrLibrary{amsmath,booktabs,counter,diagbox,siunitx,varwidth}
+\UseTblrLibrary{amsmath,booktabs,counter,diagbox,functional,siunitx,varwidth}
\usepackage{hyperref}
\hypersetup{
@@ -2463,7 +2463,7 @@ If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore! co
\end{tblr}
\end{demohigh}
-From version \verb!2021N!, trim options (\verb!l!, \verb!r!, \verb!lr!)
+From version 2021N (2021-09-01), trim options (\verb!l!, \verb!r!, \verb!lr!)
for \verb!\cmidrule! command are also supported.
\begin{demohigh}
@@ -2541,7 +2541,8 @@ and the other half to \verb!abovesep! of current row.
\end{booktabs}
\end{demohigh}
-From version 2022A, there is a \verb!longtabs! environment for writing long \verb!booktabs! tables,
+From version 2022A (2022-03-01), there is a \verb!longtabs! environment
+for writing long \verb!booktabs! tables,
and a \verb!talltabs! environment for writing tall \verb!booktabs! tables.
\section{Library \texttt{counter}}
@@ -2594,6 +2595,228 @@ $\begin{tblr}{|c|cc|}
\end{tblr}$
\end{demohigh}
+\section{Library \texttt{functional}}
+
+With \verb!\UseTblrLibrary{functional}! in the preamble of the document,
+\verb!tabularray! will load \href{https://ctan.org/pkg/functional}{\texttt{functional}} package,
+and define outer key \verb!evaluate! and inner key \verb!process!.
+These two new keys are useful for doing functional programming inside tables.
+
+\subsection{Outer key \texttt{evaluate} in action}
+
+With outer key \verb!evaluate!, you can evaluate every occurrence of a specified protected function
+(defined with \verb!\prgNewFunction!) and replace it with the return value before splitting the table body.
+
+The first application of \verb!evaluate! key is for inputting files inside tables.
+Assume you have two files \verb!test1.tmp! and \verb!test2.tmp! with the following contents:
+
+\begin{filecontents*}[overwrite]{test1.tmp}
+Some & Some \\
+\end{filecontents*}
+\begin{filecontents*}[overwrite]{test2.tmp}
+Other & Other \\
+\end{filecontents*}
+
+\begin{codehigh}
+\begin{filecontents*}[overwrite]{test1.tmp}
+Some & Some \\
+\end{filecontents*}
+\end{codehigh}
+
+\begin{codehigh}
+\begin{filecontents*}[overwrite]{test2.tmp}
+Other & Other \\
+\end{filecontents*}
+\end{codehigh}
+
+Then you can input them with outer specification \verb!evaluate=\fileInput!.
+The \verb!\fileInput! function is provided by \verb!functional! package.
+
+\begin{demohigh}
+\begin{tblr}[evaluate=\fileInput]{hlines}
+ Row1 & 1 \\
+ \fileInput{test1.tmp}
+ Row3 & 3 \\
+ \fileInput{test2.tmp}
+ Row5 & 5 \\
+\end{tblr}
+\end{demohigh}
+
+In general, you can define your functions which return parts of table contents,
+and use \verb!evaluate! key to evaluate them inside tables.
+
+\begin{demohigh}
+\IgnoreSpacesOn
+\prgNewFunction \someFunc {m} {
+ \prgReturn {#1 & #1 \\}
+}
+\IgnoreSpacesOff
+\begin{tblr}[evaluate=\someFunc]{hlines}
+ Row1 & 1 \\
+ \someFunc{Text}
+ Row3 & 3 \\
+ \someFunc{Text}
+ Row5 & 5 \\
+\end{tblr}
+\end{demohigh}
+
+\begin{demohigh}
+\IgnoreSpacesOn
+\prgNewFunction \otherFunc {} {
+ \prgReturn {Other & Other \\}
+}
+\IgnoreSpacesOff
+\begin{tblr}[evaluate=\otherFunc]{hlines}
+ Row1 & 1 \\
+ \otherFunc
+ Row3 & 3 \\
+ \otherFunc
+ Row5 & 5 \\
+\end{tblr}
+\end{demohigh}
+
+You can even generate the whole table with some function.
+
+\begin{demohigh}
+\IgnoreSpacesOn
+\prgNewFunction \makeEmptyTable {mm} {
+ \tlSet \lTmpaTl {\intReplicate {\intEval{#2-1}} {&}}
+ \tlPutRight \lTmpaTl {\\}
+ \intReplicate {#1} {\tlUse \lTmpaTl}
+}
+\IgnoreSpacesOff
+\begin{tblr}[evaluate=\makeEmptyTable]{hlines,vlines}
+ \makeEmptyTable{3}{7}
+\end{tblr}
+\end{demohigh}
+
+\subsection{Inner key \texttt{process} in action}
+
+With inner key \verb!process!, you can modify the contents and styles before the table is built.
+Several public functions defined with \verb!\prgNewFuncton! are provided for you:
+
+\begin{itemize}
+ \item \verb!\cellGetText{<rownum>}{<colnum>}!
+ \item \verb!\cellSetText{<rownum>}{<colnum>}{<text>}!
+ \item \verb!\cellSetStyle{<rownum>}{<colnum>}{<style>}!
+ \item \verb!\rowSetStyle{<rownum>}{<style>}!
+ \item \verb!\columnSetStyle{<colnum>}{<style>}!
+\end{itemize}
+
+As the first example, let's calculate the sums of cells column by column:
+
+\IgnoreSpacesOn
+\prgNewFunction \funcSum {} {
+ \intStepOneInline {1} {\arabic{colcount}} {
+ \intZero \lTmpaInt
+ \intStepOneInline {1} {\arabic{rowcount}-1} {
+ \intAdd \lTmpaInt {\cellGetText {####1} {##1}}
+ }
+ \cellSetText {\expWhole{\arabic{rowcount}}} {##1} {\intUse\lTmpaInt}
+ }
+}
+\IgnoreSpacesOff
+\begin{codehigh}
+\IgnoreSpacesOn
+\prgNewFunction \funcSum {} {
+ \intStepOneInline {1} {\arabic{colcount}} {
+ \intZero \lTmpaInt
+ \intStepOneInline {1} {\arabic{rowcount}-1} {
+ \intAdd \lTmpaInt {\cellGetText {####1} {##1}}
+ }
+ \cellSetText {\expWhole{\arabic{rowcount}}} {##1} {\intUse\lTmpaInt}
+ }
+}
+\IgnoreSpacesOff
+\end{codehigh}
+
+\begin{demohigh}
+\begin{tblr}{colspec={rrr},process=\funcSum}
+\hline
+ 1 & 2 & 3 \\
+ 4 & 5 & 6 \\
+ 7 & 8 & 9 \\
+\hline
+ & & \\
+\hline
+\end{tblr}
+\end{demohigh}
+
+Now, let's set background colors of cells depending on their contents:
+
+\IgnoreSpacesOn
+\prgNewFunction \funcColor {} {
+ \intStepOneInline {1} {\arabic{rowcount}} {
+ \intStepOneInline {1} {\arabic{colcount}} {
+ \intSet \lTmpaInt {\cellGetText {##1} {####1}}
+ \intCompareTF {\lTmpaInt} > {0}
+ {\cellSetStyle {##1} {####1} {bg=purple8}}
+ {\cellSetStyle {##1} {####1} {bg=olive8}}
+ }
+ }
+}
+\IgnoreSpacesOff
+\begin{codehigh}
+\IgnoreSpacesOn
+\prgNewFunction \funcColor {} {
+ \intStepOneInline {1} {\arabic{rowcount}} {
+ \intStepOneInline {1} {\arabic{colcount}} {
+ \intSet \lTmpaInt {\cellGetText {##1} {####1}}
+ \intCompareTF {\lTmpaInt} > {0}
+ {\cellSetStyle {##1} {####1} {bg=purple8}}
+ {\cellSetStyle {##1} {####1} {bg=olive8}}
+ }
+ }
+}
+\IgnoreSpacesOff
+\end{codehigh}
+
+\begin{demohigh}
+\begin{tblr}{hlines,vlines,cells={r,$},process=\funcColor}
+ -1 & 2 & 3 \\
+ 4 & 5 & -6 \\
+ 7 & -8 & 9 \\
+\end{tblr}
+\end{demohigh}
+
+We can also use color series of \verb!xcolor! package to color table rows:
+
+\definecolor{lightb}{RGB}{217,224,250}
+\definecolorseries{tblrow}{rgb}{last}{lightb}{white}
+\resetcolorseries[3]{tblrow}
+\IgnoreSpacesOn
+\prgNewFunction \funcSeries {} {
+ \intStepOneInline {1} {\arabic{rowcount}} {
+ \tlSet \lTmpaTl {\intMathMod {##1-1} {3}}
+ \rowSetStyle {##1} {\expWhole{bg=tblrow!![\lTmpaTl]}}
+ }
+}
+\IgnoreSpacesOff
+\begin{codehigh}
+\definecolor{lightb}{RGB}{217,224,250}
+\definecolorseries{tblrow}{rgb}{last}{lightb}{white}
+\resetcolorseries[3]{tblrow}
+\IgnoreSpacesOn
+\prgNewFunction \funcSeries {} {
+ \intStepOneInline {1} {\arabic{rowcount}} {
+ \tlSet \lTmpaTl {\intMathMod {##1-1} {3}}
+ \rowSetStyle {##1} {\expWhole{bg=tblrow!![\lTmpaTl]}}
+ }
+}
+\IgnoreSpacesOff
+\end{codehigh}
+
+\begin{demohigh}
+\begin{tblr}{hlines,process=\funcSeries}
+ Row1 & 1 \\
+ Row2 & 2 \\
+ Row3 & 3 \\
+ Row4 & 4 \\
+ Row5 & 5 \\
+ Row6 & 6 \\
+\end{tblr}
+\end{demohigh}
+
\section{Library \texttt{siunitx}}
When writing \verb!\UseTblrLibrary{siunitx}! in the preamble of the document,
@@ -2603,7 +2826,7 @@ and defines \verb!S! column as \verb!Q! column with \verb!si! key.
\begin{demohigh}
\begin{tblr}{
hlines, vlines,
- colspec={S[table-format=3.2]S[table-format=3.2]},
+ colspec={S[table-format=3.2]S[table-format=3.2]}
}
{{{Head}}} & {{{Head}}} \\
111 & 111 \\
@@ -2624,7 +2847,23 @@ and defines \verb!S! column as \verb!Q! column with \verb!si! key.
\end{tblr}
\end{demohigh}
-Note that you need to use \underline{\color{red3}triple} pairs of braces to guard non-numeric cells.
+Note that you need to use \underline{\color{red3}triple} pairs of curly braces to guard non-numeric cells.
+But it is cumbersome to enclose each cell with braces. From version 2022B (2022-06-01)
+a new key \verb!guard! is provided for cells and rows. With \verb!guard! key the previous example
+can be largely simplified.
+
+\begin{demohigh}
+\begin{tblr}{
+ hlines, vlines,
+ colspec={Q[si={table-format=3.2},c]Q[si={table-format=3.2},c]},
+ row{1} = {guard}
+}
+ Head & Head \\
+ 111 & 111 \\
+ 2.1 & 2.2 \\
+ 33.11 & 33.22 \\
+\end{tblr}
+\end{demohigh}
Also you must use \verb!l!, \verb!c! or \verb!r! to set horizontal alignment for non-numeric cells:
\nopagebreak
@@ -2635,12 +2874,13 @@ Also you must use \verb!l!, \verb!c! or \verb!r! to set horizontal alignment for
Q[si={table-format=3.2,table-number-alignment=left},l,blue7]
Q[si={table-format=3.2,table-number-alignment=center},c,teal7]
Q[si={table-format=3.2,table-number-alignment=right},r,purple7]
- }
+ },
+ row{1} = {guard}
}
- {{{Head}}} & {{{Head}}} & {{{Head}}} \\
- 111 & 111 & 111 \\
- 2.1 & 2.2 & 2.3 \\
- 33.11 & 33.22 & 33.33 \\
+ Head & Head & Head \\
+ 111 & 111 & 111 \\
+ 2.1 & 2.2 & 2.3 \\
+ 33.11 & 33.22 & 33.33 \\
\end{tblr}
\end{demohigh}
@@ -2673,7 +2913,7 @@ After setting \verb!measure=vbox!, it will use \verb!\vbox! to measure cell widt
\end{tblr}
\end{demohigh}
-From version 2022A, you can remove extra space above and below lists,
+From version 2022A (2022-03-01), you can remove extra space above and below lists,
by adding option \verb!stretch=-1!.
The following example also needs \verb!enumitem! package and its \verb!nosep! option: