Debian Codegraph @

texmf-dist/doc/latex/tikz-ext/tikz-ext-manual-en-library-pgffor.tex

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