% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
\section{Repeating Things and Other Things}
\label{pkg:pgffor-ext}
\begin{texpackage}{pgffor-ext}
This package adds small niceties to the \referencePackageandIndexO{pgffor} package.
Most of these additions are also available
with the \referenceLibraryandIndex{ext.misc} library.
\textbf{Warning:} Consider this package experimental.
At the very least, it will break the |...| notation and possibly gobbles spaces after the body.
Instead of |\foreach \var in {start, start + delta, ..., end}| one can use
|\foreach \var[use int=start to end step delta]|.
\begin{key}{/\pgfforeachext/use int=\meta{start}|to|\meta{end}\opt{|step|\meta{delta}}}\keycompat{pgf/foreach}
The values \meta{start}, \meta{end} and \meta{delta} are evaluates by \pgfname math at initialization.
The part |step |\meta{delta} is optional (\meta{delta} = 1).
\end{key}
\begin{key}{/\pgfforeachext/use float=\meta{start}|to|\meta{end}\opt{|step|\meta{delta}}}\keycompat{pgf/foreach}
Same as above, however the results are not truncated.
\end{key}
\begin{key}{/\pgfforeachext/no separator}\keycompat{pgf/foreach}
This key disables any separator between elements of the list.
Every token is its own element. This also means that Unicode characters
need to be grouped between |{| and |}| if Lua\TeX\space isn't used.
Spaces will be ignored.
\begin{codeexample}[preamble=\usetikzlibrary{ext.misc}]
\newcommand*{\board}[3][]{%
\begin{tikzpicture}[#1]
\foreach[
count=\i from 0,
ext/no separator,
evaluate=\i as \colX using {mod(\i,#2)},
evaluate=\i as \rowY using {int(\i/#2)}
] \elem in {#3} {
\draw[black, board/\elem/.try, ext/rectangle timer/.try=line]
(\colX,\rowY) rectangle node {\elem} ++(1, 1);}
\end{tikzpicture}}
\board[
board/W/.style={fill=red},
board/X/.style={fill=blue!50},
board/B/.style={fill=green},
board/-/.style={fill=gray},
]{3}{WXX---BXX}
\end{codeexample}
\end{key}
\begin{key}{/\pgfforeachext/normal list}\keycompat{pgf/foreach}
This key simply disables all other special parsers and returns to the original list parser.
\end{key}
The following keys only work with \LaTeX\ and cannot be used when only the \referenceLibraryandIndex{ext.misc}
library or the plain\TeX\space |pgffor-ext.tex| are loaded.
For this, you will need to use |\usepackage{pgffor-ext}|.
\begin{key}{/\pgfforeachext/xparser=\marg{argument specification}\marg{foreach value}}\keycompat{pgf/foreach}
This key can be used to specify a \referencePackageandIndeXExt{xparse}
specification for each element in the list.
For this to work somewhat seamless, the following needs to observed:
\begin{itemize}
\item Every \marg{argument specification} get appended |u,|.
This means there's always one additional mandatory argument at the end of every element.
\item The \marg{foreach value} needs to correspond to the
\referenceKeyandIndexO[/pgf/foreach/]{var}
value.
\end{itemize}
\end{key}
\begin{key}{/\pgfforeachext/xparser Om=\opt{default} (default \{\})}\keycompat{pgf/foreach}
Sets up a list whose elements may contain an optional argument inside |[]| which correspond to
two |\foreach| variables, say |\Options/\Text|.
The \opt{default} value is the default value if the optional argument is missing.
\end{key}
\begin{ext_handler}{{list xparse}|=|\marg{argument specification}\marg{comma-separated list of values}}%
\handlercompat{.list xparse}
This handler causes the key to be used repeatedly, namely
once for every element of the list of values.
The \meta{comma-separated list of values} is processed using |\foreach|
and the given |xparse| \meta{argument specification} with the aforementioned |xparser| key.
\end{ext_handler}
