tabularray.tex

% -*- coding: utf-8 -*-
% !TEX program = lualatex
\documentclass[oneside]{book}
\newcommand*{\myversion}{2024A}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}

\usepackage[a4paper,margin=2.5cm]{geometry}

\setlength{\parindent}{0pt}
\setlength{\parskip}{4pt plus 1pt minus 1pt}

\makeatletter
\ExplSyntaxOn
\NewDocumentCommand\MyDebugSingle{m}{
  \@ifpackageloaded{docmute}{#1}{
    \str_if_eq:onTF{\jobname}{tabularray}{#1}{
      \sys_ensure_backend:
      \debug_on:n{check-declarations}
      #1
      \debug_off:n{check-declarations}
    }
  }
}
\ExplSyntaxOff
\makeatother
\MyDebugSingle{\usepackage{tabularray}}

\usepackage{codehigh} % https://ctan.org/pkg/codehigh
\usepackage{array,multirow,amsmath}
\usepackage{chemmacros,environ}
\usepackage{enumitem}

\usepackage[firstpage=true]{background}
\backgroundsetup{contents={}}

\UseTblrLibrary{
  amsmath,booktabs,counter,diagbox,functional,siunitx,varwidth
}

\usepackage{hyperref}
\hypersetup{
  colorlinks=true,
  urlcolor=blue3,
  linkcolor=blue3,
}

\usepackage{tcolorbox}
\tcbset{sharp corners, boxrule=0.5pt, colback=red9}

\usepackage{float}
%\usepackage{enumerate}

\setcounter{tocdepth}{1}

\newcommand*{\K}[1]{\texttt{#1}}
\newcommand*{\V}[1]{\texttt{#1}}
\newcommand*{\None}{$\times$}

\NewTblrEnviron{newtblr}
\SetTblrOuter[newtblr]{long}
\SetTblrInner[newtblr]{
  hlines = {white}, column{1,2} = {co=1}, colsep = 5pt,
  row{odd} = {brown8}, row{even} = {gray8},
  row{1} = {fg=white, bg=purple2, font=\bfseries\sffamily},
}

\NewTblrEnviron{spectblr}
\SetTblrOuter[spectblr]{long}
\SetTblrInner[spectblr]{
  hlines = {white}, column{2} = {co=1}, colsep = 5pt,
  row{odd} = {brown8}, row{even} = {gray8},
  row{1} = {fg=white, bg=purple2, font=\bfseries\sffamily},
  rowhead = 1,
}

\newcommand{\mywarning}[1]{%
  \begin{tcolorbox}
  The interfaces in this #1 should be seen as
  \textcolor{red3}{\bfseries experimental}
  and are likely to change in future releases, if necessary.
  Don’t use them in important documents.
  \end{tcolorbox}
}

%\renewcommand*{\thefootnote}{*}

\colorlet{highback}{azure9}
\CodeHigh{language=latex/table,style/main=highback,style/code=highback}
\NewCodeHighEnv{code}{style/main=gray9,style/code=gray9}
\NewCodeHighEnv{demo}{style/main=gray9,style/code=gray9,demo}

%\CodeHigh{lite}

\begin{document}

\savegeometry{standard}
\newgeometry{left=0pt,right=0pt}

\begin{titlepage}

\backgroundsetup{
  scale = 1,
  angle = 0,
  opacity = 1,
  %color = black,
  contents = {
    \begin{tblr}{
      width = \paperwidth, columns = {1}, rows= {4em, gray9},
      hlines = {2.8pt,white}, vlines = {2.8pt,white},
    }
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
      & & & & & & & & & & & & & & \\
    \end{tblr}
  }
}

\noindent
\begin{tblr}{
  colspec = {rX}, colsep = 8mm, hlines = {2pt, white},
  row{odd} = {azure8}, row{even} = {gray8},
  row{1} = {6em,azure2,fg=white,font=\LARGE\bfseries\sffamily},
  row{2-Z} = {3em,font=\Large},
}
  Tabularray & Typeset Tabulars and Arrays with \LaTeX3 \\
  Author     & Jianrui Lyu (tolvjr@163.com) \\
  Version    & \myversion\ (\the\year-\mylpad\month-\mylpad\day) \\
  Code       & \url{https://github.com/lvjr/tabularray} \\
  Code       & \url{https://bitbucket.org/lvjr/tabularray} \\
  Support    & \url{https://github.com/lvjr/tabularray/discussions} \\
  Support    & \url{https://topanswers.xyz/tex} \\
  Issue      & \url{https://github.com/lvjr/tabularray/issues} \\
\end{tblr}

\begin{codehigh}[boxsep=4mm]
\begin{tblr}{
  colspec = {rX}, colsep = 8mm, hlines = {2pt, white},
  row{odd} = {azure8}, row{even} = {gray8},
  row{1} = {6em,azure2,fg=white,font=\LARGE\bfseries\sffamily},
  row{2-Z} = {3em,font=\Large},
}
  Tabularray & Typeset Tabulars and Arrays with \LaTeX3 \\
  Author     & Jianrui Lyu (tolvjr@163.com) \\
  Version    & \myversion\ (\the\year-\mylpad\month-\mylpad\day) \\
  Code       & \url{https://github.com/lvjr/tabularray} \\
  Code       & \url{https://bitbucket.org/lvjr/tabularray} \\
  Support    & \url{https://github.com/lvjr/tabularray/discussions} \\
  Support    & \url{https://topanswers.xyz/tex} \\
  Issue      & \url{https://github.com/lvjr/tabularray/issues} \\
\end{tblr}
\end{codehigh}

\end{titlepage}

\loadgeometry{standard}

\tableofcontents

\chapter{Overview of Features}

Before using \verb!tabularray! package, it is better to know how to typeset simple text and
math tables with traditional \verb!tabular!, \verb!tabularx! and \verb!array! environments,
because we will compare \verb!tblr! environment from \verb!tabularray! package with these
environments. You may read web pages on LaTeX tables on
\href{https://www.learnlatex.org/en/lesson-08}{LearnLaTeX} and
\href{https://www.overleaf.com/learn/latex/Tables}{Overleaf} first.

\section{Vertical Space}

After loading \verb!tabularray! package in the preamble,
we can use \verb!tblr! environments to typeset tabulars and arrays.
The name \verb!tblr! is short for \verb!tabularray! or \verb!top-bottom-left-right!.
The following is our first example:

\begin{demo}
\begin{tabular}{lccr}
\hline
 Alpha   & Beta  & Gamma  & Delta \\
\hline
 Epsilon & Zeta  & Eta    & Theta \\
\hline
 Iota    & Kappa & Lambda & Mu    \\
\hline
\end{tabular}
\end{demo}

\begin{demohigh}
\begin{tblr}{lccr}
\hline
 Alpha   & Beta  & Gamma  & Delta \\
\hline
 Epsilon & Zeta  & Eta    & Theta \\
\hline
 Iota    & Kappa & Lambda & Mu    \\
\hline
\end{tblr}
\end{demohigh}

You may notice that there is extra space above and below the table rows with \verb!tblr! environment.
This space makes the table look better.
If you don't like it, you could use \verb!\SetTblrInner! command:

\begin{demohigh}
\SetTblrInner{rowsep=0pt}
\begin{tblr}{lccr}
\hline
 Alpha   & Beta  & Gamma  & Delta \\
\hline
 Epsilon & Zeta  & Eta    & Theta \\
\hline
 Iota    & Kappa & Lambda & Mu    \\
\hline
\end{tblr}
\end{demohigh}

But in many cases, this \verb!rowsep! is useful:

\begin{demo}
$\begin{array}{rrr}
\hline
 \dfrac{2}{3} &  \dfrac{2}{3} &  \dfrac{1}{3} \\
 \dfrac{2}{3} & -\dfrac{1}{3} & -\dfrac{2}{3} \\
 \dfrac{1}{3} & -\dfrac{2}{3} &  \dfrac{2}{3} \\
\hline
\end{array}$
\end{demo}

\begin{demohigh}
$\begin{tblr}{rrr}
\hline
 \dfrac{2}{3} &  \dfrac{2}{3} &  \dfrac{1}{3} \\
 \dfrac{2}{3} & -\dfrac{1}{3} & -\dfrac{2}{3} \\
 \dfrac{1}{3} & -\dfrac{2}{3} &  \dfrac{2}{3} \\
\hline
\end{tblr}$
\end{demohigh}

Note that you can use \verb!tblr! in both text and math modes.

\section{Multiline Cells}

It's quite easy to write multiline cells without fixing the column width in \verb!tblr! environments:
just enclose the cell text with braces and use \verb!\\! to break lines:

\begin{demohigh}
\begin{tblr}{|l|c|r|}
\hline
 Left & {Center \\ Cent \\ C} & {Right \\ R} \\
\hline
 {L \\ Left} & {C \\ Cent \\ Center} & R \\
\hline
\end{tblr}
\end{demohigh}

\section{Cell Alignment}

From time to time,
you may want to specify the horizontal and vertical alignment of cells at the same time.
\verb!Tabularray! package provides a \verb!Q! column for this
(In fact, \verb!Q! column is the only primitive column,
other columns are defined as \verb!Q! columns with some options):

\begin{demohigh}
\begin{tblr}{|Q[l,t]|Q[c,m]|Q[r,b]|}
\hline
 {Top Baseline \\ Left Left} & Middle Center & {Right Right \\ Bottom Baseline} \\
\hline
\end{tblr}
\end{demohigh}

Note that you can use more meaningful \verb!t! instead of \verb!p! for top baseline alignment.
For some users who are familiar with word processors,
these \verb!t! and \verb!b! columns are counter-intuitive.
In \verb!tabularray! package, there are another two column types \verb!h! and \verb!f!,
which will align cell text at the head and the foot, respectively:

\begin{demohigh}
\begin{tblr}{Q[h,4em]Q[t,4em]Q[m,4em]Q[b,4em]Q[f,4em]}
\hline
 {row\\head} & {top\\line} & {middle} & {line\\bottom} & {row\\foot} \\
\hline
 {row\\head} & {top\\line} & {11\\22\\mid\\44\\55} & {line\\bottom} & {row\\foot} \\
\hline
\end{tblr}
\end{demohigh}

\section{Multirow Cells}

The above \verb!h! and \verb!f! alignments are necessary
when we write multirow cells with \verb!\SetCell! command in \verb!tabularray!.

\begin{demo}
\begin{tabular}{|l|l|l|l|}
\hline
 \multirow[t]{4}{1.5cm}{Multirow Cell One} & Alpha &
 \multirow[b]{4}{1.5cm}{Multirow Cell Two} & Alpha \\
 & Beta  & & Beta \\
 & Gamma & & Gamma \\
 & Delta & & Delta \\
\hline
\end{tabular}
\end{demo}

\begin{demohigh}
\begin{tblr}{|l|l|l|l|}
\hline
 \SetCell[r=4]{h,1.5cm} Multirow Cell One & Alpha &
 \SetCell[r=4]{f,1.5cm} Multirow Cell Two & Alpha \\
 & Beta  & & Beta \\
 & Gamma & & Gamma \\
 & Delta & & Delta \\
\hline
\end{tblr}
\end{demohigh}

Note that you don't need to load \verb!multirow! package first,
since \verb!tabularray! doesn't depend on it.
Furthermore, \verb!tabularray! will always typeset decent multirow cells.
First, it will set correct vertical middle alignment,
even though some rows have large height:

\begin{demo}
\begin{tabular}{|l|m{4em}|}
\hline
 \multirow[c]{4}{1.5cm}{Multirow} & Alpha  \\
 & Beta  \\
 & Gamma \\
 & Delta Delta Delta \\
\hline
\end{tabular}
\end{demo}

\begin{demohigh}
\begin{tblr}{|l|m{4em}|}
\hline
 \SetCell[r=4]{m,1.5cm} Multirow & Alpha  \\
 & Beta  \\
 & Gamma \\
 & Delta Delta Delta \\
\hline
\end{tblr}
\end{demohigh}

Second, it will enlarge row heights if the multirow cells have large height,
therefore it always avoids vertical overflow:

\begin{demo}
\begin{tabular}{|l|m{4em}|}
\hline
 \multirow[c]{2}{1cm}{Line \\ Line \\ Line \\ Line} & Alpha \\
\cline{2-2}
 & Beta \\
\hline
\end{tabular}
\end{demo}

\begin{demohigh}
\begin{tblr}{|l|m{4em}|}
\hline
 \SetCell[r=2]{m,1cm} {Line \\ Line \\ Line \\ Line} & Alpha \\
\cline{2}
 & Beta \\
\hline
\end{tblr}
\end{demohigh}

If you want to distribute extra vertical space evenly to two rows,
you may use \verb!vspan! option described in Chapter \ref{chap:extra}.

\section{Multi Rows and Columns}

It was a hard job to typeset cells with multiple rows and multiple columns. For example:

\begin{demo}
\begin{tabular}{|c|c|c|c|c|}
\hline
 \multirow{2}{*}{2 Rows}
     & \multicolumn{2}{c|}{2 Columns}
                 & \multicolumn{2}{c|}{\multirow{2}{*}{2 Rows 2 Columns}} \\
\cline{2-3}
     & 2-2 & 2-3 & \multicolumn{2}{c|}{} \\
\hline
 3-1 & 3-2 & 3-3 & 3-4 & 3-5 \\
\hline
\end{tabular}
\end{demo}

With \verb!tabularray! package, you can set spanned cells with \verb!\SetCell! command:
within the optional argument of \verb!\SetCell! command,
option \verb!r! is for rowspan number, and \verb!c! for colspan number;
within the mandatory argument of it, horizontal and vertical alignment options are accepted.
Therefore it's much simpler to typeset spanned cells:

\begin{demohigh}
\begin{tblr}{|c|c|c|c|c|}
\hline
 \SetCell[r=2]{c} 2 Rows
     & \SetCell[c=2]{c} 2 Columns
           &     & \SetCell[r=2,c=2]{c} 2 Rows 2 Columns & \\
\hline
     & 2-2 & 2-3 &     &     \\
\hline
 3-1 & 3-2 & 3-3 & 3-4 & 3-5 \\
\hline
\end{tblr}
\end{demohigh}

Using \verb!\multicolumn! command, the omitted cells \textcolor{red3}{must} be removed.
On the contrary,
using \verb!\multirow! command, the omitted cells \textcolor{red3}{must not} be removed.
\verb!\SetCell! command behaves the same as \verb!\multirow! command in this aspect.

With \verb!tblr! environment, any \verb!\hline! segments inside a spanned cell will be ignored,
therefore we're free to use \verb!\hline! in the above example.
Also, any omitted cell will definitely be ignored when typesetting,
no matter it's empty or not.
With this feature, we could put row and column numbers into the omitted cells,
which will help us to locate cells when the tables are rather complex:

\begin{demohigh}
\begin{tblr}{|ll|c|rr|}
\hline
 \SetCell[r=3,c=2]{h} r=3 c=2 & 1-2 & \SetCell[r=2,c=3]{r} r=2 c=3 & 1-4 & 1-5 \\
 2-1 & 2-2 & 2-3 & 2-4 & 2-5 \\
\hline
 3-1 & 3-2 & MIDDLE & \SetCell[r=3,c=2]{f} r=3 c=2 & 3-5 \\
\hline
 \SetCell[r=2,c=3]{l} r=2 c=3 & 4-2 & 4-3 & 4-4 & 4-5 \\
 5-1 & 5-2 & 5-3 & 5-4 & 5-5 \\
\hline
\end{tblr}
\end{demohigh}

\section{Column Types}

\verb!Tabularray! package supports all normal column types, as well as
the extendable \verb!X! column type,
which first occurred in \verb!tabularx! package and was largely improved by \verb!tabu! package:

\begin{demohigh}
\begin{tblr}{|X[2,l]|X[3,l]|X[1,r]|X[r]|}
\hline
 Alpha & Beta & Gamma & Delta \\
\hline
\end{tblr}
\end{demohigh}

Also, \verb!X! columns with negative coefficients are possible:

\begin{demohigh}
\begin{tblr}{|X[2,l]|X[3,l]|X[-1,r]|X[r]|}
\hline
 Alpha & Beta & Gamma & Delta \\
\hline
\end{tblr}
\end{demohigh}

We need the width to typeset a table with \verb!X! columns.
If unset, the default is \verb!\linewidth!.
To change the width, we have to first put all column specifications into \verb!colspec={...}!:

\begin{demohigh}
\begin{tblr}{width=0.8\linewidth,colspec={|X[2,l]|X[3,l]|X[-1,r]|X[r]|}}
\hline
 Alpha & Beta & Gamma & Delta \\
\hline
\end{tblr}
\end{demohigh}

You can define new column types with \verb!\NewColumnType! command.
For example, in \verb!tabularray! package,
\verb!b! and \verb!X! columns are defined as special \verb!Q! columns:
\begin{codehigh}
\NewColumnType{b}[1]{Q[b,wd=#1]}
\NewColumnType{X}[1][]{Q[co=1,#1]}
\end{codehigh}

\section{Row Types}

Now that we have column types and \verb!colspec! option,
you may ask for row types and \verb!rowspec! option.
Yes, they are here:

\begin{demohigh}
\begin{tblr}{colspec={Q[l]Q[c]Q[r]},rowspec={|Q[t]|Q[m]|Q[b]|}}
 {Alpha \\ Alpha} & Beta               & Gamma \\
 Delta            & Epsilon            & {Zeta \\ Zeta}  \\
 Eta              & {Theta \\ Theta}   & Iota  \\
\end{tblr}
\end{demohigh}

Same as column types, \verb!Q! is the only primitive row type,
and other row types are defined as \verb!Q! types with different options.
It's better to specify horizontal alignment in \verb!colspec!,
and vertical alignment in \verb!rowspec!, respectively.

Inside \verb!rowspec!, \verb!|! is the hline type.
Therefore we need not to write \verb!\hline! command, which makes table code cleaner.

\section{Hlines and Vlines}

Hlines and vlines have been improved too. You can specify the widths and styles of them:

\begin{demohigh}
\begin{tblr}{|l|[dotted]|[2pt]c|r|[solid]|[dashed]|}
\hline
One   &  Two  & Three \\
\hline\hline[dotted]\hline
Four  & Five  &   Six \\
\hline[dashed]\hline[1pt]
Seven & Eight &  Nine \\
\hline
\end{tblr}
\end{demohigh}

\section{Colorful Tables}

To add colors to your tables, you need to load \verb!xcolor! package first.
\verb!Tabularray! package will also load
\href{https://ctan.org/pkg/ninecolors}{\texttt{ninecolors}} package for proper color contrast.
First you can specify background option for \verb!Q! rows/columns inside \verb!rowspec!/\verb!colspec!:

\begin{demohigh}
\begin{tblr}{colspec={lcr},rowspec={|Q[cyan7]|Q[azure7]|Q[blue7]|}}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{colspec={Q[l,brown7]Q[c,yellow7]Q[r,olive7]},rowspec={|Q|Q|Q|}}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

Also you can use \verb!\SetRow! or \verb!\SetColumn! command to specify row or column colors:

\begin{demohigh}
\begin{tblr}{colspec={lcr},rowspec={|Q|Q|Q|}}
 \SetRow{cyan7}  Alpha   & Beta  & Gamma  \\
 \SetRow{azure7} Epsilon & Zeta  & Eta    \\
 \SetRow{blue7}  Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{colspec={lcr},rowspec={|Q|Q|Q|}}
 \SetColumn{brown7}
 Alpha          & \SetColumn{yellow7}
                  Beta            & \SetColumn{olive7}
                                    Gamma  \\
 Epsilon        & Zeta            & Eta    \\
 Iota           & Kappa           & Lambda \\
\end{tblr}
\end{demohigh}

Hlines and vlines can also have colors:

\begin{demohigh}
\begin{tblr}{colspec={lcr},rowspec={|[2pt,green7]Q|[teal7]Q|[green7]Q|[3pt,teal7]}}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{colspec={|[2pt,violet5]l|[2pt,magenta5]c|[2pt,purple5]r|[2pt,red5]}}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\chapter{Basic Interfaces}
\label{chap:basic}

\section{Old and New Interfaces}

With \verb!tabularray! package, you can change the styles of tables via old interfaces or new interfaces.

The old interfaces consist of some table commands inside the table contents.
Same as \verb!tabular! and \verb!array! environments,
all table commands \textcolor{red3}{must} be put at the beginning of the cell text.
Also, new table commands \textcolor{red3}{must} be defined with \verb!\NewTableCommand!.

The new interfaces consist of some options inside the mandatory argument,
hence totally separating the styles and the contents of tables.

\begin{newtblr}[
  caption = {Old Interfaces and New Interfaces},
  label = {key:interface},
]{verb}
  Old Interfaces                                 & New Interfaces          \\
  \verb!\SetHlines!                              & \K{hlines}              \\
  \verb!\SetHline!, \verb!\hline!, \verb!\hborder!, \verb!\cline!
                                                 & \K{hline}, \K{hborder}, \K{rowspec}  \\
  \verb!\SetVlines!                              & \K{vlines}              \\
  \verb!\SetVline!, \verb!\vline!, \verb!\vborder!, \verb!\rline!
                                                 & \K{vline}, \K{vborder}, \K{colspec}  \\
  \verb!\SetCells!                               & \K{cells}               \\
  \verb!\SetCell!                                & \K{cell}                \\
  \verb!\SetRows!                                & \K{rows}                \\
  \verb!\SetRow!                                 & \K{row}, \K{rowspec}    \\
  \verb!\SetColumns!                             & \K{columns}             \\
  \verb!\SetColumn!                              & \K{column}, \K{colspec} \\
\end{newtblr}

\section{Hlines and Vlines}\label{sec:hlines-vlines}

All available keys for hlines and vlines are described in Table \ref{key:hline} and Table \ref{key:vline}.

\begin{spectblr}[
  caption = {Keys for Hlines},
  label = {key:hline},
  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
]{}
  Key & Description and Values & Initial Value \\
  \underline{\K{dash}} & dash style: \V{solid}, \V{dashed} or \V{dotted} & \V{solid} \\
  \K{text}             & replace hline with text (like \V{!} specifier in \K{rowspec}) & \None \\
  \underline{\K{wd}}   & rule width dimension & \V{0.4pt} \\
  \underline{\K{fg}}   & rule color name & \None \\
  \K{leftpos}          & crossing or trimming position at the left side  & \V{1} \\
  \K{rightpos}         & crossing or trimming position at the right side & \V{1} \\
  \K{l}                & same as \K{leftpos}, default \V{-0.8} & \V{1} \\
  \K{r}                & same as \K{rightpos}, default \V{-0.8} & \V{1} \\
  \K{lr}               & crossing or trimming positions at both sides, default \V{-0.8} & \V{1} \\
  \K{endpos}           & adjust leftpos/rightpos for only the leftmost/rightmost column & \V{false} \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
  caption = {Keys for Vlines},
  label = {key:vline},
  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
]{}
  Key & Description and Values & Initial Value \\
  \underline{\K{dash}} & dash style: \V{solid}, \V{dashed} or \V{dotted} & \V{solid} \\
  \K{text}             & replace vline with text (like \V{!} specifier in \K{colspec}) & \None \\
  \underline{\K{wd}}   & rule width dimension & \V{0.4pt} \\
  \underline{\K{fg}}   & rule color name & \None \\
  \K{abovepos}         & crossing or trimming position at the above side & \V{0} \\
  \K{belowpos}         & crossing or trimming position at the below side & \V{0} \\
\end{spectblr}

\subsection{Hlines and Vlines in New Interfaces}

Options \verb!hlines! and \verb!vlines! are for setting all hlines and vlines, respectively.
With empty value, all hlines/vlines will be solid.

\begin{demohigh}
\begin{tblr}{hlines,vlines}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
\end{tblr}
\end{demohigh}

With values inside one pair of braces, all hlines/vlines will be styled.

\begin{demohigh}
\begin{tblr}{
 hlines = {1pt,solid}, vlines = {red3,dashed},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
\end{tblr}
\end{demohigh}

Another pair of braces before will select segments in all hlines/vlines.

\begin{demohigh}
\begin{tblr}{
 vlines = {1,3,5}{dashed},
 vlines = {2,4}{solid},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
 Rho     & Sigma & Tau     & Upsilon \\
\end{tblr}
\end{demohigh}

The above example can be simplified with \verb!odd! and \verb!even! values.
(More child selectors can be defined with \verb!\NewChildSelector! command.
Advanced users could read the source code for this.)

\begin{demohigh}
\begin{tblr}{
 vlines = {odd}{dashed},
 vlines = {even}{solid},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
 Rho     & Sigma & Tau     & Upsilon \\
\end{tblr}
\end{demohigh}

Another pair of braces before will draw more hlines/vlines (in which \verb!-! stands for all line segments).

\begin{demohigh}
\begin{tblr}{
 hlines = {1}{-}{dashed}, hlines = {2}{-}{solid},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
\end{tblr}
\end{demohigh}

Note that you \underline{must} use indexes in order: first 1, then 2, etc.

Options \verb!hline{i}! and \verb!vline{j}! are for setting some hlines and vlines, respectively.
Their values are the same as options \verb!hlines! and \verb!vlines!:

\begin{demohigh}
\begin{tblr}{
 hline{1,7} = {1pt,solid},
 hline{3-5} = {blue3,dashed},
 vline{1,5} = {3-4}{dotted},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
 Rho     & Sigma & Tau     & Upsilon \\
 Phi     & Chi   & Psi     & Omega   \\
\end{tblr}
\end{demohigh}

You can use \verb!U!, \verb!V!, \verb!W!, \verb!X!, \verb!Y!, \verb!Z! to
denote the last six children, respectively.
It is especially useful when you are writing long tables:

\begin{demohigh}
\begin{tblr}{
 hline{1,Z} = {2pt},
 hline{2,Y} = {1pt},
 hline{3-X} = {dashed},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
 Rho     & Sigma & Tau     & Upsilon \\
 Phi     & Chi   & Psi     & Omega   \\
\end{tblr}
\end{demohigh}

Now we show the usage of \verb!text! key by the following example%
\footnote{Code from \url{https://tex.stackexchange.com/questions/603023/tabularray-and-tabularx-column-separator}.}:

\begin{demohigh}
\begin{tblr}{
  vlines, hlines,
  colspec = {lX[c]X[c]X[c]X[c]},
  vline{2} = {1}{text=\clap{:}},
  vline{3} = {1}{text=\clap{\ch{+}}},
  vline{4} = {1}{text=\clap{\ch{->}}},
  vline{5} = {1}{text=\clap{\ch{+}}},
}
  Equation & \ch{CH4} & \ch{2 O2} & \ch{CO2} & \ch{2 H2O} \\
  Initial  & $n_1$    & $n_2$     & 0        & 0 \\
  Final    & $n_1-x$  & $n_2-2x$  & $x$      & $2x$ \\
\end{tblr}
\end{demohigh}

You need to load \verb!chemmacros! package for the \verb!\ch! command.

The \verb!leftpos! and \verb!rightpos! keys specify crossing or trimming positions for hlines.
The possible values for them are decimal numbers between \verb!-1! and \verb!1!.
Their initial values are \verb!1!.

\begin{center}
\begin{tblr}{width=0.5\textwidth,colspec={rX[l]},hlines}
  -1 & the hline is trimmed by \V{colsep} \\
   0 & the hline only touches the first vline \\
   1 & the hline touches all the vlines \\
\end{tblr}
\end{center}

The \verb!abovepos! and \verb!belowpos! keys for vlines have similar meanings.
But their initial values are \verb!0!.

\begin{center}
\begin{tblr}{width=0.5\textwidth,colspec={rX[l]},hlines}
  -1 & the vline is trimmed by \V{rowsep} \\
   0 & the vline only touches the first hline \\
   1 & the vline touches all the hlines \\
\end{tblr}
\end{center}

Here is an example for these four keys:

\begin{demohigh}
\begin{tblr}{
  hline{1,4} = {1}{-}{},
  hline{1,4} = {2}{-}{},
  hline{2,3} = {1}{-}{leftpos = -1, rightpos = -1},
  hline{2,3} = {2}{-}{leftpos = -1, rightpos = -1},
  vline{1,4} = {abovepos = 1, belowpos = 1},
}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

There is also an \verb!endpos! option for adjusting \verb!leftpos!/\verb!rightpos!
for only the leftmost/rightmost column:

\begin{demohigh}
\begin{tblr}{
 hline{1,4} = {1}{-}{},
 hline{1,4} = {2}{-}{},
 hline{2,3} = {leftpos = -1, rightpos = -1, endpos},
 vline{1,4} = {abovepos = 1, belowpos = 1},
}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\subsection{Hlines and Vlines in Old Interfaces}

The \verb!\hline! command has an optional argument which accepts key-value options.
The available keys are described in Table \ref{key:hline}.

\begin{demohigh}
\begin{tblr}{llll}
\hline
 Alpha   & Beta  & Gamma  & Delta \\
\hline[dashed]
 Epsilon & Zeta  & Eta    & Theta \\
\hline[dotted]
 Iota    & Kappa & Lambda & Mu    \\
\hline[2pt,blue5]
\end{tblr}
\end{demohigh}

The \verb!\cline! command also has an optional argument which is the same as \verb!\hline!.

\begin{demohigh}
\begin{tblr}{llll}
\cline{1-4}
 Alpha   & Beta  & Gamma  & Delta \\
\cline[dashed]{1,3}
 Epsilon & Zeta  & Eta    & Theta \\
\cline[dashed]{2,4}
 Iota    & Kappa & Lambda & Mu    \\
\cline[2pt,blue5]{-}
\end{tblr}
\end{demohigh}

You can use child selectors in the mandatory argument of \verb!\cline!.

\begin{demohigh}
\begin{tblr}{llll}
\cline{1-4}
 Alpha   & Beta  & Gamma  & Delta \\
\cline[dashed]{odd}
 Epsilon & Zeta  & Eta    & Theta \\
\cline[dashed]{even}
 Iota    & Kappa & Lambda & Mu    \\
\cline[2pt,blue5]{-}
\end{tblr}
\end{demohigh}

Commands \verb!\SetHline! combines the usages of \verb!\hline! and \verb!\cline!:

\begin{demohigh}
\begin{tblr}{llll}
\SetHline{1-3}{blue5,1pt}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\SetHline{2-4}{teal5,1pt}
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{llll}
\SetHline[1]{1-3}{blue5,1pt}
\SetHline[2]{1-3}{azure5,1pt}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\SetHline[1]{2-4}{teal5,1pt}
\SetHline[2]{2-4}{green5,1pt}
\end{tblr}
\end{demohigh}

In fact, table command \verb!\SetHline[<index>]{<columns>}{<styles>}! at the beginning of row \verb!i!
is the same as table option \verb!hline{i}={<index>}{<columns>}{<styles>}!.

Also, table command \verb!\SetHlines[<index>]{<columns>}{<styles>}! at the beginning of some row
is the same as table option \verb!hlines={<index>}{<columns>}{<styles>}!.

The usages of table commands \verb!\vline!, \verb!\rline!, \verb!\SetVline!, \verb!\SetVlines!
are similar to those of \verb!\hline!, \verb!\cline!, \verb!\SetHline!, \verb!\SetHlines!, respectively.
But normally you don't need to use them.

\section{Hborders and Vborders}

Options \verb!hborder{i}! and \verb!vborder{j}! are similar to \verb!hline{i}! and \verb!vline{j}!,
respectively, but they hold border specifications not related to one specific hline and vline.
All available keys for \verb!hborder{i}! and \verb!vborder{j}! are described in
Table~\ref{key:hborder} and Table~\ref{key:vborder}.

\begin{spectblr}[
  caption = {Keys for Hborders},
  label = {key:hborder},
]{}
  Key & Description and Values & Initial Value \\
  \K{pagebreak}   & pagebreak at this position: \V{yes}, \V{no} or \V{auto}
                    (See Chapter~\ref{chap:long}) & \V{auto} \\
  \K{abovespace}  & set \V{belowsep} of previous row (see Table \ref{key:row}) & \V{2pt} \\
  \K{belowspace}  & set \V{abovesep} of current row (see Table \ref{key:row}) & \V{2pt} \\
  \K{abovespace+} & increase \V{belowsep} of previous row & \None \\
  \K{belowspace+} & increase \V{abovesep} of current row  & \None \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
  caption = {Keys for Vborders},
  label = {key:vborder},
]{}
  Key & Description and Values & Initial Value \\
  \K{leftspace}   & set \V{rightsep} of previous column (see Table \ref{key:column}) & \V{6pt} \\
  \K{rightspace}  & set \V{leftsep} of current column (see Table \ref{key:column}) & \V{6pt} \\
  \K{leftspace+}  & increase \V{rightsep} of previous column & \None \\
  \K{rightspace+} & increase \V{leftsep} of current column  & \None \\
\end{spectblr}

Furthermore, table command \verb!\hborder{<specs>}! at the beginning of row \verb!i!
is the same as table option \verb!hborder{i}={<specs>}!,
and table command \verb!\vborder{<specs>}! at the beginning of column \verb!j!
is the same as table option \verb!vborder{j}={<specs>}!.

\section{Cells and Spancells}

All available keys for cells are described in Table \ref{key:cell} and Table \ref{key:cellspan}.

\begin{spectblr}[
  caption = {Keys for the Content of Cells},
  label = {key:cell},
  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
]{verb}
  Key & Description and Values & Initial Value \\
  \underline{\K{halign}}
    & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
    & \V{j} \\
  \underline{\K{valign}}
    & vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom),
      \V{h} (head) or \V{f} (foot)
    & \V{t} \\
  \underline{\K{wd}} & width dimension & \None \\
  \underline{\K{bg}} & background color name & \None \\
  \K{fg}    & foreground color name & \None \\
  \K{font}  & font commands & \None \\
  \K{mode}  & set cell mode: \V{math}, \V{imath}, \V{dmath} or \V{text} & \None \\
  \verb!$!  & same as \V{mode=math} & \None \\
  \verb!$$! & same as \V{mode=dmath} & \None \\
  \K{cmd}   & execute command for the cell text & \None \\
  \K{preto} & prepend text to the cell & \None \\
  \K{appto} & append text to the cell & \None \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
  caption = {Keys for Multispan of Cells},
  label = {key:cellspan},
]{}
  Key & Description and Values & Initial Value \\
  \K{r} & number of rows the cell spans    & 1 \\
  \K{c} & number of columns the cell spans & 1 \\
\end{spectblr}

\subsection{Cells and Spancells in New Interfaces}

Option \verb!cells! is for setting all cells.
\nopagebreak
\begin{demohigh}
\begin{tblr}{hlines={white},cells={c,blue7}}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
\end{tblr}
\end{demohigh}

Option \verb!cell{i}{j}! is for setting some cells,
where \verb!i! stands for the row numbers and \verb!j! stands for the column numbers.
\nopagebreak
\begin{demohigh}
\begin{tblr}{
  cell{1}{2-4} = {cmd=\fbox}
}
  Alpha & Beta & Gamma & Delta
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{
 hlines = {white},
 vlines = {white},
 cell{1,6}{odd} = {teal7},
 cell{1,6}{even} = {green7},
 cell{2,4}{1,4} = {red7},
 cell{3,5}{1,4} = {purple7},
 cell{2}{2} = {r=4,c=2}{c,azure7},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
 Rho     & Sigma & Tau     & Upsilon \\
 Phi     & Chi   & Psi     & Omega   \\
\end{tblr}
\end{demohigh}

\subsection{Cells and Spancells in Old Interfaces}

The \verb!\SetCell! command has a mandatory argument for setting the styles of current cell.
The available keys are described in Table \ref{key:cell}.

\begin{demohigh}
\begin{tblr}{llll}
\hline[1pt]
 Alpha   & \SetCell{bg=teal2,fg=white} Beta & Gamma \\
\hline
 Epsilon & Zeta & \SetCell{r,font=\scshape} Eta \\
\hline
 Iota    & Kappa & Lambda \\
\hline[1pt]
\end{tblr}
\end{demohigh}

The \verb!\SetCell! command also has an optional argument for setting the multispan of current cell.
The available keys are described in Table \ref{key:cellspan}.

\begin{demohigh}
\begin{tblr}{|X|X|X|X|X|X|}
\hline
 Alpha & Beta & Gamma & Delta & Epsilon & Zeta \\
\hline
 \SetCell[c=2]{c} Eta & 2-2
              & \SetCell[c=2]{c} Iota & 2-4
                              & \SetCell[c=2]{c} Lambda  & 2-6 \\
\hline
 \SetCell[c=3]{c} Nu & 3-2 & 3-3
                      & \SetCell[c=3]{c} Pi & 3-5 & 3-6   \\
\hline
 \SetCell[c=6]{c} Tau & 4-2 & 4-3 & 4-4 & 4-5 & 4-6 \\
\hline
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{|X|X|X|X|X|X|}
\hline
 Alpha & Beta    & Gamma   & Delta & Epsilon & Zeta \\
\hline
 \SetCell[r=2]{m} Eta
       & Theta   & Iota    & Kappa & Lambda  & \SetCell[r=2]{m} Mu  \\
\hline
 Nu    & Xi      & Omicron & Pi    & Rho     & Sigma \\
\hline
\end{tblr}
\end{demohigh}

In fact, table command \verb!\SetCell[<span>]{<styles>}! at the beginning of cell at row \verb!i!
and column \verb!j! is the same as table option \verb!cell{i}{j}={<span>}{<styles>}!.

Also, table command \verb!\SetCells[<span>]{<styles>}! at the beginning of some cell
is the same as table option \verb!cells={<span>}{<styles>}!.

\section{Rows and Columns}

All available keys for rows and columns are described in Table \ref{key:row} and Table \ref{key:column}.

\begin{spectblr}[
  caption = {Keys for Rows},
  label = {key:row},
  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
]{verb}
  Key & Description and Values & Initial Value \\
  \underline{\K{halign}}
    & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
    & \V{j} \\
  \underline{\K{valign}}
    & vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom),
      \V{h} (head) or \V{f} (foot)
    & \V{t} \\
  \underline{\K{ht}} & height dimension & \None \\
  \underline{\K{bg}} & background color name & \None \\
  \K{fg} & foreground color name & \None \\
  \K{font} & font commands & \None \\
  \K{mode}  & set mode for row cells: \V{math}, \V{imath}, \V{dmath} or \V{text} & \None \\
  \verb!$!  & same as \V{mode=math} & \None \\
  \verb!$$! & same as \V{mode=dmath} & \None \\
  \K{cmd}   & execute command for every cell text & \None \\
  \K{abovesep} & set vertical space above the row & \V{2pt} \\
  \K{abovesep+} & increase vertical space above the row & \None \\
  \K{belowsep} & set vertical space below the row & \V{2pt} \\
  \K{belowsep+} & increase vertical space below the row & \None \\
  \K{rowsep} & set vertical space above and below the row & \V{2pt} \\
  \K{rowsep+} & increase vertical space above and below the row & \None \\
  \K{preto} & prepend text to every cell (like \V{>} specifier in \K{rowspec}) & \None \\
  \K{appto} & append text to every cell (like \V{<} specifier in \K{rowspec}) & \None \\
\end{spectblr}
\vspace{-2em}
\begin{spectblr}[
  caption = {Keys for Columns},
  label = {key:column},
  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.}
]{verb}
  Key & Description and Values & Initial Value \\
  \underline{\K{halign}}
    & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
    & \V{j} \\
  \underline{\K{valign}}
    & vertical alignment: \V{t} (top), \V{m} (middle), \V{b} (bottom),
      \V{h} (head) or \V{f} (foot)
    & \V{t} \\
  \underline{\K{wd}} & width dimension & \None \\
  \underline{\K{co}} & coefficient for the extendable column (\V{X} column) & \None \\
  \underline{\K{bg}} & background color name & \None \\
  \K{fg} & foreground color name & \None \\
  \K{font} & font commands & \None \\
  \K{mode}  & set mode for column cells: \V{math}, \V{imath}, \V{dmath} or \V{text} & \None \\
  \verb!$!  & same as \V{mode=math} & \None \\
  \verb!$$! & same as \V{mode=dmath} & \None \\
  \K{cmd}   & execute command for every cell text & \None \\
  \K{leftsep} & set horizontal space to the left of the column & \V{6pt} \\
  \K{leftsep+} & increase horizontal space to the left of the column & \None \\
  \K{rightsep} & set horizontal space to the right of the column & \V{6pt} \\
  \K{rightsep+} & increase horizontal space to the right of the column & \None \\
  \K{colsep} & set horizontal space to both sides of the column & \V{6pt} \\
  \K{colsep+} & increase horizontal space to both sides of the column & \None \\
  \K{preto} & prepend text to every cell (like \V{>} specifier in \K{colspec}) & \None \\
  \K{appto} & append text to every cell (like \V{<} specifier in \K{colspec}) & \None \\
\end{spectblr}

\subsection{Rows and Columns in New Interfaces}

Options \verb!rows! and \verb!columns! are for setting all rows and columns, respectively.
\nopagebreak
\begin{demohigh}
\begin{tblr}{
 hlines, vlines,
 rows = {7mm}, columns = {15mm,c},
}
 Alpha   & Beta  & Gamma   & Delta \\
 Epsilon & Zeta  & Eta     & Theta \\
 Iota    & Kappa & Lambda  & Mu    \\
\end{tblr}
\end{demohigh}

Options \verb!row{i}! and \verb!column{j}! are for setting some rows and columns, respectively.

\begin{demohigh}
\begin{tblr}{
 hlines = {1pt,white},
 row{odd} = {blue7},
 row{even} = {azure7},
 column{1} = {purple7,c},
}
 Alpha   & Beta  & Gamma   & Delta   \\
 Epsilon & Zeta  & Eta     & Theta   \\
 Iota    & Kappa & Lambda  & Mu      \\
 Nu      & Xi    & Omicron & Pi      \\
 Rho     & Sigma & Tau     & Upsilon \\
 Phi     & Chi   & Psi     & Omega   \\
\end{tblr}
\end{demohigh}

The following example demonstrates the usages of \verb!bg!, \verb!fg! and \verb!font! keys:
\nopagebreak
\begin{demohigh}
\begin{tblr}{
 row{odd} = {bg=azure8},
 row{1}   = {bg=azure3, fg=white, font=\sffamily},
}
 Alpha & Beta    & Gamma \\
 Delta & Epsilon & Zeta  \\
 Eta   & Theta   & Iota  \\
 Kappa & Lambda  & Mu    \\
 Nu Xi Omicron & Pi Rho Sigma & Tau Upsilon Phi \\
\end{tblr}
\end{demohigh}

The following example demonstrates the usages of \verb!mode! key:
\nopagebreak
\begin{demohigh}
$\begin{tblr}{
  column{1} = {mode=text},
  column{3} = {mode=dmath},
}
\hline
  Alpha   & \frac12 & \frac12 \\
  Epsilon & \frac34 & \frac34 \\
  Iota    & \frac56 & \frac56 \\
\hline
\end{tblr}$
\end{demohigh}
Note that you \textcolor{red3}{cannot} write multiline math directly (such as \verb!\alpha \\ \beta!)
in any math-mode cell.

The following example demonstrates the usages of
\verb!abovesep!, \verb!belowsep!, \verb!leftsep!, \verb!rightsep! keys:
%\nopagebreak
\begin{demohigh}
\begin{tblr}{
 hlines, vlines,
 rows = {abovesep=1pt,belowsep=5pt},
 columns = {leftsep=1pt,rightsep=5pt},
}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

The following example shows that we can replace \verb!\\[dimen]! with \verb!belowsep+! key.

\begin{demohigh}
\begin{tblr}{
 hlines, row{2} = {belowsep+=5pt},
}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

\subsection{Rows and Columns in Old Interfaces}

The \verb!\SetRow! command has a mandatory argument for setting the styles of current row.
The available keys are described in Table \ref{key:row}.

\begin{demohigh}
\begin{tblr}{llll}
\hline[1pt]
 \SetRow{azure8} Alpha & Beta & Gamma & Delta \\
\hline
 \SetRow{blue8,c} Epsilon & Zeta & Eta & Theta \\
\hline
 \SetRow{violet8} Iota & Kappa & Lambda & Mu \\
\hline[1pt]
\end{tblr}
\end{demohigh}

In fact, table command \verb!\SetRow{<styles>}! at the beginning of row \verb!i!
is the same as table option \verb!row{i}={<styles>}!.

Also, table command \verb!\SetRows{<styles>}! at the beginning of some row
is the same as table option \verb!rows={<styles>}!.

The usages of table commands \verb!\SetColumn! and \verb!\SetColumns!
are similar to those of \verb!\SetRow! and \verb!\SetRows!, respectively.
But normally you don't need to use them.

\section{Colspec and Rowspec}

Options \verb!colspec!/\verb!rowspec! are for setting column/row specifications
with column/row type specifiers.

\subsection{Colspec and Width}

Option \verb!width! is for setting the width of the table with extendable columns.
The following example demonstrates the usage of \verb!width! option.
\nopagebreak
\begin{demohigh}
\begin{tblr}{width=0.8\textwidth, colspec={|l|X[2]|X[3]|X[-1]|}}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

You can omit \verb!colspec! name if it is the only key you use inside the mandatory argument.
The following example demonstrates the usages of \verb!$! and \verb!$$! keys:
\nopagebreak
\begin{demohigh}
\begin{tblr}{Q[l]Q[r,$]Q[r,$$]}
\hline
  Alpha   & \frac12 & \frac12 \\
  Epsilon & \frac34 & \frac34 \\
  Iota    & \frac56 & \frac56 \\
\hline
\end{tblr}
\end{demohigh}

\subsection{Column Types}

The \verb!tabularray! package has only one type of primitive column: the \verb!Q! column.
Other types of columns are defined as \verb!Q! columns with some keys.

\begin{codehigh}
\NewColumnType{l}{Q[l]}
\NewColumnType{c}{Q[c]}
\NewColumnType{r}{Q[r]}
\NewColumnType{t}[1]{Q[t,wd=#1]}
\NewColumnType{m}[1]{Q[m,wd=#1]}
\NewColumnType{b}[1]{Q[b,wd=#1]}
\NewColumnType{h}[1]{Q[h,wd=#1]}
\NewColumnType{f}[1]{Q[f,wd=#1]}
\NewColumnType{X}[1][]{Q[co=1,#1]}
\end{codehigh}

\begin{demohigh}
\begin{tblr}{|t{15mm}|m{15mm}|b{20mm}|}
 Alpha   & Beta  & {Gamma\\Gamma} \\
 Epsilon & Zeta  & {Eta\\Eta} \\
 Iota    & Kappa & {Lambda\\Lambda} \\
\end{tblr}
\end{demohigh}

Any new column type must be defined with \verb!\NewColumnType! command.
It can have an optional argument when it's defined.

\subsection{Row Types}

The \verb!tabularray! package has only one type of primitive row: the \verb!Q! row.
Other types of rows are defined as \verb!Q! rows with some keys.

\begin{codehigh}
\NewRowType{l}{Q[l]}
\NewRowType{c}{Q[c]}
\NewRowType{r}{Q[r]}
\NewRowType{t}[1]{Q[t,ht=#1]}
\NewRowType{m}[1]{Q[m,ht=#1]}
\NewRowType{b}[1]{Q[b,ht=#1]}
\NewRowType{h}[1]{Q[h,ht=#1]}
\NewRowType{f}[1]{Q[f,ht=#1]}
\end{codehigh}

\begin{demohigh}
\begin{tblr}{rowspec={|t{12mm}|m{10mm}|b{10mm}|}}
 Alpha   & Beta  & {Gamma\\Gamma} \\
 Epsilon & Zeta  & {Eta\\Eta} \\
 Iota    & Kappa & {Lambda\\Lambda} \\
\end{tblr}
\end{demohigh}

Any new row type must be defined with \verb!\NewRowType! command.
It can have an optional argument when it's defined.

\chapter{Extra Interfaces}
\label{chap:extra}

In general, \verb!tblr! environment can accepts both inner and outer specifications:

\begin{codehigh}
\begin{tblr}[<outer specs>]{<inner specs>}
  <table body>
\end{tblr}
\end{codehigh}

\textbf{Inner specifications} are all specifications written in the \underline{mandatory} argument
of \verb!tblr! environment, which include new interfaces described in Chapter \ref{chap:basic}.

\textbf{Outer specifications} are all specifications written in the \underline{optional} argument
of \verb!tblr! environment, most of which are used for long tables (see Chapter \ref{chap:long}).

You can use \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
to set default inner and outer specifications of tables, respectively (see Section \ref{sec:default}).

\section{Inner Specifications}

In addition to new interfaces in Chapter \ref{chap:basic},
there are several inner specifications which are described in Table~\ref{key:inner}.

\begin{spectblr}[
  caption = {Keys for Inner Specifications},
  label = {key:inner},
]{}
  Key & Description and Values & Initial Value \\
  \K{rulesep} & space between two hlines or vlines & \V{2pt} \\
  \K{stretch} & stretch ratio for struts added to cell text & \V{1} \\
  \K{abovesep} & set vertical space above every row & \V{2pt} \\
  \K{belowsep} & set vertical space below every row & \V{2pt} \\
  \K{rowsep} & set vertical space above and below every row & \V{2pt} \\
  \K{leftsep} & set horizontal space to the left of every column & \V{6pt} \\
  \K{rightsep} & set horizontal space to the right of every column & \V{6pt} \\
  \K{colsep} & set horizontal space to both sides of every column & \V{6pt} \\
  \K{hspan} & horizontal span algorithm: \V{default}, \V{even}, or \V{minimal} & \V{default} \\
  \K{vspan} & vertical span algorithm: \V{default} or \V{even} & \V{default} \\
  %\K{verb} & you need this key to use verb commands & \None \\
  \K{baseline} & set the baseline of the table & \V{m} \\
\end{spectblr}

\subsection{Space between Double Rules}

The following example shows that we can replace \verb!\doublerulesep! parameter with \verb!rulesep! key.
\nopagebreak
\begin{demohigh}
\begin{tblr}{
 colspec={||llll||},rowspec={|QQQ|},rulesep=4pt,
}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

\subsection{Minimal Strut for Cell Text}

The following example shows that we can replace \verb!\arraystretch! parameter with \verb!stretch! key.

\begin{demohigh}
\begin{tblr}{hlines,stretch=1.5}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

By replacing stretch with row heights, we can get perfect vertical centering for your numerical tables.

\begin{demohigh}
\begin{tblr}{hlines, stretch=0, rows={ht=\baselineskip}}
  2021 & 2022 & 2023 \\
  0.4  & 0.5  & 0.6  \\
  1.1  & 2.2  & 3.3  \\
\end{tblr}
\end{demohigh}

\subsection{Rowseps and Colseps for All}

The following example uses \verb!rowsep! and \verb!colsep! keys to set padding for all rows and columns.
\nopagebreak
\begin{demohigh}
\SetTblrInner{rowsep=2pt,colsep=2pt}
\begin{tblr}{hlines,vlines}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{tblr}
\end{demohigh}

\subsection{Hspan and Vspan Algorithms}

With \verb!hspan=default! or \verb!hspan=even!,
\verb!tabularray! package will compute column widths from span widths.
But with \verb!hspan=minimal!, it will compute span widths from column widths.
The following examples show the results from different \verb!hspan! values.

\begin{demohigh}
\SetTblrInner{hlines, vlines, hspan=default}
\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
 111 111 & 222 222 & 333 333 \\
 12 Multi Columns Multi Columns 12 & & 333 \\
 13 Multi Columns Multi Columns Multi Columns 13 & & \\
 111 & 23 Multi Columns Multi Columns 23 & \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\SetTblrInner{hlines, vlines, hspan=even}
\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
 111 111 & 222 222 & 333 333 \\
 12 Multi Columns Multi Columns 12 & & 333 \\
 13 Multi Columns Multi Columns Multi Columns 13 & & \\
 111 & 23 Multi Columns Multi Columns 23 & \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\SetTblrInner{hlines, vlines, hspan=minimal}
\begin{tblr}{cell{2}{1}={c=2}{l},cell{3}{1}={c=3}{l},cell{4}{2}={c=2}{l}}
 111 111 & 222 222 & 333 333 \\
 12 Multi Columns Multi Columns 12 & & 333 \\
 13 Multi Columns Multi Columns Multi Columns 13 & & \\
 111 & 23 Multi Columns Multi Columns 23 & \\
\end{tblr}
\end{demohigh}

The following examples show the results from different \verb!vspan! values.
\nopagebreak
\begin{demohigh}
\SetTblrInner{hlines, vlines, vspan=default}
\begin{tblr}{column{2}={3.25cm}, cell{2}{2}={r=3}{l}}
  Column1 & Column2 \\
  Row1 & Long text that needs multiple lines.
         Long text that needs multiple lines.
         Long text that needs multiple lines. \\
  Row2 & \\
  Row3 & \\
  Row4 & Short text \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\SetTblrInner{hlines, vlines, vspan=even}
\begin{tblr}{column{2}={3.25cm}, cell{2}{2}={r=3}{l}}
  Column1 & Column2 \\
  Row1 & Long text that needs multiple lines.
         Long text that needs multiple lines.
         Long text that needs multiple lines. \\
  Row2 & \\
  Row3 & \\
  Row4 & Short text \\
\end{tblr}
\end{demohigh}

\subsection{Set Baseline for the Table}

With \verb!baseline! key, you can set baseline for the table.
All possible values for \verb!baseline! are as follows:

\begin{center}
\begin{tblr}{width=0.6\textwidth,colspec={cX[l]},hlines}
  \V{t}    & align the table at the top \\
  \V{T}    & align the table at the first row \\
  \V{m}    & align the table at the middle, initial value \\
  \V{b}    & align the table at the bottom \\
  \V{B}    & align the table at the last row \\
  \V{<n>}  & align the table at row \V{<n>} (a positive integer) \\
\end{tblr}
\end{center}

If there is no hline above the first row, you get the same result with either \V{t} or \V{T}.
But you get different results if there are one or more hlines above the row:

\begin{demohigh}
Baseline\begin{tblr}{hlines,baseline=t}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}Baseline
\end{demohigh}

\begin{demohigh}
Baseline\begin{tblr}{hlines,baseline=T}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}Baseline
\end{demohigh}

The differences between \verb!b! and \verb!B! are similar to \verb!t! and \verb!T!.
In fact, these two values \verb!T! and \verb!B! are better replacements
for currently obsolete \verb!\firsthline! and \verb!\lasthline! commands.

\section{Outer Specifications}

Except for specifications to be introduced in Chapter \ref{chap:long},
there are several other outer specifications which are described in Table~\ref{key:outer}.

\begin{spectblr}[
  caption = {Keys for Outer Specifications},
  label = {key:outer},
]{}
  Key & Description and Values & Initial Value \\
  \K{baseline} & set the baseline of the table & \V{m} \\
  \K{long} & change the table to a long table & \None \\
  \K{tall} & change the table to a tall table & \None \\
  \K{expand} & you need this key to use verb commands & \None \\
  \K{expand+} & like \K{expand} but appends to previous values & \None \\
\end{spectblr}

\subsection{Set Baseline in Another Way}

You may notice that you can write \K{baseline} option as either an inner or an outer specification.
It is true that either way would do the job. But there is a small difference:
when \verb!baseline=t/T/m/b/B! is an outer specification,
you can omit the key name and write the value only.

\begin{demohigh}
Baseline\begin{tblr}[m]{hlines}
 Alpha   & Beta  & Gamma  \\
 Epsilon & Zeta  & Eta    \\
 Iota    & Kappa & Lambda \\
\end{tblr}Baseline
\end{demohigh}

\subsection{Long and Tall Tables}

You can change a table to long table by passing outer specification \K{long},
or change it to tall table by passing outer specification \K{tall} (see Chapter~\ref{chap:long}).
Therefore the following two tables are the same:
\begin{codehigh}
\begin{longtblr}{lcr}
  Alpha & Beta & Gamma
\end{longtblr}
\begin{tblr}[long]{lcr}
  Alpha & Beta & Gamma
\end{tblr}
\end{codehigh}

\subsection{Expand Macros First}

In contrast to traditional \verb!tabular! environment, \verb!tabularray! environments
need to see every \verb!&! and \verb!\\! when splitting the table body with \verb!l3regex!.
And you can not put cell text inside any table command defined with \verb!\NewTableCommand!.
But you could use outer key \verb!expand! to make \verb!tabularray! expand
every occurrence of any of the specified macros \underline{once} and \underline{in the given order} before splitting the table body.
Note that you \underline{can not} expand a command defined with \verb!\NewDocumentCommand!.
You can also use \verb!expand+! if you still want to keep the macros in the current \verb!expand! setting.

To expand a command without optional argument, you can define it with \verb!\newcommand!.

\begin{demohigh}
\newcommand*\tblrrowa{
  20 & 30 & 40 \\
}
\newcommand*\tblrrowb{
  50 & 60 & 70 \\
}
\newcommand*\tblrbody{
 \hline
  \tblrrowa
  \tblrrowb
 \hline
}
\SetTblrOuter{expand=\tblrbody\tblrrowa}
\begin{tblr}[expand+=\tblrrowb]{ccc}
 \hline
  AA & BB & CC \\
  \tblrbody
  DD & EE & FF \\
  \tblrbody
  GG & HH & II \\
 \hline
\end{tblr}
\end{demohigh}

To expand commands with optional arguments, you \underline{can not} define them
with \verb!\newcommand!. But you can define them with \verb!\NewExpandableDocumentCommand!,
and use option \verb!expand=\expanded! to do exhaustive expansions.

\begin{demohigh}
\NewExpandableDocumentCommand\yes{O{Yes}m}{\SetCell{bg=green9}#1}
\NewExpandableDocumentCommand\no{O{No}m}{\SetCell{bg=red9}#1}
\begin{tblr}[expand=\expanded]{hlines}
  What I get               & is below              \\
  \expanded{\yes{}}        & \expanded{\no{}}      \\
  \expanded{\yes[Great]{}} & \expanded{\no[Bad]{}}
\end{tblr}
\end{demohigh}

Note that you need to protect fragile commands (if any) inside them with \verb!\unexpanded! command.

\section{Default Specifications}%
\label{sec:default}

\verb!Tabularray! package provides \verb!\SetTblrInner! and \verb!\SetTblrOuter! commands
for you to change the default inner and outer specifications of tables.

In general different \verb!tabularray! environments (\verb!tblr!, \verb!talltblr!,
\verb!longtblr!, etc) could have different default specifications.
You can list the environments in the optional arguments of these two commands,
and they only apply to \verb!tblr! environment when the optional arguments are omitted.

In the following example, the first line draws all hlines and vlines for all \verb!tblr! tables
created afterwards, while the second line makes all \verb!tblr! tables created afterwards
vertically align at the last row.

\begin{codehigh}
\SetTblrInner{hlines,vlines}
\SetTblrOuter{baseline=B}
\end{codehigh}

And the following example sets zero \verb!rowsep! for all \verb!tblr! and \verb!longtblr! tables
created afterwards.

\begin{codehigh}
\SetTblrInner[tblr,longtblr]{rowsep=0pt}
\end{codehigh}

\section{New Tabularray Environments}

You can define new \verb!tabularray! environments using \verb!\NewTblrEnviron! command:

\begin{demohigh}
\NewTblrEnviron{mytblr}
\SetTblrInner[mytblr]{hlines,vlines}
\SetTblrOuter[mytblr]{baseline=B}
Text \begin{mytblr}{cccc}
 Alpha   & Beta  & Gamma  & Delta \\
 Epsilon & Zeta  & Eta    & Theta \\
 Iota    & Kappa & Lambda & Mu    \\
\end{mytblr} Text
\end{demohigh}

\section{New General Environments}

With \verb!+b! argument type of \verb!\NewDocumentEnvironment! command,
you can also define a new general environment based on \verb!tblr! environment
(note that there is an extra pair of curly braces at the end):

\NewDocumentEnvironment{fancytblr}{+b}{
  Before Text
  \begin{tblr}{hlines}
    #1
  \end{tblr}
  After Text
}{}
\begin{codehigh}
\NewDocumentEnvironment{fancytblr}{+b}{
  Before Text
  \begin{tblr}{hlines}
    #1
  \end{tblr}
  After Text
}{}
\end{codehigh}
\begin{demohigh}
\begin{fancytblr}
  One   & Two   & Three \\
  Four  & Five  & Six   \\
  Seven & Eight & Nine  \\
\end{fancytblr}
\end{demohigh}

\section{New Table Commands}

All commands which change the specifications of tables \textcolor{red3}{must} be defined with \verb!\NewTableCommand!.
The following example demonstrates how to define a new table command:

\begin{demohigh}
\NewTableCommand\myhline{\hline[0.1em,red5]}
\begin{tblr}{llll}
\myhline
 Alpha   & Beta  & Gamma   & Delta \\
 Epsilon & Zeta  & Eta     & Theta \\
 Iota    & Kappa & Lambda  & Mu    \\
\myhline
\end{tblr}
\end{demohigh}

\section{Odd and Even Selectors}

From version 2022A, child selectors \verb!odd! and \verb!even! accept an optional argument,
in which you can specify the start index and the end index of the children.

\begin{demohigh}
\begin{tblr}{
  cell{odd}{1} = {red9},
  cell{odd[4]}{2} = {green9},
  cell{odd[3-X]}{3} = {blue9},
}
  Head   & Head    & Head   \\
  Talk A & Place A & Date A \\
  Talk B & Place B & Date B \\
  Talk C & Place C & Date C \\
  Talk D & Place D & Date D \\
  Talk E & Place E & Date E \\
  Talk F & Place F & Date F \\
  Talk G & Place G & Date G \\
  Talk H & Place H & Date H \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{
  cell{even}{1} = {yellow9},
  cell{even[4]}{2} = {cyan9},
  cell{even[3-X]}{3} = {purple9},
}
  Head   & Head    & Head   \\
  Talk A & Place A & Date A \\
  Talk B & Place B & Date B \\
  Talk C & Place C & Date C \\
  Talk D & Place D & Date D \\
  Talk E & Place E & Date E \\
  Talk F & Place F & Date F \\
  Talk G & Place G & Date G \\
  Talk H & Place H & Date H \\
\end{tblr}
\end{demohigh}

\section{Counters and Lengths}

Counters \verb!rownum!, \verb!colnum!, \verb!rowcount!, \verb!colcount! can be used in cell text:
\nopagebreak
\begin{demohigh}
\begin{tblr}{hlines}
 Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
 Row=\arabic{rowcount}, Col=\arabic{colcount} &
 Row=\arabic{rowcount}, Col=\arabic{colcount} &
 Row=\arabic{rowcount}, Col=\arabic{colcount} &
 Row=\arabic{rowcount}, Col=\arabic{colcount} \\
 Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] &
 Cell[\arabic{rownum}][\arabic{colnum}] & Cell[\arabic{rownum}][\arabic{colnum}] \\
\end{tblr}
\end{demohigh}

Also, lengths \verb!\leftsep!, \verb!\rightsep!, \verb!\abovesep!, \verb!\belowsep! can be used in cell text.

\section{Tracing Tabularray}

To trace internal data behind \verb!tblr! environment, you can use \verb!\SetTblrTracing! command.
For example, \verb!\SetTblrTracing{all}! will turn on all tracings,
and \verb!\SetTblrTracing{none}! will turn off all tracings.
\verb!\SetTblrTracing{+row,+column}! will only tracing row and column data.
All tracing messages will be written to the log files.

\chapter{Use Long Tables}
\label{chap:long}

\section{A Simple Example}

To make a decent long table with header and footer, it is better to separate header/footer as
\underline{table head/foot} (which includes caption, footnotes, continuation text)
and \underline{row head/foot} (which includes some rows of the table that should appear in every page).
By this approach, alternating row colors work as expected.

\NewTblrTheme{fancy}{
  \SetTblrStyle{firsthead}{font=\bfseries}
  \SetTblrStyle{firstfoot}{fg=blue2}
  \SetTblrStyle{middlefoot}{\itshape}
  \SetTblrStyle{caption-tag}{red2}
}
\begin{longtblr}[
  theme = fancy,
  caption = {A Long Long Long Long Long Long Long Table},
  entry = {Short Caption},
  label = {tblr:test},
  note{a} = {It is the first footnote.},
  note{$\dag$} = {It is the second long long long long long long footnote.},
  remark{Note} = {Some general note. Some general note. Some general note.},
  remark{Source} = {Made up by myself. Made up by myself. Made up by myself.},
]{
  colspec = {XXX}, width = 0.85\linewidth,
  rowhead = 2, rowfoot = 1,
  row{odd} = {gray9}, row{even} = {brown9},
  row{1-2} = {purple7}, row{Z} = {blue7},
}
\hline
 Head    & Head  & Head    \\
\hline
 Head    & Head  & Head    \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta\TblrNote{a}       & Eta    \\
\hline
 Iota    & Kappa\TblrNote{$\dag$} & Lambda \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Foot    & Foot  & Foot    \\
\hline
\end{longtblr}

As you can see in the above example, the appearance of long tables of \verb!tabularray! package
is similar to that of \verb!threeparttablex! packages.
It supports table footnotes, but not page footnotes.

\newpage

The source code for the above long table is shown below. It is mainly self-explanatory.

\begin{codehigh}
\NewTblrTheme{fancy}{
  \SetTblrStyle{firsthead}{font=\bfseries}
  \SetTblrStyle{firstfoot}{fg=blue2}
  \SetTblrStyle{middlefoot}{\itshape}
  \SetTblrStyle{caption-tag}{red2}
}
\begin{longtblr}[
  theme = fancy,
  caption = {A Long Long Long Long Long Long Long Table},
  entry = {Short Caption},
  label = {tblr:test},
  note{a} = {It is the first footnote.},
  note{$\dag$} = {It is the second long long long long long long footnote.},
  remark{Note} = {Some general note. Some general note. Some general note.},
  remark{Source} = {Made up by myself. Made up by myself. Made up by myself.},
]{
  colspec = {XXX}, width = 0.85\linewidth,
  rowhead = 2, rowfoot = 1,
  row{odd} = {gray9}, row{even} = {brown9},
  row{1-2} = {purple7}, row{Z} = {blue7},
}
\hline
 Head    & Head  & Head    \\
\hline
 Head    & Head  & Head    \\
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta\TblrNote{a}       & Eta    \\
\hline
 Iota    & Kappa\TblrNote{$\dag$} & Lambda \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
......
\hline
 Alpha   & Beta  & Gamma   \\
\hline
 Epsilon & Zeta  & Eta     \\
\hline
 Iota    & Kappa & Lambda  \\
\hline
 Nu      & Xi    & Omicron \\
\hline
 Rho     & Sigma & Tau     \\
\hline
 Phi     & Chi   & Psi     \\
\hline
 Foot    & Foot  & Foot    \\
\hline
\end{longtblr}
\end{codehigh}

As you can see in the above code, we typeset long tables with \verb!longtblr! environment.
And we can totally separate contents and styles of long tables with \verb!tabularray! package.

Row head and row foot consist of some lines of the table and should appear in every page.
Their options are inner specifications and should be put in the mandatory argument of the \verb!longtblr! environment.
In the above example, We set \verb!rowhead=2! and \verb!rowfoot=1!.

\begin{spectblr}[
  caption = {Inner Specifications for Row Heads and Row Foots}
]{}
  Key Name    & Key Description & Initial Value \\
  \V{rowhead} & number of the first rows of the table appear in every page & \V{0} \\
  \V{rowfoot} & number of the last rows of the table appear in every page  & \V{0} \\
\end{spectblr}

Table head and table foot consist of the caption, continuation text, footnotes and remarks.
Their options are outer specifications and should be put in the optional argument of the \verb!longtblr! environment.

\begin{spectblr}[
  caption = {Outer Specifications for Table Heads and Table Foots}
]{verb}
  Key Name            & Key Description & Initial Value \\
  \V{headsep}         & vertical space between table head and table body & \V{6pt} \\
  \V{footsep}         & vertical space between table foot and table body & \V{6pt} \\
  \V{presep}          & vertical space between table head and the above text & \verb!1.5\bigskipamount! \\
  \V{postsep}         & vertical space between table foot and the below text & \verb!1.5\bigskipamount! \\
  \V{theme}           & table theme (including settings for templates and styles) & \None \\
  \V{caption}         & table caption & \None \\
  \V{entry}           & short table caption to be put in List of Tables & \None \\
  \V{label}           & table label & \None \\
  \V{note\{<name>\}}   & table note with \V{<name>} as tag & \None \\
  \V{remark\{<name>\}} & table remark with \V{<name>} as tag & \None \\
\end{spectblr}

If you write \verb!entry=none!, \verb!tabularray! package will not add an entry in List of Tables.
Therefore \verb!caption=text,entry=none! is similar to \verb!\caption[]{text}! in \verb!longtable!.

If you write \verb!label=none!, \verb!tabularray! package will not step \verb!table! counter,
and set the \verb!caption-tag! and \verb!caption-sep! elements (see below) to empty.
Therefore \verb!caption=text,entry=none,label=none! is similar to \verb!\caption*{text}!
in \verb!longtable!, except for the counter.

\section{Customize Templates}

\subsection{Overview of Templates}

The template system for table heads and table foots in \verb!tabularray! is largely inspired
by \verb!beamer!, \verb!caption! and \verb!longtable! packages. For elements in Table \ref{tblr:element},
you can use \verb!\DefTblrTemplate!\footnote{From version 2022A,
\texttt{\string\DefTblrTemplate} has another name \texttt{\string\DeclareTblrTemplate}.}
to define and modify templates,
and use \verb!\SetTblrTemplate! to choose default templates. In defining templates,
you can include other templates with \verb!\UseTblrTemplate! and \verb!\ExpTblrTemplate! commands.

\begin{spectblr}[
  caption = {Elements for Table Heads and Table Foots},
  label = {tblr:element},
]{}
  Element Name     & Element Description and Default Template \\
  \V{contfoot-text}& continuation text in the foot, normally ``Continued on next page'' \\
  \V{contfoot}     & continuation paragraph in the foot, normally including \V{contfoot-text} template \\
  \V{conthead-text}& continuation text in the head, normally ``(Continued)'' \\
  \V{conthead}     & continuation paragraph in the head, normally including \V{conthead-text} template \\
  \V{caption-tag}  & caption tag, normally like ``Table 4.2'' \\
  \V{caption-sep}  & caption separator, normally like ``:\quad'' \\
  \V{caption-text} & caption text, normally using user provided value \\
  \V{caption}      & including \V{caption-tag} + \V{caption-sep} + \V{caption-text} \\
  \V{note-tag}     & note tag, normally using user provided value \\
  \V{note-sep}     & note separator, normally like ``\enskip'' \\
  \V{note-text}    & note tag, normally using user provided value \\
  \V{note}         & including \V{note-tag} + \V{note-sep} + \V{note-text} \\
  \V{remark-tag}   & remark tag, normally using user provided value \\
  \V{remark-sep}   & remark separator, normally like ``:\enskip'' \\
  \V{remark-text}  & remark text, normally using user provided value\\
  \V{remark}       & including \V{remark-tag} + \V{remark-sep} + \V{remark-text} \\
  \V{firsthead}    & table head on the first page, normally including \V{caption} template \\
  \V{middlehead}   & table head on middle pages, normally including \V{caption} and \V{conthead} templates \\
  \V{lasthead}     & table head on the last page, normally including \V{caption} and \V{conthead} templates \\
  \V{head}         & setting all of \V{firsthead}, \V{middlehead} and \V{lasthead} \\
  \V{firstfoot}    & table foot on the first page, normally including \V{contfoot} template \\
  \V{middlefoot}   & table foot on middle pages, normally including \V{contfoot} template \\
  \V{lastfoot}     & table foot on the last page, normally including \V{note} and \V{remark} templates \\
  \V{foot}         & setting all of \V{firstfoot}, \V{middlefoot} and \V{lastfoot} \\
\end{spectblr}

An element which only includes short text is called a \underline{sub element}.
Normally there is one \verb!-! in the name of a sub element.
An element which includes one or more paragraphs is called a \underline{main element}.
Normally there isn't any \verb!-! in the name of a main element.

For each of the above elements, two templates \verb!normal! and \verb!empty! are always defined.
You can select one of them with \verb!\SetTblrTemplate! command.

\subsection{Continuation Templates}

Let us have a look at the code for defining templates of continuation text first:%
\footnote{To tell the truth, the default \texttt{conthead-text} and \texttt{contfoot-text}
are actually stored in commands \texttt{\string\tblrcontheadname} and \texttt{\string\tblrcontfootname}
respectively. And you may contribute your translations of them to \textbf{babel} package.}

\begin{codehigh}
\DefTblrTemplate{contfoot-text}{normal}{Continued on next page}
\SetTblrTemplate{contfoot-text}{normal}
\DefTblrTemplate{conthead-text}{normal}{(Continued)}
\SetTblrTemplate{conthead-text}{normal}
\end{codehigh}

In the above code, command \verb!\DefTblrTemplate! defines the templates with name \verb!normal!,
and then command \verb!\SetTblrTemplate! sets the templates with name \verb!normal! as default.
The \verb!normal! template is always defined and set as default for any element in \verb!tabularray!.
Therefore you had better use another name when defining new templates.

If you use \verb!default! as template name in \verb!\DefTblrTemplate!,
you define and set it as default at the same time.
Therefore the above code can be written in another way:

\begin{codehigh}
\DefTblrTemplate{contfoot-text}{default}{Continued on next page}
\DefTblrTemplate{conthead-text}{default}{(Continued)}
\end{codehigh}

You may modify the code to customize continuation text to fit your needs.

The templates for \verb!contfoot! and \verb!conthead! normally
include the templates of their sub elements with \verb!\UseTblrTemplate! commands.
But you can also handle user settings such as horizontal alignment here.

\begin{codehigh}
\DefTblrTemplate{contfoot}{default}{\UseTblrTemplate{contfoot-text}{default}}
\DefTblrTemplate{conthead}{default}{\UseTblrTemplate{conthead-text}{default}}
\end{codehigh}

\subsection{Caption Templates}

Normally a caption consists of three parts, and their templates are defined with the follow code:

\begin{codehigh}
\DefTblrTemplate{caption-tag}{default}{Table\hspace{0.25em}\thetable}
\DefTblrTemplate{caption-sep}{default}{:\enskip}
\DefTblrTemplate{caption-text}{default}{\InsertTblrText{caption}}
\end{codehigh}

The command \verb!\InsertTblrText{caption}! inserts the value of \verb!caption! key,
which you could write in the optional argument of \verb!longtblr! environment.

The \verb!caption! template normally includes three sub templates with \verb!\UseTblrTemplate! commands:
The \verb!caption! template will be used in \verb!firsthead! template.

\begin{codehigh}
\DefTblrTemplate{caption}{default}{
  \UseTblrTemplate{caption-tag}{default}
  \UseTblrTemplate{caption-sep}{default}
  \UseTblrTemplate{caption-text}{default}
}
\end{codehigh}

Furthermore \verb!capcont! template includes \verb!conthead! template as well.
The \verb!capcont! template will be used in \verb!middlehead! and \verb!lasthead! templates.

\begin{codehigh}
\DefTblrTemplate{capcont}{default}{
  \UseTblrTemplate{caption-tag}{default}
  \UseTblrTemplate{caption-sep}{default}
  \UseTblrTemplate{caption-text}{default}
  \UseTblrTemplate{conthead-text}{default}
}
\end{codehigh}

\subsection{Note and Remark Templates}

The templates for table notes can be defined like this:

\begin{codehigh}
\DefTblrTemplate{note-tag}{default}{\textsuperscript{\InsertTblrNoteTag}}
\DefTblrTemplate{note-sep}{default}{\space}
\DefTblrTemplate{note-text}{default}{\InsertTblrNoteText}
\end{codehigh}
\begin{codehigh}
\DefTblrTemplate{note}{default}{
  \MapTblrNotes{
    \noindent
    \UseTblrTemplate{note-tag}{default}
    \UseTblrTemplate{note-sep}{default}
    \UseTblrTemplate{note-text}{default}
    \par
  }
}
\end{codehigh}

The \verb!\MapTblrNotes! command loops for all table notes,
which are written in the optional argument of \verb!longtblr! environment.
Inside the loop, you can use \verb!\InsertTblrNoteTag! and \verb!\InsertTblrNoteText!
commands to insert current note tag and note text, respectively.

The definition of remark templates are similar to note templates.
\nopagebreak
\begin{codehigh}
\DefTblrTemplate{remark-tag}{default}{\InsertTblrRemarkTag}
\DefTblrTemplate{remark-sep}{default}{:\space}
\DefTblrTemplate{remark-text}{default}{\InsertTblrRemarkText}
\end{codehigh}
\begin{codehigh}
\DefTblrTemplate{remark}{default}{
  \MapTblrRemarks{
    \noindent
    \UseTblrTemplate{remark-tag}{default}
    \UseTblrTemplate{remark-sep}{default}
    \UseTblrTemplate{remark-text}{default}
    \par
  }
}
\end{codehigh}

\subsection{Head and Foot Templates}

The templates for table heads and foots are defined as including other templates:

\begin{codehigh}
\DefTblrTemplate{firsthead}{default}{
  \UseTblrTemplate{caption}{default}
}
\DefTblrTemplate{middlehead,lasthead}{default}{
  \UseTblrTemplate{capcont}{default}
}
\DefTblrTemplate{firstfoot,middlefoot}{default}{
  \UseTblrTemplate{contfoot}{default}
}
\DefTblrTemplate{lastfoot}{default}{
  \UseTblrTemplate{note}{default}
  \UseTblrTemplate{remark}{default}
}
\end{codehigh}

Note that you can define the same template for multiple elements in \verb!\DefTblrTemplate! command.
If you only want to show table caption in the first page, you may change the definitions of
\verb!middlehead! and \verb!lasthead! elements:

\begin{codehigh}
\DefTblrTemplate{middlehead,lasthead}{default}{
  \UseTblrTemplate{conthead}{default}
}
\end{codehigh}

\section{Change Styles}

All available keys for template elements are described in Table \ref{key:element}.

\begin{spectblr}[
  caption = {Keys for the Styles of Elements},
  label = {key:element},
  remark{Note} = {In most cases, you can omit the underlined key names and write only their values.
                  The keys \K{halign}, \K{indent} and \K{hang} are only for main templates.}
]{}
  Key Name               & Key Description  & Initial Value\\
  \underline{\K{fg}}     & foreground color & \None \\
  \underline{\K{font}}   & font commands    & \None \\
  \underline{\K{halign}}
     & horizontal alignment: \V{l} (left), \V{c} (center), \V{r} (right) or \V{j} (justify)
                                            & \V{j} \\
  \K{indent}             & parindent value  & \V{0pt} \\
  \K{hang}               & hangindent value & \V{0pt} or \V{0.7em} \\
\end{spectblr}

You may change the styles of elements with \verb!\SetTblrStyle! command:

\begin{codehigh}
\SetTblrStyle{firsthead}{font=\bfseries}
\SetTblrStyle{firstfoot}{fg=blue2}
\SetTblrStyle{middlefoot}{\itshape}
\SetTblrStyle{caption-tag}{red2}
\end{codehigh}

When you write \verb!\UseTblrTemplate{element}{default}! in defining a template,
beside including template code of the \verb!element!, the foreground color and font commands
of the \verb!element! will be set up automatically.
In contrast, \verb!\ExpTblrTemplate{element}{default}! will only include template code.

\section{Define Themes}

You may define your own themes for table heads and foots with \verb!\NewTblrTheme! command.
a theme consists of some template and style settings. For example:
\nopagebreak
\begin{codehigh}
\NewTblrTheme{fancy}{
  \DefTblrTemplate{conthead}{default}{[Continued]}
  \SetTblrStyle{firsthead}{font=\bfseries}
  \SetTblrStyle{firstfoot}{fg=blue2}
  \SetTblrStyle{middlefoot}{\itshape}
  \SetTblrStyle{caption-tag}{red2}
}
\end{codehigh}

After defining the theme \verb!fancy!, you can use it
by writing \verb!theme=fancy! in the optional argument of \verb!longtblr! environment.

\section{Control Page Breaks}

Just like \verb!longtable! package, inside \verb!longtblr! environment,
you can use \verb!\\*! or \verb!\nopagebreak! to prohibit a page break,
and use \verb!\pagebreak! to force a page break.

\section{Floatable Tall Tables}

There is also a \verb!talltblr! environment as an alternative to \verb!threeparttable! environment.
It can not cross multiple pages, but it can be put inside \verb!table! environment.

\begin{demohigh}
TEXT\begin{talltblr}[
  caption = {Long Long Long Long Tabular},
  entry = {Short Caption},
  label = {tblr:tall},
  note{a} = {It is the first footnote.},
  note{$\dag$} = {It is the second long long long long long long footnote.},
]{
  colspec = {XXX}, width = 0.5\linewidth, hlines,
}
  Alpha   & Beta  & Gamma \\
  Epsilon & Zeta  & Eta\TblrNote{a} \\
  Iota    & Kappa & Lambda\TblrNote{$\dag$} \\
\end{talltblr}TEXT
\end{demohigh}

\chapter{Use Some Libraries}

The \verb!tabularray! package emulates or fixes some commands in other packages.
To avoid potential conflict, you need to enable them with \verb!\UseTblrLibrary! command.

\section{Library \texttt{amsmath}}

With \verb!\UseTblrLibrary{amsmath}! in the preamble of the document,
\verb!tabularray! will load \verb!amsmath! package, and define \verb!+array!, \verb!+matrix!,
\verb!+bmatrix!, \verb!+Bmatrix!, \verb!+pmatrix!, \verb!+vmatrix!, \verb!+Vmatrix! and \verb!+cases!
environments. Each of the environments is similar to the environment without \verb!+! prefix in its name,
but has default \verb!rowsep=2pt! just as \verb!tblr! environment. Every environment
except \verb!+array! accepts an optional argument, where you can write inner specifications.

\begin{demo}
$\begin{pmatrix}
 \dfrac{2}{3} &  \dfrac{2}{3} &  \dfrac{1}{3} \\
 \dfrac{2}{3} & -\dfrac{1}{3} & -\dfrac{2}{3} \\
 \dfrac{1}{3} & -\dfrac{2}{3} &  \dfrac{2}{3} \\
\end{pmatrix}$
\end{demo}

\begin{demohigh}
$\begin{+pmatrix}[cells={r},row{2}={purple8}]
 \dfrac{2}{3} &  \dfrac{2}{3} &  \dfrac{1}{3} \\
 \dfrac{2}{3} & -\dfrac{1}{3} & -\dfrac{2}{3} \\
 \dfrac{1}{3} & -\dfrac{2}{3} &  \dfrac{2}{3} \\
\end{+pmatrix}$
\end{demohigh}

\begin{demo}
$f(x)=\begin{cases}
 0,            & x=1; \\
 \dfrac{1}{3}, & x=2; \\
 \dfrac{2}{3}, & x=3; \\
 1,            & x=4. \\
\end{cases}$
\end{demo}

\begin{demohigh}
$f(x)=\begin{+cases}
 0,            & x=1; \\
 \dfrac{1}{3}, & x=2; \\
 \dfrac{2}{3}, & x=3; \\
 1,            & x=4. \\
\end{+cases}$
\end{demohigh}

\section{Library \texttt{booktabs}}

With \verb!\UseTblrLibrary{booktabs}! in the preamble of the document,
\verb!tabularray! will load \verb!booktabs! package,
and define
  \verb!\toprule!, \verb!\midrule!, \verb!\bottomrule!,
  \verb!\cmidrule!, \verb!\cmidrulemore!, \verb!\morecmidrules!,
  \verb!\specialrule!, \verb!\addrowspace!, and \verb!\addlinespace!
as table commands.

\begin{demohigh}
\begin{tblr}{llll}
\toprule
 Alpha   & Beta  & Gamma   & Delta \\
\midrule
 Epsilon & Zeta  & Eta     & Theta \\
\cmidrule{1-3}
 Iota    & Kappa & Lambda  & Mu    \\
\cmidrule{2-4}
 Nu      & Xi    & Omicron & Pi    \\
\bottomrule
\end{tblr}
\end{demohigh}

Just like \verb!\hline! and \verb!\cline! commands,
you can also specify rule width and color by using hline keys in the optional
argument of any of these commands.

Like in \verb!booktabs!, by default
  width of \verb!\toprule! and \verb!\bottomrule! are determined by \verb!\heavyrulewidth!,
  width of \verb!\midrule! is determined by \verb!\lightrulewidth!, and
  width of \verb!\cmidrule! and \verb!\cmidrulemore! are determined by \verb!\cmidrulewidth!, respectively.
All three \verb!\...rulewidth! are dimensions.

\begin{demohigh}
\begin{tblr}{llll}
\toprule[2pt,purple3]
 Alpha   & Beta  & Gamma  & Delta \\
\midrule[blue3]
 Epsilon & Zeta  & Eta    & Theta \\
\cmidrule[azure3]{2-3}
 Iota    & Kappa & Lambda & Mu    \\
\bottomrule[2pt,purple3]
\end{tblr}
\end{demohigh}

If you need more than one \verb!\cmidrule!s, you can use \verb!\cmidrulemore!
command, which is simpler than the \verb!booktabs! usage
\verb!\morecmidrules\cmidrule!.
\verb!\cmidrulemore! can receive hline keys in an optional argument too.

\begin{demohigh}
\begin{tblr}{llll}
\toprule
 Alpha   & Beta  & Gamma   & Delta \\
\cmidrule{1-3} \cmidrulemore{2-4}
 Epsilon & Zeta  & Eta     & Theta \\
\cmidrule{1-3} \morecmidrules \cmidrule{2-4}
 Iota    & Kappa & Lambda  & Mu    \\
\bottomrule
\end{tblr}
\end{demohigh}

From version 2021N (2021-09-01), you can set trimming positions of
\verb!\cmidrule! and \verb!\cmidrulemore!, using newly introduced trimming
options (\verb!leftpos!, \verb!rightpos!, \verb!endpos!, \verb!l!, \verb!r!,
and \verb!lr!) (see Section~\ref{sec:hlines-vlines}).
Option \verb!endpos! is already applied to these two commands.

\begin{demohigh}
\begin{tblr}{llll}
\toprule
 Alpha   & Beta  & Gamma   & Delta \\
\cmidrule[lr]{1-2} \cmidrule[lr=-0.4]{3-4}
 Epsilon & Zeta  & Eta     & Theta \\
\cmidrule[r]{1-2} \cmidrule[l]{3-4}
 Iota    & Kappa & Lambda  & Mu    \\
\bottomrule
\end{tblr}
\end{demohigh}

Since \verb!booktabs! tables usually don't have vlines, the meaningful values
here are decimal numbers between \verb!-1! and \verb!0!.
The default value \verb!-0.8! for \verb!l!, \verb!r!, and \verb!lr! is chosen to
make similar result as \verb!booktabs! package does.

There is also a \verb!booktabs! environment for you. With this environment,
the default \verb!rowsep=0pt!, but extra vertical space will be added by
\verb!\toprule!, \verb!\midrule!, \verb!\bottomrule! and \verb!\cmidrule! commands.
The sizes of vertical space are determined by \verb!\aboverulesep! and \verb!\belowrulesep! dimensions.

\begin{demohigh}
\begin{booktabs}{
  colspec = lcccc,
  cell{1}{1} = {r=2}{}, cell{1}{2,4} = {c=2}{},
}
\toprule
  Sample & I &   & II &   \\
\cmidrule[lr]{2-3} \cmidrule[lr]{4-5}
         & A & B & C & D \\
\midrule
  S1     & 5 & 6 & 7 & 8 \\
  S2     & 6 & 7 & 8 & 5 \\
  S3     & 7 & 8 & 5 & 6 \\
\bottomrule
\end{booktabs}
\end{demohigh}
% S4     & 8 & 5 & 6 & 7 \\

You can also use \verb!\specialrule! command.
The second argument sets \verb!belowsep! of previous row,
and the third argument sets \verb!abovesep! of current row,

\begin{demohigh}
\begin{booktabs}{row{2}={olive9}}
\toprule
 Alpha   & Beta  & Gamma   & Delta \\
\specialrule{0.5pt}{4pt}{6pt}
 Epsilon & Zeta  & Eta     & Theta \\
\specialrule{0.8pt,blue3}{3pt}{2pt}
 Iota    & Kappa & Lambda  & Mu    \\
\bottomrule
\end{booktabs}
\end{demohigh}

At last, there is also an \verb!\addlinespace! command, with an alternative
name \verb!\addrowspace!.
You can specify the size of vertical space to be added in its optional
argument, and the default size is determinted by \verb!\defaultaddspace!
dimension, initially \verb!0.5em!.
This command adds one half of the space to \verb!belowsep! of previous row,
and the other half to \verb!abovesep! of current row.

\begin{demohigh}
\begin{booktabs}{row{2}={olive9}}
\toprule
 Alpha   & Beta  & Gamma   & Delta \\
\addlinespace
 Epsilon & Zeta  & Eta     & Theta \\
\addlinespace[1em]
 Iota    & Kappa & Lambda  & Mu    \\
\bottomrule
\end{booktabs}
\end{demohigh}

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

You need to load \verb!counter! library with \verb!\UseTblrLibrary{counter}!,
if you want to modify some LaTeX counters inside \verb!tabularray! tables.

\begin{demohigh}
\newcounter{mycnta}
\newcommand{\mycnta}{\stepcounter{mycnta}\arabic{mycnta}}
\begin{tblr}{hlines}
  \mycnta & \mycnta & \mycnta \\
  \mycnta & \mycnta & \mycnta \\
  \mycnta & \mycnta & \mycnta \\
\end{tblr}
\end{demohigh}

\section{Library \texttt{diagbox}}

When writing \verb!\UseTblrLibrary{diagbox}! in the preamble of the document,
\verb!tabularray! package loads \verb!diagbox! package,
and you can use \verb!\diagbox! and \verb!\diagboxthree! commands inside \verb!tblr! environment.

\begin{demohigh}
\begin{tblr}{hlines,vlines}
 \diagbox{Aa}{Pp} & Beta & Gamma \\
 Epsilon & Zeta  & Eta \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{hlines,vlines}
 \diagboxthree{Aa}{Pp}{Hh} & Beta & Gamma \\
 Epsilon & Zeta  & Eta \\
 Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

You can also use \verb!\diagbox! and \verb!\diagboxthree! commands in math mode.
\nopagebreak
\begin{demohigh}
$\begin{tblr}{|c|cc|}
\hline
 \diagbox{X_1}{X_2} & 0 & 1 \\
\hline
  0 & 0.1 & 0.2 \\
  1 & 0.3 & 0.4 \\
\hline
\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!.
This library brings intuitive functional programming into \verb!tabularray! tables.

\subsection{Evaluate inner specifications}

With this library, \verb!tabularray! will evaluate every function
(defined with \verb!\prgNewFunction!) within inner specifications,
replacing it with its return value, before parsing the key-value pairs. Here is an example:

\begin{demohigh}
\begin{tblr}{
  row{2} = {bg=\intIfOddTF{\value{page}}{\prgReturn{red7}}{\prgReturn{blue7}}}
}
  Alpha   & Beta  & Gamma  \\
  Epsilon & Zeta  & Eta    \\
  Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

You may like to define a new function for it if you need to use it several times:

\begin{demohigh}
\IgnoreSpacesOn
\prgNewFunction \magicColor {mm} {
  \intIfOddTF{\value{page}}{\prgReturn{#1}}{\prgReturn{#2}}
}
\IgnoreSpacesOff
\begin{tblr}{
  row{1} = {bg=\magicColor{yellow7}{brown7}},
  row{3} = {bg=\magicColor{green7}{teal7}}
}
  Alpha   & Beta  & Gamma  \\
  Epsilon & Zeta  & Eta    \\
  Iota    & Kappa & Lambda \\
\end{tblr}
\end{demohigh}

\subsection{Evaluate table body}

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}

From version 2023A, you can evaluate all functions in the table body
with option \texttt{evaluate=all}.

\subsection{Process table elements}

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{hook}}

This library is experimental, please see\\
\url{https://github.com/lvjr/tabularray/wiki/HooksAndVariables}.

\section{Library \texttt{html}}

This library is experimental, please see\\
\url{https://github.com/lvjr/tabularray/wiki/HooksAndVariables}.

\section{Library \texttt{nameref}}

From version 2022D, you can load \verb!nameref! library
to make \verb!\nameref! and \verb!longtblr! work together.

\section{Library \texttt{siunitx}}

When writing \verb!\UseTblrLibrary{siunitx}! in the preamble of the document,
\verb!tabularray! package loads \verb!siunitx! package,
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]}
}
 {{{Head}}} & {{{Head}}} \\
   111      &   111      \\
     2.1    &     2.2    \\
    33.11   &    33.22   \\
\end{tblr}
\end{demohigh}

\begin{demohigh}
\begin{tblr}{
  hlines, vlines,
  colspec={Q[si={table-format=3.2},c]Q[si={table-format=3.2},c]}
}
 {{{Head}}} & {{{Head}}} \\
   111      &   111      \\
     2.1    &     2.2    \\
    33.11   &    33.22   \\
\end{tblr}
\end{demohigh}

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
\begin{demohigh}
\begin{tblr}{
  hlines, vlines, columns={6em},
  colspec={
    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 \\
\end{tblr}
\end{demohigh}

Both \verb!S! and \verb!s! columns are supported. In fact, These two columns have been defined as follows:
\begin{codehigh}
\NewColumnType{S}[1][]{Q[si={#1},c]}
\NewColumnType{s}[1][]{Q[si={#1},c,cmd=\TblrUnit]}
\end{codehigh}
You don't need to and are not allowed to define them again.

\section{Library \texttt{varwidth}}

To build a nice table, \verb!tabularray! need to measure the widths of cells.
By default, it uses \verb!\hbox! to measure the sizes.
This causes an error if a cell contains some vertical material, such as lists or display maths.

With \verb!\UseTblrLibrary{varwidth}! in the preamble of the document,
\verb!tabularray! will load \verb!varwidth! package,
and add a new inner specification \verb!measure! for tables.
After setting \verb!measure=vbox!, it will use \verb!\vbox! to measure cell widths.

\begin{demohigh}
\begin{tblr}{hlines,measure=vbox}
  Text Text Text Text Text Text Text
  \begin{itemize}
    \item List List List List List List
    \item List List List List List List List
  \end{itemize}
  Text Text Text Text Text Text Text \\
\end{tblr}
\end{demohigh}

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:

{\centering\begin{tblr}{
  hlines,vlines,rowspec={Q[l,t]Q[l,b]},
  measure=vbox,stretch=-1,
}
  \begin{itemize}[nosep]
    \item List List List List List
    \item List List List List List List
  \end{itemize} & oooo \\
  \begin{itemize}[nosep]
    \item List List List List List
    \item List List List List List List
  \end{itemize} & gggg \\
\end{tblr}\par}

%% BUG: there is extra vertical space at the beginning of the first cell if I use demohigh
%\begin{demohigh}
\begin{codehigh}
\begin{tblr}{
  hlines,vlines,rowspec={Q[l,t]Q[l,b]},
  measure=vbox,stretch=-1,
}
  \begin{itemize}[nosep]
    \item List List List List List
    \item List List List List List List
  \end{itemize} & oooo \\
  \begin{itemize}[nosep]
    \item List List List List List
    \item List List List List List List
  \end{itemize} & gggg \\
\end{tblr}
\end{codehigh}
%\end{demohigh}

Note that option \verb!stretch=-1! also removes struts from cells, therefore it may not work well
in \verb!tabularray! environments with \verb!rowsep=0pt!, such as
\verb!booktabs!/\verb!longtabs!/\verb!talltabs! environments from \verb!booktabs! library.

\section{Library \texttt{zref}}

From version 2022D, you can load \verb!zref! library
to make \verb!\zref! and \verb!longtblr! work together.

\chapter{Tips and Tricks}

\section{Control Horizontal Alignment}

You can control horizontal alignment of cells in \texttt{tabularray} with
\href{https://www.ctan.org/pkg/ragged2e}{\texttt{ragged2e}} package,
by redefining some of the following commands:

\begin{codehigh}
\RenewDocumentCommand\TblrAlignBoth{}{\justifying}
\RenewDocumentCommand\TblrAlignLeft{}{\RaggedRight}
\RenewDocumentCommand\TblrAlignCenter{}{\Centering}
\RenewDocumentCommand\TblrAlignRight{}{\RaggedLeft}
\end{codehigh}

Please read the documentation of \texttt{ragged2e} package for more details of
their alignment commands.

\section{Use Safe Verbatim Commands}%
\label{sec:fakeverb}

Due to the limitations of TeX,
we are not able to make \fakeverb{\verb} command behave well inside \texttt{tabularray} tables.
As a replacement, you may use \fakeverb{\fakeverb} command from \href{https://www.ctan.org/pkg/codehigh}{\texttt{codehigh}} package.

The \verb|\fakeverb| command will remove the backslashes in the following control symbols before
typesetting its content: \fakeverb{\\\\}, \fakeverb{\\\{}, \fakeverb{\\\}}, \fakeverb{\\\#}, \fakeverb{\\\^} and \texttt{\textbackslash\textvisiblespace}, \fakeverb{\\\%}.
Also the argument of \verb|\fakeverb| command need to be enclosed with curly braces.
Therefore it could be safely used inside \verb|tabularray| tables and other LaTeX commands.

Here is an example of using \verb!\fakeverb! commands inside a \verb|tblr| environment
(you don't need \texttt{verb} option to use \verb!\fakeverb!):

\begin{demohigh}
\begin{tblr}{hlines}
  Special & \fakeverb{\abc{}$&^_^uvw 123} \\
  Spacing & \fakeverb{\bfseries\ \#\%}    \\
  Nesting & \fbox{\fakeverb{$\left\\\{A\right.$\#}}
\end{tblr}
\end{demohigh}

In the above example, balanced curly braces and control words (such as \verb!\bfseries!)
need not to be escaped---only several special characters need to be escaped.
Please read the documentation of \texttt{codehigh} package for more details of
\verb|\fakeverb| commands.%
\footnote{By the way, \fakeverb{\EscVerb} command from
\href{https://www.ctan.org/pkg/fvextra}{\texttt{fvextra}} package is similar to
\fakeverb{\fakeverb} command, but with \fakeverb{\EscVerb} you need to escape every control word.}

\chapter{History and Future}

\section{The Future}

As a policy, \verb!tabularray! can support at most four TeX Live releases with latest updates.
For example, \verb!tabularray! releases published in \the\year{} could be used in TeX Live
\inteval{\year-3}--\the\year{} with latest updates.

To make the upcoming releases more stable, you are very welcome to test the latest package file
in the repository. To test it, you only need to download the following \verb!tabularray.sty!
and put it into the folder of your TeX documents:\newline
\centerline{\url{https://github.com/lvjr/tabularray/raw/main/tabularray.sty}}

\section{The History}

The change log of \verb!tabularray! package will be updated on the wiki page:\newline
\centerline{\url{https://github.com/lvjr/tabularray/wiki/ChangeLog}}

In version 2023A, inner key \verb!verb! was marked as obsolete,
and it will be removed in the future. But don't worry too much,
because you can stick to old version by \verb!\usepackage{tabularray}[=2023-03-01]!.

In version 2022A, there were several breaking changes:

\begin{itemize}[nosep]
  \item \verb!\multicolumn! command was removed; it is better to use \verb!\SetCell! command.
  \item \verb!\multirow! command was removed; it is better to use \verb!\SetCell! command.
  \item \verb!\firsthline! command was removed; it is better to use \verb!baseline=T! option.
  \item \verb!\lasthline! command was removed; it is better to use \verb!baseline=B! option.
\end{itemize}

For your old documents, you can still rollback to version 2021 by \verb!\usepackage{tabularray}[=v2021]!.

\chapter{The Source Code}

%\CodeHigh{lite}
\dochighinput[language=latex/latex3]{tabularray.sty}

\end{document}