| 1 |
% !TeX spellcheck = en_US |
| 2 |
% !TeX root = tikz-ext-manual.tex |
| 3 |
% Copyright 2022 by Qrrbrbirlbel |
| 4 |
% |
| 5 |
% This file may be distributed and/or modified |
| 6 |
% |
| 7 |
% 1. under the LaTeX Project Public License and/or |
| 8 |
% 2. under the GNU Free Documentation License. |
| 9 |
% |
| 10 |
\section{Repeating Things and Other Things} |
| 11 |
\label{pkg:pgffor-ext} |
| 12 |
\begin{texpackage}{pgffor-ext} |
| 13 |
This package adds small niceties to the \referencePackageandIndexO{pgffor} package. |
| 14 |
Most of these additions are also available |
| 15 |
with the \referenceLibraryandIndex{ext.misc} library. |
| 16 |
|
| 17 |
\textbf{Warning:} Consider this package experimental. |
| 18 |
At the very least, it will break the |...| notation and possibly gobbles spaces after the body. |
| 19 |
|
| 20 |
\inspiration{ForeachUse-Q, ForeachNoSep-Q, ForeachXparse-Q}{ForeachUse-A, ForeachNoSep-A, ForeachXparse-A} |
| 21 |
\end{texpackage} |
| 22 |
|
| 23 |
Instead of |\foreach \var in {start, start + delta, ..., end}| one can use |
| 24 |
|\foreach \var[use int=start to end step delta]|. |
| 25 |
|
| 26 |
\begin{key}{/\pgfforeachext/use int=\meta{start}|to|\meta{end}\opt{|step|\meta{delta}}}\keycompat{pgf/foreach} |
| 27 |
The values \meta{start}, \meta{end} and \meta{delta} are evaluates by \pgfname math at initialization. |
| 28 |
The part |step |\meta{delta} is optional (\meta{delta} = 1). |
| 29 |
\end{key} |
| 30 |
|
| 31 |
\begin{key}{/\pgfforeachext/use float=\meta{start}|to|\meta{end}\opt{|step|\meta{delta}}}\keycompat{pgf/foreach} |
| 32 |
Same as above, however the results are not truncated. |
| 33 |
\end{key} |
| 34 |
|
| 35 |
\begin{key}{/\pgfforeachext/no separator}\keycompat{pgf/foreach} |
| 36 |
This key disables any separator between elements of the list. |
| 37 |
Every token is its own element. This also means that Unicode characters |
| 38 |
need to be grouped between |{| and |}| if Lua\TeX\space isn't used. |
| 39 |
Spaces will be ignored. |
| 40 |
|
| 41 |
\begin{codeexample}[preamble=\usetikzlibrary{ext.misc}] |
| 42 |
\newcommand*{\board}[3][]{% |
| 43 |
\begin{tikzpicture}[#1] |
| 44 |
\foreach[ |
| 45 |
count=\i from 0, |
| 46 |
ext/no separator, |
| 47 |
evaluate=\i as \colX using {mod(\i,#2)}, |
| 48 |
evaluate=\i as \rowY using {int(\i/#2)} |
| 49 |
] \elem in {#3} { |
| 50 |
\draw[black, board/\elem/.try, ext/rectangle timer/.try=line] |
| 51 |
(\colX,\rowY) rectangle node {\elem} ++(1, 1);} |
| 52 |
\end{tikzpicture}} |
| 53 |
\board[ |
| 54 |
board/W/.style={fill=red}, |
| 55 |
board/X/.style={fill=blue!50}, |
| 56 |
board/B/.style={fill=green}, |
| 57 |
board/-/.style={fill=gray}, |
| 58 |
]{3}{WXX---BXX} |
| 59 |
\end{codeexample} |
| 60 |
\end{key} |
| 61 |
|
| 62 |
\begin{key}{/\pgfforeachext/normal list}\keycompat{pgf/foreach} |
| 63 |
This key simply disables all other special parsers and returns to the original list parser. |
| 64 |
\end{key} |
| 65 |
|
| 66 |
The following keys only work with \LaTeX\ and cannot be used when only the \referenceLibraryandIndex{ext.misc} |
| 67 |
library or the plain\TeX\space |pgffor-ext.tex| are loaded. |
| 68 |
For this, you will need to use |\usepackage{pgffor-ext}|. |
| 69 |
\begin{key}{/\pgfforeachext/xparser=\marg{argument specification}\marg{foreach value}}\keycompat{pgf/foreach} |
| 70 |
This key can be used to specify a \referencePackageandIndeXExt{xparse} |
| 71 |
specification for each element in the list. |
| 72 |
|
| 73 |
For this to work somewhat seamless, the following needs to observed: |
| 74 |
\begin{itemize} |
| 75 |
\item Every \marg{argument specification} get appended |u,|. |
| 76 |
This means there's always one additional mandatory argument at the end of every element. |
| 77 |
\item The \marg{foreach value} needs to correspond to the |
| 78 |
\referenceKeyandIndexO[/pgf/foreach/]{var} |
| 79 |
value. |
| 80 |
\end{itemize} |
| 81 |
\end{key} |
| 82 |
|
| 83 |
\begin{key}{/\pgfforeachext/xparser Om=\opt{default} (default \{\})}\keycompat{pgf/foreach} |
| 84 |
Sets up a list whose elements may contain an optional argument inside |[]| which correspond to |
| 85 |
two |\foreach| variables, say |\Options/\Text|. |
| 86 |
The \opt{default} value is the default value if the optional argument is missing. |
| 87 |
\end{key} |
| 88 |
|
| 89 |
\begin{ext_handler}{{list xparse}|=|\marg{argument specification}\marg{comma-separated list of values}}% |
| 90 |
\handlercompat{.list xparse} |
| 91 |
This handler causes the key to be used repeatedly, namely |
| 92 |
once for every element of the list of values. |
| 93 |
The \meta{comma-separated list of values} is processed using |\foreach| |
| 94 |
and the given |xparse| \meta{argument specification} with the aforementioned |xparser| key. |
| 95 |
\end{ext_handler} |