Debian Codegraph @

texmf-dist/doc/latex/forest/forest-doc.tex

raw
1 %% forest-doc.tex
2 %% `forest-doc.tex` is a main documentation source of package `forest`.
3 %%
4 %% Copyright (c) 2012-2017 Saso Zivanovic
5 %% (Sa\v{s}o \v{Z}ivanovi\'{c})
6 %% [email protected]
7 %%
8 %% This work may be distributed and/or modified under the
9 %% conditions of the LaTeX Project Public License, either version 1.3
10 %% of this license or (at your option) any later version.
11 %% The latest versionx of this license is in
12 %%
13 %% http://www.latex-project.org/lppl.txt
14 %%
15 %% and version 1.3 or later is part of all distributions of LaTeX
16 %% version 2005/12/01 or later.
17 %%
18 %% This work has the LPPL maintenance status `author-maintained'.
19 %%
20 %% This file is a part of package `forest'. For the list of files
21 %% constituting the package see main source file of the package,
22 %% `forest.dtx', or the derived `forest.sty'.
23 %%
24 \documentclass{ltxdoc}
25 \usepackage[a4paper,
26 top=2cm,bottom=2.5cm,
27 reversemarginpar,marginparwidth=2cm,
28 right=1.5cm,
29 nohead
30 ]{geometry}
31
32 \immediate\write18{makeindex -s forest-doc.ist forest-doc}
33 \def\indexlettertotoc#1\relax{%
34 \phantomsection\addcontentsline{toc}{subsection}{#1}%
35 #1%
36 }
37 \makeatletter
38 \c@IndexColumns=2 \makeatother
39 \IndexPrologue{Color legend: \textcolor{red}{definition}, \textcolor{darkgreen}{example}, \textcolor{blue}{other}. If an entry belongs to a library, the library name is given in parenthesis. All page numbers are hyperlinks, and definitions in text are hyperlinked to this index.}
40 \makeindex
41
42 \makeatletter
43 \def\bigbadforlist{}
44 \def\forest@@doc@@hook@bigbadforlist{\aftergroup\forest@@doc@@hook@bigbadforlist@}
45 \def\forest@@doc@@hook@bigbadforlist@{%
46 \forestset{define long step/.append code={%
47 \ifforest@nodewalkstephandler@makefor
48 \appto\bigbadforlist{[##1]}%
49 \fi
50 }%
51 }%
52 }
53 \def\bigbadprocesslist{}
54 \makeatother
55 \usepackage[external]{forest}
56 \useforestlibrary{edges}
57 \useforestlibrary{linguistics}
58 % \tikzexternalize
59 % forest-tikzexternalize either contains \tikzexternalize or not ... make adjusts this
60 \IfFileExists{forest-doc.tex-externalize.tex}{%
61 \input forest-doc.tex-externalize\relax
62 }{}
63 \tikzset{
64 external/prefix={forest.for.dir/},
65 external/system call={
66 pdflatex \tikzexternalcheckshellescape -halt-on-error -interaction=nonstopmode -jobname "\image" "\texsource"},
67 external/up to date check=simple,
68 }
69
70 \usepackage{forest-doc}
71 % \usepackage{patchpgf}
72 % \newcommand\pgfprofilenewforcommandcs[2]{%
73 % \expandafter\pgfprofilenewforcommand\expandafter{\csname #1\endcsname}{#2}}
74 % \newcommand\pgfprofilenewforpgfkey[1]{%
75 % \edef\marshal{%
76 % \noexpand\pgfprofilenewforcommandpattern[#1]{\expandonce{\csname pgfk@#1/.@cmd\endcsname}}{####1\noexpand\pgfeov}{####1\noexpand\pgfeov}
77 % }\marshal
78 % }
79 % \usetikzlibrary{profiler}
80 % \makeatletter
81 % \pgfprofilenewforcommand{\forestindex@index}{3}
82 % \pgfprofilenewforcommand{\pgfmathparse}{1}
83 % \pgfprofilenewforpgfkey{/forest/split}
84 % \pgfprofilenewforpgfkey{/forest/nodewalk/reverse}
85 % \pgfprofilenewforcommand{\forest@Nodewalk}{2}
86 % \pgfprofilenewforcommand{\pgfkeysalso}{1}
87 % \makeatother
88
89 \usepackage{hyperref}
90 \hypersetup{unicode=true,colorlinks=true,linkcolor=blue,citecolor=blue,hyperindex=false}
91 \usepackage{url}
92 \usepackage[numbers]{natbib}
93 \usepackage[multiple]{footmisc}
94 \usepackage{tipa}
95 \usepackage[inline,shortlabels]{enumitem}
96 \newlist{compactitem}{itemize}{2}
97 \setlist[compactitem]{nosep,label=\textbullet}
98 \newlist{arguments}{enumerate}{1}
99 \setlist[arguments]{nosep,label=\textbf{\#\arabic*}}
100 \renewcommand\DescribeMacro[1]{\texttt{\detokenize{#1}}\marginpar{\hfill\small\strut\texttt{\detokenize{#1}}}}
101 \usepackage{printlen}
102 \usepackage{tabularx}
103 \DeleteShortVerb\|
104 \newcommand\OR{\ensuremath{\,|\,}}%
105 \usepackage{multicol}
106
107 %\usepackage[silent]{trace-pgfkeys} % silent, stack, trace, verbose
108 %\pgfkeystracelevel{trace}
109
110 %%% begin listing region: index_macro_style
111 \forestset{
112 detokenize/.style={result=\protect\detokenize{##1}},
113 tt/.style={result=\protect\texttt{##1}},
114 macro/.style={detokenize, +result={\char\escapechar}, tt, print in color, hyper},
115 }
116 %%% end listing region: index_macro_style
117 \forestset{
118 pgfkey/.style={tt,print in color,hyper},
119 path/.style={+result={/},pgfkey},
120 handler/.style={+result={.},pgfkey},
121 option value/.style={
122 format={tt,result+={ value}},
123 for first={format=pgfkey},
124 },
125 environment/.style={
126 detokenize,
127 tt,
128 print in color,
129 if stage={index}{}{
130 if index entry type={definition}{
131 temptoksa/.register=result,
132 hyper,
133 result/.process=ROw2{result}{argument}{%
134 \texttt{\string\begin\char`\{##1\char`\}}%
135 ##2%
136 \texttt{\string\end\char`\{##1\char`\}}%
137 }
138 }{
139 hyper
140 }
141 }
142 },
143 empty/.style={result={{}}},
144 meta/.style={result=\protect\meta{##1},print in color,hyper},
145 index library/.style={
146 if index entry type={definition}{
147 for first leaf'={
148 index format+={
149 result+'={\space
150 {\protect\scriptsize
151 (\protect\texttt{\protect\hyperrefnocolor[sec:library-#1]{#1}})%
152 }%
153 }
154 }
155 },
156 }{}
157 },
158 margin/.style={print format={result=\marginpar{\strut##1}}},
159 also margin/.style={print format={result=##1\marginpar{\strut##1}}},
160 }
161
162 \let\origmeta\meta
163 \renewcommand\meta[1]{\origmeta{\rm\ignorespaces#1}}
164 \renewcommand\rstyle{\color{red}}
165 \newcommand\hyperrefnocolor[2][]{{\hypersetup{linkcolor=black}\hyperref[#1]{#2}}}
166 \newcommand\librarysection[1]{%
167 \subsection{\protect\texttt{#1}}%
168 \label{sec:library-#1}%
169 \forestset{every index end/.style={set={index library={#1}}}}%
170 }
171 \newcommand\reflibrary[1]{\hyperref[sec:library-#1]{\texttt{#1}}}
172
173 \index[not print,not index,set={
174 index key=unknown,
175 form={\textbf{unknown!!}},
176 for first={format={
177 result/.expanded=\noexpand\textbf{\forestregister{result}??},
178 print in color}}}
179 ]>{@unknown}
180
181 \indexset
182 [print form={},for first={format=pgfkey}]
183 >{node key}
184
185 \indexset
186 [for first={format={+result={/tikz/},pgfkey}}]
187 >{tikz key}
188
189 \indexset
190 [for first={format=pgfkey}]
191 >{option,readonly option,bracket key,nodewalk key,register,propagator,style,nodewalk style,stage,dynamic tree,step,loop,conditional,anchor,package option}
192
193 %%% begin listing region: index_macro_category
194 \indexset
195 [for first={format=macro}]
196 >{macro}
197 %%% end listing region: index_macro_category
198
199 \indexset
200 [for first={format=environment}]
201 >{environment}
202
203 \indexset
204 [format=empty]>{empty}
205
206 \indexset
207 [index form={type (of options and registers)},for first={format=meta}]
208 >{type}
209
210 \indexset
211 [for first={format=handler}]
212 >{handler}
213
214 \indexset
215 [format={aggregate function},for first={format=handler}]
216 >{aggregate}
217
218 \indexset
219 [form={\texttt{pgfmath} function},for first={format={detokenize,pgfkey}}]
220 >{pgfmath}
221
222 \indexset
223 [for first={format=path}]
224 >{path}
225
226 \indexset[
227 form={},
228 index key={},
229 for first={
230 for first={
231 key+/.option=!parent.argument,
232 index format={
233 result+/.process={Ow1} {!parent.argument} {\protect\meta{##1 option}},
234 },
235 print format={
236 if argument={}{}{
237 result+/.option=argument
238 },
239 },
240 format={
241 pgfkey
242 },
243 }
244 }
245 ]>{prefix}
246
247 \indexset[
248 form={},
249 index key={},
250 for first={
251 for first={
252 +key/.option=!parent.argument,
253 index format={
254 +result/.process={Ow1} {!parent.argument} {\protect\meta{##1 option}},
255 },
256 print format={
257 if argument={}{}{
258 +result/.option=argument
259 },
260 },
261 format={
262 pgfkey
263 },
264 }
265 }
266 ]>{suffix}
267
268 \indexset[
269 form={},
270 index key={},
271 for first={
272 for first={
273 key/.process={OOw2} {key} {!parent,parent.argument} {##1 ##2},
274 index format={
275 result+/.process={Ow1} {!parent,parent.argument} {\space\protect\meta{##1}},
276 },
277 print format={
278 if argument={}{}{
279 result+={\space},
280 result+/.option=argument
281 }
282 },
283 format={
284 pgfkey
285 },
286 }
287 }
288 ]>{word prefix}
289
290 \indexset[
291 form={},
292 index key={},
293 for first={
294 for first={
295 key/.process={OOw2} {key} {!parent,parent.argument} {##2 ##1},
296 index format={
297 +result/.process={Ow1} {!parent,parent.argument} {\protect\meta{##1}\space},
298 },
299 print format={
300 if argument={}{}{
301 +result={\space},
302 +result/.option=argument
303 }
304 },
305 format={
306 pgfkey
307 },
308 }
309 }
310 ]>{word suffix}
311
312 \indexset[%option values
313 index key format={result/.expanded=\forestoption{argument} value},
314 format={result/.expanded=\noexpand\texttt{\forestoption{argument}} value},
315 for first={format=pgfkey}
316 ]>{value of}
317
318 \indexset[
319 index key format={result/.expanded=\forestoption{argument} option},
320 format={result/.expanded=\noexpand\texttt{\forestoption{argument}} option},
321 for first={format=pgfkey}
322 ]>{option of}
323
324 \indexset
325 [form={},for first={
326 print format={if argument={}{}{
327 result+={:\ },
328 result+/.option=argument,
329 }},
330 format=meta,
331 }]>{meta}
332
333 \indexset[
334 for first={+key={{cs }},format={pgfkey}}
335 ]>{forest cs}
336
337 \indexset[
338 for first={+key={{ss }},format={pgfkey}}
339 ]>{short step}
340
341 \indexset
342 [for first={format=pgfkey}]
343 >{named nodewalk}
344
345 \indexset[
346 format={result/.expanded=\noexpand\texttt{process instruction}},
347 for first={format=pgfkey}
348 ]>{processor}
349
350 {\makeatletter % an dirty patch: \lst@nolig can sneak in the name...
351 \gdef\myexampleindex#1{{\def\lst@nolig{}\lstaspectindex{#1}{}}}
352 }
353 \lstset{indexstyle={[1]\myexampleindex}}
354 %%% end lst-related stuff
355
356 \EnableCrossrefs
357 \setlength\hfuzz{15pt} % dont make so many
358 \hbadness=7000 % over and under full box warnings
359
360 \usetikzlibrary{intersections}
361 \tikzset{>=latex}
362 \forestset{
363 background tree/.style={
364 for tree={text opacity=0.2,draw opacity=0.2,edge={draw opacity=0.2}}}
365 }
366
367 \title{\FoRest;: a \PGF;/\TikZ;-based package for drawing linguistic trees\\\normalsize\forestversion}
368 \author{Sa\v so \v Zivanovi\'c\footnote{e-mail:
369 \href{mailto:[email protected]}{[email protected]};
370 web:
371 \href{http://spj.ff.uni-lj.si/zivanovic/}{http://spj.ff.uni-lj.si/zivanovic/}}}
372
373 %\usepackage[verbose]{trace-pgfkeys} % silent, stack, trace, verbose
374 %\pgfkeystracelevel{trace}
375
376 \begin{document}
377
378 \typeout{)}% hacking auctex's error finding routing
379
380 % short verbatim: | (changes spaces into _)
381 \DeleteShortVerb\|
382 \def\indexpipe{|}
383 {\catcode`\_=12 \def\marshal{%
384 \lstMakeShortInline[basicstyle=\ttfamily,literate={_}{ }1 {__}{_}1]}%
385 \expandafter}\marshal |
386
387 \IfFileExists{forest-doc-test.tex}{%
388 \input forest-doc-test\relax
389 }{}
390
391 \newbox\treebox
392 \newbox\codebox
393
394 {\settodayfromforestdate\maketitle}
395
396 \begin{abstract}
397 \FoRest; is a \PGF;/\TikZ;-based package for drawing linguistic (and
398 other kinds of) trees. Its main features are
399 \begin{enumerate*}[(i)]
400 \item a packing algorithm which can produce very compact trees;
401 \item a user-friendly interface consisting of the familiar bracket encoding of trees plus the
402 key--value interface to option-setting;
403 \item many tree-formatting options, with control over option values of individual nodes and
404 mechanisms for their manipulation;
405 \item a powerful mechanism for traversing the tree;
406 \item the possibility to decorate the tree using the full power of \PGF;/\TikZ;;
407 \item an externalization mechanism sensitive to code-changes.
408 \end{enumerate*}
409 \end{abstract}
410
411 \vspace{1cm}
412
413 \begin{forestexample}[basicstyle=\ttfamily\scriptsize,layout=tree on top,no label,v sep=1cm,index={content,pgfmath,conditional>if,repeat,append,before drawing tree,y,alias,for step,step>children,edge,before typesetting nodes,tree,s sep,dimen+,option>l,ancestors,typeset node,nodewalk,readonly option>level,sort by,step>min}]
414 \pgfmathsetseed{14285}
415 \begin{forest}
416 random tree/.style n args={3}{% #1 = max levels, #2 = max children, #3 = max content
417 content/.pgfmath={random(0,#3)},
418 if={#1>0}{repeat={random(0,#2)}{append={[,random tree={#1-1}{#2}{#3}]}}}{}},
419 before typesetting nodes={for tree={draw,s sep=2pt,rotate={int(30*rand)},l+={5*rand},
420 if={isodd(level())}{fill=green}{fill=yellow}}},
421 important/.style={draw=red,line width=1.5pt,edge={red,line width=1.5pt}},
422 before drawing tree={sort by=y, for nodewalk={min=tree,ancestors}{important,typeset node}}
423 [,random tree={9}{3}{100}]
424 \end{forest}
425 \end{forestexample}%
426 \begin{center}\mbox{}\box\treebox\\\box\codebox\end{center}
427
428 \newpage
429 {%
430 \parskip 0pt
431 \begin{multicols}{2}
432 \tableofcontents
433 \end{multicols}
434 }
435
436 \newpage
437
438 \section{Introduction}
439
440 Over several years, I had been a grateful user of various packages
441 for typesetting linguistic trees. My main experience was with
442 |qtree| and |synttree|, but as far as I can tell, all of the tools
443 on the market had the same problem: sometimes, the trees were just
444 too wide. They looked something like the tree on the left,
445 while I wanted something like the tree on the right.
446 \begin{center}
447 \begin{forest}
448 baseline,
449 for tree={parent anchor=south,child anchor=north,l=7ex,s sep=10pt},
450 for children={fit=rectangle}
451 [CP
452 [DP
453 [D][NP[N][CP[C][TP[T][vP[v][VP[DP][V'[V][DP]]]]]]]]
454 [TP
455 [T][vP[v][VP[DP][V'[V][DP]]]]]
456 ]
457 \end{forest}
458 \hfill
459 \begin{forest}
460 baseline,
461 for tree={parent anchor=south,child anchor=north,l=7ex,s sep=10pt},
462 [CP
463 [DP
464 [D][NP[N][CP[C][TP[T][vP[v][VP[DP][V'[V][DP]]]]]]]]
465 [TP
466 [T][vP[v][VP[DP][V'[V][DP]]]]]
467 ]
468 \end{forest}
469 \end{center}
470
471 Luckily, it was possible to tweak some parameters by hand to get a
472 narrower tree, but as I quite dislike constant manual adjustments, I
473 eventually started to develop \foRest;. It started out as
474 |xyforest|, but lost the |xy| prefix as I became increasingly fond
475 of \PGF;/\TikZ;, which offered not only a drawing package but also a
476 `programming paradigm.' It is due to the awesome power of the
477 supplementary facilities of \PGF;/\TikZ; that \foRest; is now, I
478 believe, the most flexible tree typesetting package for \LaTeX\ you can get.
479
480 The latest stable version of \FoRest; is \href{http://www.ctan.org/pkg/forest}{available at CTAN}.
481 Development version(s) can be found \href{https://github.com/sasozivanovic/forest}{at GitHub}.
482 Comments, criticism, suggestions and code are all very welcome! If you find the package useful, you
483 can show your appreciation by making a PayPal donation to \url{[email protected]}.
484
485
486 \section{Tutorial}
487 \label{sec:tutorial}
488
489 This short tutorial progresses from basic through useful to obscure \dots fortunately, it is not the
490 only newcomer's source of information on \foRest;: check out
491 \href{http://mirrors.ctan.org/info/forest-quickstart/ForestQuickstart.pdf}{Forest Quickstart Guide
492 for Linguists}. Another very useful source of information (and help!) about \foRest; and \TeX\ in
493 general is \href{http://tex.stackexchange.com}{\TeX\ StackExchange}. Check out the questions tagged
494 \href{http://tex.stackexchange.com/questions/tagged/forest}{\texttt{forest}}!
495
496
497 \subsection{Basic usage}
498 \label{tut:basic-usage}
499
500 A tree is input by enclosing its specification in a \index{forest}
501 environment. The tree is encoded by \emph{the bracket syntax}:
502 every node is enclosed in square brackets; the children of a
503 node are given within its brackets, after its content.
504 {\lstdefinelanguage[my]{TeX}[LaTeX]{TeX}{keywords=forest,
505 otherkeywords={[,]},keywordstyle=\pstyle,texcsstyle={}}%
506 \lstset{language={[my]TeX}}%
507 \begin{forestexample}
508 \begin{forest}
509 [VP
510 [DP]
511 [V'
512 [V]
513 [DP]
514 ]
515 ]
516 \end{forest}
517 \end{forestexample}}
518 Binary trees are nice, but not the only thing this package can draw.
519 Note that by default, the children are vertically centered with
520 respect to their parent, i.e.\ the parent is vertically aligned with the midpoint between the
521 first and the last child.
522 \begin{forestexample}
523 \begin{forest}
524 [VP
525 [DP[John]]
526 [V'
527 [V[sent]]
528 [DP[Mary]]
529 [DP[D[a]][NP[letter]]]
530 ]
531 ]
532 \end{forest}
533 \end{forestexample}
534 Spaces around brackets are ignored --- format your code as you
535 desire!
536 \begin{forestexample}
537 \begin{forest}
538 [VP[DP][V'[V][DP]]]
539 \end{forest}
540 \quad
541 \begin{forest}[VP
542 [DP ] [ V'[V][ DP]]
543 ]\end{forest}
544 \end{forestexample}
545 If you need a square bracket as part of a node's content, use
546 braces. The same is true for the other characters which have a
547 special meaning in the \foRest; package, like comma
548 |,| and equality sign |=|.
549 \begin{forestexample}
550 \begin{forest}
551 [V{P,}
552 [{[DP]}]
553 [V'
554 [V]
555 [{===DP===}]]]
556 \end{forest}
557 \end{forestexample}
558 Macros in a node specification will be expanded when the node is
559 drawn --- you can freely use formatting commands inside nodes!
560 \begin{forestexample}
561 \begin{forest}
562 [VP
563 [{~\textbf~{DP}}]
564 [V'
565 [V]
566 [DP]]]
567 \end{forest}
568 \end{forestexample}
569
570 All the examples given above produced top-down trees with centered children. The other sections
571 of this manual explain how various properties of a tree can be changed, making it possible to
572 typeset radically different-looking trees. However, you don't have to learn everything about this
573 package to profit from its power. Using styles, you can draw predefined types of trees with ease.
574 For example, a phonologist can use the \index{GP1} style from library \reflibrary{linguistics} to easily
575 typeset (Government Phonology) phonological representations. The style is applied simply by
576 writing its name before the first (opening) bracket of the tree.
577 \begin{forestexample}[label=ex:gp1-frost,code prefix={\def\usepackage[##1]##2{}}]
578 \usepackage[~linguistics~]{forest}
579 % ...
580 \begin{forest} ~GP1~ [
581 [O[x[f]][x[r]]]
582 [R[N[x[o]]][x[s]]]
583 [O[x[t]]]
584 [R[N[x]]]
585 ]\end{forest}
586 \end{forestexample}
587 Of course, someone needs to develop the style --- you, me, your local \TeX nician \dots\@
588 Fortunately, designing styles is not very difficult once you get the hang of \foRest;, if you
589 write one, please contribute! Some macros relating to various fields are collected in
590 \emph{libraries} that are distributed alongside the main package. This is the case for the
591 \index{GP1} style used above, which is defined in the |linguistics| library. The simplest way to
592 load a library is as shown in the example, by loading the package with an optional argument. For
593 more information on loading libraries, see \S\ref{ref:package-options}.
594
595
596 \subsection{Options}
597 \label{tut:options}
598
599 A node can be given various options, which control various
600 properties of the node and the tree. For example, at the end of
601 section~\ref{tut:basic-usage}, we have seen that the \index{GP1} style
602 vertically aligns the parent with the first
603 child. This is achieved by setting option \index{calign} (for
604 \emph{c}hild-\emph{align}ment) to \index{value of=calign>first} (child).
605
606 Let's try. Options are given inside the brackets, following the
607 content, but separated from it by a comma. (If multiple options are
608 given, they are also separated by commas.) A single option
609 assignment takes the form \meta{option name}|=|\meta{option value}. (There are
610 also options which do not require a value or have a default value:
611 these are given simply as \meta{option name}.)
612 \begin{forestexample}[label=ex:numerals-simple,index={calign,value of=align>first}]
613 \begin{forest}
614 [\LaTeX\ numerals, ~calign=first~
615 [arabic[1][2][3][4]]
616 [roman[i][ii][iii][iv]]
617 [alph[a][b][c][d]]
618 ]
619 \end{forest}
620 \end{forestexample}
621
622 The experiment has succeeded only partially. The root node's
623 children are aligned as desired (so \index{calign}|=|\index{value of=calign>first} applied to the
624 root node), but the value of the \index{calign} option didn't get
625 automatically assigned to the root's children! \emph{An option given
626 at some node applies only to that node.} In \foRest;, the options
627 are passed to the node's relatives via special keys, called
628 \emph{propagators}. What we need above is the \index{for step=\index{tree}}
629 propagator. Observe:
630
631 \begin{forestexample}[label=ex:numerals-manual]
632 \begin{forest}
633 [\LaTeX\ numerals,
634 ~for tree~={calign=first}
635 [arabic[1][2][3][4]]
636 [roman[i][ii][iii][iv]]
637 [alph[a][b][c][d]]
638 ]
639 \end{forest}
640 \end{forestexample}
641 The value of propagator \index{for step=\index{tree}} is a list of keys that we
642 want to process. This keylist is propagated to all the nodes in
643 the subtree\footnote{It might be more precise to call \index{for step=\index{tree}}
644 \texttt{for subtree} \dots\@ but this name at least saves some typing.}
645 rooted in the current node (i.e.\ the node where \index{for step=\index{tree}} was
646 given), including the node itself. (Propagator \index{for step=\index{descendants}} is
647 just like \index{for step=\index{tree}}, only that it excludes the node itself. There
648 are many other \index{for step=\meta{step}} propagators; for the complete list, see
649 sections~\ref{ref:spatial-propagators} and \ref{ref:nodewalks}.)
650
651 Some other useful options are \index{option>parent anchor}, \index{option>child anchor} and
652 \index{tier}. The \index{option>parent anchor} and \index{option>child anchor} options tell
653 where the parent's and child's endpoint of the edge between them should be, respectively: usually,
654 the value is either empty (meaning a smartly determined border point
655 \citep[see][\S16.11]{tikzpgf2.10}; this is the default) or a compass direction
656 \citep[see][\S16.5.1]{tikzpgf2.10}. (Note: the \index{option>parent anchor} determines where the edge
657 from the child will arrive to this node, not where the node's edge to its parent will start!)
658
659 Option \index{tier} is what makes the
660 skeletal points $\times$ in example (\ref{ex:gp1-frost}) align horizontally although they
661 occur at different levels in the logical structure of the tree.
662 Using option \index{tier} is very simple: just set |tier=tier_name| at
663 all the nodes that you want to align horizontally. Any tier name
664 will do, as long as the tier names of different tiers are
665 different \dots\@ (Yes, you can have multiple tiers!)
666 \begin{forestexample}[point={tier},index={option>parent anchor,option>child anchor,tier},label=ex:tier-manual]
667 \begin{forest}
668 [VP, for tree={~parent anchor~=south, ~child anchor~=north}
669 [DP[John,tier=word]]
670 [V'
671 [V[sent,tier=word]]
672 [DP[Mary,tier=word]]
673 [DP[D[a,tier=word]][NP[letter,tier=word]]]
674 ]
675 ]
676 \end{forest}
677 \end{forestexample}
678 Before discussing the variety of \foRest;'s options, it is worth
679 mentioning that \foRest;'s node accepts all options \citep[see
680 \S16]{tikzpgf2.10} that \TikZ;'s node does --- mostly, it just passes
681 them on to \TikZ;. For example, you can easily encircle a node like
682 this:\footnote{If option \texttt{draw} was not given, the shape of the node
683 would still be circular, but the edge would not be drawn. For
684 details, see \cite[\S16]{tikzpgf2.10}.}
685 \begin{forestexample}
686 \begin{forest}
687 [VP,~circle~,~draw~
688 [DP][V'[V][DP]]
689 ]
690 \end{forest}
691 \end{forestexample}
692
693 Let's have another look at example (\ref{ex:gp1-frost}). You will note that the skeletal
694 positions were input by typing |x|s, while the result looks like
695 this: $\times$ (input as |\times| in math mode). Obviously, the
696 content of the node can be changed. Even more, it can be
697 manipulated: added to, doubled, boldened, emphasized, etc. We will
698 demonstrate this by making example (\ref{ex:numerals-manual}) a bit
699 fancier: we'll write the input in the arabic numbers and have
700 \LaTeX\ convert it to the other formats. We'll start with the
701 easiest case of roman numerals: to get them, we can use the (plain)
702 \TeX\ command |\romannumeral|. To change the content of the node,
703 we use option \index{content}. When specifying its new value, we can use
704 |#1| to insert the current content.\footnote{This mechanism is called
705 \emph{wrapping}. By default, \index{content} is the only \index{autowrapped toks} option,
706 i.e.\ option where wrapping works implicitely (simply
707 because I assume that wrapping will be almost exclusively used with this option). To wrap values
708 of other options, use handler \index{wrap value}; see~\S\ref{ref:handlers}.}
709 \begin{forestexample}[point={content,delay},index={for step,step>children,content,delay},label=ex:romannumeral]
710 \begin{forest}
711 [roman, delay={for children={content=\romannumeral#1}}
712 [1][2][3][4]
713 ]
714 \end{forest}
715 \end{forestexample}
716 This example introduces another option: \index{delay}. Without it, the example wouldn't work: we
717 would get arabic numerals. This is so because of the order in which the options are processed.
718 First, the processing proceeds through the tree in a depth-first, parent-first fashion (first the
719 parent is processed, and then its children, recursively; but see \index{processing order}). Next,
720 the option string of a node is processed linearly, in the order they were given. Option
721 \index{content} is specified implicitely and is always the first. If a propagator is encountered,
722 the options given as its value are propagated \emph{immediately}. The net effect is that if the
723 above example contained simply |roman,for_children={content=...}|, the \index{content} option
724 given there would be processed \emph{before} the implicit content options given to the children
725 (i.e.\ numbers |1|, |2|, |3| and |4|). Thus, there would be nothing for the |\romannumeral| to
726 change --- it would actually crash; more generally, the content assigned in such a way would get
727 overridden by the implicit content. Key \index{delay} is true to its name. It delays the
728 processing of the keylist given as its argument until the whole tree was processed. In other words, it
729 introduces cyclical option processing. Whatever is delayed in one cycle, gets processed in the next
730 one. The number of cycles is not limited --- you can nest \index{delay}s as deep as you need.
731
732 Unlike \index{for step=\meta{step}} keys we have met before, \index{delay} is not a
733 spatial, but a temporal propagator. Several other temporal propagators options exist, see
734 \S\ref{ref:stages}.
735
736 We are now ready to learn about simple conditionals.\footnote{See \S\ref{ref:conditionals} for
737 further information on conditionals, including the generic \index{if} and \index{where}.} Every
738 node option has the corresponding \index{if option=\meta{option}} and \index{where
739 option=\meta{option}} keys. \index{if option=\meta{option}}|=|\meta{value}\meta{true
740 options}\meta{false options} checks whether the value of \meta{option} equals \meta{value}. If
741 so, \meta{true options} are processed, otherwise \meta{false options}. The \index{where
742 option=\meta{option}} keys are the same, but do this for the every node in the subtree; informally
743 speaking, |where| = |for_tree| + |if|. To see this in action, consider the rewrite of the
744 \index{tier} example (\ref{ex:tier-manual}) from above. We don't set the tiers manually, but rather
745 put the terminal nodes (option \index{n children} is a read-only option containing the number of
746 children) on tier \keyname{word}.\footnote{We could omit the braces around \texttt{0} because it is
747 a single character. If we were hunting for nodes with 42 children, we'd have to write
748 \texttt{where n children=\{42\}...}.}
749 \begin{forestexample}[index={tier,where option,n children}]
750 \begin{forest}
751 ~where n children~=0{tier=word}{}
752 [VP
753 [DP[John]]
754 [V'
755 [V[sent]]
756 [DP[Mary]]
757 [DP[D[a]][NP[letter]]]
758 ]
759 ]
760 \end{forest}
761 \end{forestexample}
762
763 \begin{advise}
764 \item Note that you usually don't want to embed a \index{where option=...} conditional in a \index{for
765 step=\index{tree}}, as this will lead to a multiple traversal of many nodes, resulting in a
766 slower execution. If you're inside a \index{for step=\index{tree}}, you probably want to use
767 \index{if}.
768 \end{advise}
769
770
771 Finally, let's talk about styles.
772 (They are not actually defined in the \foRest; package, but rather
773 inherited from |pgfkeys|.)
774
775
776
777
778 At the first approximation, styles are abbreviations: if you
779 often want to have non-default parent/child anchors, say south/north as in example
780 (\ref{ex:tier-manual}), you could save some typing by defining a style. Styles are defined using
781 \PGF;'s handler |.style|, like shown below.\footnote{Style \index{sn edges} is actually already
782 defined by library \reflibrary{linguistics}. The definition there is a bit more generic.}
783 \begin{forestexample}[index={tier,option>parent anchor,option>child anchor}]
784 \begin{forest}
785 ~sn edges~/~.style~={for tree={
786 parent anchor=south, child anchor=north}},
787 ~sn edges~
788 [VP,
789 [DP[John,tier=word]]
790 [V'
791 [V[sent,tier=word]]
792 [DP[Mary,tier=word]]
793 [DP[D[a,tier=word]][NP[letter,tier=word]]]]]
794 \end{forest}
795 \end{forestexample}
796 If you want to use a style in more than one tree, you have to define it outside the \index{forest}
797 environment. Use macro \index{forestset} to do this.
798 \begin{lstlisting}
799 ~\forestset~{
800 sn edges/.style={for tree={parent anchor=south, child anchor=north}},
801 background tree/.style={for tree={
802 text opacity=0.2,draw opacity=0.2,edge={draw opacity=0.2}}}
803 }
804 \end{lstlisting}
805
806 You might have noticed that in the last two examples, some keys occurred even before the
807 first opening bracket, contradicting was said at the beginning of this section. This is mainly
808 just syntactic sugar (it can separate the design and the content): such \emph{preamble}
809 keys behave as if they were given in the root node, the only difference (which often does not
810 matter) being that they get processed before all other root node options, even the implicit
811 \index{content}.
812
813 If you find yourself writing the same preamble for every tree in your document,
814 consider modifying \index{default preamble}, which is implicitely included at the beginning
815 of every preamble.
816
817 \begin{forestexample}[index={default preamble}]
818 \forestset{
819 ~default preamble~={
820 font=\Huge,
821 for tree={circle,draw}
822 }
823 }
824 \begin{forest} [A[B][C]] \end{forest}
825 \begin{forest} red [D[E][F]] \end{forest}
826 \begin{forest} for tree={dotted} [G[H][I]] \end{forest}
827 \end{forestexample}
828
829 \subsection{Decorating the tree}
830 \label{tut:decorating}
831
832 The tree can be decorated (think movement arrows) with arbitrary
833 \TikZ; code.
834 \begin{forestexample}
835 \begin{forest}
836 [XP
837 [specifier]
838 [X$'$
839 [X$^0$]
840 [complement]
841 ]
842 ]
843 ~\node at (current bounding box.south)
844 [below=1ex,draw,cloud,aspect=6,cloud puffs=30]
845 {\emph{Figure 1: The X' template}};~
846 \end{forest}
847 \end{forestexample}
848
849 However, decorating the tree would make little sense if one could
850 not refer to the nodes. The simplest way to do so is to give them a
851 \TikZ; name using the \index{option>name} option, and then use this name in \TikZ;
852 code as any other (\TikZ;) node name.
853 \begin{forestexample}[point=name,index={option>phantom,option>name}]
854 \begin{forest}
855 [CP
856 [DP,name=spec CP]
857 [\dots
858 [,phantom]
859 [VP
860 [DP]
861 [V'
862 [V]
863 [DP,name=object]]]]]
864 \draw[->,dotted] ~(object)~ to[out=south west,in=south] ~(spec CP)~;
865 \end{forest}
866 \end{forestexample}
867
868 It gets better than this, however! In the previous examples, we put
869 the \TikZ; code after the tree specification, i.e.\ after the closing
870 bracket of the root node. In fact, you can put \TikZ; code after
871 \emph{any} closing bracket, and \foRest; will know what the current
872 node is. (Putting the code after a node's bracket is actually just a
873 special way to provide a value for option \index{tikz} of that node.) To
874 refer to the current node, simply use an empty node name. This works both with and without
875 anchors \citep[see][\S16.11]{tikzpgf2.10}: below, |(.south east)| and |()|.
876 \begin{forestexample}[index={option>phantom,option>name}]
877 \begin{forest}
878 [CP
879 [DP,name=spec CP]
880 [\dots
881 [,phantom]
882 [VP
883 [DP]
884 [V'
885 [V]
886 [DP,draw] ~{~
887 \draw[->,dotted] ~()~ to[out=south west,in=south] (spec CP);
888 \draw[<-,red] ~(.south east)~--++(0em,-4ex)--++(-2em,0pt)
889 node[anchor=east,align=center]{This guy\\has moved!};
890 ~}~
891 ]]]]
892 \end{forest}
893 \end{forestexample}
894
895 Important: \emph{the \TikZ; code should usually be enclosed in braces} to hide
896 it from the bracket parser. You don't want all the bracketed code
897 (e.g.\ |[->,dotted]|) to become tree nodes, right? (Well, they
898 probably wouldn't anyway, because \TeX\ would spit out a thousand
899 errors.)
900
901 \bigskip
902
903 Finally, the most powerful tool in the node reference toolbox:
904 \emph{relative nodes}. It is possible to refer to other nodes which stand
905 in some (most often geometrical) relation to the current node. To
906 do this, follow the node's name with a \index>{!} and a \emph{nodewalk}
907 specification.
908
909 A nodewalk is a concise\footnote{Actually, \foRest; distinguishes two kinds of steps in node walks:
910 long-form and short-form steps. This section introduces only short-form steps. See
911 \S\ref{ref:nodewalks}.} way of expressing node relations. It is simply a string of steps, which
912 are represented by single characters, where: \index{ss u} stands for the parent node (up); \index{ss
913 p} for the previous sibling; \index{ss n} for the next sibling; \index{ss s} for \emph{the}
914 sibling (useful only in binary trees); \index{ss 1}, \index{ss 2}, \index[not print]{ss 3,ss 4,ss
915 5,ss 6,ss 7,ss 8}\dots\ \index{ss 9} for first, second, \dots\ ninth child; \index{ss l}, for the
916 last child, etc. For the complete specification, see section~\ref{ref:short-form-steps}.
917
918 To see the nodewalk in action, consider the following examples.
919 In the first example, the agree arrow connects the V node, specified
920 simply as |()|, since the \TikZ; code follows |[V]|, and the DP node,
921 which is described as ``a sister of V's parent'': |!us| = up +
922 sibling.
923 \begin{forestexample}[index>={!}]
924 \begin{forest}
925 [VP
926 [DP]
927 [V'
928 [V] {\draw[<->] ~()~
929 .. controls +(left:1cm) and +(south west:0.4cm) ..
930 node[very near start,below,sloped]{\tiny agree}
931 ~(!us)~;}
932 [DP]
933 ]
934 ]
935 \end{forest}
936 \end{forestexample}
937
938 \begingroup
939 \footnotesize
940 \begin{forestexample}[index={option>phantom,tikz,fit to,tree},layout=export,basicstyle=\footnotesize\ttfamily]
941 \begin{forest}
942 [CP
943 [DP$_1$]
944 [\dots
945 [,phantom]
946 [VP,tikz={\node [draw,red,inner sep=0,~fit to~=tree]{};}
947 [DP$_2$]
948 [V'
949 [V]
950 [DP$_3$]
951 ]]]]
952 \end{forest}
953 \end{forestexample}%
954 \endgroup
955
956 The second example uses \TikZ;'s fitting library (automatically loaded by \foRest;) to compute the
957 smallest rectangle containing node VP, its first child (DP$_2$) and its last grandchild (DP$_3$).
958 The example also illustrates that the \TikZ; code
959 can be specified via the ``normal'' option syntax, i.e.\ as a value
960 to option \index{tikz}.\footnote{\label{fn:fit-to-tree}Actually, there's a simpler way to do this: use \index{fit to}\keyname{=}\index{tree}!\forestexampleimport}
961 \begin{forestexample}[point=tikz,index={option>phantom,tikz},index>={!}]
962 \begin{forest}
963 [CP
964 [DP$_1$]
965 [\dots
966 [,phantom]
967 [VP,tikz={\node [draw,red,fit=~()(!1)(!ll)~] {};}
968 [DP$_2$]
969 [V'
970 [V]
971 [DP$_3$]
972 ]]]]
973 \end{forest}
974 \end{forestexample}
975
976
977 \subsection{Node positioning}
978 \label{tut:node-positioning}
979
980 \FoRest; positions the nodes by a recursive bottom-up algorithm which, for every non-terminal node,
981 computes the positions of the node's children relative to their parent. By default, all the
982 children will be aligned horizontally some distance down from their parent: the ``normal'' tree
983 grows down. More generally, however, the direction of growth can change from node to node; this is
984 controlled by option \index{grow}=\meta{direction}.\footnote{The direction can be specified either in
985 degrees (following the standard mathematical convention that $0$ degrees is to the right, and that
986 degrees increase counter-clockwise) or by the compass directions: \texttt{east}, \texttt{north east},
987 \texttt{north}, etc.} The system computes and stores the positions of children using a
988 coordinate system dependent on the parent, called an \emph{ls-coordinate system}: the origin is the
989 parent's anchor; l-axis is in the direction of growth in the parent; s-axis is orthogonal to the
990 l-axis (positive side in the counter-clockwise direction from $l$-axis); l stands for \emph{l}evel,
991 s for \emph{s}ibling. The example shows the ls-coordinate system for a node with
992 |grow=45|.\footnote{The axes are drawn using coordinates given in \texttt{forest cs} coordinate
993 system; the ``manually'' given polar coordinate equivalent is shown in the comment.}
994
995 \begin{forestexample}[point=grow,index={grow}]
996 \begin{forest} background tree
997 [parent, grow=45
998 [child 1][child 2][child 3][child 4][child 5]
999 ]
1000 %\draw[,->](-135:1cm)--(45:3cm) node[below]{$l$};
1001 \draw[,->](forest cs:l=-1cm,s=0)--(forest cs:l=3cm,s=0) node[below]{$l$};
1002 %\draw[,->](-45:1cm)--(135:3cm) node[right]{$s$};
1003 \draw[,->](forest cs:s=-1cm,l=0)--(forest cs:s=3cm,l=0) node[right]{$s$};
1004 \end{forest}
1005 \end{forestexample}
1006
1007 \begin{forestexample}[basicstyle=\scriptsize\ttfamily,layout=export]
1008 \newcommand\measurexdistance[5][####1]{\measurexorydistance{#2}{#3}{#4}{#5}{\x}{-|}{(5pt,0)}{#1}}
1009 \newcommand\measureydistance[5][####1]{\measurexorydistance{#2}{#3}{#4}{#5}{\y}{|-}{(0,5pt)}{#1}}
1010 \tikzset{dimension/.style={<->,>=latex,thin,every rectangle node/.style={midway,font=\scriptsize}},
1011 guideline/.style=dotted}
1012 \newdimen\absmd
1013 \def\measurexorydistance#1#2#3#4#5#6#7#8{%
1014 \path #1 #3 #6 coordinate(md1) #1; \draw[guideline] #1 -- (md1);
1015 \path (md1) #6 coordinate(md2) #2; \draw[guideline] #2 -- (md2);
1016 \path let \p1=($(md1)-(md2)$), \n1={abs(#51)} in \pgfextra{\xdef\md{#51}\global\absmd=\n1\relax};
1017 \def\distancelabelwrapper##1{#8}%
1018 \ifdim\absmd>5mm
1019 \draw[dimension] (md1)--(md2) node[#4]{\distancelabelwrapper{\uselengthunit{mm}\rndprintlength\absmd}};
1020 \else
1021 \ifdim\md>0pt
1022 \draw[dimension,<-] (md1)--+#7; \draw[dimension,<-] let \p1=($(0,0)-#7$) in (md2)--+(\p1);
1023 \else
1024 \draw[dimension,<-] let \p1=($(0,0)-#7$) in (md1)--+(\p1); \draw[dimension,<-] (md2)--+#7;
1025 \fi
1026 \draw[dimension,-] (md1)--(md2) node[#4]{\distancelabelwrapper{\uselengthunit{mm}\rndprintlength\absmd}};
1027 \fi}
1028 \end{forestexample}
1029 \input{\jobname.tmp}
1030
1031
1032 The l-coordinate of children is (almost) completely under your control, i.e.\ you set what is often
1033 called the level distance by yourself. Simply set option \index{option>l} to change the distance of
1034 a node from its parent.\footnote{If setting \index{option>l} seems to have no effect, read about
1035 \index{l sep} further down this section.} More precisely, \index{option>l}, and the related option
1036 \index{option>s}, control the distance between the (node) anchors of a node and its parent. The
1037 anchor of a node can be changed using option \index{option>anchor}: by default, nodes are anchored
1038 at their base; see \cite[\S16.5.1]{tikzpgf2.10}.) In the example below, positions of the anchors
1039 are shown by dots: observe that anchors of nodes with the same \index{option>l} are aligned and that
1040 the distances between the anchors of the children and the parent are as specified in the
1041 code.\footnote{Here are the definitons of the macros for measuring distances. Args: the x or y
1042 distance between points \#2 and \#3 is measured; \#4 is where the distance line starts (given as
1043 an absolute coordinate or an offset to \#2); \#5 are node options; the optional arg \#1 is the
1044 format of label. (Lengths are printed using package \texttt{printlen}.)
1045
1046 \box\codebox}
1047 \begin{forestexample}[layout=tree on top,index={for step,tree,tikz,option>l,option>anchor},index>={!}]
1048 \begin{forest} background tree,
1049 for tree={draw,tikz={\fill[](.anchor)circle[radius=1pt];}}
1050 [parent
1051 [child 1, ~l~=10mm, ~anchor~=north west]
1052 [child 2, ~l~=10mm, ~anchor~=south west]
1053 [child 3, ~l~=12mm, ~anchor~=south]
1054 [child 4, ~l~=12mm, ~anchor~=base east]
1055 ]
1056 \measureydistance[\texttt{l(child)}=#1]{(!2.anchor)}{(.anchor)}{(!1.anchor)+(-5mm,0)}{left}
1057 \measureydistance[\texttt{l(child)}=#1]{(!3.anchor)}{(.anchor)}{(!4.anchor)+(5mm,0)}{right}
1058 \measurexdistance[\texttt{s sep(parent)}=#1]{(!1.south east)}{(!2.south west)}{+(0,-5mm)}{below}
1059 \measurexdistance[\texttt{s sep(parent)}=#1]{(!2.south east)}{(!3.south west)}{+(0,-5mm)}{below}
1060 \measurexdistance[\texttt{s sep(parent)}=#1]{(!3.south east)}{(!4.south west)}{+(0,-8mm)}{below}
1061 \end{forest}
1062 \end{forestexample}
1063
1064 Positioning the chilren in the s-dimension is the job and \emph{raison d'etre} of the package. As a
1065 first approximation: the children are positioned so that the distance between them is at least the
1066 value of option \index{s sep} (s-separation), which defaults to double \PGF;'s |inner_xsep| (and this
1067 is 0.3333em by default). As you can see from the example above, s-separation is the distance
1068 between the borders of the nodes, not their anchors!
1069
1070 A fuller story is that \index{s sep} does not control the s-distance between two siblings, but rather
1071 the distance between the subtrees rooted in the siblings. When the green and the yellow child of
1072 the white node are s-positioned in the example below, the horizontal
1073 distance between the green and the yellow subtree is computed. It can be seen with the naked eye
1074 that the closest nodes of the subtrees are the TP and the DP with a red border. Thus, the children
1075 of the root CP (top green DP and top yellow TP) are positioned so that the horizontal distance
1076 between the red-bordered TP and DP equals \index{s sep}.
1077 \begin{forestexample}[index={for step,tree,s sep}]
1078 \begin{forest}
1079 important/.style={name=#1,draw={red,thick}}
1080 [CP, ~s sep~=3mm, for tree=draw
1081 [DP, for tree={fill=green}
1082 [D][NP[N][CP[C][TP,important=left
1083 [T][vP[v][VP[DP][V'[V][DP]]]]]]]]
1084 [TP,for tree={fill=yellow}
1085 [T][vP[v][VP[DP,important=right][V'[V][DP]]]]]
1086 ]
1087 \measurexdistance[\texttt{s sep(root)}=#1]
1088 {(left.north east)}{(right.north west)}{(.north)+(0,3mm)}{above}
1089 \end{forest}
1090 \end{forestexample}
1091
1092 Note that \foRest; computes the same distances between nodes
1093 regardless of whether the nodes are filled or not, or whether their
1094 border is drawn or not. Filling the node or drawing its border does
1095 not change its size. You can change the size by adjusting \TikZ;'s
1096 |inner_sep| and |outer_sep| \citep[\S16.2.2]{tikzpgf2.10}, as shown
1097 below:
1098 \begin{forestexample}[index={for step,tree,s sep}]
1099 \begin{forest}
1100 important/.style={name=#1,draw={red,thick}}
1101 [CP, s sep=3mm, for tree=draw
1102 [DP, for tree={fill=green,~inner sep~=0}
1103 [D][NP,important=left[N][CP[C][TP[T][vP[v]
1104 [VP[DP][V'[V][DP]]]]]]]]
1105 [TP,for tree={fill=yellow,~outer sep~=2pt}
1106 [T,important=right][vP[v][VP[DP][V'[V][DP]]]]]
1107 ]
1108 \measurexdistance[\texttt{s sep(root)}=#1]
1109 {(left.north east)}{(right.north west)}{(.north)+(0,3mm)}{above}
1110 \end{forest}
1111 \end{forestexample}
1112 (This looks ugly!) Observe that having increased |outer sep| makes the edges stop touching
1113 borders of the nodes. By (\PGF;'s) default, the |outer sep| is exactly half of the border
1114 line width, so that the edges start and finish precisely at the border.
1115
1116 Let's play a bit and change the \index{option>l} of the root of the yellow subtree. Below, we set the
1117 vertical
1118 distance of the yellow TP to its parent to 3\,cm: and the yellow submarine sinks diagonally \dots\@
1119 Now, the closest nodes are the higher yellow DP and the green VP.
1120 \begin{forestexample}[index={option>l,s sep,for step,tree}]
1121 \begin{forest}
1122 important/.style={name=#1,draw={red,thick}}
1123 [CP, s sep=3mm, for tree=draw
1124 [DP, for tree={fill=green}
1125 [D][NP[N][CP[C][TP
1126 [T][vP[v][VP,important=left[DP][V'[V][DP]]]]]]]]
1127 [TP,for tree={fill=yellow}, l=3cm
1128 [T][vP[v][VP[DP,important=right][V'[V][DP]]]]]
1129 ]
1130 \measurexdistance[\texttt{s sep(root)}=#1]
1131 {(left.north east)}{(right.north west)}{(.north)+(0,3mm)}{above}
1132 \end{forest}
1133 \end{forestexample}
1134
1135 Note that the yellow and green nodes are not vertically aligned anymore. The positioning algorithm
1136 has no problem with that. But you, as a user, might have, so here's a neat trick. (This only works
1137 in the ``normal'' circumstances, which are easier to see than describe.)
1138 \begin{forestexample}[label=ex:l*,index={dimen*=l,option>phantom,for step,tree}]
1139 \begin{forest}
1140 [CP, for tree=draw
1141 [DP, for tree={fill=green},~l*~=3
1142 [D][NP]]
1143 [TP,for tree={fill=yellow}
1144 [T][VP[DP][V'[V][DP]]]]
1145 ]
1146 \end{forest}
1147 \end{forestexample}
1148 We have changed DP's \index{option>l}'s value via ``augmented assignment'' known from
1149 many programming languages: above, we have used |l*=3| to triple
1150 \index{option>l}'s value; we could have also said |l+=5mm| or |l-=5mm| to
1151 increase or decrease its value by 5\,mm, respectively. This
1152 mechanism works for every numeric and dimensional option in \foRest;.
1153
1154 Let's now play with option \index{s sep}.
1155 \begin{forestexample}[index={s sep,option>l,dimen*=l,for step,tree}]
1156 \begin{forest}
1157 [CP, for tree=draw, ~s sep~=0
1158 [DP, for tree={fill=green},l*=3
1159 [D][NP]]
1160 [TP,for tree={fill=yellow}
1161 [T][VP[DP][V'[V][DP]]]]
1162 ]
1163 \end{forest}
1164 \end{forestexample}
1165 Surprised? You shouldn't be. The value of \index{s sep} at a given node controls the s-distance
1166 \emph{between the subtrees rooted in the children of that node}! It has no influence over the
1167 internal geometry of these subtrees. In the above example, we have set |s_sep=0| only for the root
1168 node, so the green and the yellow subtree are touching, although internally, their nodes are not.
1169 Let's play a bit more. In the following example, we set the \index{s sep} to: $0$ at the last
1170 branching level (level 3; the root is level 0), to 2\,mm at level 2, to 4\,mm at level 1 and to
1171 6\,mm at level 0.
1172
1173 \begin{forestexample}[label=ex:spread-s,point={level},index={readonly option>level,for step,tree,s sep},index>={!}]
1174 \begin{forest}
1175 for tree={~s sep~=(3-level)*2mm}
1176 [CP, for tree=draw
1177 [DP, for tree={fill=green},l*=3
1178 [D][NP]]
1179 [TP,for tree={fill=yellow}
1180 [T][VP[DP][V'[V][DP]]]]
1181 ]
1182 \measurexdistance{(!11.south east)}{(!12.south west)}{+(0,-5mm)}{below}
1183 \path(md2)-|coordinate(md)(!221.south east);
1184 \measurexdistance{(!221.south east)}{(!222.south west)}{(md)}{below}
1185 \measurexdistance{(!21.north east)}{(!22.north west)}{+(0,2cm)}{above}
1186 \measurexdistance{(!1.north east)}{(!221.north west)}{+(0,-2.4cm)}{below}
1187 \end{forest}
1188 \end{forestexample}
1189 As we go up the tree, the nodes ``spread.'' At the lowest level, V and DP are touching. In the
1190 third level, the \index{s sep} of level 2 applies, so DP and V' are 2\,mm apart. At the second
1191 level we
1192 have two pairs of nodes, D and NP, and T and TP: they are 4\,mm apart. Finally, at level 1, the
1193 \index{s sep} of level 0 applies, so the green and yellow DP are 6\,mm apart. (Note that D and NP are
1194 at level 2, not 4! Level is a matter of structure, not geometry.)
1195
1196 As you have probably noticed, this example also demostrated that we can compute the value of an
1197 option using an (arbitrarily complex) formula. This is thanks to \PGF;'s module |pgfmath|.
1198 \FoRest; provides an interface to |pgfmath| by defining |pgfmath| functions for every node option,
1199 and some other information, like the \index{readonly option>level} we have used above, the number of children
1200 \index{n children}, the sequential number of the child \index{readonly option>n}, etc. For details, see
1201 \S\ref{ref:pgfmath}.
1202
1203 The final separation parameter is \index{l sep}. It determines the minimal
1204 separation of a
1205 node from its descendants. It the value of \index{option>l} is too small, then \emph{all} the
1206 children (and thus their subtrees)
1207 are pushed
1208 away from the parent (by increasing their \index{option>l}s), so that the distance between the node's
1209 and each child's subtree
1210 boundary is at least \index{l sep}. The initial \index{option>l} can be too small for
1211 two reasons: either
1212 some child is too high, or the parent is too deep. The first problem is easier to see: we force the
1213 situation using a bottom-aligned multiline node. (Multiline nodes can be easily created using |\\|
1214 as a line-separator. However, you must first specify the horizontal alignment using option
1215 \index{align} (see \S\ref{ref:node-appearance}).
1216 Bottom vertical alignment is achieved by setting \index{base}|=|\index{value of=base>bottom};
1217 the default, unlike in \TikZ;, is \index{base}|=|\index{value of=base>top}).
1218 \begin{forestexample}[point={align,base},index={align,base}]
1219 \begin{forest}
1220 [parent
1221 [child]
1222 [child]
1223 [a very\\tall\\child, align=center, base=bottom]
1224 ]
1225 \end{forest}
1226 \end{forestexample}
1227
1228 The defaults for \index{option>l} and \index{l sep} are set so that they ``cooperate.''
1229 What this
1230 means and why it is necessary is a complex issue explained in \S\ref{tut:defaults}, which you will
1231 hopefully never have to read \dots\@ You might be out of luck, however. What if you
1232 needed to decrease the level distance? And nothing happened, like below on the left? Or, what if
1233 you used lots of parenthesis in your nodes? And got a strange vertical misalignment, like below
1234 on the right? Then rest assured that these (at least) are features not bugs and read
1235 \S\ref{tut:defaults}.
1236 \begin{forestexample}[layout=tree on top,v sep=-55ex,code left skip=-3cm,label=ex:misalignments,index={option>phantom,for step,step>children,fit,baseline,edge,descendants,content,pgfmath,ss 1}]
1237 \begin{forest}
1238 [,phantom,for children={l sep=1ex,fit=band,
1239 for 1={edge'=,l=0},baseline}
1240 [{l+=5mm},for descendants/.pgfmath=content
1241 [AdjP[AdvP][Adj'[Adj][PP]]]]
1242 [default
1243 [AdjP[AdvP][Adj'[Adj][PP]]]]
1244 [{l-=5mm},for descendants/.pgfmath=content
1245 [AdjP[AdvP][Adj'[Adj][PP]]]]
1246 ]
1247 \path (current bounding box.west)|-coordinate(l1)(!212.base);
1248 \path (current bounding box.west)|-coordinate(l2)(!2121.base);
1249 \path (current bounding box.east)|-coordinate(r1)(!212.base);
1250 \path (current bounding box.east)|-coordinate(r2)(!2121.base);
1251 \draw[dotted] (l1)--(r1) (l2)--(r2);
1252 \end{forest}
1253 \hspace{5cm}
1254 \begin{forest}
1255 [x forest, baseline
1256 [x[x[x[x[x[x[x[x[x[x[x[x[x]]]]]]]]]]]]]
1257 [(x)[(x)[(x)[(x)[(x)[(x)[(x)[(x)[(x)[(x)[(x)[(x)[(x)]]]]]]]]]]]]]
1258 ]
1259 \end{forest}
1260 \end{forestexample}
1261
1262 \subsubsection{The defaults, or the hairy details of vertical alignment}
1263 \label{tut:defaults}
1264
1265 In this section we discuss the default values of options controlling the l-alignment of the nodes.
1266 The defaults are set with top-down trees in mind, so l-alignment is actually vertical alignment.
1267 There are two desired effects of the defaults. First, the spacing between the nodes of a tree
1268 should adjust to the current font size. Second, the nodes of a given level should be vertically
1269 aligned (at the base), if possible.
1270
1271 Let us start with the base alignment: \TikZ;'s default is to anchor the nodes at their center,
1272 while \foRest;, given the usual content of nodes in linguistic representations, rather anchors them
1273 at the base \cite[\S16.5.1]{tikzpgf2.10}. The difference is particularly clear for a ``phonological''
1274 representation:
1275 \begin{forestexample}[index={for step,tree,option>anchor}]
1276 \begin{forest} for tree={anchor=center}
1277 [maybe[m][a][y][b][e]]
1278 \end{forest}\quad
1279 \begin{forest}
1280 [maybe[m][a][y][b][e]]
1281 \end{forest}
1282 \end{forestexample}
1283 The following example shows that the vertical distance between nodes depends on the current font size.
1284 \begin{forestexample}
1285 \hbox{\small A small tree
1286 \begin{forest} baseline
1287 [VP[DP][V'[V][DP]]]
1288 \end{forest}
1289 \normalsize and
1290 \large
1291 a large tree
1292 \begin{forest} baseline
1293 [VP[DP][V'[V][DP]]]
1294 \end{forest}}
1295 \end{forestexample}
1296 Furthermore, the distance between nodes also depends on the value of \PGF;'s |inner_sep| (which
1297 also depends on the font size by default: it equals 0.3333\,em).
1298 \[\index{l sep}=\mbox{height}(\mbox{strut})+\mbox{\texttt{inner ysep}}\]
1299 The default value of \index{s sep} depends on |inner_xsep|: more precisely, it equals double
1300 |inner_xsep|).
1301 \begin{forestexample}[index={baseline,for step,tree}]
1302 \begin{forest} baseline,for tree=draw
1303 [VP[DP][V'[V][DP]]]
1304 \end{forest}
1305 \pgfkeys{/pgf/inner sep=0.6666em}
1306 \begin{forest} baseline,for tree=draw
1307 [VP[DP][V'[V][DP]]]
1308 \end{forest}
1309 \end{forestexample}
1310 Now a hairy detail: the formula for the default \index{option>l}.
1311 \[\index{option>l}=\index{l sep}+2\cdot\mbox{\texttt{outer ysep}}+\mbox{total
1312 height}(\mbox{`dj'})\]
1313
1314 To understand what this is all about we must first explain why it is necessary to set the default
1315 \index{option>l} at all? Wouldn't it be enough to simply set \index{l sep} (leaving
1316 \index{option>l} at 0)?
1317 The problem is that not all letters have the same height and depth. A tree where the vertical
1318 position of the nodes would be controlled solely by (a constant) \index{l sep} could
1319 result in a ragged tree (although the height of the child--parent edges would be constant).
1320 \begin{forestexample}[index={baseline,for step,step>children,no edge,option>name,descendants,option>l}]
1321 \begin{forest}
1322 [default,baseline,for children={no edge}
1323 [DP
1324 [AdjP[Adj]]
1325 [D'[D][NP,name=np]]]]
1326 \path (current bounding box.west)|-coordinate(l)(np.base);
1327 \path (current bounding box.east)|-coordinate(r)(np.base);
1328 \draw[dotted] (l)--(r);
1329 \end{forest}
1330 \begin{forest}
1331 [{l=0},baseline,for children={no edge}
1332 [DP,for descendants={l=0}
1333 [AdjP[Adj]]
1334 [D'[D][NP,name=np]]]]
1335 \path (current bounding box.west)|-coordinate(l)(np.base);
1336 \path (current bounding box.east)|-coordinate(r)(np.base);
1337 \draw[dotted] (l)--(r);
1338 \end{forest}
1339 \end{forestexample}
1340 The vertical misalignment of Adj in the right tree is a consequence of the fact that letter j is the
1341 only letter with non-zero depth in the tree. Since only \index{l sep} (which is constant
1342 throughout the tree) controls the vertical positioning, Adj, child of Ad\emph{j}P, is pushed lower
1343 than the other nodes on level 2. If the content of the nodes is variable enough (various heights
1344 and depths), the cumulative effect can be quite strong, see the right tree of example
1345 (\ref{ex:misalignments}).
1346
1347 Setting only a default \index{l sep} thus does not work well enough in general. The same
1348 is true for the reverse possibility, setting a default \index{option>l} (and leaving \index{l sep} at 0). In the example below, the depth of the multiline node (anchored at the top
1349 line) is such that the child--parent edges are just too short if the level distance is kept constant.
1350 Sometimes, misalignment is much preferred \dots
1351 \begin{forestexample}[index={align,{value of=align>center},for step,tree,l sep}]
1352 \mbox{}\begin{forest}
1353 [default,baseline
1354 [first child[a][b][c]]
1355 [{second child\\[-1ex]\scriptsize(a copy)},
1356 align=center[a][b][c]]
1357 ]
1358 \end{forest}\quad
1359 \begin{forest} for tree={l sep=0}
1360 [{\texttt{l sep}=0},baseline
1361 [first child[a][b][c]]
1362 [{second child\\[-1ex]\scriptsize(a copy)},
1363 align=center[a][b][c]]
1364 ]
1365 \end{forest}
1366 \end{forestexample}
1367
1368 Thus, the idea is to make \index{option>l} and \index{l sep} work as a team:
1369 \index{option>l} prevents
1370 misalignments, if possible, while \index{l sep} determines the minimal vertical distance
1371 between levels. Each of the two options deals with a certain kind of a ``deviant'' node, i.e.\ a
1372 node which is too high or too deep, or a node which is not high or deep enough, so we need to
1373 postulate what a \emph{standard} node is, and synchronize them so that their effect on standard
1374 nodes is the same.
1375
1376 By default, \foRest; sets the standard node to be a node containing letters d and j. Linguistic
1377 representations consist mainly of letters, and in the \TeX's default Computer Modern font, d is the
1378 highest letter (not character!), and j the deepest, so this decision guarantees that trees
1379 containing only letters will look nice. If the tree contains many parentheses, like the right
1380 tree of example (\ref{ex:misalignments}), the default will of course fail
1381 and the standard node needs to be modified. But for many applications, including nodes with
1382 indices, the default works.
1383
1384 The standard node can be changed using macro \index{forestStandardNode};
1385 see \ref{ref:standard-node}.
1386 % TODO: primer? ali raje po spremembi interfaceja
1387
1388 \subsection{Advanced option setting}
1389 \label{tut:advanced-option-setting}
1390
1391 We have already seen that the value of options can be manipulated: in (\ref{ex:romannumeral}), we
1392 have converted numeric content from arabic into roman numerals using the \emph{wrapping} mechanism
1393 |content=\romannumeral#1|; in (\ref{ex:l*}), we have tripled the value of |l| by saying |l*=3|. In
1394 this section, we will learn more about the mechanisms for setting options and referring to their
1395 values.
1396
1397 One other way to access an option value is using macro \index{forestoption}. The macro takes a
1398 single argument: an option name. In the
1399 following example, the node's child sequence number is appended to the existing content. (This is
1400 therefore also an example of wrapping.)
1401 \begin{forestexample}[label=ex:forestoption,index={option>phantom,delay,for step,descendants,content,readonly option>n,forestoption}]
1402 \begin{forest}
1403 [,phantom,delay={for descendants={
1404 content=#1$_{~\forestoption~{n}}$}}
1405 [c][o][u][n][t]]
1406 \end{forest}
1407 \end{forestexample}
1408
1409 However, only options of the current node can be accessed using \index{forestoption}. Possibly the simplest way to
1410 access option values of other nodes is to use \foRest;'s extensions to the \PGF;'s mathematical library
1411 |pgfmath|, documented in \citep[part VI]{tikzpgf2.10}. To see |pgfmath| in action,
1412 first take a look at the crazy tree on the title page, and observe how the nodes are
1413 rotated: the value given to option \index{rotate} is a full-fledged |pgfmath| expression
1414 yielding an integer
1415 in the range from $-30$ to $30$. Similiarly, \index{dimen+=l} adds a random float
1416 in the $[-5,5]$ range to the current value of \index{option>l}.
1417
1418 Example (\ref{ex:spread-s}) demonstrated that information about
1419 the node, like the node's level, can be accessed within |pgfmath| expressions. All
1420 options are accessible in this way, i.e.\ every option has a corresponding |pgfmath| function.
1421 For example, we could rotate the node based on its content:
1422 \begin{forestexample}[index={delay,for step,tree,content}]
1423 \begin{forest}
1424 delay={for tree={~rotate=content~}}
1425 [30[-10[5][0]][-90[180]][90[-60][90]]]
1426 \end{forest}
1427 \end{forestexample}
1428
1429 All numeric, dimensional and boolean options of \foRest; automatically pass the given value
1430 through |pgfmath|. If you need pass the value through |pgfmath|
1431 for a string option, use the \index{pgfmath} handler. The following example sets the node's
1432 content to its child sequence number (the root has child sequence number 0).
1433 \begin{forestexample}[index={delay,for step,tree,content,readonly option>n,pgfmath}]
1434 \begin{forest}
1435 delay={for tree={content/~.pgfmath~=int(n)}}
1436 [[[][][]][[][]]]
1437 \end{forest}
1438 \end{forestexample}
1439
1440 As mentioned above, using |pgfmath| it is possible to access options of non-current nodes. This
1441 is achieved by providing the option function with a \index{relative node name}
1442 (see~\S\ref{ref:relative-node-names}) argument.\footnote{The form without
1443 parentheses \texttt{option\string_name} that we have been using until now to refer to an option of
1444 the
1445 current node is just a short-hand notation for \texttt{option\string_name()} --- note that in some
1446 contexts, like preceding \texttt{+} or \texttt{-}, the short form does not work! (The same
1447 seems to be true for all pgfmath functions with ``optional'' arguments.)} In the next example, we
1448 rotate the node based on the content of its parent (\index{short step>u} means `up').
1449 \begin{forestexample}[index={delay,for step,descendants,content,ss u},index>={!}]
1450 \begin{forest}
1451 delay={for descendants={rotate=content~("!u")~}}
1452 [30[-10[5][0]][-90[180]][90[-60][90]]]
1453 \end{forest}
1454 \end{forestexample}
1455 Note that the argument of the option function is surrounded by double quotation marks: this is
1456 to prevent evaluation of the relative node name as a |pgfmath| function --- which it is not.
1457
1458 For further ways to access option values, see \S\ref{tut:wrapping}. Here, we continue by introducing
1459 \emph{relative node setting}: write \index{relative node name}|.|\meta{option}|=|\meta{value} to set
1460 the value of \meta{option} of the specified relative node. Important: computation of the value is
1461 done in the context of the original node. The following example defines style \keyname{move} which
1462 not only draws an arrow from the source (the current node) to the target, but also moves the content
1463 of the source to the target (leaving a trace). Note the difference between |#1| and |##1|: |#1| is
1464 the argument of the style \keyname{move} (a node walk determining the target), while |##1| is the
1465 original option (in this case, \indexex{option>content}) value.
1466 \begin{forestexample}[index={for step,tree,calign,tikz,delay,content},index>={!}]
1467 \begin{forest}
1468 for tree={calign=fixed edge angles},
1469 move/.style={
1470 tikz={\draw[->] () to[out=south west,in=south] (#1);},
1471 delay={~#1.content~={##1},content=$t$}},
1472 [CP[][C'[C][\dots[,phantom][VP[DP][V'[V][DP,move=!r1]]]]]]
1473 \end{forest}
1474 \end{forestexample}
1475
1476 \begin{forestexample}[index={if option,n children,content,for step,step>children,delay,pgfmath},index>={!},basicstyle=\scriptsize\ttfamily,layout=export]
1477 \begin{forest}
1478 calc/.style={if n children={0}{}{content=0,for children={calc,~!u.content~/.pgfmath=int(content("!u")+content())}}},
1479 delay=calc,
1480 [[[3][4][5]][[3][9]][8][[[1][2][3]]]]
1481 \end{forest}
1482 \end{forestexample}
1483
1484 In the following example, the content of the branching nodes is computed by \foRest;: a branching
1485 node is a sum of its children. The algorithm visits each node (but the root node) and adds its
1486 content to the content of the parent. Note that as the computation must proceed bottom-up,
1487 \index{for step=\index{descendants children-first}} propagator is used to walk through the
1488 tree.\footnote{It would be possible to emulate \index{for step=\index{descendants children-first}}
1489 by defining a recursive style, as was done in this manual for versions of the package prior to
1490 introduction of the bottom-up propagator. The following code produces identical result as the code
1491 in the main text.
1492
1493 \box\codebox}
1494
1495 \begin{forestexample}[index={if option,n children,content,for step,step>children,delay,pgfmath},index>={!}]
1496 \begin{forest}
1497 delay={
1498 where n children={0}{}{content=0},
1499 for descendants children-first={
1500 ~!u.content~/.pgfmath=int(content("!u")+content())}
1501 }
1502 [[[3][4][5]][[3][9]][8][[[1][2][3]]]]
1503 \end{forest}
1504 \end{forestexample}
1505
1506 Actually, for common computations such as summing things up, \foRest; provides an easier way to do it: aggregate functions (\S\ref{ref:aggregate-functions}). Below, aggregate function \index{sum}, defined as |pgfkeys| handler, walks through the \index{step>children} (second argument) of the current node, summing up their \index{content} (first argument) and stores the result as the \index{content} of the current node (because \index{content} is the handled key).
1507
1508 \begin{forestexample}[index={sum,aggregate postparse,for step,tree children-first,delay,n children,if option,content,step>children}]
1509 \begin{forest}
1510 delay={
1511 aggregate postparse=int,
1512 for tree children-first={
1513 if n children={0}{}{
1514 content/~.sum~={content}{children}
1515 }
1516 }
1517 }
1518 [[[3][4][5]][[3][9]][8][[[1][2][3]]]]
1519 \end{forest}
1520 \end{forestexample}
1521
1522 \subsection{Wrapping}
1523 \label{tut:wrapping}
1524
1525 We have already seen examples of inserting option values into other expressions. In example
1526 (\ref{ex:romannumeral}), we have wrapped the value of the option being assigned to (|#1| stood for
1527 the current value of option \index{content}); example (\ref{ex:forestoption}) additionally wrapped
1528 the value of option \index{readonly option>n} (of the current node) using macro \index{forestoption}. In general,
1529 \foRest; offers two ways to perform computations (from simple option value lookups to
1530 complicated formulas) and insert their results into another expression (of any kind: \TeX\ code,
1531 |pgfkeys| keylist, |pgfmath| expression, etc.).
1532
1533 Historically, the first \foRest;'s mechanism that offered wrapping of computed values were handlers
1534 \index{wrap pgfmath arg} and \index{wrap $n$ pgfmath args} (for $n=2,\dots,8$), which combine the
1535 wrapping mechanism with the |pgfmath| evaluation. The idea is to compute (most often, just access
1536 option values) arguments using |pgfmath| and then wrap them into the given macro body (marked below)
1537 using \TeX's parameters (|#1| etc.). Below, this is used to subscript the contents of a node with
1538 its sequential number and the number of parent's children.
1539 \begin{forestexample}[index={option>phantom,delay,for step,descendants,content,readonly option>n,n children,wrap $n$ pgfmath args},index>={!},label=ex:pgfmathwrap]
1540 \begin{forest} [,phantom,delay={for descendants={
1541 content/.wrap 3 pgfmath args=
1542 ~{#1$_{#2/#3}$}~
1543 {content}{n}{n_children("!u")}}}
1544 [c][o][u][n][t]]
1545 \end{forest}
1546 \end{forestexample}
1547 Note the underscore |__| character in |n__children|: in |pgfmath| function names, spaces,
1548 apostrophes and other non-alphanumeric characters from option names are all replaced by
1549 underscores.
1550
1551 As another example, let's make the numerals example (\ref{ex:numerals-simple}) a bit fancier.
1552 The numeral type is read off the parent's content and used to construct the appropriate control
1553 sequence (|\@arabic|, |\@roman| and |\@alph|). (The numbers are not specified in content
1554 anymore: we simply read the sequence number \index{readonly option>n}.)
1555 \begin{forestexample}[index={delay,where option,readonly option>level,content,readonly option>n,for step,step>children,option>l,wrap $n$ pgfmath args},index>={!}]
1556 \begin{forest}
1557 delay={where level={2}{content/.wrap 2 pgfmath args=
1558 {\csname @#1\endcsname{#2}}
1559 {content("!u")}{n}}{}},
1560 for children={l*=n},
1561 [\LaTeX\ numerals,
1562 [arabic[][][][]]
1563 [roman[][][][]]
1564 [alph[][][][]]
1565 ]
1566 \end{forest}
1567 \end{forestexample}
1568
1569 Invoking |pgfmath| is fairly time consuming and using it to do nothing but retrieve an option value
1570 seems a bit of an overkill. To remedy the situation, argument processor
1571 (\S\ref{ref:argument-processor}) was introduced in \FoRest; v2.0 and considerably expanded in v2.1.
1572 One way to invoke it is using handler \index{handler>process}.
1573
1574 The argument processor takes a sequence of instructions and an arbitrary number of arguments,
1575 transforms the given arguments according to the instructions, and feeds the resulting list of
1576 arguments into the handled key.
1577
1578 An instruction is given by a single-character code. The simplest instructions are:
1579 \index{processor>O}, which expects its argument to be an option name (possibly preceded by a
1580 \index{relative node name}|.| to access the option value of a non-current node) and returns the
1581 value of the option; \index{processor>R}, which does the same for registers; and \index{processor>noop}, which
1582 leaves the argument unchanged.
1583
1584 In the following example, we define style |test| taking four arguments and call it by providing
1585 the arguments via \index{handler>process}. The instruction string |ROO__| tells the argument processor that
1586 the first argument is the value of (scratch) register \indexex{temptoksa}, the second the value of
1587 option \indexex{n children} at the current node, the third the value of option \indexex{content} of
1588 the second child of the current node, and the fourth just a plain string. Macro |test| is thus
1589 actually invoked with argument list |{Hello}{3}{Jane}{Goodbye}|.
1590
1591 \begin{forestexample}[index={handler>process,processor>noop,processor>R,processor>O,delay,content,n
1592 children,temptoksa}]
1593 \begin{forest}
1594 test/.style n args={4}{align=center,
1595 content={#1!\\I have #2 children.\\One of them is #3.\\#4!}}
1596 [,delay={temptoksa=Hello,
1597 test/.process={~ROO_~}{temptoksa}{n children}{!2.content}{Goodbye}}
1598 [John][Jane][Joe]]
1599 \end{forest}
1600 \end{forestexample}
1601
1602 To wrap using the argument processor, use instruction \index{processor>w}. Unless wrapping a single
1603 argument, this instruction should be followed by a number indicating the number of arguments
1604 consumed. \index{processor>w} will take the required number of arguments from the list of already
1605 processed arguments and wrap them in the macro body given as the next (yet unprocessed) argument.
1606
1607 The following example has the same result as example (\ref{ex:pgfmathwrap}). Note that the
1608 order of the wrapper-macro body and the arguments is different for \index{handler>process} and \index{wrap
1609 $n$ pgfmath args}. (Experience shows that \index{handler>process}'s order is easier on the eyes.) The
1610 example also illustrates that (i) the instructions need not be enclosed in braces and (ii) that
1611 repetition of an argument processor instruction can be indicated by appending a number to the
1612 instruction: thus |O3| below means the same as |OOO|.
1613
1614 \begin{forestexample}[index={option>phantom,delay,for step,descendants,content,readonly option>n,n children},index>={!}]
1615 \begin{forest} [,phantom,delay={for descendants={
1616 content/.process=~O3 w3~
1617 {content}{n}{!u.n children}
1618 {#1$_{#2/#3}$}
1619 }}
1620 [c][o][u][n][t]]
1621 \end{forest}
1622 \end{forestexample}
1623
1624 Note that the order of the wrapper-macro body and the arguments is different for
1625 \index{handler>process} and \index{wrap $n$ pgfmath args}. Experience shows that
1626 \index{handler>process}'s order is easier on the eyes. The example also illustrates that the
1627 instructions need not be enclosed in braces and that repetition of an argument processor instruction
1628 can be indicated by appending a number to the instruction: |O3| above is equivalent to |OOO|.
1629
1630 % \begin{forestexample}[index={process,processor>w}]
1631 % \begin{forest}
1632 % [root,delay={align=center,
1633 % content/.process={OO ~w2~}
1634 % {n children}{content}
1635 % {This node has #1 children.\\It's original content is ``#2''.}
1636 % }]
1637 % \end{forest}
1638 % \end{forestexample}
1639
1640 \index{wrap $n$ pgfmath args} always returns a single braced expression and is thus a bit cumbersome
1641 to use when the handled key expects multiple arguments: the trick is to enclose the expected
1642 argument list in extra braces (marked in the code below). As \index{handler>process} can return multiple
1643 arguments, there is no need for such a workaround. See the following example for comparison of the
1644 two methods.
1645
1646 \begin{forestexample}[index={for step,step>name,handler>process,processor>O,processor>w,wrap $n$ pgfmath args}]
1647 \begin{forest}
1648 [,phantom
1649 [pgfmath[2,delay={for n/.wrap 2 pgfmath args=
1650 ~{~{#1}{content=#2,draw}~}~
1651 {content}{content("!u")}
1652 } [x][x][x][x]]]
1653 [process[3, delay={for n/.process=
1654 {O Ow1}{content}
1655 {!u.content}{content=#1,draw}
1656 } [x][x][x][x]]]
1657 ]
1658 \end{forest}
1659 \end{forestexample}
1660
1661 A single \index{handler>process} invocation can perform multiple wrappings. The numbering of arguments of
1662 each wrapping starts at |#1|. In the example below, \index{for step=\index{nodewalk}} takes two
1663 arguments, a nodewalk and a list of nodekeys. Each is produced by an independent wrapping (wrap bodies
1664 are marked in the code).
1665
1666 \begin{forestexample}[index={handler>process,processor>R,processor>w,for step,nodewalk,+toks,content}]
1667 \begin{forest}
1668 declare toks register=prefix,
1669 declare count register=level to prefix,
1670 prefix=X-,
1671 level to prefix=1,
1672 delay={
1673 for nodewalk/.process=Rw Rw
1674 {level to prefix}{~level=#1~}
1675 {prefix}{~+content=#1~}
1676 }
1677 [0[1[2]][3[4][5]][6[7][8][9]]]
1678 \end{forest}
1679 \end{forestexample}
1680
1681
1682
1683
1684 \subsection{Externalization}
1685 \label{tut:externalization}
1686
1687 \FoRest; can be quite slow, due to the slowness of both \PGF;/\TikZ; and its own computations.
1688 However, using \emph{externalization}, the amount of time spent in \foRest; in everyday life can
1689 be reduced dramatically. The idea is to typeset the trees only once, saving them in separate
1690 PDFs, and then, on the subsequent compilations of the document, simply include these PDFs instead
1691 of doing the lenghty tree-typesetting all over again.
1692
1693 \FoRest;'s externalization mechanism is built on top of \TikZ;'s |external| library. It
1694 enhances it by automatically detecting the code and context changes: the tree is recompiled if and
1695 only if either the code in the \index{forest} environment or the context (arbitrary parameters; by
1696 default, the parameters of the standard node) changes.
1697
1698 To use \foRest;'s externalization facilities, say:\footnote{When you switch on
1699 the externalization for a document containing many \keyname{forest} environments, the first
1700 compilation can take quite a while, much more than the compilation without externalization. (For
1701 example, more than ten minutes for the document you are reading!) Subsequent compilations,
1702 however, will be very fast.}\index[not print]{external}
1703 \begin{lstlisting}[point=external]
1704 \usepackage[external]{forest}
1705 ~\tikzexternalize~
1706 \end{lstlisting}
1707
1708 If your \index{forest} environment contains some macro, you will probably want the externalized
1709 tree to be recompiled when the definition of the macro changes. To achieve this, use
1710 \index{forestset}|{|\index{external/depends on macro}|=|\cmdname{macro}|}|. The effect is
1711 local to the \TeX\ group.
1712
1713 \TikZ;'s externalization library promises a |\label| inside the externalized graphics to work
1714 out-of-box, while |\ref| inside the externalized graphics should work only if the externalization
1715 is run manually or by |make| \citep[\S32.4.1]{tikzpgf2.10}. A bit surprisingly perhaps, the
1716 situation is roughly reversed in \foRest;. |\ref| inside the externalized graphics will work
1717 out-of-box. |\label| inside the externalized graphics will not work at all. Sorry. (The reason
1718 is that \foRest; prepares the node content in advance, before merging it in the whole tree, which
1719 is when \TikZ;'s externalization is used.)
1720
1721 \subsection{Expansion control in the bracket parser}
1722 \label{tut:bracket}
1723
1724 By default, macros in the bracket encoding of a tree are not
1725 expanded until nodes are being drawn --- this way, node
1726 specification can contain formatting instructions, as illustrated in
1727 section~\ref{tut:basic-usage}. However, sometimes it is useful to
1728 expand macros while parsing the bracket representation, for example to
1729 define tree templates such as the X-bar template, familiar
1730 to generative grammarians:\footnote{Honestly, dynamic node creation might be a better way to do
1731 this; see~\S\ref{ref:dynamic}.}
1732 \begin{forestexample}[index={bracketset,action character}]
1733 ~\bracketset{action character=@}~
1734 \def\XP#1#2#3{#1P[#2][#1'[#1][#3]]}
1735 \begin{forest}
1736 [~@~\XP T{DP}{~@~\XP V{DP}{DP}}]
1737 \end{forest}
1738 \end{forestexample}
1739 In the above example, the |\XP| macro is preceded by the \emph{action character} |@|: as
1740 the result, the token following the action character was expanded before the parsing proceeded.
1741
1742 The action character is not hard coded into \foRest;. Actually, there is no action character by
1743 default. (There's enough special characters in \foRest; already, anyway, and the situations where
1744 controlling the expansion is preferable to using the |pgfkeys| interface are not numerous.) It is
1745 defined at the top of the example by processing key \index{action character} in the
1746 |/bracket| path; the definition is local to the \TeX\ group.
1747
1748 Let us continue with the description of the expansion control facilities of the bracket parser.
1749 The expandable token following the
1750 action character is expanded only once. Thus, if one defined macro
1751 |\VP| in terms of the general |\XP| and tried to use it in the same
1752 fashion as |\XP| above, he would fail. The correct way is to follow
1753 the action character by a braced expression: the braced expression
1754 is fully expanded before bracket-parsing is resumed.
1755 \begin{forestexample}[index={bracketset,action character}]
1756 \bracketset{action character=@}
1757 \def\XP#1#2#3{#1P[#2][#1'[#1][#3]]}
1758 \def\VP#1#2{\XP V{#1}{#2}}
1759 \begin{forest}
1760 [@\XP T{DP}{~@{~\VP{DP}{DP}~}~}]
1761 \end{forest}
1762 \end{forestexample}
1763
1764 In some applications, the need for macro expansion might be much
1765 more common than the need to embed formatting instructions.
1766 Therefore, the bracket parser provides commands |@+| and |@-|: |@+|
1767 switches to full expansion mode --- all tokens are fully expanded
1768 before parsing them; |@-| switches back to the default mode, where
1769 nothing is automatically expanded.
1770 \begin{forestexample}[index={bracketset,action character}]
1771 \bracketset{action character=@}
1772 \def\XP#1#2#3{#1P[#2][#1'[#1][#3]]}
1773 \def\VP#1#2{\XP V{#1}{#2}}
1774 \begin{forest} ~@+~
1775 [\XP T{DP}{\VP{DP}{DP}}]
1776 \end{forest}
1777 \end{forestexample}
1778
1779 All the action commands discussed above were dealing only with
1780 \TeX's macro expansion. There is one final action command, |@@|,
1781 which yields control to the user code and expects it to call
1782 |\bracketResume| to resume parsing. This is useful to e.g.\
1783 implement automatic node enumeration:
1784 \begin{forestexample}[index={bracketset,action character,option>phantom,delay,where option,readonly option>level,content}]
1785 \bracketset{action character=@}
1786 \newcount\xcount
1787 \def\x#1{~@@~\advance\xcount1
1788 \edef\xtemp{[$\noexpand\times_{\the\xcount}$[#1]]}%
1789 \expandafter\bracketResume\xtemp
1790 }
1791 \begin{forest}
1792 phantom,
1793 delay={where level=1{content={\strut #1}}{}}
1794 ~@+~
1795 [\x{f}\x{o}\x{r}\x{e}\x{s}\x{t}]
1796 \end{forest}
1797 \end{forestexample}
1798 This example is fairly complex, so let's discuss how it works. |@+| switches to the full
1799 expansion mode, so that macro |\x| can be easily run. The real magic hides in this macro. In
1800 order to be able to advance the node counter |\xcount|, the macro takes control from \foRest; by
1801 the |@@| command. Since we're already in control, we can use |\edef| to define the node content.
1802 Finally, the |\xtemp| macro containing the node specification is expanded with the resume command
1803 sticked in front of the expansion.
1804
1805
1806
1807 \section{Reference}
1808 \label{sec:reference}
1809
1810 This section documents all publicly exposed keys and macros defined by the core package. All other
1811 commands defined by the package (see the implementation typeset in |forest.pdf|) are considered
1812 internal and might change without prior notice or compatibility support.
1813
1814 \subsection{Package loading and options}
1815 \label{ref:package-options}
1816
1817 Load the package by writing |\usepackage{forest}| in the document preamble.
1818
1819 Field-specific definitions and defaults are stored in separate libraries. Use
1820 |\usepackage[|\meta{library name}|]{forest}| to load library \meta{library name} and its defaults
1821 alongside the main package. Loading several libraries in this way is allowed: however, if you need
1822 more control over loading the defaults, use the following macros.
1823
1824 \begin{syntax}
1825 \indexitem{macro>useforestlibrary}[|*|][|[|\meta{options}|]|]|{|\meta{library}|,...}|
1826 Loads the given libraries.
1827
1828 The starred version applies their defaults as well, while the starless does not. Multiple library
1829 names can be given, separated by commas. Libraries can receive \meta{options}. This macro can only
1830 be used in the preamble.
1831
1832 \indexitem{macro>forestapplylibrarydefaults}|{|\meta{library name},...|}|
1833 Loads the default settings of \meta{library}.
1834
1835 Multiple library names can be given, separated by commas. This macro can be used either in the
1836 preamble or in the document body. Its effect is local to the current \TeX\ scope.
1837 \end{syntax}
1838
1839 For example, the |linguistics| library defines c-command related nodewalks, changes the default
1840 parent--child edges to south--north (the main package default is border--border) and sets the
1841 baseline to the root\footnote{For details, see \S\ref{sec:library-linguistics}.} node. Thus, if you write |\usepackage[linguistics]{forest}| in your preamble,
1842 or use macro \cmdname{forestapplylibrarydefaults} like below, you get the following:
1843
1844 \begin{forestexample}[tree bin=minipage,index={for step,c-commanded}]
1845 package defaults:
1846 \begin{forest}
1847 [VP % cannot use "for c-commanded" below!
1848 [DP, for sibling={for tree=red}]
1849 [V'[V][DP]]
1850 ]
1851 \end{forest}\\[1ex]
1852 |linguistics| library defaults:
1853 ~\forestapplylibrarydefaults{linguistics}~
1854 \begin{forest}
1855 [VP
1856 [DP, ~for c-commanded~={red}]
1857 [V'[V][DP]]
1858 ]
1859 \end{forest}
1860 \end{forestexample}
1861
1862 \begin{syntax}
1863 \indexitem(false){package option>external}|=|\alternative{true,false}
1864
1865 Enable/disable externalization, see \S\ref{ref:externalization}.
1866
1867 \indexitem(most){package option>compat}|=|\meta{keylist}
1868 Enter compatibility mode with previous versions of the package.
1869
1870 If at all possible, each backwards incompatible change is given a key in the |compat| path, e.g.\
1871 |compat=|\index{1.0-forstep} reverts to the old behaviour of spatial propagators \index{for
1872 step=\meta{step}}, where a propagator could not fail.
1873
1874 While each compatibility feature can be enabled individually, they are grouped for ease of use. To
1875 load compatibility features since the last version of form
1876 |x|[|.y|[|.z|]], write |compat=x|[|.y|[|.z|]]|-all| or
1877 |compat=x|[|.y|[|.z|]]|-most|. The former enables all compatibility features since that release, the
1878 latter only those that are guaranteed to not disrupt any new functionality of the package.
1879
1880 To load all compatibility features since the last major release (|x| in |x.y.z|), write
1881 |compat=|\indexdef{value of=compat>all}; to load most of them, write |compat=|\indexdef{value of=compat>most} or simply |compat|.
1882
1883 To enable multiple compatibility features, either use this option multiple times, or provide it with
1884 a comma-separated list of compatibility features. (Surround the list by braces.)
1885
1886 Specifying this option also defines macro \indexdef{macro>forestcompat} (taking the same arguments
1887 as the package option) which can be used to enable compatibility features locally, within the
1888 document body. To enable compatibility mode but not enable any specific compatibility feature for
1889 the entire document, write |compat=|\indexdef{value of=compat>none} as a package option.
1890
1891 For a list of compatibility features, see \S\ref{sec:changelog}.
1892
1893 By default, the package warns when a compatibility feature is used. Disable this behaviour by
1894 |compat=|\indexdef{value of=compat>silent}.
1895
1896 \indexitem(true){package option>tikzcshack}|=|\alternative{true,false}
1897
1898 Enable/disable the hack into \TikZ;'s implicit coordinate syntax, see
1899 \S\ref{ref:relative-node-names}.
1900
1901 \indexitem(true){package option>tikzinstallkeys}|=|\alternative{true,false}
1902
1903 Install certain keys into the \keyname{/tikz} path. Currently: \index{fit to}.
1904
1905 \indexitem{package option>debug}|=|\meta{debug category}[, \meta{debug category}]*
1906
1907 Prints out some debugging info to the log file. When given no argument, prints out all the
1908 available information, otherwise only the information on the listed (comma-separated) debug categories. The available categories are listed below.
1909
1910 \begin{syntax}
1911 \indexitem{value of=debug>nodewalks}
1912 \indexitem{value of=debug>dynamics}
1913 \indexitem{value of=debug>process}
1914 \end{syntax}
1915
1916 \end{syntax}
1917
1918 \subsection{Invocation}
1919 \label{sec:invocation}
1920
1921 \begin{syntax}
1922 %%% begin listing region: forest_environment_doc
1923 \indexitem{environment>forest={[\texttt{(}\meta{config}\texttt{)}]\meta{tree}}}
1924 %%% end listing region: forest_environment_doc
1925 \indexitem{macro>Forest}[*][|(|\meta{config}|)|]\marg{tree}
1926
1927 The environment and the starless version of the macro introduce a group; the starred macro does
1928 not, so the created nodes can be used afterwards, like in the example below. (Note that this will
1929 leave a lot of temporary macros lying around. This shouldn't be a problem, however, since all of
1930 them reside in the |\forest| ``namespace''.)
1931
1932 {\tikzexternaldisable
1933 \begin{forestexample}
1934 We create a
1935 ~\Forest*~{
1936 [DP,name=DP,baseline
1937 [D]
1938 [NP]
1939 ]
1940 }
1941 and merge it into a
1942 ~\Forest*~{
1943 [VP,baseline
1944 [V]
1945 [,replace by=DP
1946 ]
1947 ]
1948 }
1949 \end{forestexample}}
1950
1951 \meta{config} is a keylist that configures the behaviour of the environment/macro. The
1952 configuration is the first operation that the environment/macro does; it precedes even the reading
1953 of the tree specification. Currently, \meta{config} accepts only one key:
1954 \begin{syntax}
1955 \indexitem{option of=forest>stages}|=|\meta{keylist}
1956
1957 By default, after reading the tree specification, \foRest; executes style \index{style>stages}.
1958 If key |stages| is used in \meta{config}, \meta{keylist} is executed instead.
1959 \end{syntax}
1960
1961 \indexitem{macro>forestset}\marg{keylist}
1962
1963 Execute \meta{keylist} (of node keys) with the default path set to \keyname{/forest}.
1964 \begin{advise}
1965 \item This macro is usually used to define \foRest; styles.
1966 \item Usually, no current node is set when this macro is called. Thus, executing most node keys
1967 in this place will fail. However, if you have some nodes lying around, you can use
1968 propagator \index{for step=\index{option>name}}|=|\meta{node name} to set the node with the given name as
1969 current.
1970 \end{advise}
1971 \end{syntax}
1972
1973
1974 \subsection{The bracket representation}
1975 \label{ref:bracket}
1976
1977 A bracket representation of a tree is a token list with the following syntax:
1978 \begin{eqnarray*}
1979 \meta{tree}&=&\left[\meta{preamble}\right]\meta{node}\\
1980 \meta{node}&=&\texttt{[}\left[\meta{content}\right]\left[\texttt{,}\meta{keylist}\right]
1981 \left[\meta{children}\right]\texttt{]}\meta{afterthought}\\
1982 \meta{preamble}&=&\meta{keylist}\\
1983 \meta{keylist}&=&\meta{key--value}\left[,\meta{keylist}\right]\\
1984 \meta{key--value}&=&\meta{key}\OR\meta{key}\texttt{=}\meta{value}\\
1985 \meta{children}&=&\meta{node}\left[\meta{children}\right]
1986 \end{eqnarray*}
1987
1988 The \meta{preamble} keylist is stored into keylist register \index{preamble}. The \meta{keylist} of
1989 a \meta{node} is stored into keylist option \index{given options}. \meta{content} and
1990 \meta{afterthought} are normally stored by prepending and appending
1991 \index{content}|'=|\meta{content} and \index{afterthought}|=|\meta{afterthought} to \index{given
1992 options}, respectively; this is customizable via \index{content to} and redefining style
1993 \index{afterthought}.
1994
1995 Normally, the tokens in the bracket representation are not expanded while the input is parsed.
1996 However, it is possible to control expansion. Expansion control sequences of \foRest;'s bracket
1997 parser are shown below. Note that by default, there is no \index{action character}.
1998 \begin{center}
1999 \begin{tabular}{ll}
2000 \rstyle\meta{action character}\texttt{-}&no-expansion mode (default): nothing is expanded\\
2001 \rstyle\meta{action character}\texttt{+}&expansion mode: everything is fully expanded\\
2002 \rstyle\meta{action character}\texttt{}\meta{token}&expand \meta{token}\\
2003 \rstyle\meta{action character}\texttt{}\meta{\TeX-group}&fully expand \meta{\TeX-group}\\
2004 \rstyle\meta{action character}\meta{action character}&yield control;\\&upon finishing its job,
2005 user's code should call \indexdef{macro>bracketResume}
2006 \end{tabular}
2007 \end{center}
2008
2009 To customize the bracket parser, call
2010 \indexdef{macro>bracketset}\meta{keylist}, where the keys can be the following.
2011 \begin{syntax}
2012 \indexitem({{[%]
2013 }}){bracket key>opening bracket}|=|\meta{character}
2014 \indexitem({{{{%[
2015 ]}}}}){bracket key>closing bracket}|=|\meta{character}
2016 \indexitem(none){bracket key>action character}|=|\meta{character}
2017 \end{syntax}
2018
2019 \begin{advise}
2020 \item Careful when setting the \index{opening bracket} to |(|, %)
2021 as an initial |(| %)
2022 is understood as the delimiter of the optional \meta{config} argument of the
2023 \index{environment>forest} environment or \index{macro>Forest} macro. The workaround is to either
2024 provide an empty \meta{config} argument |()|, or put some whitespace (e.g.\ a newline) before the
2025 tree specification.
2026 \end{advise}
2027
2028 By redefining the following two keys, the bracket parser can be used outside \foRest;.
2029 \begin{syntax}
2030 \indexitem{bracket key>new node}|=|\meta{preamble}\meta{node specification}\meta{csname}.
2031 Required semantics: create a new node given the preamble (in the case of a new
2032 root node) and the node specification and store the new node's id into \meta{csname}.
2033 \indexitem{bracket key>set afterthought}|=|\meta{afterthought}\meta{node id}.
2034 Required semantics: store the afterthought in the node with given id.
2035 \end{syntax}
2036
2037 \subsection{The workflow}
2038 \label{sec:workflow}
2039
2040 \subsubsection{Stages}
2041 \label{ref:stages}
2042
2043 \FoRest; does its job in several stages. The default course of events is the following:
2044 \begin{enumerate}
2045 \item\label{step:parsing-bracket} The bracket representation of the tree (\S\ref{ref:bracket}) is
2046 parsed and stored in a data structure.
2047 \item\label{step:given-options} The keys given in the bracket representation are processed. In
2048 detail, \index{default preamble} is processed first, then the given \index{preamble} (both in the
2049 context of the (formal) root node) and finally the keylists given to individual nodes. The latter
2050 are processed recursively, in a depth-first, parent-first fashion.
2051 \item\label{step:typeset-nodes} Each node is typeset in its own |tikzpicture| environment, saved
2052 in a box and its measures are taken.
2053 \item\label{step:pack} The nodes of the tree are \emph{packed}, i.e.\ the relative positions of the nodes are
2054 computed so that the nodes don't overlap. That's difficult. The result: option \index{option>s} is
2055 set for all nodes. (Sometimes, the value of \index{option>l} is adjusted as well.)
2056 \item\label{step:compute-xy} Absolute positions, or rather, positions of the nodes relative to the
2057 root node are computed. That's easy. The result: options \index{option>x} and \index{y} are
2058 set.
2059 \item\label{step:draw-tree} The \TikZ; code that will draw the tree is produced and executed. (The nodes are
2060 drawn by using the boxes typeset in step~\ref{step:typeset-nodes}.)
2061 \end{enumerate}
2062
2063 Stage~\ref{step:parsing-bracket} collects user input and is thus ``fixed''. However, the other
2064 stages, which do the actual work, are under user's control.
2065
2066 First, hooks exist between the individual stages which make it possible (and easy) to change the
2067 properties of the tree between the processing stages. For a simple example, see
2068 example~(\ref{ex:adjustxy}): the manual adjustment of \index{y} can only be done after the absolute
2069 positions have been computed, so the processing of this option is deferred by \index{before drawing
2070 tree}. For a more realistic example, see the definition of style \index{GP1}: before packing,
2071 \texttt{outer xsep} is set to a high (user determined) value to keep the $\times$s uniformly spaced;
2072 before drawing the tree, the \texttt{outer xsep} is set to \texttt{0pt} to make the arrows look
2073 better.
2074
2075 Second, the execution of the processing stages \ref{step:given-options}--\ref{step:draw-tree} is
2076 \emph{completely} under user's control. To facilitate adjusting the processing flow, the approach
2077 is twofold. The outer level: \foRest; initiates the processing by executing style \index{style>stages},
2078 which by default executes the processing stages \ref{step:given-options}--\ref{step:draw-tree},
2079 preceding the execution of each but the first stage by processing the keys embedded in temporal
2080 propagators \keyname{before ...} (see \S\ref{ref:temporal-propagators}). The inner level: each
2081 processing step is the sole resident of a stage-style, which makes it easy to adjust the workings of
2082 a single step. What follows is the default content of style \keyname{stages}, including the default
2083 content of the individual stage-styles. Both nicely readable and ready to copy-paste versions are given.
2084 \begin{syntax}
2085 \indexitem{style>stages}
2086 \begin{syntax}
2087 \item \index{for step=\index{root'}}|={|
2088 \item | |\index{process keylist register}|=|\index{default preamble}|,|
2089 \item | |\index{process keylist register}|=|\index{preamble}
2090 \item |}|
2091 \item \index{process keylist}|=|\index{given options}
2092 \item \index{process keylist}|=|\index{before typesetting nodes}
2093 \indexitem{style>typeset nodes stage}\hfill
2094 |{|\index{for step=\index{root'}}|=|\index{typeset nodes}|}|
2095 \item \index{process keylist}|=|\index{before packing}
2096 \indexitem{style>pack stage}\hfill
2097 |{|\index{for step=\index{root'}}|=|\index{pack}|}|
2098 \item \index{process keylist}|=|\index{before computing xy}
2099 \indexitem{style>compute xy stage}\hfill
2100 |{|\index{for step=\index{root'}}|=|\index{compute xy}|}|
2101 \item \index{process keylist}|=|\index{before drawing tree}
2102 \indexitem{style>draw tree stage}\hfill
2103 |{|\index{for step=\index{root'}}|=|\index{draw tree}|}|
2104 \end{syntax}
2105 \end{syntax}
2106 \lstinputregion{forest.dtx}{stages}
2107
2108 Both style \keyname{stages} and the individual stage-styles may be freely modified by the user.
2109 Obviously, as a style must be redefined before it is processed, |stages| should be redefined (using
2110 macro \index{forestset}) outside the \index{forest} environment; alternatively, stages can be given
2111 as the (parenthesized) optional argument of the environment (see~\S\ref{sec:invocation}). A stage
2112 style can also be redefined in the preamble or in any of the keylists processed prior to entering
2113 that stage.
2114
2115 Here's the list of keys used either in the default processing or useful in an alternative
2116 processing flow.
2117 \begin{syntax}
2118 \indexitem{stage>typeset nodes}
2119 \itemnosep
2120 \indexitem{stage>typeset nodes'}
2121
2122 Typesets each node of the current node's subtree in its own |tikzpicture| environment. The result
2123 is saved in a box (which is used later, in the \index{draw tree stage}) and its measures are
2124 taken.
2125
2126 In the |typeset_nodes'| variant, the node box's content is not overwritten if the box already
2127 exists.
2128
2129 The order in which the nodes are typeset is controlled by nodewalk style \indexdef{nodewalk
2130 style>typeset nodes processing order} or, if this style is not defined, by \index{processing
2131 order}.
2132
2133 \indexitem{node key>typeset node} Typesets the \emph{current} node, saving the result in the node box.
2134
2135 This key can be useful also in the default \index{style>stages}. If, for example, the node's content
2136 is changed and the node retypeset just before drawing the tree, the node will be positioned as if
2137 it contained the ``old'' content, but have the new content: this is how the constant distance
2138 between $\times$s is implemented in the \index{GP1} style.
2139
2140 \indexitem{stage>pack} The nodes of the tree are \emph{packed}, i.e.\ the relative positions of
2141 the nodes are computed so that the nodes don't overlap. The result: option \index{option>s} is set
2142 for all nodes; sometimes (in tier alignment and for some values of \index{calign}), the value
2143 of some nodes' \index{option>l} is adjusted as well.
2144
2145 \indexitem{node key>pack'} ``Non-recursive'' packing: packs the children of the current node only.
2146 (Experimental, use with care, especially when combining with tier alignment.)
2147
2148 \indexitem{stage>compute xy} Computes the positions of the nodes in the subtree relative to the
2149 current node. The results are stored into options \index{option>x} and \index{y}. The current node's
2150 \index{option>x} and \index{y} remain unchanged.
2151
2152 \indexitem{stage>draw tree}
2153 \itemnosep
2154 \indexitem{stage>draw tree'}
2155 Produces and executes the \TikZ; code that draws the (sub)tree rooted in the current node.
2156
2157 The procedure uses the node boxes typeset by \index{typeset nodes} or friends. The |'| variant
2158 includes the node boxes in the picture using \cmdname{copy}, not \cmdname{box}, thereby preserving
2159 them.
2160
2161 For details and customization, see \S\ref{sec:draw-tree}.
2162
2163 \indexitem{node key>draw tree box}|=|[\meta{\TeX\ box}] The picture drawn by the subsequent
2164 invocations of \index{draw tree} and \index{draw tree'} is put into \meta{\TeX\ box}. If
2165 the argument is omitted, the subsequent pictures are typeset normally (the default).
2166
2167 \indexitem{node key>process keylist}|=|\meta{keylist option}
2168 For each node in the entire tree, the keylist saved in \meta{keylist option} of the node is
2169 processed (in the context of that node).
2170
2171 Note that this key is not sensitive to the current node: it processes the keylists for the whole
2172 tree. Actually, it is possible to control which nodes are visited: \index{keylist option
2173 processing order=\meta{keylist option}} is walked if it is defined, otherwise \index{processing
2174 order}. In both cases, the processing nodewalk starts at the formal root of the tree (see
2175 \index{root'} and \index{set root}), which is reevaluated at the beginning of each internal cycle
2176 (see below). By default, \index{keylist option processing order=\meta{keylist option}} is indeed
2177 undefined, while the \index{processing order} defauls to \index{tree}, which means that \emph{all
2178 the nodes in the entire tree} are processed.
2179
2180 Keylist-processing proceeds in cycles. In a given cycle, the value of option \meta{keylist option
2181 name} is processed for every node visited by the processing nodewalk. During a cycle, keys may
2182 be \emph{delayed} using key \index{delay}. Keys delayed in a cycle are processed in the next
2183 cycle. The number of cycles in unlimited.
2184
2185 Dynamic creation of nodes happens between the cycles. The options given to the dynamically
2186 created nodes are implicitely delayed and thus processed at the end of the next cycle.
2187
2188 This key is primarily intended for use within \index{style>stages}.
2189 The calls of this key should \emph{not} be nested, and it should not be embedded under
2190 \index{process keylist'} or \index{process keylist register}.
2191
2192 When changing the processing nodewalk, note that delayed keys will be executed only for nodes
2193 visited by the processing nodewalk. Delayed spatially propagated keys will be remembered,
2194 though, and executed when the given keylist is processed for the target node. Using spatial
2195 propagators without delaying cannot result in a non-processed key.
2196
2197 \indexitem{node key>process keylist'}|=|\meta{keylist option}\meta{nodewalk}
2198
2199 This key is a variant of \index{process keylist}. The differences are as follows.
2200
2201 The processing nodewalk is given explicitely (by \meta{nodewalk}) and starts at the current node
2202 (in each internal cycle).
2203
2204 There is no dynamic creation of nodes between the delay cycles. Any dynamic node
2205 instructions will be remembered and executed after the next cycle of \index{process keylist}, or
2206 an explicit call to \index{do dynamics}.
2207
2208 It is safe to embed this key within \index{process keylist} and (all) friends.
2209
2210 \indexitem{node key>process keylist''}|=|\meta{keylist option}\meta{nodewalk}
2211
2212 This key is a variant of \index{process keylist} which executes neither dynamic node operations nor
2213 delayed keys (there are thus no internal cycles). Any delayed keys will not be processed
2214 during the execution of this key. They will be remembered and executed at the end of the next cycle
2215 of \index{process keylist} or \index{process keylist'}.
2216
2217 As for \index{process keylist'}, the processing nodewalk is given explicitely (by \meta{nodewalk})
2218 and starts at the current node.
2219
2220 It is safe to embed this key within \index{process keylist} and (all) friends.
2221
2222 \indexitem{node key>process keylist register}|=|\meta{register}
2223
2224 Process the keylist saved in \meta{register} in the context of the current node.
2225
2226 Any delayed keys will not be processed during the execution of this key. They will be
2227 remembered and executed at the end of the next cycle of \index{process keylist} or
2228 \index{process keylist'}.
2229
2230 It is safe to embed this key within \index{process keylist} or \index{process keylist'}.
2231
2232 \indexitem{node key>process delayed}|=|\meta{nodewalk} Process delayed keys.
2233
2234 Keylist \index{delay} cannot be processed using \index{process keylist} or \index{process
2235 keylist'}. Thus this key.
2236
2237 Like \index{process keylist} or \index{process keylist'}, this key uses internal cycles. Thus,
2238 any embedded \index{delay}s will be processed.
2239
2240 There is no dynamic creation of nodes between the delay cycles. Any dynamic node instructions will
2241 be remembered and executed after the next cycle of \index{process keylist} or \index{process
2242 keylist'}, or an explicit call to \index{do dynamics}.
2243
2244 This key is safe to use within \index{process keylist}, \index{process keylist'} and
2245 \index{process keylist register}.
2246
2247 \indexitem(tree){nodewalk style>processing order}|/.nodewalk style=|\meta{nodewalk}
2248
2249 Redefine this style to change the default order in which \index{process keylist} processes a keylist
2250 option. For example, to process the nodes in a child-first fashion, write
2251 \begin{lstlisting}
2252 processing order/.nodewalk style=tree children first
2253 \end{lstlisting}
2254 Note that this is a \emph{nodewalk} style, so it must be defined either using |.style| handler
2255 during a nodewalk or using \index{nodewalk style}.
2256
2257 \indexitem(processing order)[form={processing order}]{word suffix=keylist option>nodewalk style>processing order=\meta{keylist option}}|/.nodewalk style=|\meta{nodewalk}
2258
2259 Redefine this style to change the \index{process keylist} processing order for a specific
2260 \meta{keylist option}. For example, to process \index{before drawing tree} options in the
2261 child-first fashion, leaving the processing of other |before ...| keylists untouched, write
2262 \begin{lstlisting}
2263 before drawing tree processing order/.nodewalk style=tree children first
2264 \end{lstlisting}
2265
2266 \indexitem{node key>do dynamics} Experimental. Perform pending dynamic tree operations.
2267
2268 Do not use this key within \index{process keylist} or \index{process keylist'}.
2269
2270 \end{syntax}
2271
2272 \subsubsection{Temporal propagators}
2273 \label{ref:temporal-propagators}
2274
2275 Temporal propagators delay processing of given keys until some other point in the processing of the
2276 tree. There are three kinds of temporal propagators. Most of the propagators have the form
2277 |before_...| and defer the processing of the given keys to a hook just before some stage in the
2278 workflow (\S\ref{ref:stages}). \index{before packing node} and \index{after packing node} are
2279 special as they fire \emph{during} the packing stage. The \index{delay} propagator is
2280 ``internal'' to the current hook: the keys in the hook are processed cyclically, and \keyname{delay}
2281 delays the processing of the given keys until the next cycle.
2282
2283 Formally, temporal propagators are keylist options (except \index{delay n}, which is a style), so
2284 augmented assignments are possible (\S\ref{sec:option-setting}).
2285
2286 All temporal propagators can be nested without limit.
2287
2288 \begin{advise}
2289 \item A note on typos.
2290
2291 By default, all keys unknown to \foRest; are appended to keylist option \index{node options} The
2292 value of \index{node options} is fed to \TikZ; when typesetting a node, so any typos are caught by
2293 \TikZ;. However, as nodes are normally typeset in stage \index{typeset nodes stage}, any typos in
2294 keys temporally propagated past that stage will not be noticed, simply because noone will use the
2295 value of \index{node options} where they end up (the exception being nodes which are explicitely
2296 retypeset by the user using \index{typeset node}).
2297
2298 To sum up, typos in any keys temporally propagated by \index{before packing}, \index{before
2299 packing node}, \index{after packing node}, \index{before computing xy} and \index{before drawing
2300 tree} will be silently ignored. This is probably not what you want, so double-check everything
2301 you write there.
2302
2303 Using \index{unknown to}|=|\index{unknown key error}, it is possible to change the default
2304 behaviour. You will catch all typos if you append the command to \index{pack stage}, as shown
2305 below. This can be done either in the tree or by \index{forestset}.
2306
2307 \begin{lstlisting}
2308 typeset nodes stage/.append style={unknown to=unknown key error}
2309 \end{lstlisting}
2310
2311 Of course, this makes it impossible to write simply
2312 |before_drawing_tree={inner_sep=5pt,_typeset_node}|. Any |tikz|'s options must be given
2313 explicitely via \index{node options}:
2314 |before_drawing_tree={node_options={inner_sep=5pt},_typeset_node}|.
2315 \end{advise}
2316
2317 \begin{syntax}
2318 \indexitem{propagator>delay}|=|\meta{keylist} Defers the processing of the \meta{keylist} until the next
2319 cycle.
2320
2321 Internally, |delay| is a keylist option, so augmented operators of the \index{keylist} type can be
2322 used.
2323
2324 To check whether any keys were delayed, use conditional \index{if have delayed}.
2325 \indexitem{propagator>delay n}|=|\meta{integer}\meta{keylist} Defers the processing of the
2326 \meta{keylist} for $n$ cycles. $n$ may be $0$, and it may be given as a |pgfmath| expression.
2327
2328 \indexitem{propagator>given options}
2329
2330 When \index{style>stages} processing starts, this list holds the keys given by the user in the
2331 bracket representation.
2332
2333 \indexitem{propagator>before typesetting nodes}|=|\meta{keylist} Defers the processing of the
2334 \meta{keylist} to until just before the nodes are typeset.
2335
2336 \indexitem{propagator>before packing}|=|\meta{keylist}
2337
2338 \indexitem{propagator>before packing node}|=|\meta{keylist}
2339
2340 Defers the processing of the \meta{keylist} given to the node to until just before/after the
2341 subtree of \emph{this specific node} is packed. Even before packing node, the (subtrees of the)
2342 children of the node have already been packed.\footnote{\FoRest; employs two variants of the
2343 packing algorithm: the faster one is used for (parts of) trees with uniform growth, i.e.\
2344 subtrees where \index{grow} does not change; the slower, generic variant is used in where this
2345 is not the case. Now, the fast method works by dealing with l and s dimension separately, and
2346 it is able to do this for the entire (sub)tree, without needing to invoke the packing method for
2347 its constituents. The consequence is that there is no place where \index{before packing node}
2348 could be called meaningfully, as the node's constituents are not packed individually, ``just
2349 before packing the current node'' is the same as ``just before packing the tree'', and for many
2350 nodes packing is not called anyway in the fast method. As the rationale behind \index{before
2351 packing node} is to be able to adjust the options of the subtree based on the information
2352 gained by packing its constituents, specifying \index{before packing node} automatically
2353 switches to the generic method.} \indexitem{propagator>after packing node}|=|\meta{keylist} Defers
2354 the processing of the \meta{keylist} given to the node to until just after \emph{this specific
2355 node} is packed.
2356
2357 \begin{forestexample}[index={after packing node,no edge,calign,value of=calign>first,option>l,l sep,content format,content,if option,n children,pgfmath,option>s,max x,min x,for step,step>children,wrap pgfmath arg,typeset node,dimen+=s}]
2358 \forestset{box/.style={
2359 draw, no edge, l=0, l sep=1.5ex,
2360 calign=first, anchor=base west,
2361 content format={\strut\forestoption{content}},
2362 if n children=0{}{
2363 ~after packing node~={
2364 minimum width/.pgfmath=
2365 {s("!l")+max_x("!l")-s("!1")-min_x("!1")},
2366 for children/.wrap pgfmath arg={s+={##1}}{0},
2367 typeset node}}}}
2368 \begin{forest} for tree={box} [/
2369 [home[saso[Download][TeX]][alja][joe]]
2370 [usr[bin][share]]]
2371 \end{forest}
2372 \end{forestexample}
2373
2374 \begin{advise}
2375 \item Remember to typeset or pack the node using \index{pack'} if you have changed options
2376 influencing the typesetting or packing process.
2377 \end{advise}
2378
2379 \indexitem{propagator>before computing xy}|=|\meta{keylist} Defers the processing of the
2380 \meta{keylist} to until just before the absolute positions of the nodes are computed.
2381 \indexitem{propagator>before drawing tree}|=|\meta{keylist} Defers the processing of the
2382 \meta{keylist} to until just before the tree is drawn.
2383 \end{syntax}
2384
2385
2386 \subsubsection{Drawing the tree}
2387 \label{sec:draw-tree}
2388
2389 This section provides a detailed description of how \index{draw tree} and friends draw the tree.
2390
2391 First, here's the default course of events. \index{draw tree} is called from style \index{draw tree
2392 stage} in the context of the formal root node. It does not draw the tree directly, but rather
2393 produces \TikZ; code that actually does the drawing. The tree-drawing instructions are enclosed in
2394 a |tikzpicture| environment and come in three parts: the (non-phantom) nodes are drawn first,
2395 followed by edges between the drawn nodes and finally the custom \TikZ; code (of all, including
2396 phantom nodes). Each of those is drawn for the entire (sub)tree of the current node, in recursive,
2397 depth-first parent-first first-child-first order.
2398
2399 Most parts of the tree drawing procedure are customizable. Zooming in from the invocation of
2400 \index{draw tree} to the keys that produce the drawing code, the customization options are as
2401 follows.
2402
2403 There are two ways the invocation of \index{draw tree} can differ from the default. First,
2404 \index{draw tree} can be called within the context of any node. As a first approximation, that node
2405 will become the root of the tree that is being drawn; for the whole truth, see \index{draw tree
2406 method}. Second, \index{draw tree} can be called not only at \index{draw tree stage}, but any
2407 time after the nodes to be drawn have been typeset (see \index{typeset nodes stage}) and their
2408 absolute coordinates (\index{option>x} and \index{option>y}) computed (see \index{compute xy stage}).
2409
2410
2411 \begin{syntax}
2412 \indexitem(\begin{tikzpicture}){node key>begin draw}|/.code=|\meta{toks: \TeX\ code} \vspace{-\parskip}
2413 \indexitem(\end{tikzpicture}){node key>end draw}|/.code=|\meta{toks: \TeX\ code}
2414
2415 The code produced by \index{draw tree} is put in the environment specified by \keyname{begin
2416 draw} and \keyname{end draw}. Thus, it is this environment, normally a |tikzpicture|, that does
2417 the actual drawing.
2418
2419 A common use of these keys might be to enclose the |tikzpicture| environment in a |center|
2420 environment, thereby automatically centering all trees; or, to provide the \TikZ; code to execute
2421 at the beginning and/or end of the picture.
2422
2423 Note that \keyname{begin draw} and \keyname{end draw} are \emph{not} node options: they are
2424 |\pgfkeys|' code-storing keys \citep[\S55.4.3--4]{tikzpgf2.10}.
2425
2426 \end{syntax}
2427
2428 Repeating from (\S\ref{ref:stages}), there are two variants of \index{draw tree}, which differ in
2429 how they use the node boxes created by \index{typeset nodes}: \index{draw tree} includes them using
2430 \cmdname{box}, so they are gone; \index{draw tree'} uses \cmdname{copy}, so they are preserved.
2431 Next, setting \index{draw tree box} will cause the tree to be drawn in the given \TeX\ box.
2432
2433
2434 \begin{syntax}
2435
2436 \indexitem{style>draw tree method}
2437
2438 This is the heart of the tree-drawing procedure: it determines which parts of the tree are drawn
2439 and in what order. What this style does by default was already described above, but is actually
2440 best seen from the definition itself:
2441
2442 \lstinputregion{forest.dtx}{draw_tree_method}
2443
2444 This style may be modified by the user, but it is and should be invoked only within \index{draw
2445 tree}, by the package: \emph{do not execute this style directly!}
2446
2447 The nodewalks occurring in the default definition of this style are, with the exception of
2448 \index{processing order}, not used anywhere else in the package.
2449
2450 \indexitem{nodewalk style>draw tree nodes processing order}
2451 \itemnosep
2452 \indexitem{nodewalk style>draw tree edges processing order}
2453 \itemnosep
2454 \indexitem{nodewalk style>draw tree tikz processing order}
2455
2456 For each of these nodewalk styles the following holds. If it is defined, it determines which nodes
2457 / edges / pieces of \index{tikz} code are drawn and in which order. If any of these styles is not
2458 defined, its function is taken over by \index{draw tree processing order}. By default, none of
2459 them are defined.
2460
2461 \indexitem{nodewalk style>draw tree processing order}
2462
2463 If this nodewalk is defined, it functions as a fallback for node-, edge- and tikz-code-specific
2464 nodewalks. If it is not defined (the default situation), it has its own fallback:
2465 \index{processing order} (which defaults to \index{tree}).
2466
2467 \indexitem{node key>draw tree node}
2468 \itemnosep
2469 \indexitem{node key>draw tree node'}
2470
2471 Draws the current node at location specified by \index{option>x} and \index{option>y}. The |'|
2472 variant draws the node even if it's \index{phantom}.
2473
2474 These keys should only be used only within the definition of \index{draw tree method}.
2475
2476 \indexitem{conditional>if node drawn}|=|\meta{nodewalk}\meta{true keylist}\meta{false keylist}
2477
2478 Execute \meta{true keylist} if the node at the end of \meta{nodewalk} was already drawn in the
2479 current invocation of \index{draw tree}; otherwise, execute \meta{false keylist}.
2480
2481
2482 \indexitem{node key>draw tree edge}
2483 \itemnosep
2484 \indexitem{node key>draw tree edge'}
2485
2486 Draws the edge from the current node to its parent, using the information in \index{edge path} and
2487 \index{edge}.
2488
2489 The variant without |'| variant tries to be smart: it draws the edge only if both the current node
2490 and its parent have been drawn in the current invocation of \index{draw tree}. (This prevents
2491 drawing the edge from the root node and edges from or to phantom nodes.) The |'| variant is dumb.
2492
2493 These keys should only be used only within the definition of \index{draw tree method}.
2494
2495 \indexitem(draw tree tikz'){style>draw tree tikz}
2496 \itemnosep
2497 \indexitem{node key>draw tree tikz'}
2498
2499 Executes the custom code stored in option \index{tikz} of the current node.
2500
2501 By default, both keys execute the code without performing any checks. Specifically, \index{tikz}
2502 code of phantom nodes is executed. To change this behaviour easily, the user can redefine
2503 \index{draw tree tikz}, which is a style; probably, the definition will employ \index{draw tree
2504 tikz'}. For example, to execute \index{tikz} code only if the node is not \index{phantom}, write
2505
2506 \begin{lstlisting}
2507 draw tree tikz/.style={if phantom={draw tree tikz'}{}}
2508 \end{lstlisting}
2509
2510 These keys should only be used only within the definition of \index{draw tree method}.
2511
2512 \end{syntax}
2513
2514
2515
2516 \subsection{Node keys}
2517 \label{ref:node-keys}
2518
2519 \FoRest; is mostly controlled using \PGF;'s key management utility |pgfkeys|
2520 \citep[\S55]{tikzpgf2.10}. Most of the keys can be given next to the content in the bracket
2521 representation of a tree (\S\ref{ref:bracket}): we call these \emph{node keys}. Some keys,
2522 notably \emph{nodewalk steps} (\S\ref{ref:nodewalks}), must be used as arguments of specific
2523 commands.
2524
2525 Most node keys perform some operation on the \emph{current node}. When the keylist given after the
2526 content of a node is processed, the current node is set to that node. However, the current node can
2527 be temporarily changed, for example by spatial propagators (\S\ref{ref:spatial-propagators}) or,
2528 more genarally, nodewalks (\S\ref{ref:nodewalks}).
2529
2530 The most common function that node keys perform is to set or modify an \emph{option} of the current
2531 node (\S\ref{sec:options-and-registers}), usually to determine the appearance or position of the
2532 node and its edge (\S\ref{sec:formatting-tree}), but there are also several kinds of more exotic
2533 keys like spatial (\S\ref{ref:spatial-propagators}) propagators, which temporarily change the
2534 current node, temporal (\S\ref{ref:temporal-propagators}) propagators, which delay the processing of
2535 the keylist until some other stage in the workflow, keys that dynamically create and move nodes
2536 (\S\ref{ref:dynamic}), keys that control the way \foRest; processes the tree (\S\ref{ref:stages})
2537 etc. Finally, users can also define their own keys, either by defining |pgfkeys| styles\footnote{%
2538 Styles are a feature of the \keyname{pgfkeys} package. They are named keylists, whose usage
2539 ranges from mere abbreviations through templates to devices implementing recursion. To define a
2540 style, use \PGF;'s handler \keyname{.style} \citep[\S55.4.4]{tikzpgf2.10}: \meta{style
2541 name}\keyname{/.style=}\meta{keylist}.} \citep[\S55.4.4]{tikzpgf2.10} or using \foRest;'s option
2542 declaration mechanism (\S\ref{sec:option-declaring}).
2543
2544 \begin{advise}
2545 \item The style definitions and option declarations given among the other keys in the bracket
2546 specification are local to the current tree (but note that \foRest;'s keylist processing,
2547 including temporal and spatial propagation, introduces no groups). To define globally accessible
2548 styles and options (well, they are always local to the current \TeX\ group), use
2549 macro \cmdname{forestset} outside the \index{forest} environment, e.g.\ in the preamble of the
2550 document. (Although \index{forestset}\meta{keylist} is currently equivalent to
2551 \cmdname{pgfkeys}\texttt{\{/forest,}\meta{keylist}\texttt{\}}, don't rely on this as it will
2552 change in some (near) future version of the package, as there is a plan to introduce namespaces
2553 \dots)
2554 \end{advise}
2555
2556 By default, unknown keys are assumed to be \TikZ; keys and are forwarded to \index{node options}.
2557 This behaviour can be changed using \index{unknown to}.
2558
2559 The following subsections list the node keys which are not described elsewhere (see above): spatial
2560 propagators (\S\ref{ref:spatial-propagators}) and general-purpose node keys, i.e.\ those which don't
2561 deal with tree formatting (\S\ref{sec:node-keys-various}).
2562
2563
2564 \subsubsection{Spatial propagators}
2565 \label{ref:spatial-propagators}
2566
2567 Spatial propagators pass the given \meta{keylist} to other node(s) in the tree.
2568
2569 Spatial propagation does not change the current node: after visiting the nodes the keys are
2570 propagated to, a spatial propagator (silently, using a so-called fake step) returns to the origin of
2571 the embedded nodewalk.
2572
2573 \FoRest; provides many spatial propagators. Almost all of them are built from long-form nodewalk
2574 steps using prefix \index{for step}. This is why the list below is so short: it only documents this
2575 prefix and the exceptions. For the list of nodewalk steps, see \S\ref{ref:nodewalks}, in particular
2576 \S\ref{ref:single-step-keys} for single-step keys and \S\ref{ref:multi-step-keys} for multi-step
2577 keys.
2578
2579
2580 \begin{syntax}
2581 \indexitem{word prefix=step>propagator>for=\meta{step}}|=|\meta{arg$_1$}|...|\meta{arg$_n$}\meta{keylist: every-step}
2582 \itemnosep
2583 \indexitem[not short]{word prefix=step>propagator>for=\index{nodewalk}}|=|\meta{nodewalk}\meta{keylist: every-step}
2584 \itemnosep
2585 \indexitem[not short]{word prefix=step>propagator>for=\index{nodewalk key>Nodewalk}}|=|\meta{keylist: config}\meta{nodewalk}\meta{keylist: every-step}
2586
2587 Walks the (single- or multi-step) \meta{step} from the current node and executes the given
2588 \meta{keylist} at every visited node. The current node remains unchanged.
2589
2590 \meta{step} must be a long-form nodewalk step. If it has any arguments, they
2591 (\meta{arg$_1$}|...|\meta{arg$_n$}) should be given before every-step \meta{keylist}, with two
2592 exceptions: embedded nodewalk steps (\index{step>Nodewalk} and \index{nodewalk}) already require
2593 the \meta{keylist: every-step} argument, so it should be omitted, as it makes no sense to provide
2594 the every-step keylist twice.
2595
2596 Examples:
2597 \begin{itemize}
2598 \item |for_parent={l_sep+=3mm}|
2599 \item |for_n=2{circle,draw}|
2600 \item |for_nodewalk={uu2}{blue}|
2601 \item |for_tree={s_sep+=1em}|
2602 \end{itemize}
2603
2604 \long\def\printbigbadforlist#1{%
2605 {%
2606 \tikzexternaldisable
2607 \bracketset{action character=!}%
2608 \begin{forest}(stages={
2609 process keylist=given options,
2610 for root'={
2611 sort by={>O+t+c{content}},
2612 %sort=children,
2613 temptoksa={},
2614 for sort={children}{
2615 TeX and memoize/.process=ROw2{temptoksa}{content}{####1\texttt{for\space}\index{step>####2}},
2616 temptoksa={,\space},
2617 },
2618 }
2619 })
2620 [!\bigbadforlist[nodewalk][nodewalk'][Nodewalk]]
2621 \end{forest}%
2622 }%
2623 }%
2624 \makeatletter
2625 \forest@memoize\printbigbadforlist
2626 \makeatother
2627
2628 {\tolerance=10000
2629 Here's the big list of all spatial propagators built with prefix |for|:
2630 % to update,
2631 % - uncomment \appto\bigbadforlist{[#1]} in define long step in forest.dtx
2632 % - delete line \forest@memo@load {forest@memo@\printbigbadforlist ... in forest-doc.memo
2633 \printbigbadforlist{}.
2634 For details on nodewalk steps, see \S\ref{ref:nodewalks}.
2635
2636 }
2637
2638 \indexitem{propagator>for tree'}|=|\meta{keylist 1}\meta{keylist 2} A ``combination'' of
2639 \index{for step=\index{tree children-first}} and \index{for step=\index{tree}}.
2640
2641 Passes the keylists to the current node and its the descendants. At each node, the \meta{keylist
2642 1} is processed first; then, children are processed recursively; finally, \meta{keylist 2}
2643 is processed.
2644
2645 For an example, see the definition of \index{draw brackets} from \reflibrary{linguistics}.
2646
2647 \indexitem{propagator>for 1}, \dots\indexdef[not print]{propagator>for 2}\indexdef[not print]{propagator>for 3}\indexdef[not print]{propagator>for 4}\indexdef[not print]{propagator>for 5}\indexdef[not print]{propagator>for 6}\indexdef[not print]{propagator>for 7}\indexdef[not print]{propagator>for 8}, \indexdef{propagator>for 9}|=|\meta{keylist}
2648 \itemnosep
2649 \indexitem{propagator>for -1}, \dots\indexdef[not print]{propagator>for -2}\indexdef[not print]{propagator>for -3}\indexdef[not print]{propagator>for -4}\indexdef[not print]{propagator>for -5}\indexdef[not print]{propagator>for -6}\indexdef[not print]{propagator>for -7}\indexdef[not print]{propagator>for -8}, \indexdef{propagator>for -9}|=|\meta{keylist}
2650
2651 Although \index{for step} normally cannot precede short forms of steps, an exception is made
2652 for \index{ss 1}\index[not print]{ss 2,ss 3,ss 4,ss 5,ss 6,ss 7,ss 8}, \dots, \index{ss 9}. (These keys will work even if the short steps are redefined.)
2653
2654 |for |$n$ passes the \meta{keylist} to the $n$th child of the current node. |for -|$n$ starts counting at the last child.
2655 \indexitem{node key>Nodewalk}|=|\meta{keylist: config}\meta{nodewalk}\meta{keylist: every-step}
2656
2657 Configures and executes the \meta{nodewalk}. This key is a nodekey-space copy of nodewalk step
2658 \index{step>Nodewalk}.
2659
2660 \begin{advise}
2661 \item Use this key carefully as it can change the current node!
2662 \item The envisioned purpose of this key is to change the current node within the every-step
2663 keylist of (an outer) nodewalk, where only node keys are accepted. The config defaults
2664 (independent every-step, shared history) are set to facilitate that purpose. But it can also be
2665 used as a simple node key, of course.
2666 \end{advise}
2667
2668 \indexitem{node key>node walk}|=|\meta{node walk} \textbf{Deprecated!!!} Requires
2669 \index{compat}|=1.0-nodewalk|. Please use \index{for step=\index{nodewalk}} in new code. From the
2670 old documentation:
2671
2672 \begin{quote}
2673 This is the most general way to use a \meta{node walk}.
2674
2675 Before starting the \meta{node walk}, key \indexdef{node key>node walk/before walk} is processed.
2676 Then, the \meta{step}s composing the \meta{node walk} are processed: making a step (normally)
2677 changes the current node. After every step, key \indexdef{node key>node walk/every step} is
2678 processed. After the walk, key \indexdef{node key>node walk/after walk} is processed.
2679
2680 \keyname{node walk/before walk}, \keyname{node walk/every step} and \keyname{node walk/after
2681 walk} are processed with \keyname{/forest} as the default path: thus, \foRest;'s node keys can
2682 be used normally inside their definitions.
2683
2684 \begin{advise}
2685 \item Node walks can be tail-recursive, i.e.\ you can call another node walk from \keyname{node
2686 walk/after walk} --- embedding another node walk in \keyname{node walk/before walk} or
2687 \keyname{node walk/every step} will probably fail, because the three node walk styles are not
2688 saved and restored (a node walk doesn't create a \TeX\ group).
2689 \item \keyname{every step} and \keyname{after walk} can be redefined even during the walk.
2690 Obviously, redefining \keyname{before walk} during the walk has no effect (in the current
2691 walk).
2692 \end{advise}
2693 \end{quote}
2694 \end{syntax}
2695
2696
2697 \subsubsection{Various}
2698 \label{sec:node-keys-various}
2699
2700 \begin{syntax}
2701
2702 \indexitem{style>afterthought}|=|\meta{toks} Provides the afterthought explicitely.
2703
2704 This key is normally not used by the end-user, but rather called by the bracket parser. By
2705 default, this key is a style defined by |afterthought/.style={tikz+={#1}}|: afterthoughts are
2706 interpreted as (cumulative) \TikZ; code. If you'd like to use afterthoughts for some other
2707 purpose, redefine this style --- this will take effect even if you do it in the tree preamble.
2708
2709 \indexitem{node key>also}|=|\meta{keylist} Execute the keys in the given \meta{keylist}.
2710
2711 If we are currently processing node keys, \meta{keylist} should contain node keys. If we are
2712 in a nodewalk, \meta{keylist} should (or rather, may also) contain nodewalk keys.
2713
2714 For example, to execute, during a nodewalk, a nodewalk keylist stored in register |tempkeylista|,
2715 write |also/.register=|\indexex{tempkeylista}. Note that no embedded nodewalk will be introduced.
2716
2717 \indexitem{node key>autoforward}|=|\meta{option}\meta{keylist}, \indexdef{node key>autoforward register}|=|\meta{register}\meta{keylist}
2718 \itemnosep
2719 \indexitem{node key>autoforward'}|=|\meta{option}\meta{keylist}, \indexdef{node key>autoforward register'}|=|\meta{register}\meta{keylist}
2720
2721 Whenever the value of an autoforwarded option or register is given or changed (via an augmented
2722 assignment), \meta{option}|=|\meta{new value} or \meta{register}|=|\meta{new value} is appended to
2723 \meta{keylist}. This can be used to ``intercept and remember'' \TikZ; options, like \index{option>anchor}
2724 and \index{rotate}.
2725
2726 The |autoforward'| variant keeps only a single instance of \meta{option} in \meta{keylist}.
2727
2728 If you ever need to use the non-forwarded version of the key, prefix it with word |autoforwarded|,
2729 e.g.\ |autoforwarded_rotate|. Autoforwarding is limited to the current \TeX\ group.
2730
2731 \indexitem{node key>Autoforward}|=|\meta{option}\meta{style definition}, \indexdef{node key>Autoforward register}|=|\meta{register}\meta{style definition}
2732
2733 This is a more generic variant of autoforwarding. After the value of an option or register
2734 autoforwarded with this key is changed, the style defined by \meta{style definition} is called with
2735 the new option/register value as its argument.
2736
2737 \begin{forestexample}[index={Autoforward,content,node options}]
2738 \forestset{~Autoforward~={content}{node options={#1}}}
2739 \begin{forest}
2740 [red[blue][green]]
2741 \end{forest}
2742 \end{forestexample}
2743
2744 \indexitem{node key>unautoforward}|=|\meta{option or register} Undoes the autoforwarding of the
2745 option or register made by any of the autoforwarding keys.
2746
2747 \indexitem{node key>content to}|=|\meta{key} When parsing the bracket representation of the tree,
2748 store the given content using \meta{key}|=|\meta{content}.
2749
2750 \indexitem{node key>copy command key}|=|\meta{pgfkey: source}\meta{pgfkey: destination}
2751
2752 Copies the |pgf| key in a way that |.add code| and |.add style| handlers still work.
2753
2754 \indexitem({{{{{}}}}}){register>default preamble}|=|\meta{keylist}
2755 \itemnosep
2756 \indexitem{register>preamble}|=|\meta{keylist}
2757
2758 These registers hold the content of the default preamble and the preamble of the current tree.
2759
2760 |preamble| is set by the bracket parser. Set |default preamble| outside the \index{forest}
2761 environment using \index{forestset}.
2762
2763 As |default preamble| and |preamble| are not styles but keylist registers, the |#| characters do
2764 not need to be doubled: you can freely copy and paste your keylists between the node options of
2765 the root node, the preamble and the default preamble. The only difference will be the order of
2766 execution: first default preamble, then preamble, and finally the root node's options.
2767
2768 \indexitem{node key>save and restore register}|=|\meta{register}\meta{keylist}
2769
2770 Restores the current value of \meta{register} after executing the \meta{keylist}.
2771
2772 \indexitem{node key>split}|=|\meta{toks}\meta{separator}\meta{keylist}
2773 \itemnosep
2774 \indexitem{node key>split option}|=|\meta{option}\meta{separator}\meta{keylist}
2775 \itemnosep
2776 \indexitem{node key>split register}|=|\meta{register}\meta{separator}\meta{keylist}
2777
2778 Split \meta{toks} or the value of \meta{option} or \meta{register} at occurrences of
2779 \meta{separator} (which must be a single token), and process the keys in \meta{keylist} with the
2780 pieces of the split token list as arguments, in the order given.
2781
2782 \meta{option} can be either a simple \meta{option name} or a \meta{relative node name}\texttt{.}\meta{option name}.
2783
2784 The difference in the number of split values and given keys is handled gracefully. If there is
2785 not enough values, the superfluous keys are not processed; if there are too many values, the last
2786 key is called repeatedly.
2787
2788 The keys in \meta{keylist} can be any valid keys, including augmented assignments, non-current
2789 option assignments, even \index{TeX} or user-defined styles. Actually, as |split| works by simply
2790 appending |={|\meta{current value}|}| to the relevant given key, it is possible for the key to be
2791 a (sub)keylist ending in a simple, non-valued key, like shown below.
2792
2793 \begin{advise}
2794 \item Pay attention to |%| characters around the subkeylist. In order for it to actually function
2795 as a sublist, its braces should be stripped, but this can only happen if no spaces surround it.
2796 \end{advise}
2797
2798 \begin{forestexample}[point=split option,index={delay,content,split option,process args},label=ex:split option]
2799 \begin{forest}
2800 [
2801 {1,2,3,4}
2802 [,delay={
2803 ~split option~=
2804 {!parent.content}
2805 {,}
2806 {
2807 content',%
2808 {content+={+},content+}%
2809 },
2810 tempcounta'/.process={O+n}{content},
2811 content+={=},
2812 content+/.register=tempcounta,
2813 }
2814 ]
2815 ]
2816 \end{forest}
2817 \end{forestexample}
2818
2819 \indexitem{node key>TeX}|=|\meta{toks: \TeX\ code} The given code is executed immediately.
2820
2821 This can be used for e.g.\ enumerating nodes:
2822 \begin{forestexample}[point=TeX,index={TeX,delay,where option,tier,content,GP1},label=ex:enumerate]
2823 \newcount\xcount
2824 \begin{forest} GP1,
2825 delay={TeX={\xcount=0},
2826 where tier={x}{TeX={\advance\xcount1},
2827 content/.expanded={##1$_{\the\xcount}$}}{}}
2828 [
2829 [O[x[f]]]
2830 [R[N[x[o]]]]
2831 [O[x[r]]]
2832 [R[N[x[e]]][x[s]]]
2833 [O[x[t]]]
2834 [R[N[x]]]
2835 ]
2836 \end{forest}
2837 \end{forestexample}
2838
2839 \indexitem{node key>TeX'}|=|\meta{toks: \TeX\ code} This key is a combination of keys \index{TeX}
2840 and \index{TeX''}: the given code is both executed and externalized.
2841
2842 \indexitem{node key>TeX''}|=|\meta{toks: \TeX\ code} The given code is externalized, i.e.\ it will be
2843 executed when the externalized images are loaded.
2844
2845 The image-loading and \keyname{TeX'(')} produced code are intertwined.
2846
2847 \indexitem{node key>typeout}|=|\meta{toks} A \foRest; version of \LaTeX\ macro |\typeout|. Useful
2848 for debugging, trust me on this one.
2849
2850 \indexitem(node options){node key>unknown to}|=|\meta{key} Forward unknown keys to \meta{key}.
2851
2852 \begin{advise}
2853 \item Do \emph{not} use handler |.unknown| to deal with unknown keys, as it is used internally by
2854 \foRest;, and is set up to make it possible to set options of non-current nodes (see
2855 \S\ref{sec:option-setting}).
2856 \end{advise}
2857
2858 \indexitem{node key>unknown key error}|=|\meta{keyval} Produces an error.
2859
2860 Write \index{unknown to}|=unknown key error| to produce an error when a key unknown to \foRest; is
2861 used.
2862
2863 \end{syntax}
2864
2865
2866
2867 \subsection{Options and registers}
2868 \label{sec:options-and-registers}
2869
2870 \FoRest; introduces two types of data storage: \emph{node options} (or just \emph{options} for
2871 short) and \emph{registers}.
2872
2873 Options store data related to particular nodes. Each node has its own set of option values, i.e.\
2874 the value of an option at some node is independent of its value at other nodes: in particular,
2875 setting an option of a node does \emph{not} set this option for the node's descendants. Register
2876 values are not associated to nodes.
2877
2878 Note that option and register keys share the same ``namespace'' (|pgfkeys| path and |pgfmath|
2879 function names) so it is not possible to have an option and a register of the same name!
2880
2881 \subsubsection{Setting}
2882 \label{sec:option-setting}
2883
2884 The simplest way to set the value of an option or a register is to use the key of the same name.
2885 \begin{syntax}
2886 \indexitem[index key={@@@opt},form={}]{prefix>assignment>current node=\meta{option}}|=|\meta{value}
2887 Sets the value of \meta{option} of the current node to \meta{value}.
2888
2889 Note that option types \index{keylist} and \index{autowrapped toks} redefine this basic key.
2890
2891 \indexitem[index key={@@@reg},form={}]{prefix>assignment>current node=\meta{register}}|=|\meta{value}
2892 Sets the value of \meta{register} to \meta{value}.
2893
2894 Note that register types \index{keylist} and \index{autowrapped toks} redefine this basic key.
2895 \end{syntax}
2896
2897 Options can also be set for the non-current node:
2898 \begin{syntax}
2899 % \indexitem[index key={@@@.},form={.},+print format={+result={\index(not print){relative node name}\index(not index)[+print format=definition]{relative node name}}},+index format={+result={\meta{relative node name}}}]{prefix>assignment>relative node=\meta{option}}|=|\meta{value}
2900 \indexitem[index key={@@@.},form={.},+print format={+result={\index{relative node name}}},+index format={+result={\meta{relative node name}}}]{prefix>assignment>relative node=\meta{option}}|=|\meta{value}
2901
2902 Sets the value of \meta{option} of the node specified by \meta{relative node name} to \meta{value}.
2903
2904 Notes: \begin{enumerate*}[(i)]
2905 \item\emph{\meta{value} is evaluated in the context of the current node.}
2906 \item In general, the resolution of \meta{relative node name} depends on the
2907 current node; see \S\ref{ref:relative-node-names}.
2908 \item \meta{option} can also be an ``augmented assignment operator'' (see below) or, indeed, any
2909 node key.
2910 \end{enumerate*}
2911 \end{syntax}
2912
2913 Additional keys for setting and modifying the value of an option or a register exist, depending on
2914 its data type. Informally, you can think of these keys as \emph{augmented operators} known from
2915 various programming languages.
2916
2917 \begin{syntax}
2918 \indexitem{type>toks} contains \TeX's \meta{balanced text} \citep[275]{texbook}.
2919
2920 A toks \meta{option} additionally defines the following keys:
2921 \begin{syntax}
2922 \indexitem{suffix>augmented assignment=toks>+=\meta{option}}|=|\meta{toks} appends the given \meta{toks} to the
2923 current value of the option.
2924
2925 \indexitem{prefix>augmented assignment=toks>+=\meta{option}}|=|\meta{toks} prepends the given \meta{toks} to the
2926 current value of the option.
2927
2928 % \item \index{if in toks option=\meta{toks option}}| =|\meta{toks}\meta{true
2929 % keylist}\meta{false keylist} checks if \meta{toks} occurs in the option value; if it does,
2930 % \meta{true keylist} are executed, otherwise \meta{false keylist}.
2931
2932 % \item \index{where in toks option=\meta{toks option}}| =|\meta{toks}\meta{true
2933 % keylist}\meta{false keylist} is a style equivalent to \index{for step=\index{tree}}|={|\keyname{if in }\meta{option}=\meta{toks}\meta{true keylist}\meta{false keylist}|}|: for every node in
2934 % the subtree rooted in the current node, \keyname{if in }\meta{option} is executed in
2935 % the context of that node.
2936 \end{syntax}
2937
2938 \indexitem{type>autowrapped toks} is a subtype of \index{toks} and contains \TeX's \meta{balanced
2939 text} \citep[275]{texbook}.
2940
2941 {\rstyle\meta{option}}|=|\meta{toks} of an autowrapped \meta{option} is redefined to
2942 \meta{option}|/|\index{wrap value}|=|\meta{toks} of a normal \meta{toks} option.
2943
2944 Keyvals \indexdef{suffix>augmented assignment=autowrapped toks>+=\meta{option}}|=|\meta{toks} and
2945 \indexdef{prefix>augmented assignment=autowrapped toks>+=\meta{option}}|=|\meta{toks} are redefined to
2946 \index{toks+=\meta{option}}|/|\index{wrap value}|=|\meta{toks} and
2947 \index{+toks=\meta{option}}|/|\index{wrap value}|=|\meta{toks}, respectively. The normal toks
2948 behaviour can be accessed via keys \indexdef{suffix>augmented assignment=autowrapped toks>'=\meta{option}},
2949 \indexdef{suffix>augmented assignment=autowrapped toks>+'=\meta{option}}, and
2950 \indexdef[set={print format={result/.expanded=+\forestoption{argument}',pgfkey},index form=+\meta{autowrapped toks option}',index format=pgfkey,index key=+'}]{augmented assignment>+autowrapped toks'=\meta{option}}.
2951
2952 \indexitem{type>keylist} is a subtype of \index{toks} and contains a comma-separated list of
2953 \meta{key}[|=|\meta{value}] pairs.
2954
2955 Augmented assignment operators \indexdef{suffix>augmented assignment=keylist>+=\meta{option}} and
2956 \indexdef{prefix>augmented assignment=keylist>+=\meta{option}} automatically insert a comma
2957 before/after the appended/prepended material.
2958
2959 Augmented assignment operator \indexdef{suffix>augmented assignment=keylist>-=\meta{option}}|=|\meta{keylist} deletes the keys
2960 from keylist \meta{option}. \meta{keylist} specifies which keys to delete. If a key is given no
2961 value, all occurrences of that key will be deleted. If a key is given a value, only occurrences
2962 with that value will be deleted. To delete occurrences without value, use special value
2963 \indexdef{macro>forestnovalue}. (Note: if you include a key in \meta{keylist} more than once,
2964 only the last occurrence counts.)
2965
2966 {\rstyle\meta{option}}|=|\meta{keylist} of a keylist option is redefined to
2967 \meta{option}\keyname{+}|=|\meta{keylist}. In other words, keylists behave additively by
2968 default. The rationale is that one usually wants to add keys to a keylist. The usual,
2969 non-additive behaviour can be accessed by \indexdef{suffix>augmented assignment=keylist>'=\meta{option}}|=|\meta{keylist}.
2970
2971 Manipulating the keylist option using augmented assignments might have the side-effect of adding
2972 an empty key to the list.
2973
2974 \indexitem{type>dimen} contains a dimension.
2975
2976 The value given to a dimension option is automatically evaluated by |pgfmath|. In other words,
2977 {\rstyle\meta{option}}|=|\meta{value} is implicitly understood as
2978 \meta{option}|/|\index{pgfmath}|=|\meta{value}.
2979
2980 For a \meta{dimen} option \meta{option}, the following additional keys (``augmented
2981 assignments'') are defined:
2982 \begin{syntax}
2983 \indexitem{suffix>augmented assignment=dimen>+=\meta{option}}|=|\meta{value} is equivalent to \meta{option}|=|\meta{option}|()+|\meta{value}
2984 \indexitem{suffix>augmented assignment=dimen>-=\meta{option}}|=|\meta{value} is equivalent to \meta{option}|=|\meta{option}|()-|\meta{value}
2985 \indexitem{suffix>augmented assignment=dimen>*=\meta{option}}|=|\meta{value} is equivalent to \meta{option}|=|\meta{option}|()*|\meta{value}
2986 \indexitem{suffix>augmented assignment=dimen>:=\meta{option}}|=|\meta{value} is equivalent to \meta{option}|=|\meta{option}|()/|\meta{value}
2987 \end{syntax}
2988
2989 The evaluation of \meta{pgfmath} can be quite slow. There are two tricks to speed things up
2990 \emph{if} the \meta{pgfmath} expression is simple, i.e.\ just a \TeX\ \meta{dimen}:
2991 \begin{enumerate}
2992 \item |pgfmath| evaluation of simple values can be sped up by prepending |+| to the value
2993 \citep[\S62.1]{tikzpgf2.10};
2994 \item use the key \indexdef{suffix>augmented assignment=dimen>'=\meta{option}}|=|\meta{value} to invoke a normal \TeX\ assignment.
2995 \end{enumerate}
2996
2997 The two above-mentioned speed-up tricks work for the augmented assignments as well. The keys for
2998 the second, \TeX-only trick are: \indexdef{suffix>augmented assignment=dimen>'+}, \indexdef{suffix>augmented assignment=dimen>'-}, \indexdef{suffix>augmented assignment=dimen>'*}, \indexdef{suffix>augmented assignment=dimen>':} --- note that for the latter two,
2999 the value should be an integer.
3000
3001 \indexitem{type>count} contains an integer.
3002
3003 The additional keys and their behaviour are the same as for the \meta{dimen} options.%
3004 \indexdef[not print]{suffix>augmented assignment=count>+}%
3005 \indexdef[not print]{suffix>augmented assignment=count>-}%
3006 \indexdef[not print]{suffix>augmented assignment=count>*}%
3007 \indexdef[not print]{suffix>augmented assignment=count>:}%
3008 \indexdef[not print]{suffix>augmented assignment=count>'}%
3009 \indexdef[not print]{suffix>augmented assignment=count>'+}%
3010 \indexdef[not print]{suffix>augmented assignment=count>'-}%
3011 \indexdef[not print]{suffix>augmented assignment=count>'*}%
3012 \indexdef[not print]{suffix>augmented assignment=count>':}%
3013
3014 \indexitem{type>boolean} contains $0$ (false) or $1$ (true).
3015
3016 In the general case, the value given to a \meta{boolean} option is automatically
3017 parsed by |pgfmath| (just as for \meta{count} and \meta{dimen}): if the computed value is
3018 non-zero, $1$ is stored; otherwise, $0$ is stored. Note that |pgfmath| recognizes constants
3019 |true| and |false|, so it is possible to write \meta{option}|=true| and
3020 \meta{option}|=false|.
3021
3022 If key \meta{option} is given no argument, pgfmath evaluation does not apply and a true value is
3023 set. To quickly set a false value, use key \indexdef{word prefix=boolean option>>not=\meta{option}} (with no arguments).
3024 \end{syntax}
3025
3026 \subsubsection{Reading}
3027 \label{sec:option-reading}
3028
3029 Option and register values can be accessed using the four macros listed below, handlers
3030 \index{handler>option} and \index{handler>register} (\S\ref{ref:handlers}) and |pgfmath| functions
3031 (\ref{ref:pgfmath}).
3032
3033 \begin{syntax}
3034 \indexitem{macro>forestoption}|{|\meta{option}|}|
3035 \itemnosep
3036 \indexitem{macro>foresteoption}|{|\meta{option}|}|
3037 \itemnosep
3038 \indexitem{macro>forestregister}|{|\meta{register}|}|
3039 \itemnosep
3040 \indexitem{macro>foresteregister}|{|\meta{register}|}|
3041
3042 These macros expand to the value of the given option or register. Note that
3043 \index{macro>forestoption} and \index{macro>foresteoption} expand to the value of the given option
3044 of the \emph{current node}; to access option values of a non-current node, use |pgfmath|
3045 functions.
3046
3047 In the context of |\edef|, \cmdname{forestoption} and \cmdname{forestregister} expand precisely to
3048 the token list of the option value, while \cmdname{foresteoption} and \cmdname{foresteregister}
3049 fully expand the value.
3050
3051 \begin{advise}
3052 \item These macros can be useful in \TeX\ code introduced by \index{TeX} or \PGF;'s handler
3053 |.expanded| \citep[\S55.4.6]{tikzpgf2.10}.
3054 \end{advise}
3055 \end{syntax}
3056
3057
3058 \subsubsection{Declaring}
3059 \label{sec:option-declaring}
3060
3061 Using the following keys, users can also declare their own options and registers. The new options
3062 and registers will behave exactly like the predefined ones.
3063
3064 Note that the declaration of an option must provide a default value, while the declaration of a
3065 register must not do that (registers are initialized to the empty string, |0pt| or |0|, as
3066 appropriate for the type). The default value of an option will be assigned to any newly created
3067 nodes; the existing nodes are not affected.
3068
3069 \begin{syntax}
3070 \indexitem{node key>declare toks}|=|\meta{option name}\meta{default value}
3071 Declares a \meta{toks} option.
3072
3073 \indexitem{node key>declare autowrapped toks}|=|\meta{option name}\meta{default value}
3074 Declares an \meta{autowrapped toks} option.
3075
3076 \indexitem{node key>declare keylist}|=|\meta{option name}\meta{default value}
3077 Declares a \meta{keylist} option.
3078
3079 \indexitem{node key>declare dimen}|=|\meta{option name}\meta{default value}
3080 Declares a \meta{dimen} option. The default value is processed by \index{forestmath}.
3081
3082 \indexitem{node key>declare count}|=|\meta{option name}\meta{default value}
3083 Declares a \meta{count} option. The default value is processed by \index{forestmath}.
3084
3085 \indexitem{node key>declare boolean}|=|\meta{option name}\meta{default value}
3086 Declares a \meta{boolean} option. The default value is processed by \index{forestmath}.
3087
3088 \indexitem{node key>declare toks register}|=|\meta{register name}
3089 Declares a \meta{toks} register.
3090
3091 \indexitem{node key>declare autowrapped toks register}|=|\meta{register name}
3092 Declares an \meta{autowrapped toks} register.
3093
3094 \indexitem{node key>declare keylist register}|=|\meta{register name}
3095 Declares a \meta{keylist} register.
3096
3097 \indexitem{node key>declare dimen register}|=|\meta{register name}
3098 Declares a \meta{dimen} register.
3099
3100 \indexitem{node key>declare count register}|=|\meta{register name}
3101 Declares a \meta{count} register.
3102
3103 \indexitem{node key>declare boolean register}|=|\meta{register name}
3104 Declares a \meta{boolean} register.
3105 \end{syntax}
3106
3107 Several scratch registers are predefined:
3108 \begin{syntax}
3109 \indexitem{register>temptoksa}, \indexdef{register>temptoksb}, \indexdef{register>temptoksc}, \indexdef{register>temptoksd} Predefined \meta{toks} registers.
3110
3111 \indexitem{register>tempkeylista}, \indexdef{register>tempkeylistb}, \indexdef{register>tempkeylistc}, \indexdef{register>tempkeylistd} Predefined \meta{keylist} registers.
3112
3113 \indexitem{register>tempdima}, \indexdef{register>tempdimb}, \indexdef{register>tempdimc}, \indexdef{register>tempdimd}, \indexdef{register>tempdimx}, \indexdef{register>tempdimy}, \indexdef{register>tempdiml}, \indexdef{register>tempdims}, \indexdef{register>tempdimxa}, \indexdef{register>tempdimya}, \indexdef{register>tempdimla}, \indexdef{register>tempdimsa}, \indexdef{register>tempdimxb}, \indexdef{register>tempdimyb}, \indexdef{register>tempdimlb}, \indexdef{register>tempdimsb} Predefined \meta{dimen} registers.
3114
3115 \indexitem{register>tempcounta}, \indexdef{register>tempcountb}, \indexdef{register>tempcountc}, \indexdef{register>tempcountd} Predefined \meta{count} registers.
3116
3117 \indexitem{register>tempboola}, \indexdef{register>tempboolb}, \indexdef{register>tempboolc}, \indexdef{register>tempboold} Predefined \meta{boolean} registers.
3118 \end{syntax}
3119
3120
3121
3122 \subsection{Formatting the tree}
3123 \label{sec:formatting-tree}
3124
3125
3126 \subsubsection{Node appearance}
3127 \label{ref:node-appearance}
3128
3129 The following options apply at stage \index{typeset nodes}. Changing them
3130 afterwards has no effect in the normal course of events.
3131
3132 \begin{syntax}
3133 \indexitem({{{{{}}}}}){option>align}|=|\index{value of=align>left}\OR\index{value of=align>center}\OR\index{value of=align>right}\OR\meta{toks: tabular header}
3134
3135 Creates a left/center/right-aligned multiline node, or a tabular node. In the
3136 \index{content} option, the lines of the node should separated by |\\| and the columns (if
3137 any) by |&|, as usual.
3138
3139 The vertical alignment of the multiline/tabular node can be specified by option \index{base}.
3140
3141 \begin{forestexample}[index={l sep,align,base}]
3142 \begin{forest} l sep+=2ex
3143 [special value&actual value\\\hline
3144 \indexdef{value of=align>left}&||\texttt{@\{\}l@\{\}}\\
3145 \indexdef{value of=align>center}&||\texttt{@\{\}c@\{\}}\\
3146 \indexdef{value of=align>right}&||\texttt{@\{\}r@\{\}}\\
3147 ,~align~=ll,draw
3148 [top base\\right aligned, ~align~=right,~base~=top]
3149 [left aligned\\bottom base, ~align~=left,~base~=bottom]
3150 ]
3151 \end{forest}
3152 \end{forestexample}
3153
3154 Internally, setting this option has two effects:
3155 \begin{enumerate}
3156 \item The option value (a |tabular| environment header specification) is set. The special
3157 values \keyname{left}, \keyname{center} and \keyname{right} invoke styles setting the actual
3158 header to the value shown in the above example.
3159 \begin{advise}
3160 \item If you know that the \keyname{align} was set with a special value, you can easily check
3161 the value using \index{if in toks option=\index{align}}.
3162 \end{advise}
3163 \item Option \index{content format} is set to the following value:
3164 \begin{lstlisting}
3165 \noexpand\begin{tabular}[\forestoption{base}]{\forestoption{align}}%
3166 \forestoption{content}%
3167 \noexpand\end{tabular}%
3168 \end{lstlisting}
3169 As you can see, it is this value that determines that options \keyname{base}, \keyname{align} and
3170 \keyname{content} specify the vertical alignment, header and content of the table.
3171 \end{enumerate}
3172
3173 \indexitem(t){option>base}|=|\meta{toks: vertical alignment}
3174
3175 This option controls the vertical alignment of multiline (and in general, \texttt{tabular}) nodes
3176 created with \index{align}. Its value becomes the optional argument to the \texttt{tabular}
3177 environment. Thus, sensible values are \indexdef{value of=base>t} (the top line of the table will
3178 be the baseline) and \indexdef{value of=base>b} (the bottom line of the table will be the baseline).
3179 Note that this will only have effect if the node is anchored on a baseline, like in the default
3180 case of \index{option>anchor}|=base|.
3181
3182 For readability, you can use \indexdef{value of=base>top} and \indexdef{value of=base>bottom} instead
3183 of \keyname{t} and \keyname{b}. (\keyname{top} and \keyname{bottom} are still stored as
3184 \keyname{t} and \keyname{b}.)
3185
3186 \indexitem({{{{{}}}}}){option>content}|=|\meta{autowrapped toks} The content of the node.
3187
3188 Normally, the value of option \keyname{content} is given implicitely by virtue of the special
3189 (initial) position of content in the bracket representation (see~\S\ref{ref:bracket}). However,
3190 the option also be set explicitely, as any other option.
3191
3192 \begin{forestexample}[index={for step,tree,if option,readonly option>n,readonly option>n'},point={content,delay},index={content,delay}]
3193 \begin{forest}
3194 delay={for tree={
3195 if n=1{content=L}
3196 {if n'=1{content=R}
3197 {content=C}}}}
3198 [[[][][]][[][][]]]
3199 \end{forest}
3200 \end{forestexample}
3201 Note that the execution of the \keyname{content} option should usually be delayed: otherwise, the
3202 implicitely given content (in the example below, the empty string) will override the explicitely
3203 given content.
3204
3205 \begin{forestexample}[index={for step,tree,if option,readonly option>n,readonly option>n',content},point={content}]
3206 \begin{forest}
3207 for tree={
3208 if n=1{content=L}
3209 {if n'=1{content=R}
3210 {content=C}}}
3211 [[[][][]][[][][]]]
3212 \end{forest}
3213 \end{forestexample}
3214
3215 \indexitem(\forestoption{content}){option>content format}|=|\meta{toks}
3216
3217 When typesetting the node under the default conditions (see option \index{node format}), the
3218 value of this option is passed to the \TikZ; \texttt{node} operation as its \meta{text} argument
3219 \citep[\S16.2]{tikzpgf2.10}. The default value of the option simply puts the content in the
3220 node.
3221
3222 This is a fairly low level option, but sometimes you might still want to change its value. If
3223 you do so, take care of what is expanded when. Most importantly, if you use a formatting
3224 command such as |\textbf| in the default setting of \index{node format}, be sure to precede
3225 it with |\noexpand|. For details, read the documentation of option \index{node format} and
3226 macros \index{forestoption} and \index{foresteoption}; for an example, see option
3227 \index{align}.
3228
3229 \indexitem{node key>math content} Changes \index{content format} so that the content of the node
3230 will be typeset in a math environment.
3231
3232 \indexitem{node key>plain content} Resets \index{content format} to the default value.
3233
3234 \indexitem{option>node format}|=|\meta{toks}
3235 \hfill|\noexpand\node(\forestoption{name})|\\
3236 \mbox{}\hfill|[\forestoption{node options}]{\foresteoption{content format}};|
3237
3238 The node is typeset by executing the expansion of this option's value in a |tikzpicture|
3239 environment.
3240
3241 Important: the value of this option is first expanded using |\edef| and only then executed. Note
3242 that in its default value, \index{content format} is fully expanded using
3243 \index{foresteoption}: this is necessary for complex content formats, such as |tabular|
3244 environments.
3245
3246 This is a low level option. Ideally, there should be no need to change its value. If you do,
3247 note that the \TikZ; node you create should be named using the value of option \index{option>name};
3248 otherwise, parent--child edges can't be drawn, see option \index{edge path}.
3249
3250 \indexitem{node key>node format'}|=|\meta{toks}
3251
3252 Sets \index{node format}, automatically wrapping the given \meta{toks} by
3253 |\noexpand\node(\forestoption{name})| and |;|. Only the node options and content must therefore be
3254 given.
3255
3256 \indexitem(anchor=base){option>node options}|=|\meta{keylist}
3257
3258 When the node is being typeset under the default conditions (see option \index{node format}),
3259 the content of this option is passed to \TikZ; as options to the
3260 \TikZ; |node| operation \citep[\S16]{tikzpgf2.10}.
3261
3262 This option is rarely manipulated manually: almost all options unknown to \foRest; are
3263 automatically appended to \keyname{node options}. Exceptions are (i) \index{label} and
3264 \index{pin}, which require special attention in order to work; and (ii) \index{option>anchor},
3265 which is saved in order to retain the information about the selected anchor.
3266
3267 \begin{forestexample}[index={for step,descendants,option>anchor,option>child anchor,option>parent anchor,grow,l sep,tree,propagator>where,delay,content,node options,pgfmath}]
3268 \begin{forest}
3269 for descendants={anchor=east,child anchor=east},
3270 grow=west,anchor=north,parent anchor=north,
3271 l sep=1cm,
3272 for tree={~fill=yellow~},where={n()<=3}{~draw=red~}{},
3273 delay={for tree={content/.pgfmath=~node_options~}}
3274 [root,rotate=90,
3275 [,~fill=white~]
3276 [,~node options'~]
3277 []
3278 []
3279 [,~node options~={~ellipse~}]
3280 ]
3281 \end{forest}
3282 \end{forestexample}
3283
3284 \indexitem(false){option>phantom}|=|\meta{boolean}
3285
3286 A phantom node and its surrounding edges are taken into account when packing, but not
3287 drawn. (This option applies in stage \index{draw tree}.)
3288 \begin{forestexample}[point=phantom,index={option>phantom}]
3289 \begin{forest}
3290 [VP[DP][V',phantom[V][DP]]]
3291 \end{forest}
3292 \end{forestexample}
3293
3294 \end{syntax}
3295
3296
3297
3298 \subsubsection{Node position}
3299 \label{ref:ref-node-position}
3300
3301 Most of the following options apply at stage \index{pack}. Changing them afterwards has no effect
3302 in the normal course of events. (Options \index{option>l}, \index{option>s}, \index{option>x}, \index{y} and
3303 \index{option>anchor} are exceptions; see their documentation for details).
3304
3305 \begin{syntax}
3306
3307 \indexitem(base){option>anchor}|=|\meta{toks: \foRest; anchor}
3308
3309 While this option is saved by \foRest;, it is essentially an option of \TikZ;'s |\node| command
3310 \citep[see][\S16.5.1]{tikzpgf2.10}. \FoRest; \index{autoforward}s it to keylist option
3311 \index{node options}, which is passed on to \TikZ;'s |\node| command when the node is typeset.
3312 (Option |anchor| thus normally applies in stage \index{typeset nodes}.)
3313
3314 In the \TikZ; code, you can refer to the node's anchor using \FoRest;'s anchor
3315 \index{anchor>anchor}; this anchor is sometimes also called the node anchor in this
3316 documentation, to distinguish it clearly from parent and child anchors.
3317
3318 \meta{toks: \foRest; anchor} can be any \TikZ; anchor. Additionally, \FoRest; defines several
3319 tree hierarchy related anchors; for details, see \S\ref{sec:anchors}.
3320
3321 The effect of setting the node anchor is twofold:
3322 \begin{itemize}
3323 \item during packing, the anchors of all siblings are \index{option>l}-aligned;
3324 \item some \index{calign} methods use node anchors (of the parent and/or certain children) to
3325 \index{option>s}-align the block of children to the parent.
3326 \end{itemize}
3327
3328 \indexitem(center){option>calign}|=|\alternative{child,child edge,midpoint,edge midpoint,fixed
3329 angles,fixed edge angles}\\\alternative{first,last,center}.
3330
3331 The packing algorithm positions the children so that they don't overlap, effectively computing
3332 the minimal distances between the node anchors of the children. This option (\keyname{calign}
3333 stands for child alignment) specifies how the children are positioned
3334 with respect to the parent (while respecting the above-mentioned minimal distances).
3335
3336 The child alignment methods refer to the primary and the secondary child, and to the primary and
3337 the secondary angle. These are set using the keys described just after \keyname{calign}.
3338
3339 \let\outerleftmargin\leftmargin
3340 \begin{syntax}
3341 \item\keyname{calign}|=|\indexdef{value of=calign>child} s-aligns the node anchors of the parent and
3342 the primary child.
3343 \item\keyname{calign}|=|\indexdef{value of=calign>child edge} s-aligns the parent anchor of the parent
3344 and the child anchor of the primary child.
3345 \item \keyname{calign}|=|\indexdef{value of=calign>first} is an abbreviation for
3346 |calign=child,calign_child=1|.
3347 \item \keyname{calign}|=|\indexdef{value of=calign>last} is an abbreviation for
3348 |calign=child,calign_child=-1|.
3349 \item\keyname{calign}|=|\indexdef{value of=calign>midpoint} s-aligns the parent's node anchor and the
3350 midpoint between the primary and the secondary child's node anchor.
3351 \item\keyname{calign}|=|\indexdef{value of=calign>edge midpoint} s-aligns the parent's parent anchor
3352 and the midpoint between the primary and the secondary child's child anchor.
3353 \item \keyname{calign}|=|\indexdef{value of=calign>center} is an abbreviation for\\
3354 |calign=midpoint,| |calign_primary_child=1,| |calign_secondary_child=-1|.
3355 \begin{forestexample}
3356 \begin{forest}
3357 [center,calign=center[1]
3358 [first,calign=first[A][B][C]][3][4][5][6]
3359 [last,calign=last[A][B][C]][8]]
3360 \end{forest}
3361 \end{forestexample}
3362 \item\keyname{calign}|=|\indexdef{value of=calign>fixed angles}: The angle between the direction of
3363 growth at the current node (specified by option \index{grow}) and the line through the node
3364 anchors of the parent and the primary/secondary child will equal the primary/secondary angle.
3365
3366 To achieve this, the block of children might be spread or further distanced from the parent.
3367 \item\keyname{calign}|=|\indexdef{value of=calign>fixed edge angles}: The angle between the direction of
3368 growth at the current node (specified by option \index{grow}) and the line through the
3369 parent's parent anchor and the primary/secondary child's child anchor will equal the
3370 primary/secondary angle.
3371
3372 To achieve this, the block of children might be spread or further distanced from the parent.
3373 \begin{forestexample}[point=calign,index={calign,fixed edge angles,calign primary angle,calign secondary angle,for step,tree,option>l},index>={!}]
3374 \begin{forest}
3375 calign=fixed edge angles,
3376 calign primary angle=-30,calign secondary angle=60,
3377 for tree={l=2cm}
3378 [CP[C][TP]]
3379 \draw[dotted] (!1) -| coordinate(p) () (!2) -| ();
3380 \path ()--(p) node[pos=0.4,left,inner sep=1pt]{-30};
3381 \path ()--(p) node[pos=0.1,right,inner sep=1pt]{60};
3382 \end{forest}
3383 \end{forestexample}
3384 \end{syntax}
3385 \indexitem{node key>calign child}|=|\meta{count} is an abbreviation for \index{calign primary
3386 child}|=|\meta{count}.
3387 \indexitem(1){option>calign primary child}|=|\meta{count} Sets the primary child.
3388 (See \index{calign}.)
3389
3390 \meta{count} is the child's sequence number. Negative numbers start counting at the last child.
3391 \indexitem(-1){option>calign secondary child}|=|\meta{count} Sets the secondary child.
3392 (See \index{calign}.)
3393
3394 \meta{count} is the child's sequence number. Negative numbers start counting at the last child.
3395 \indexitem{node key>calign angle}|=|\meta{count} is an abbreviation for: \index{calign primary
3396 angle}|=-|\meta{count}, \index{calign secondary angle}|=|\meta{count}.
3397 \indexitem(-35){option>calign primary angle}|=|\meta{count} Sets the primary angle.
3398 (See \index{calign}.)
3399 \indexitem(35){option>calign secondary angle}|=|\meta{count} Sets the secondary angle.
3400 (See \index{calign}.)
3401 \indexitem{node key>calign with current} s-aligns the node anchors of the current node and its
3402 parent. This key is an abbreviation for:\indexex[not print]{wrap pgfmath arg,calign,child,calign primary child}
3403 \begin{lstlisting}
3404 for parent/.wrap pgfmath arg={calign=child,calign primary child=##1}{n}.
3405 \end{lstlisting}
3406 \indexitem{node key>calign with current edge} s-aligns the child anchor of the current node and the
3407 parent anchor of its parent. This key is an abbreviation for:\indexex[not print]{wrap pgfmath arg,calign,child edge,calign primary child}
3408 \begin{lstlisting}
3409 for parent/.wrap pgfmath arg={calign=child edge,calign primary child=##1}{n}
3410 \end{lstlisting}
3411
3412 \indexitem(tight){option>fit}|=|\alternative{tight,rectangle,band}
3413
3414 \begin{forestexample}[layout=export,basicstyle=\footnotesize\ttfamily]
3415 \makeatletter\tikzset{use path/.code={\tikz@addmode{\pgfsyssoftpath@setcurrentpath#1}
3416 \appto\tikz@preactions{\let\tikz@actions@path#1}}}\makeatother
3417 \forestset{show boundary/.style={
3418 before drawing tree={get min s tree boundary=\minboundary, get max s tree boundary=\maxboundary},
3419 tikz+={\draw[red,use path=\minboundary]; \draw[red,use path=\maxboundary];}}}
3420 \end{forestexample}
3421 \input{\jobname.tmp}
3422
3423 This option sets the type of the (s-)boundary that will be computed for the subtree rooted in the
3424 node, thereby determining how it will be packed into the subtree rooted in the node's parent.
3425 There are three choices:\footnote{Below is the definition of style \keyname{show boundary}. The
3426 \keyname{use path} trick is adjusted from \TeX\ Stackexchange question
3427 \href{http://tex.stackexchange.com/questions/26382/calling-a-previously-named-path-in-tikz}{Calling
3428 a previously named path in tikz}.
3429
3430 \box\codebox}
3431 \begin{itemize}
3432 \item\keyname{fit}|=|\indexdef{value of=fit>tight}: an exact boundary of the node's subtree is computed,
3433 resulting in a compactly packed tree. Below, the boundary of subtree L is drawn.
3434 \begin{forestexample}[point={fit,tight},index={fit,{value of=fit>tight},delay,for step,tree,option>name,content,pgfmath}]
3435 \begin{forest}
3436 delay={for tree={name/.pgfmath=content}}
3437 [root
3438 [L,fit=tight, % default
3439 show boundary
3440 [L1][L2][L3]]
3441 [R]
3442 ]
3443 \end{forest}
3444 \end{forestexample}
3445 \makeatletter\tikzset{use path/.code={%
3446 \tikz@addmode{\pgfsyssoftpath@setcurrentpath#1}%
3447 \appto\tikz@preactions{\let\tikz@actions@path#1}%
3448 }}\makeatother
3449 \item\keyname{fit}|=|\indexdef{value of=fit>rectangle}: puts the node's subtree in a rectangle and effectively
3450 packs this rectangle; the resulting tree will usually be wider.
3451 \begin{forestexample}[point={fit,rectangle},index={fit,{value of=fit>rectangle},delay,for step,tree,option>name,content,pgfmath}]
3452 \begin{forest}
3453 delay={for tree={name/.pgfmath=content}}
3454 [root
3455 [L,fit=rectangle,
3456 show boundary
3457 [L1][L2][L3]]
3458 [R]
3459 ]
3460 \end{forest}
3461 \end{forestexample}
3462 \item\keyname{fit}|=|\indexdef{value of=fit>band}: puts the node's subtree in a rectangle of ``infinite
3463 depth'': the space under the node and its descendants will be kept clear.
3464 \begin{forestexample}[point={fit,band},index={fit,{value of=fit>band},delay,for step,tree,option>name,content,pgfmath}]
3465 \begin{forest}
3466 delay={for tree={name/.pgfmath=content}}
3467 [root
3468 [L[L1][L2][L3]]
3469 [C,fit=band]
3470 [R[R1][R2][R3]]
3471 ]
3472 \draw[thin,red]
3473 (C.south west)--(C.north west)
3474 (C.north east)--(C.south east);
3475 \draw[thin,red,dotted]
3476 (C.south west)--+(0,-1)
3477 (C.south east)--+(0,-1);
3478 \end{forest}
3479 \end{forestexample}
3480 \end{itemize}
3481
3482 \indexitem(270){option>grow}|=|\meta{count}, \indexdef{node key>grow'}|=|\meta{count},
3483 \indexdef{node key>grow''}|=|\meta{count}
3484
3485 The direction of the tree's growth at the node.
3486
3487 The growth direction is understood as in \TikZ;'s tree library \citep[\S18.5.2]{tikzpgf2.10}
3488 when using the default growth method: the (node anchor's of the) children of the node are placed
3489 on a line orthogonal to the current direction of growth. (The final result might be different,
3490 however, if \index{option>l} is changed after packing or if some child undergoes tier alignment.)
3491
3492 This option is essentially numeric (|pgfmath| function \keyname{grow} will always return an
3493 integer), but there are some twists. The growth direction can be specified either numerically
3494 or as a compass direction (|east|, |north east|, \dots). Furthermore, like in \TikZ;, setting
3495 the growth direction using key \keyname{grow} additionally sets the value of option
3496 \index{reversed} to |false|, while setting it with \keyname{grow'} sets it to |true|; to
3497 change the growth direction without influencing \index{reversed}, use key \index{grow''}.
3498
3499 Between stages \index{pack} and \index{compute xy}, the value of \keyname{grow} should not
3500 be changed.
3501
3502 \begin{forestexample}[index={delay,where in toks option,content,for step,current,grow,grow',grow'',pgfmath}]
3503 \begin{forest}
3504 delay={where in content={~grow~}{
3505 for current/.pgfmath=content,
3506 content=\texttt{#1}
3507 }{}
3508 }
3509 [{~grow~=south}
3510 [{~grow'~=west}[1][2][3]
3511 [{~grow''~=90}[1][2][3]]]
3512 [2][3][4]
3513 [{~grow~=east}[1][2][3]
3514 [{~grow''~=90}[1][2][3]]]]
3515 \end{forest}
3516 \end{forestexample}
3517
3518 \indexitem(false){option>ignore}|=|\meta{boolean}
3519
3520 If this option is set, the packing mechanism ignores the node, i.e.\ it pretends that the node has
3521 no boundary. Note: this only applies to the node, not to the tree.
3522
3523 Maybe someone will even find this option useful for some reason \dots
3524
3525 \indexitem(false){option>ignore edge}|=|\meta{boolean}
3526
3527 If this option is set, the packing mechanism ignores the edge from the node to the parent, i.e.\
3528 nodes and other edges can overlap it. (See \S\ref{sec:bugs} for some problematic situations.)
3529
3530 \begin{forestexample}[index={ignore edge,option>l,dimen*=l}]
3531 \begin{forest}
3532 [A[B[B][B][B][B]][C
3533 [\texttt{not ignore edge},l*=2]]]
3534 \end{forest}
3535 \begin{forest}
3536 [A[B[B][B][B][B]][C
3537 [\texttt{ignore edge},l*=2,~ignore edge~]]]
3538 \end{forest}
3539 \end{forestexample}
3540
3541 \indexitem{option>l}|=|\meta{dimen} The l-position of the node, in the parent's ls-coordinate system. (The
3542 origin of a node's ls-coordinate system is at its (node) anchor. The l-axis points in the
3543 direction of the tree growth at the node, which is given by option \index{grow}. The s-axis is
3544 orthogonal to the l-axis; the positive side is in the counter-clockwise direction from |l| axis.)
3545
3546 The initial value of \keyname{l} is set from the standard node. By default, it equals:
3547 \[\index{l sep}+2\cdot\mbox{\texttt{outer ysep}}+\mbox{total
3548 height(standard node)}\]
3549
3550 The value of \keyname{l} can be changed at any point, with different effects.
3551 \begin{itemize}
3552 \item The value of \keyname{l} at the beginning of stage \index{pack} determines the minimal
3553 l-distance between the anchors of the node and its parent. Thus, changing \keyname{l} before
3554 packing will influence this process. (During packing, \keyname{l} can be increased due to
3555 parent's \index{l sep}, tier alignment, or \index{calign} methods
3556 \index{fixed angles} and \index{fixed edge angles}.
3557
3558 \item Changing \keyname{l} after packing but before stage \index{compute xy} will result in a
3559 manual adjustment of the computed position. (The augmented assignment operators can be useful here.)
3560
3561 \item Changing \keyname{l} after the absolute positions have been computed has no effect in the
3562 normal course of events.
3563 \end{itemize}
3564
3565 \indexitem{option>l sep}|=|\meta{dimen} The minimal l-distance between the node and its
3566 descendants.
3567
3568 This option determines the l-distance between the \emph{boundaries} of the node and its descendants,
3569 not node anchors. The final effect is that there will be a \keyname{l sep} wide band,
3570 in the l-dimension, between the node and all its descendants.
3571
3572 The initial value of \keyname{l sep} is set from the standard node and equals
3573 \[\mbox{height}(\mbox{strut})+\mbox{\texttt{inner ysep}}\]
3574
3575 Note that despite the similar name, the semantics of \keyname{l sep} and \keyname{s sep} are
3576 quite different.
3577
3578 \indexitem(false){option>reversed}|=|\meta{boolean}
3579
3580 If |false|, the children are positioned around the node in the counter-clockwise direction; if
3581 |true|, in the clockwise direction. See also \index{grow}.
3582
3583 \indexitem(0){option>rotate}|=|\meta{count}
3584
3585 This option is saved and \index{autoforward}ed to \TikZ;'s |\node| command via \index{node options}.
3586
3587 \indexitem{option>s}|=|\meta{dimen} The s-position of the node, in the parent's ls-coordinate system.
3588 (The origin of a node's ls-coordinate system is at its (node) anchor. The l-axis points in the
3589 direction of the tree growth at the node, which is given by option \index{grow}. The s-axis is
3590 orthogonal to the l-axis; the positive side is in the counter-clockwise direction from |l| axis.)
3591
3592 The value of \keyname{s} is computed in stage \index{pack stage} and used in stage \index{compute xy
3593 stage}, so it only makes sense to (inspect and) change it in \index{before computing xy} and
3594 during packing (\index{before packing node} and \index{after packing node}). \emph{Any value given
3595 before packing is overridden, and changing the value after computing xy has no effect.}
3596
3597 For example, consider the manual correction below. By default, B is closer to A than C because
3598 packing proceeds from the first to the last child --- the position of B would be the same if there
3599 was no C. Adjusting \keyname{s} at the right moment, it is easy to center B between A and C.
3600 \begin{forestexample}[tree bin=minipage,point=s,index={before computing xy,option>s}]
3601 \begin{forest}
3602 [no manual correction of B
3603 [A[1][2][3][4]]
3604 [B]
3605 [C[1][2][3][4]]
3606 ]
3607 \end{forest}
3608
3609 \begin{forest}
3610 [manual correction of B
3611 [A[1][2][3][4]]
3612 [B,before computing xy={s/.average={s}{siblings}}]
3613 [C[1][2][3][4]]
3614 ]
3615 \end{forest}
3616 \end{forestexample}
3617
3618 \indexitem{option>s sep}|=|\meta{dimen}
3619
3620 The subtrees rooted in the node's children will be kept at least \keyname{s sep} apart in the
3621 s-dimension. Note that \keyname{s sep} is about the minimal distance between node
3622 \emph{boundaries}, not node anchors.
3623
3624 The initial value of \keyname{s sep} is set from the standard node and equals
3625 $2\cdot\mbox{\texttt{inner xsep}}$.
3626
3627 Note that despite the similar name, the semantics of \keyname{s sep} and \keyname{l sep} are
3628 quite different.
3629
3630 \indexitem({{{{{}}}}}){option>tier}|=|\meta{toks}
3631
3632 Setting this option to something non-empty ``puts a node on a tier.'' All the nodes on the same
3633 tier are aligned in the l-dimension.
3634
3635 Tier alignment across changes in growth direction is impossible. In the case of incompatible
3636 options, \foRest; will yield an error.
3637
3638 Tier alignment also does not work well with \index{calign}|=|\index{fixed angles} and \index{calign}|=|\index{fixed edge angles}, because these child alignment methods may change the
3639 l-position of the children. When this might happen, \foRest; will yield a warning.
3640
3641 \indexitem{option>x}=\meta{dimen}
3642 \vspace{-\parskip}
3643 \indexitem{option>y}=\meta{dimen}
3644
3645 \keyname{x} and \keyname{y} are the coordinates of the node in the ``normal'' (paper) coordinate
3646 system, relative to the root of the tree that is being drawn. So, essentially, they are absolute
3647 coordinates.
3648
3649 The values of \keyname{x} and \keyname{y} are computed in stage \index{compute xy}. It only
3650 makes sense to inspect and change them (for manual adjustments) afterwards (normally, in the
3651 \index{before drawing tree} hook, see \S\ref{ref:stages}.) \keyname{x} and \keyname{y} of the
3652 (formal) root node are exceptions, as they are not changed in stage \index{compute xy}.
3653 \begin{forestexample}[label=ex:adjustxy,index={y,dimen-,grow',option>l,for step,tree,before drawing tree}]
3654 \begin{forest}
3655 for tree={grow'=45,l=1.5cm}
3656 [A[B][C][D,before drawing tree={~y-~=4mm}[1][2][3][4][5]][E][F]]
3657 \end{forest}
3658 \end{forestexample}
3659
3660 \end{syntax}
3661
3662 \subsubsection{Edges}
3663 \label{ref:ref-edge}
3664
3665 These options determine the shape and position of the edge from a node to its parent. They apply
3666 at stage \index{draw tree}.
3667
3668 \begin{syntax}
3669 \indexitem({{{{{}}}}}){option>child anchor}|=|\meta{toks: \foRest; anchor} See \index{option>parent anchor}.
3670
3671 \indexitem(draw){option>edge}|=|\meta{keylist}
3672
3673 When \index{edge path} has its default value, the value of this option is passed as options to
3674 the \TikZ; |\path| expression used to draw the edge between the node and its parent.
3675
3676 Also see key \index{no edge}.
3677
3678 \begin{forestexample}[point=edge,index={edge,no edge,for step,tree,grow',option>l,option>anchor,option>child anchor}]
3679 \begin{forest} for tree={grow'=0,l=2cm,anchor=west,child anchor=west},
3680 [root
3681 [normal]
3682 [none,~no~ edge]
3683 [dotted,edge=dotted]
3684 [dashed,edge=dashed]
3685 [dashed,edge={dashed,red}]
3686 ]
3687 \end{forest}
3688 \end{forestexample}
3689
3690 \indexitem({{{{{}}}}}){option>edge label}|=|\meta{toks: \TikZ; code}
3691
3692 When \index{edge path} has its default value, the value of this option is used at the end of
3693 the edge path specification to typeset a node (or nodes) along the edge.
3694
3695 The packing mechanism is not sensitive to edge labels.
3696
3697 \begin{forestexample}[index={edge label}]
3698 \begin{forest}
3699 [VP
3700 [V,~edge label~={node[midway,left,font=\scriptsize]{head}}]
3701 [DP,~edge label~={node[midway,right,font=\scriptsize]{complement}}]
3702 ]
3703 \end{forest}
3704 \end{forestexample}
3705
3706 \indexitem{option>edge path}|=|\meta{toks: \TikZ; code}
3707 \hfill |\noexpand\path[|\index{forestoption}|{|\index{edge}|}]|\\
3708 \mbox{}\hfill |(|\index>{!}|u.|\index{anchor>parent anchor}|)--(.|\index{anchor>child anchor}|)|\index{forestoption}|{|\index{edge label}|};|
3709
3710 This option contains the code that draws the edge from the node to its parent. By default, it
3711 creates a path consisting of a single line segment between the node's \index{option>child anchor} and
3712 its parent's \index{option>parent anchor}. Options given by \index{edge} are passed to the path; by
3713 default, the path is simply drawn. Contents of \index{edge label} are used to potentially place
3714 a node (or nodes) along the edge.
3715
3716 When specifying the edge path, the values of options \index{edge} and \index{edge label} can be
3717 used. Furthermore, two anchors, \index{anchor>parent anchor} and \index{anchor>child anchor}, are defined,
3718 to facilitate access to options \index{option>parent anchor} and \index{option>child anchor} from the \TikZ; code.
3719
3720 The node positioning algorithm is sensitive to edges, i.e.\ it will avoid a node overlapping an
3721 edge or two edges overlapping. However, the positioning algorithm always behaves as if the
3722 \keyname{edge path} had the default value --- \emph{changing the \keyname{edge path} does not
3723 influence the packing!} Sorry. (Parent--child edges can be ignored, however: see option
3724 \index{ignore edge}.)
3725
3726 \indexitem{node key>edge path'}|=|\meta{toks: \TikZ; code}
3727
3728 Sets \index{edge path}, automatically wrapping the given path by
3729 |\noexpand\path[\forestoption{edge}]| and |\forestoption{edge label};|.
3730
3731 \indexitem({{{{{}}}}}){option>parent anchor}|=|\meta{toks: \foRest; anchor} (Information also applies to
3732 option \index{option>child anchor}.)
3733
3734 \FoRest; defines anchors \index{anchor>parent anchor} and
3735 \index{anchor>child anchor} (which work only for \foRest; and not also \TikZ;
3736 nodes, of course) to facilitate reference to the desired endpoints of child--parent edges.
3737 Whenever one of these anchors is invoked, it looks up the value of the \keyname{parent anchor} or
3738 \keyname{child anchor} of the node named in the coordinate specification, and forwards the request
3739 to the (\TikZ;) anchor given as the value.
3740
3741 The intended use of the two anchors is chiefly in \index{edge path} specification, but they can
3742 used in any \TikZ; code.
3743 \begin{forestexample}[index={anchor>parent anchor,anchor>child anchor,for step,tree},index>={!}]
3744 \begin{forest}
3745 for tree={~parent anchor~=south,~child anchor~=north}
3746 [VP[V][DP]]
3747 \path[fill=red] (.parent anchor) circle[radius=2pt];
3748 \path[fill=blue] (!1.child anchor) circle[radius=2pt]
3749 (!2.child anchor) circle[radius=2pt];
3750 \end{forest}
3751 \end{forestexample}
3752
3753 The empty value (which is the default) is interpreted as in \TikZ;: as an edge to the appropriate
3754 border point. See also \S\ref{sec:anchors} for a list of additional anchors defined by \foRest;.
3755
3756 \indexitem{node key>no edge} Clears the edge options (\index{edge}|'={}|) and sets \index{ignore
3757 edge}.
3758
3759 \end{syntax}
3760
3761 \subsubsection{Information about node}
3762 \label{ref:node-info}
3763 \label{ref:readonly-options}
3764
3765 The values of these options provide various information about the tree and its nodes.
3766
3767 \begin{syntax}
3768 \indexitem{node key>alias}|=|\meta{toks}
3769 \itemnosep
3770 \indexitem{node key>alias'}|=|\meta{toks} Sets the alias for the node's name.
3771
3772 Unlike \index{option>name}, \keyname{alias} is \emph{not} an option: you cannot e.g.\ query it's
3773 value via a |pgfmath| expression.
3774
3775 If the given alias clashes with an existing node name, |alias| will yield an error, while |alias'|
3776 will silently rename the node with this name to its default value (|node@|\meta{id}).
3777
3778 Aliases can be used as the \meta{forest node name} part of a relative node name and as the
3779 argument to the \index{step>name} step of a node walk. The latter includes the usage
3780 as the argument of the \index{for step=\index{step>name}} propagator.
3781
3782 Technically speaking, \foRest; alias is \emph{not} a \TikZ; alias! However, you can still use
3783 it as a ``node name'' in \TikZ; coordinates, since \foRest; hacks \TikZ;'s implicit node
3784 coordinate system to accept relative node names; see \S\ref{ref:forest-cs}.
3785
3786 \indexitem{readonly option>id}|=|\meta{count} The internal id of the node.
3787
3788 \indexitem{readonly option>level}|=|\meta{count} The hierarchical level of the node. The root is on level $0$.
3789
3790 \indexitem{readonly option>max x}|=|\meta{dimen} \vspace{-\parskip}
3791 \indexitem{readonly option>max y}|=|\meta{dimen} \vspace{-\parskip}
3792 \indexitem{readonly option>min x}|=|\meta{dimen} \vspace{-\parskip}
3793 \indexitem{readonly option>min y}|=|\meta{dimen}
3794 Measures of the node, in the shape's coordinate system
3795 \citep[see][\S16.2,\S48,\S75]{tikzpgf2.10} shifted so that the node anchor is at the origin.
3796
3797 In |pgfmath| expressions, these options are accessible as |max__x|, |max__y|, |min__x| and |min__y|.
3798
3799 \indexitem{readonly option>n}|=|\meta{count} The child's sequence number in the list of its parent's
3800 children.
3801
3802 The enumeration starts with 1. For a geometric root, \keyname{n} equals $0$.
3803
3804 \indexitem{readonly option>n'}|=|\meta{count} Like \index{readonly option>n}, but starts counting at the last child.
3805
3806 In |pgfmath| expressions, this option is accessible as |n__|.
3807
3808 \indexitem{option>name}|=|\meta{toks} \hfill \texttt{node@}\meta{id}
3809 \itemnosep
3810 \indexitem{node key>name'}|=|\meta{toks} Sets the name of the node.
3811
3812 The expansion of \meta{toks} becomes the \meta{forest node name} of the node. The \TikZ; node
3813 created from the \foRest; node will get the name specified by this option.
3814
3815 Node names must be unique. If a node with the given name already exists, |name| will yield an
3816 error, while |name'| will silently rename the node with this name to its default (|node@|\meta{id})
3817 value. Use an empty argument to reset the node's name to its default value.
3818
3819
3820 \indexitem{readonly option>n children}|=|\meta{count} The number of children of the node.
3821
3822 In |pgfmath| expressions, this option is accessible as |n__children|.
3823 \end{syntax}
3824
3825
3826 \subsubsection{Various}
3827
3828 \begin{syntax}
3829 \indexitem{node key>baseline} The node's anchor becomes the baseline of the whole tree
3830 \citep[cf.][\S69.3.1]{tikzpgf2.10}.
3831
3832 In plain language, when the tree is inserted in your (normal \TeX) text, it will be vertically
3833 aligned to the anchor of the current node.
3834
3835 Behind the scenes, this style sets the alias of the current node to \keyname{forest@baseline@node}.
3836 {\tikzexternaldisable
3837 \begin{forestexample}[index={baseline,use as bounding box'}]
3838 Baseline at the
3839 \begin{forest}
3840 [parent,~baseline~,use as bounding box'
3841 [child]]
3842 \end{forest}
3843 and baseline at the
3844 \begin{forest}
3845 [parent
3846 [child,~baseline~,use as bounding box']]
3847 \end{forest}.
3848 \end{forestexample}}
3849
3850 \indexitem>{tikz key>fit to}|=|\meta{nodewalk} Fits the \TikZ; node to the nodes in the given
3851 \meta{nodewalk}.
3852
3853 This key should be used like \keyname{/tikz/fit} of the \TikZ;'s fitting library
3854 \citep[see][\S34]{tikzpgf2.10}: as an option to \emph{\TikZ;'s} |node| operation, the obvious
3855 restriction being that \keyname{fit to} must be used in the context of some \foRest; node.
3856 For an example, see footnote~\ref{fn:fit-to-tree}.
3857
3858 This key works by calling \keyname{/tikz/fit} and providing it with the the coordinates of the
3859 subtree's boundary.
3860
3861 The \meta{nodewalk} inherits its history from the outer nodewalk (if there is one). Its every-step
3862 keylist is empty.
3863
3864 \indexitem{node key>get min s tree boundary}|=|\meta{cs} \vspace{-\parskip}
3865 \indexitem{node key>get max s tree boundary}|=|\meta{cs}
3866
3867 Puts the boundary computed during the packing process into the given \meta{cs}. The boundary is
3868 in the form of \PGF; path. The |min| and |max| versions give the two sides of the node. For an
3869 example, see how the boundaries in the discussion of \index{fit} were drawn.
3870
3871 \indexitem{option>label}|=|\meta{toks: \TikZ; node} The current node is labelled by a \TikZ; node.
3872
3873 The label is specified as a \TikZ; option \texttt{label} \citep[\S16.10]{tikzpgf2.10}.
3874 Technically, the value of this option is passed to \TikZ;'s as a late option
3875 \citep[\S16.14]{tikzpgf2.10}. (This is so because \foRest; must first typeset the nodes
3876 separately to measure them (stage \index{typeset nodes}); the preconstructed nodes are inserted
3877 in the big picture later, at stage \index{draw tree}.) Another option with the same
3878 technicality is \index{pin}.
3879
3880 \indexitem{option>pin}|=|\meta{toks: \TikZ; node} The current node gets a pin, see
3881 \citep[\S16.10]{tikzpgf2.10}.
3882 ¸
3883 The technical details are the same as for \index{label}.
3884
3885
3886 \indexitem{node key>use as bounding box} The current node's box is used as a bounding box for the
3887 whole tree.
3888
3889 \indexitem{node key>use as bounding box'} Like \index{use as bounding box}, but subtracts the
3890 (current) inner and outer sep from the node's box. For an example, see \index{baseline}.
3891
3892 \indexitem({{{{{}}}}}){option>tikz}|=|\meta{toks: \TikZ; code} ``Decorations.''
3893
3894 The code given as the value of this option will be included in the |tikzpicture| environment used
3895 to draw the tree. By default, the code is included after all nodes of the tree have been drawn,
3896 so it can refer to any node of the tree (furthermore, relative node names can be used to refer to
3897 nodes of the tree, see \S\ref{ref:relative-node-names}) and the code given to various nodes is
3898 appended in a depth-first, parent-first fashion. See \S\ref{sec:draw-tree} for details and
3899 customization.
3900
3901 By default, bracket parser's afterthoughts feed the value of this option. See
3902 \index{afterthought}.
3903
3904 \end{syntax}
3905
3906
3907
3908 \subsection{Nodewalks}
3909 \label{ref:nodewalks}
3910
3911 A \emph{nodewalk} is a sequence of \emph{steps} describing a path through the tree. Most steps
3912 are defined relative to the current node, for example \index{step>parent} steps to the parent of the
3913 current node, and \index{step>n}|=2| steps to the second child of the current node, where ``to make a
3914 step'' means to change the current node. Thus, nodewalk |parent,_parent,_n=2| describes the path
3915 which first steps to the parent of the \emph{origin} node, then to its grandparent and finally to
3916 the second child of the origin's grandparent.
3917
3918 The origin of the nodewalk depends on how the nodewalk is invoked. When used after the \index>{!}
3919 in a relative node name (\S\ref{ref:relative-node-names}), the origin is the node with the name
3920 given before \index>{!}; when invoked by a spatial propagator such as \index{for
3921 step=\index{nodewalk}} (\S\ref{ref:spatial-propagators}), the origin is the current node; when
3922 invoked within another (outer) nodewalk, the origin is the current node of the outer nodewalk.
3923
3924 Formally, a \meta{nodewalk} is a list of |pgfkeys| key--value pairs. Steps in a nodewalk are thus
3925 separated by commas. However, \foRest; also recognizes \emph{short-form} steps, whose names consist
3926 of a single character and which do not need to be separated by a comma. For example, nodewalk
3927 |parent,_parent,_n=2| can be concisely written as |uu2|. Long and short forms can be mixed freely,
3928 like this: |next,_uu2,_previous|.
3929
3930 Besides nodewalk keys, a \meta{nodewalk} can also contain node keys (or
3931 even \TikZ; keys).\footnote{The precise algorithm for keyname resulotion in nodewalks is as follows.
3932 \begin{itemize}
3933 \item First, \foRest; searches for the given \meta{keyname} in the \index{path>forest/nodewalk}
3934 path. If found (a long-form step or a nodewalk style), it is executed.
3935 \item Next, it is checked whether \meta{keyname} is a sequence of short-form steps; is so, they are
3936 executed.
3937 \item Otherwise, \meta{key} is executed in the \keyname{/forest} path. This includes both
3938 \foRest;'s and \TikZ;'s keys. The latter are usually forwarded to \TikZ; via \index{node
3939 options}.
3940 \end{itemize}
3941 There are some clashes between node key and nodewalk step names. For example, \keyname{l} is both a
3942 \meta{dimen} option and a short form of the step to the last child. According to the rules above,
3943 the nodewalk step will take precedence in case of a clash. Use nodewalk key \index{options} to
3944 execute a clashing node key.} These keys do their usual function, but within the context of the
3945 current node of the nodewalk: |parent, s=2em,| |parent, text=red| sets the parent's |s| to 2em and
3946 the grandparent's text color to red. It is worth noting that node keys include \index{TeX}, which
3947 makes it possible to execute any \TeX\ code while nodewalking.
3948
3949 Some steps target a single node, like above-mentioned \index{step>parent} and \index{step>n}.
3950 Others, called multi-steps, describe mini-walks themselves: for example \index{step>children} visits
3951 each child of the node in turn, and \index{tree} visits each of the node's descendants (including
3952 the node itself). The path of many steps is determined by the geometric relations of the tree, or
3953 the value of some option. However, there are also keys for embedding nodewalks (\index{nodewalk
3954 key>nodewalk}, \index{branch}, etc.), saving and loading nodewalks, sorting them, or even
3955 re-walking the history of steps made (like in a web browser).\footnote{Note that nesting operation
3956 (\S\ref{ref:nodewalk-operations}) and history (\S\ref{ref:nodewalk-history}) steps, or embedding
3957 nodewalks under these steps doesn't work, for most combinations, as many of them internally
3958 manipulate nodewalk history.} Finally, if all this is not enough, you can define your own steps,
3959 see \S\ref{ref:defining-steps}.
3960
3961 Each nodewalk has an associated \emph{every-step keylist}: a keylist of node keys\footnote{When
3962 executing the \index{register>every step} keylist, \foRest; switches into the
3963 \index{path>forest} path, which makes it impossible to directly include a nodewalk into the
3964 every-step keylist. The reason is performance. Every time a \index{path>forest/nodewalk} key
3965 is not found, the short-form nodewalk recognition algorithm is executed, and this algorithm is
3966 slow. As \index{register>every step} is used a lot (it is for example used every invocation of
3967 every spatial propagator) and the keys in \index{register>every step} are usually node options
3968 from \index{path>forest} path, \foRest; would spend way too much time checking if a given node
3969 option is actually a short-form nodewalk.
3970
3971 If you need to execute nodewalk keys within the every-step keylist, use node key \index{node
3972 key>Nodewalk}.} which get executed after each step of the nodewalk. The every-step keylist of
3973 the current nodewalk is contained in register \index{register>every step} and can be changed at any
3974 point during the nodewalk. Its value at the start of the nodewalk depends on how the nodewalk was
3975 invoked. In most cases (e.g.\ \index{step>nodewalk} or prefix \index{for step}-based spatial
3976 propagators), it is given explicitely as an argument to the key that executes the nodewalk.
3977 However, see \index{step>Nodewalk} option \index{option of=Nodewalk>every step} for information on
3978 how the every-step keylist of an embedded nodewalk can interact with the every-step keylist of its
3979 parent nodewalk.
3980
3981 Each nodewalk step can be either \emph{real} or \emph{fake}. Fake steps only change the current
3982 node. Real steps also trigger execution of the every-step keylist and update of history. Fake
3983 steps are sometimes useful as a ``computational tool''. They can be introduced explicitely using
3984 \index{nodewalk key>fake}; some other keys (like several history nodewalk keys,
3985 \S\ref{ref:nodewalk-history}) introduce fake steps implicitely.
3986
3987 In some cases, the nodewalk might step ``out of the tree''. (Imagine using \index{step>parent} at the
3988 root of the tree, or \index{readonly option>n}|=42| at a node with less that 42 children.) Our official term will
3989 be that the nodewalk stepped on an \emph{invalid node}; what happens formally is that the current
3990 node is changed to the node with \index{readonly option>id}|=0|. Normally, such an event raises an
3991 error. However, the full story is told by \index{nodewalk key>on invalid}.
3992
3993 Nodewalks can be hard to follow, especially when designing styles. \FoRest; does its best to
3994 help. First, it logs the nodewalk stack in case of error. Second, if package option
3995 \index{debug}|=|\index{option of=debug>nodewalks} is given, it logs every step made.
3996
3997
3998 \subsubsection{Invoking (embedded) nodewalks}
3999 \label{ref:embedded-walks}
4000
4001 There are many ways to invoke a nodewalk. For example, several keys, like \index{fit to}, and
4002 aggregate functions (\S\ref{ref:aggregate-functions}) expect a \meta{nodewalk} argument. This
4003 section lists keys which can be used to explicitely invoke a nodewalk.
4004
4005 The keys in this section can be used not only as node keys (in fact, not all of them can be used
4006 so), but also as nodewalk keys. The latter fact means that they can be used to introduce embedded
4007 nodewalks, which (can) have its own every-step keylist, history and on-invalid mode; for details on
4008 how these properties of outer and embedded nodewalk can interact, see \index{step>Nodewalk}. There
4009 is no limit to the depth of nodewalks embedding (nodewalk within nodewalk within nodewalk \dots).
4010
4011 An embedded nodewalk functions as a single, fake step of the outer nodewalk. Specifically, this
4012 means that, while stepping through the embedded nodewalk, the every-step keylist of the outer
4013 nodewalk is not executed. Furthermore, by default, modifying the every-step keylist of the inner
4014 walk (by manipulating register \index{register>every step}) does not influence the outer nodewalk
4015 (but see option \index{option of=Nodewalk>every step}).
4016
4017 An embedded nodewalk does not count as a (real, every-step keyslist invoking) step of the outer
4018 nodewalk. After it is finished, there are two options with respect to the new current node of the
4019 outer nodewalk,\footnote{Even the outermost explicitly invoked nodewalks actually have the outer
4020 nodewalk. It is ``static'' in the sense that no real step is ever made in it, but it has all the
4021 nodewalk properties --- the current node, \index{register>every step} keylist register, \index{option
4022 of=Nodewalk>history} and \index{option of=Nodewalk>on invalid} mode (error) --- which can
4023 interact with the embedded nodewalk.} depending on whether the embedded nodewalk was invoked using
4024 a variant of the key with or without the \index{for step} prefix (all keys in this section have the
4025 \index{for step} variant).
4026 \begin{itemize}
4027 \item For keys \emph{without} the \index{for step} prefix, the current node of the outer nodewalk
4028 changes, \emph{via a fake step}, to the final node visited by the embedded nodewalk. This holds
4029 even if the final node was reached as a fake step and even if it is invalid
4030 (\index{option>id}|=0|). The fake step in the outer nodewalk cannot be made real, not even by
4031 \index{nodewalk key>real}: if you want to execute the every-step keylist of the outer nodewalk at
4032 the finishing node of the embedded nodewalk, follow the latter by step \index{current}.
4033 \item For keys \emph{with} the \index{for step} prefix, the current node of the outer nodewalk
4034 remains unchanged. For this reason, the \index{for step}-prefixed keys are available as node keys
4035 (we call them spatial propagators, \S\ref{ref:spatial-propagators}), while the steps without this
4036 prefix are generally not, with the sole exception of \index{step>Nodewalk}, which I advise to use
4037 carefully.
4038 \end{itemize}
4039
4040 All steps described in this section can be prefixed by \index{for step}. All of them, with or
4041 without this prefix, are available as nodewalk keys. The list of keys from this section which are
4042 available as node keys: \index{step>Nodewalk}, \index{for step=\index{step>Nodewalk}}, \index{for
4043 step=\index{nodewalk}}; you will most often want to use the latter.
4044
4045
4046 \begin{syntax}
4047 \indexitem{step>Nodewalk}|=|\meta{keylist: config}\meta{nodewalk}\meta{keylist: every-step}
4048
4049 Walks an \meta{nodewalk} starting at the current node.
4050
4051 This is the most generic form of embedding a nodewalk. Unlike other keys described in this
4052 subsection, it can also be used as a node key even without the \index{for step} prefix, but take
4053 care as it will, in general, change the current node.
4054
4055 The \meta{config} argument serves to specify the interaction between the outer and embedded
4056 nodewalk. It can contain the following keys:
4057
4058 \let\outerleftmargin\leftmargin
4059 \begin{syntax}
4060 \indexitem(independent){option of=Nodewalk>every step}|={|\alternative{independent,inherited,shared}|}|
4061 \indexitem(shared){option of=Nodewalk>history}|={|\alternative{independent,inherited,shared}|}|
4062
4063 The following table shows what happens to the every-step keylist and history depending on the
4064 value of \keyname{every step} and \keyname{history}, respectively. State B is \meta{every-step}
4065 for every step and empty for history.
4066
4067 \begin{tabular}{l|ccc}
4068 &\keyname{independent}&\keyname{inherited}&\keyname{shared}\\\hline
4069 state of the outer nodewalk&A&A&A\\
4070 initial state of the inner nodewalk&B&A&A\\
4071 \dots\\
4072 final state of the inner nodewalk&C&C&C\\
4073 state of the outer nodewalk&A&A&C
4074 \end{tabular}
4075 \end{syntax}
4076
4077 As shown in the table above, argument \meta{every-step} is used to initialize the
4078 embedded nodewalk's every-step keylist when it is independent of the outer nodewalk. In other
4079 cases, this argument is ignored (use |{}|).
4080
4081 \begin{syntax}
4082 \indexitem(inherited){option of=Nodewalk>on invalid}|={|\alternative{error,fake,error in real,last valid,inherited}|}|
4083
4084 Like \index{nodewalk key>on invalid}, but local to this nodewalk. The additional alternative
4085 \indexdef{value of=on invalid>inherited} (which is the default) means to retain the current
4086 value, regardless of how it was set (by an outer nodewalk, explicit \index{nodewalk key>on
4087 invalid}, or the package default, \index{value of=on invalid>error}).
4088 \end{syntax}
4089
4090 \begin{advise}
4091 \item Use \index{node key>Nodewalk} if you need to execute nodewalk keys within the every-step
4092 keylist.
4093 \end{advise}
4094
4095 \begin{forestexample}[index={register>every step}]
4096 \begin{forest}
4097 for 2=calign with current, for children={for descendants={circle,draw}}
4098 [every step,
4099 [independent,for nodewalk={
4100 1,Nodewalk={~every step=independent~}{1,every step=fill,1}{},1
4101 }{draw=red},
4102 [[[[]]]]]
4103 [inherited,for nodewalk={
4104 1,Nodewalk={~every step=inherited~}{1,every step=fill,1}{},1
4105 }{draw=red},
4106 [[[[]]]]]
4107 [shared,for nodewalk={
4108 1,Nodewalk={~every step=shared~}{1,every step=fill,1}{},1
4109 }{draw=red},
4110 [[[[]]]]]]
4111 \end{forest}
4112 \end{forestexample}
4113
4114
4115 \begin{forestexample}[index={history,walk back}]
4116 \begin{forest}
4117 mark/.style={tempcounta+=1,content+/.register=tempcounta,content+={,}},
4118 [history:\\effect on the,align=center
4119 [inner nodewalk
4120 % uncommenting this would result in an error:
4121 % [independent, delay={for nodewalk={
4122 % tempcounta=0,111,
4123 % Nodewalk={history=independent}{walk back=2}{mark,fill=yellow}
4124 % }{mark,draw=red}},
4125 % [[[]]]]
4126 [inherited\\or\\shared, align=center,delay={for nodewalk={
4127 tempcounta=0,111,
4128 Nodewalk={~history=inherited~}{walk back=2}{mark,fill=yellow}
4129 }{mark,draw=red}},
4130 [[[]]]]]
4131 [outer nodewalk
4132 [inherited,delay={for nodewalk={
4133 tempcounta=0,111,
4134 Nodewalk={~history=inherited~}{11}{mark,fill=yellow},
4135 walk back=2
4136 }{mark,draw=red}},
4137 [[[[[]]]]]]
4138 [shared,delay={for nodewalk={
4139 tempcounta=0,111,
4140 Nodewalk={~history=shared~}{11}{mark,fill=yellow},
4141 walk back=2
4142 }{mark,draw=red}},
4143 [[[[[]]]]]]]]
4144 \end{forest}
4145 \end{forestexample}
4146
4147 \indexitem{step>nodewalk}|=|\meta{nodewalk}\meta{keylist: every-step}
4148
4149 This key is a shorthand for
4150
4151 \begin{center}
4152 \index{step>Nodewalk}|={|\index{option of=Nodewalk>every step}|=independent,|\index{option
4153 of=Nodewalk>history}|=independent,|\index{option of=Nodewalk>on
4154 invalid}|=inherited}|\meta{nodewalk}\meta{keylist: every-step}
4155 \end{center}
4156
4157 \begin{advise}
4158 \item \index{for step=\index{nodewalk}} is the most common way to explicitely invoke a nodewalk from a
4159 node keylist (the keylist immediately following the content of the node).
4160 \end{advise}
4161
4162 \indexitem{step>nodewalk'}|=|\meta{nodewalk}
4163
4164 This key is a shorthand for
4165
4166 \begin{center}
4167 \index{step>Nodewalk}|={|\index{option of=Nodewalk>every step}|=inherited,|\index{option
4168 of=Nodewalk>history}|=independent,|\index{option of=Nodewalk>on
4169 invalid}|=inherited}|\meta{nodewalk}|{}|
4170 \end{center}
4171
4172 \begin{advise}
4173 \item Using this key, it is easy to ``\emph{temporarily} change'' the \index{register>every step}
4174 keylist of a nodewalk.
4175 \item Using \index{for step=\index{nodewalk'}} is probably the easiest way to make a ``trip''
4176 within a nodewalk, i.e.\ walk some steps but return to their origin afterwards.
4177 \item This key (with or without the \index{for step} prefix) is not available as a node key --- it
4178 would make little sense there, as it has no every-step keylist argument.
4179 \end{advise}
4180
4181 \end{syntax}
4182
4183
4184 \subsubsection{Single-step keys}
4185 \label{ref:single-step-keys}
4186
4187 Single-step nodewalk keys visit a single node. The behaviour in the situation when the target node
4188 does not exist is determined by \index{nodewalk key>on invalid}.
4189
4190 For each single-step key, spatial propagator \index{for step=\meta{step}} is also defined.
4191 \index{for step=\meta{step}}|=|\meta{keylist} is equivalent to
4192 \index{for step=\index{nodewalk}}|={|\meta{step}|}{|\meta{keylist}|}|. If the step takes an argument, then its
4193 \index{for step=\meta{step}} propagator takes two and the argument of the step precedes the
4194 \meta{keylist}. See also \S\ref{ref:spatial-propagators}.
4195
4196 Linear order below means the order of nodes in the bracket representation, i.e.\ depth-first
4197 parent-first first-child-first.
4198
4199 \begin{syntax}
4200 \indexitem{step>current} an ``empty'' step: the current node remains the same\footnote{While it
4201 might at first sight seem stupid to have an empty step, this is not the case. For example,
4202 using propagator \index{for step=\index{current}} derived from this step, one can process a \meta{keylist} constructed using \index[not index,print format+={result+={\index[not print]{wrap pgfmath arg}\index[not print]{wrap $n$ pgfmath args}}}]{handler>wrap ($n$) pgfmath arg(s)} or \index{wrap value}.}
4203 \indexitem{step>first} the first child
4204 \indexitem{step>first leaf}, \indexdef{step>first leaf'} the first leaf (terminal node) of the
4205 current node's descendants (|first leaf|) or subtree (|first leaf'|), in the linear order
4206 \indexitem{step>id}|=|\meta{id} the node with the given id; this step does not depend on the current node
4207 \indexitem{step>last} the last child
4208 \indexitem{step>last dynamic node} the last non-integrated (created/removed/replaced) node; see \S\ref{ref:dynamic}
4209 \indexitem{step>last leaf}, \indexdef{step>last leaf'} the last leaf (terminal node) of the
4210 current node's descendants (|last leaf|) or subtree (|last leaf'|), in the linear order
4211 \indexitem{step>n}|=|$n$ the $n$th child; counting starts at $1$\footnote{Note that \keyname{n}
4212 \emph{without} an argument is a short form of \keyname{next}.}
4213 \indexitem{step>n'}|=|$n$ the $n$th child, starting the count from the last child
4214 \indexitem{step>name}|=|\meta{name} the node with the given name or alias; this step does not depend on the current node
4215 \indexitem{step>next} the next sibling
4216 \indexitem{step>next leaf} the next node (in the linear order) which is a leaf (the current node need not be a leaf)
4217 \indexitem{step>next node} the next node of the entire tree, in the linear order
4218 \indexitem{step>next on tier}|=|\meta{tier} the next node (in the linear order) on the given tier; if no tier is given, assume the tier of the current node
4219 \indexitem{step>origin} the starting node of the nodewalk; note that the starting point does not automatically count as a step: if you want to step on it, use this key (or \index{current}, at the beginning of the nodewalk)
4220 \indexitem{step>parent} the parent
4221 \indexitem{step>previous} the previous sibling
4222 \indexitem{step>previous leaf} the previous node (in the linear order) which is a leaf (the current node need not be a leaf)
4223 \indexitem{step>previous node} the previous node of the entire tree, in the linear order
4224 \indexitem{step>previous on tier}|=|\meta{tier} the previous node (in the linear order) on the given tier; if no tier is given, assume the tier of the current node
4225 \indexitem{step>root} the root node, i.e.\ the ancestor of the current node without the parent; note that this key \emph{does} depend on the current node
4226 \indexitem{step>root'} the formal root node (see \index{set root} in \S\ref{ref:dynamic}); this key does not depend on the current node
4227 \indexitem{step>sibling} the sibling
4228
4229 (don't use if the parent doesn't have exactly two children \dots)
4230 \indexitem{step>to tier}|=|\meta{tier} the first ancestor of the current node (or the node itself) on the given \meta{tier}
4231 \end{syntax}
4232
4233
4234 \subsubsection{Multi-step keys}
4235 \label{ref:multi-step-keys}
4236
4237 Multi-step keys visit several nodes, in general. If a multi-step key visits no nodes, the current
4238 node remains unchanged.
4239
4240 For each multi-step key, spatial propagator \index{for step=\meta{step}} is also defined, see
4241 \S\ref{ref:spatial-propagators}.
4242
4243 Many of the keys below have a |reversed| variant. Those keys reverse the order of \emph{children}.
4244 Note that in general, this differs from operation key \index{reverse}, which reverses the order of
4245 the entire embedded nodewalk.
4246
4247 Linear order below means the order of nodes in the bracket representation, i.e.\ depth-first
4248 parent-first first-child-first.
4249
4250 \begin{syntax}
4251 \indexitem{step>children}, \indexdef{step>children reversed}
4252
4253 Visit all the children of the current
4254 node.
4255
4256 \indexitem{step>tree}, \indexdef{step>tree reversed}
4257 \itemnosep
4258 \indexitem{step>tree children-first}, \indexdef{step>tree children-first reversed}
4259 \itemnosep
4260 \indexitem{step>tree breadth-first}, \indexdef{step>tree breadth-first reversed}
4261
4262 Visit the current node and all its descendants.
4263
4264 The above keys differ in the order the nodes are visited. The basic key, \keyname{tree},
4265 traverses the nodes in the depth-first, parent-first first-child-first order, i.e.\ the order in
4266 which they are given in the bracket representation: so it visits the parent before its children and
4267 it visits the children from the first to the last.
4268
4269 |reversed| variants reverse the order of \emph{children}, visiting them from the last to the first
4270 (from the viewpoint of the bracket representation).
4271
4272 |children-first| variants visit the children before the parent.
4273
4274 |breadth-first| variants behave like |level| steps below: they first visit level |0| nodes, then
4275 level |1| nodes etc.
4276
4277 \begin{forestexample}[index={}]
4278 \forestset{
4279 enumerate/.style={
4280 tempcounta=1,
4281 for #1={
4282 content/.pgfmath=tempcounta,
4283 tempcounta+=1
4284 }
4285 }
4286 }
4287 \newcommand\enumtree[1]{%
4288 \begin{forest}
4289 [#1,l sep=0,for n=1{
4290 l=0,no edge,delay={enumerate=#1}}
4291 [[[[][]][[][]]][[[][]]]]
4292 ]
4293 \end{forest}
4294 }
4295 \renewcommand\arraystretch{2}
4296 \begin{tabular}{cc}
4297 \enumtree{tree}&
4298 \enumtree{tree reversed}\\
4299 \enumtree{tree children-first}&
4300 \enumtree{tree children-first reversed}\\
4301 \enumtree{tree breadth-first}&
4302 \enumtree{tree breadth-first reversed}
4303 \end{tabular}
4304 \end{forestexample}
4305
4306 \indexitem{step>descendants}, \indexdef{step>descendants reversed}
4307 \itemnosep
4308 \indexitem{step>descendants children-first}, \indexdef{step>descendants children-first reversed}
4309 \itemnosep
4310 \indexitem{step>descendants breadth-first}, \indexdef{step>descendants breadth-first reversed}
4311
4312 Visit all the descendants of the current node.
4313
4314 Like the |tree| keys, but the current node is not visited.
4315
4316 \indexitem[print form+=\spaces{9}]{step>relative level<},
4317 \indexdef[print form+=\spaces{9}]{step>relative level},
4318 \indexdef[set={form=relative level\protect\greaterthan}]{step>relative levelGT}\texttt{\spaces{9}}|=|\meta{count}
4319 \itemnosep
4320 \indexitem{step>relative level reversed<},
4321 \indexdef{step>relative level reversed},
4322 \indexdef[set={form=relative level reversed\protect\greaterthan}]{step>relative level reversedGT}|=|\meta{count}
4323 \itemnosep
4324 \indexitem[print form+=\spaces{9},+print form=\spaces{9}]{step>level<},
4325 \indexdef[print form+=\spaces{9},+print form=\spaces{9}]{step>level},
4326 \indexdef[set={form=level\protect\greaterthan},+print form=\spaces{9}]{step>levelGT}\texttt{\spaces{9}}|=|\meta{count}
4327 \itemnosep
4328 \indexitem[+print form=\spaces{9}]{step>level reversed<},
4329 \indexdef[+print form=\spaces{9}]{step>level reversed},
4330 \indexdef[set={form=level reversed\protect\greaterthan},+print form=\spaces{9}]{step>level reversedGT}|=|\meta{count}
4331
4332 Visits the nodes in the subtree of the current node whose level (depth) is less than \emph{or
4333 equal to}, equal to, or greater than \emph{or equal to} the given level.
4334
4335 The |relative| variants consider the level as relative to the current node: relative level of the
4336 current node is $0$; relative level of its children is $1$, of its grandchildren $2$, etc. The
4337 absolute variants consider the depth with respect to the (geometric) root, i.e.\ as returned by
4338 node option \index{readonly option>level}.
4339
4340 The nodes are traversed in the breadth-first order. The |reversed| variants reverse the order of
4341 the children within each level, but the levels are still traversed from the highest to the
4342 deepest.
4343
4344 \indexitem{step>leaves}
4345
4346 Visits all the leaves in the current node's subtree.
4347
4348 \indexitem[index key={level-}]{step>-level}|=|\meta{count}
4349 \itemnosep
4350 \indexitem[index key={level-'}]{step>-level'}|=|\meta{count}
4351
4352 Visits all the nodes \meta{count} levels above the leaves in the current node's subtree.
4353
4354 \indexitem[+print form=\spaces{12},print form+=\spaces{9}]{step>preceding siblings}\quad\quad
4355 \indexdef[+print form=\spaces{12}]{step>following siblings}%
4356 \itemnosep
4357 \indexitem[print form+=\spaces{9}]{step>current and preceding siblings}\quad\quad
4358 \indexdef{step>current and following siblings}%
4359 \itemnosep
4360 \indexitem[+print form=\spaces{12}]{step>preceding siblings reversed}\quad\quad
4361 \indexdef[+print form=\spaces{12}]{step>following siblings reversed}%
4362 \itemnosep
4363 \indexitem{step>current and preceding siblings reversed}\quad\quad
4364 \indexdef{step>current and following siblings reversed}%
4365 \itemnosep
4366 \indexitem[+print form=\spaces{22},print form+=\spaces{9}]{step>siblings}%
4367 \itemnosep
4368 \indexitem[print form={current and \spaces{9} siblings\spaces{9}}]{step>current and siblings}%
4369 \itemnosep
4370 \indexitem[+print form=\spaces{22},print form+=\spaces{9}]{step>siblings reversed}%
4371 \itemnosep
4372 \indexitem[print form={current and \spaces{9} siblings reversed}]{step>current and siblings reversed}%
4373
4374 Visit preceding, following or all siblings; visit the current node as well or not; visit in normal
4375 or reversed order.
4376
4377 \indexitem{step>ancestors}
4378 \itemnosep
4379 \indexitem{step>current and ancestors}
4380
4381 Visit the ancestors of the current node, starting from the parent/current node, ending at the root node.
4382
4383 \indexitem[+print form=\spaces{12}]{step>preceding nodes}\quad\quad
4384 \indexdef[+print form=\spaces{12}]{step>following nodes}%
4385 \itemnosep
4386 \indexitem{step>current and preceding nodes}\quad\quad
4387 \indexdef{step>current and following nodes}%
4388
4389 Visit all preceding or following nodes of the entire tree, in the linear order; visit the current node as well or not.
4390
4391 \end{syntax}
4392
4393
4394 \subsubsection{Operations}
4395 \label{ref:nodewalk-operations}
4396
4397 Generally speaking, nodewalk operations take an \emph{input nodewalk} and transform it into
4398 an \emph{output nodewalk}, while possibly also having side effects.
4399
4400 The most important categorization of operations is in terms of the input nodewalk:
4401 \begin{itemize}
4402 \item ``Normal'' keys execute the input nodewalk ``invisibly'', i.e.\ with a every-step keylist that
4403 is initially empty. However, even such an ``invisible'' nodewalk might not always be completely
4404 without effect. For example, the effects of any node keys contained in the input nodewalk or
4405 modifications of its (initially empty) every-step keylist will be felt.
4406 \item Most of the operation keys have the |walk_and_...| variant, where input given nodewalk is meant to
4407 be ``visible'': it is walked directly in the context of the invoking nodewalk (specifically, with
4408 its every-step keylist in effect).
4409 \item Some operation keys have the |..._in_nodewalk| variant, which operates on the portion of the
4410 current nodewalk that was already walked.
4411 \item \index{load} has no input nodewalk.
4412 \end{itemize}
4413 All operation keys except |..._in_nodewalk| variants can be prefixed by \index{for step} to create a
4414 spatial propagator (\S\ref{ref:spatial-propagators}).
4415
4416 The output nodewalk is always walked in the context of the invoking nodewalk. However, note that,
4417 as mentioned above, in the case of |walk_and_...| variants, that context can be changed during the
4418 execution of the input nodewalk.
4419
4420 Trivia: \index{save} is the only operation with no output nodewalk and also the only operation with
4421 a ``side effect'' (of saving the nodewalk, obviously).
4422
4423 For some operations (\index{filter} and \index{branch}), the every-step keylist contains instructions
4424 on how collect the relevant information. While you can safely append and prepend to
4425 \index{register>every step} keylist of their input nodewalk, you should not completely rewrite
4426 it. If you want the operations to actually work, of course.
4427
4428 \begin{syntax}
4429 \indexitem{step>group}|=|\meta{nodewalk}
4430
4431 Treat \meta{nodewalk} as a single step of the (outer) nodewalk, i.e.\ the outer every-step keylist
4432 is executed only at the end of the embedded nodewalk. The embedded \meta{nodewalk} inherits
4433 history from the outer nodewalk. Using this key is equivalent to writing
4434 \begin{center}
4435 \index{step>Nodewalk}|={|\index{option of=Nodewalk>every step}|=independent,|\index{option
4436 of=Nodewalk>history}|=inherited}|\meta{nodewalk}|{}, current|
4437 \end{center}
4438
4439
4440 \indexitem{step>reverse}|=|\meta{nodewalk}
4441 \itemnosep
4442 \indexitem{step>walk and reverse}|=|\meta{nodewalk}
4443
4444 Visits the nodes of the given \meta{nodewalk} in the reversed order.
4445
4446
4447 \indexitem{step>unique}|=|\meta{nodewalk}
4448
4449 Walks the \meta{nodewalk}, but visits each node at most once.
4450
4451
4452 \indexitem{step>filter}|=|\meta{nodewalk}\index{forestmath=condition}
4453
4454 Visit the nodes of the given \meta{nodewalk} for which the given \meta{condition} is true.
4455
4456 \begin{advise}
4457 \item You can safely append and prepend to \index{register>every step} keylist during the input
4458 \meta{nodewalk}, but you should not completely rewrite it.
4459 \end{advise}
4460
4461
4462 \indexitem{step>branch}|={|\meta{nodewalk$_1$}|,...,|\meta{nodewalk$_n$}|}|
4463 \itemnosep
4464 \indexitem{step>branch'}|={|\meta{nodewalk$_1$}|,...,|\meta{nodewalk$_n$}|}|
4465
4466 Visit the nodes in a ``cartesian product'' of any number of nodewalks, where a cartesian product is
4467 defined as a nodewalk where at every step of \meta{nodewalk$_i$} ($1\leq i<n$),
4468 \meta{nodewalk$_{i+1}$} is executed.
4469
4470 The |branch| variant visits only the nodes visited by the innermost nodewalk, \meta{nodewalk$_n$}.
4471 The |branch'| variant visits the nodes visited by all the nodewalks of the product,
4472 \meta{nodewalk$_1$} \dots\ \meta{nodewalk$_n$}.
4473
4474 For an example of each, see \index{c-commanded} and \index{c-commanders} from the
4475 \reflibrary{linguistics} library.
4476
4477 \begin{advise}
4478 \item You can safely append and prepend to \index{register>every step} keylists during the input
4479 \meta{nodewalk}s, but you should not completely rewrite them.
4480 \end{advise}
4481
4482
4483 \indexitem{step>save}|=|\meta{toks: name}\meta{nodewalk}
4484 \itemnosep
4485 \indexitem{step>walk and save}|=|\meta{toks: name}\meta{nodewalk}
4486
4487 Saves the given \meta{nodewalk} under the given name.
4488
4489 \indexitem{step>save append}|=|\meta{toks: name}\meta{nodewalk}
4490 \itemnosep
4491 \indexitem{step>save prepend}|=|\meta{toks: name}\meta{nodewalk}
4492 \itemnosep
4493 \indexitem{step>walk and save append}|=|\meta{toks: name}\meta{nodewalk}
4494 \itemnosep
4495 \indexitem{step>walk and save prepend}|=|\meta{toks: name}\meta{nodewalk}
4496
4497 Appends/prepends the given \meta{nodewalk} to nodewalk \meta{name}.
4498
4499 \indexitem{step>load}|=|\meta{toks: name} Walks the nodewalk saved under the given name.
4500
4501 Note that it is node \index{readonly option>id}s that are saved: loading a named nodewalk with in a context of
4502 a different current node, or even with a tree whose geometry has changed (see \S\ref{ref:dynamic})
4503 will still visit exactly the nodes that were visited when the nodewalk was saved.
4504
4505
4506 \indexitem{step>sort}|=|\meta{nodewalk}
4507 \itemnosep
4508 \indexitem{step>sort'}|=|\meta{nodewalk}
4509 \itemnosep
4510 \indexitem{step>walk and sort}|=|\meta{nodewalk}
4511 \itemnosep
4512 \indexitem{step>walk and sort'}|=|\meta{nodewalk}
4513
4514 Walks the nodes of the nodewalk in the order specified by the last invokation of \index{sort
4515 by}. The \keyname{sort} variants sort in the ascending order, the \keyname{sort'} variants in
4516 the descending order. The \keyname{walk and sort} variants first visit the nodes in the order
4517 specified by the given \meta{nodewalk}.
4518
4519 \indexitem{node key>sort by}|={|\index{forestmath}|,|\dots|,|\index{forestmath}|}|
4520
4521 Sets the sorting order used by all keys comparing nodes: \index{step>sort}, \index{step>min}
4522 and \index{step>max} key families in the nodewalk namespace, and the \index{dynamic
4523 tree>sort} key family in the option namespace (dynamic tree).
4524
4525 For each node being ordered, an ``$n$-dimensional coordinate'' is computed by evaluating the given
4526 list of |pgfmath| expressions in the context of that node.\footnote{Don't worry, lazy evaluation
4527 is used.} Nodes are then ordered by the usual sort order for multi-dimensional arrays: the
4528 first item is the most important, the second item is the second most important, etc.
4529
4530 Simply put, if you want to sort first by the number of children and then by content, say
4531 |sort_by={|\index[+print format=pgfmath]{n children}|,_|\index{content}|}|.
4532
4533 In the simplest case, the given \index{forestmath} expressions are simply node options. However, as
4534 any |pgfmath| expression is allowed in the sort key, you can easily sort by the product of the
4535 content of the current node and the content of its first child:
4536 |sort_by={|\index{content}|()*|\index{content}|("|\index>{!}|1")|.
4537
4538 To sort alphabetically, one must use the argument processor (\S\ref{ref:argument-processor}) to
4539 specify the sort order. In particular, the key must be marked as text using \index{processor>t}.
4540 The first example below shows a simple alphabetical sort by content; the second sorts the
4541 filenames by suffix first (in the ascending order) and then by the basename (in the descending
4542 order, see \index{processor>-}).
4543
4544 \begin{forestexample}
4545 \begin{forest}
4546 [,phantom,grow'=0,for children={anchor=west,child anchor=west},s sep=0,
4547 delay={~sort by=>O+t{content},sort~}
4548 [example.tex][example.pdf][example.log][example.aux]
4549 [thesis.tex][thesis.pdf][thesis.log][thesis.aux][thesis.toc]
4550 ]
4551 \end{forest}
4552 \end{forestexample}
4553
4554 \begin{forestexample}
4555 \begin{forest}
4556 declare toks={basename}{},
4557 declare toks={extension}{},
4558 [,phantom,grow'=0,for children={anchor=east},s sep=0,
4559 delay={
4560 for children={split option={content}{.}{basename,extension}},
4561 ~sort by={>O+t{extension},>O+t-{basename}}~,
4562 ~sort~,
4563 }
4564 [example.tex][example.pdf][example.log][example.aux]
4565 [thesis.tex][thesis.pdf][thesis.log][thesis.aux][thesis.toc]
4566 ]
4567 \end{forest}
4568 \end{forestexample}
4569
4570 \indexitem{step>min}|=|\meta{nodewalk}, \indexdef{step>max}|=|\meta{nodewalk}
4571 \itemnosep
4572 \indexitem{step>walk and min}|=|\meta{nodewalk}, \indexdef{step>walk and max}|=|\meta{nodewalk}
4573 \itemnosep
4574 \indexitem{step>mins}|=|\meta{nodewalk}, \indexdef{step>maxs}|=|\meta{nodewalk}
4575 \itemnosep
4576 \indexitem{step>walk and mins}|=|\meta{nodewalk}, \indexdef{step>walk and maxs}|=|\meta{nodewalk}
4577
4578
4579 Visit the node(s) in the given \meta{nodewalk} with a minimum/maximum value with
4580 respect to the sort order previously specified by \index{sort by}.
4581
4582 Variants \keyname{mins}/\keyname{maxs} visit all the nodes that with the minimum/maximum value of
4583 the sorting key; variants \keyname{min}/\keyname{max} visit only the first such node (first in the order specified by the given nodewalk).
4584
4585 \indexitem{step>min in nodewalk}, \indexdef{step>max in nodewalk}
4586 \itemnosep
4587 \indexitem{step>mins in nodewalk}, \indexdef{step>maxs in nodewalk}
4588 \itemnosep
4589 \indexitem{step>min in nodewalk'}, \indexdef{step>max in nodewalk'}
4590
4591 These keys search for the minimum/maximum among the nodes that were already visited in the current
4592 nodewalk.
4593
4594 Keys \keyname{mins in nodewalk} and \keyname{maxs in nodewalk} visits all nodes that reach the minimum/maximum, while keys \keyname{min in nodewalk} and \keyname{max in nodewalk} variants visit only the first such node.
4595
4596 Keys \keyname{min in nodewalk'} and \keyname{max in nodewalk'} visit the first minimal/maximal
4597 node by moving back in the history, see \index{back}.
4598
4599
4600 \end{syntax}
4601
4602 \subsubsection{History}
4603 \label{ref:nodewalk-history}
4604
4605 \FoRest; keeps track of nodes visited in a nodewalk and makes it possible to revisit them, in a
4606 fashion similar to clicking the back and forward button in a web browser.
4607
4608 These keys cannot be prefixed by \index{for step}.
4609
4610 \begin{syntax}
4611 \indexitem{step>back}|=|\meta{count: n}
4612 \itemnosep
4613 \indexitem{step>jump back}|=|\meta{count: n}
4614 \itemnosep
4615 \indexitem{step>walk back}|=|\meta{count: n}
4616
4617 Move $n$ steps back in the history. In the \keyname{back} variant, all steps are fake; in
4618 the \keyname{jump back} variant, the final step is real; and in the \keyname{walk back} variant,
4619 all steps are real.
4620
4621 Note that as the origin is not a part of the history, these keys will \emph{not} step there
4622 (unless \index{current} was the first step of your nodewalk). (Use \index{origin} to move
4623 to the origin of the nodewalk.)
4624
4625 \indexitem{step>forward}|=|\meta{count: n}
4626 \itemnosep
4627 \indexitem{step>jump forward}|=|\meta{count: n}
4628 \itemnosep
4629 \indexitem{step>walk forward}|=|\meta{count: n}
4630
4631 Move $n$ steps forward in the history. In the \keyname{forward} variant, all steps are fake; in
4632 the \keyname{jump forward} variant, the final step is real; and in the \keyname{walk forward} variant,
4633 all steps are real.
4634
4635 \indexitem{node key>save history}|=|\meta{toks: back name}\meta{toks: forward name}
4636
4637 Saves the backwards and forwards history under the given names. (Load them using \index{load}.) The
4638 backwards history is saved in the reverse order of how it was walked, i.e.\ outward from the
4639 perspective of the current position in the nodewalk.
4640 \end{syntax}
4641
4642
4643 \subsubsection{Miscellaneous}
4644 \label{ref:nodewalk-miscellaneous}
4645
4646 The following nodewalk keys are not steps. Rather, they influence the behaviour of nodewalk steps in
4647 various ways. The keys in this section having \meta{nodewalk} arguments do not start a new nodewalk
4648 in the sense of \S\ref{ref:embedded-walks}; the given nodewalk steps rather become a part of the
4649 current nodewalk.
4650
4651 \begin{syntax}
4652 \indexitem{register>every step}|=|\meta{keylist} Contains the every-step keylist of the current
4653 nodewalk.
4654
4655 \indexitem{nodewalk key>fake}|=|\meta{nodewalk}
4656 \itemnosep
4657 \indexitem{nodewalk key>real}|=|\meta{nodewalk}
4658
4659 The \meta{nodewalk} embedded under |fake| consists of ``fake'' steps: while
4660 the current node is changed, every-step keylist is not executed and the history is not updated.
4661
4662 Note that these keys do not introduce an embedded nodewalk. The given \meta{nodewalk} will not
4663 have its own history and every-step keylist.
4664
4665 |real| undoes the effect of |fake|, but cannot make real the implicitely fake steps, such as the
4666 return to the origin in spatial propagators like \index{for step=\index{nodewalk}}.
4667 |fake| and |real| can be nested without limit.
4668
4669 \indexitem{step>last valid}
4670 \itemnosep
4671 \indexitem{step>last valid'}
4672
4673 If the current node is valid, these keys do nothing. If the current node of the nodewalk is
4674 invalid (i.e.\ its \index{readonly option>id} is $0$), they step to the last valid visited node. If
4675 there was no such node, they step to the origin of the nodewalk.
4676
4677 The variant \emph{without} |'| makes a fake step. More precisely, it behaves as if both
4678 \index{nodewalk key>fake} and \index{nodewalk key>on invalid}|=fake| are in effect.
4679
4680 \indexitem{nodewalk key>on invalid}|={|\alternative{error,fake,step}|}|\meta{nodewalk}
4681
4682 This key determines what should happen if a nodewalk step landed on the invalid node, i.e.\ the node
4683 with \index{readonly option>id}|=0|.
4684
4685 There is a moment within the step when the current node is changed but the step itself is not yet
4686 really done, is ``still fake'', i.e.\ the history is not yet updated and the every-step keylist is
4687 not yet executed. If the new current node is invalid, this key determines what should happen next.
4688
4689 \let\outerleftmargin\leftmargin
4690 \begin{syntax}
4691 \item |on invalid={|\indexdef{value of=on invalid>error}|}|\meta{nodewalk} produces an error;
4692 \item |on invalid={|\indexdef{value of=on invalid>fake}|}|\meta{nodewalk} does nothing: history is
4693 not updated and the every-step keylist is not executed, thus making the step essentialy fake;
4694 \item |on invalid={|\indexdef{value of=on invalid>error if real}|}|\meta{nodewalk} produces an
4695 error unless \index{nodewalk key>fake} is in effect.
4696 \item |on invalid={|\indexdef{value of=on invalid>last valid}|}|\meta{nodewalk} returns to the
4697 last valid node, by making a fake step, like \index{step>last valid}.
4698 \end{syntax}
4699
4700 Loops with the implicit |id=0| condition (\S\ref{ref:loops}) automatically switch to
4701 |on_invalid=fake| mode.
4702
4703 See also \index{step>Nodewalk} option \index{option of=Nodewalk>on invalid}.
4704
4705 \indexitem{nodewalk key>options}=\meta{keylist: node keys}
4706
4707 Execute the given node options in the context of the current node.
4708
4709 There is not much need to use this key, as any keys that are not (long) steps or sequences of
4710 short steps are automatically used as \foRest; node options any way, but there are still usage
4711 cases, for example whenever the names of node options and (long) steps are the same, or in a style
4712 that wants to ensure there is no overlap.
4713
4714 \indexitem{nodewalk key>strip fake steps}|=|\meta{nodewalk}
4715
4716 If \meta{nodewalk} ends with fake steps, return to the last node current before those steps were made. For details, see \index{define long step}.
4717
4718 \end{syntax}
4719
4720
4721 \subsubsection{Short-form steps}
4722 \label{ref:short-form-steps}
4723
4724 All short forms of steps are one token long. When using them, there is no need to separate them by
4725 commas. Here's the list of predefined short steps and their corresponding long-form steps.
4726
4727 \begin{syntax}
4728 \indexitem{short step>1}, \indexdef{short step>2}, \indexdef{short step>3}, \indexdef{short step>4}, \indexdef{short step>5}, \indexdef{short step>6}, \indexdef{short step>7}, \indexdef{short step>8}, \indexdef{short step>9} the first, \dots, ninth child --- \index{readonly option>n}|=1|,\dots,|,9|
4729 \indexitem{short step>l} the last child --- \index{step>last}
4730 \indexitem{short step>u} the parent (up) --- \index{step>parent}
4731 \indexitem{short step>p} the previous sibling --- \index{previous}
4732 \indexitem{short step>n} the next sibling --- \index{next}
4733 \indexitem{short step>s} the sibling --- \index{sibling}
4734 \indexitem{short step>P} the previous leaf --- \index{previous leaf}
4735 \indexitem{short step>N} the next leaf --- \index{next leaf}
4736 \indexitem{short step>F} the first leaf --- \index{first leaf}
4737 \indexitem{short step>L} the last leaf --- \index{last leaf}
4738 \indexitem[set={index key={<GT},form=\protect\greaterthan}]{short step>GT}
4739 the next node on the current tier --- \index{next on tier}
4740 \indexitem{short step><} the previous node on the current tier --- \index{previous on tier}
4741 \indexitem{short step>c} the current node --- \index{current}
4742 \indexitem{short step>o} the origin --- \index{origin}
4743 \indexitem{short step>r} the root node --- \index{root}
4744 \indexitem{short step>R} the formal root node --- \index{root'}
4745 \indexitem{short step>b} back one fake step in history --- \index{back}|=1|
4746 \indexitem{short step>f} forward one fake step in history --- \index{forward}|=1|
4747 \indexitem{short step>v} last valid node in the current nodewalk, fake version --- \index{step>last valid}
4748 \indexitem{short step>*}\meta{count: n}\meta{keylist} repeat keylist $n$ times --- \index{repeat}|=|\meta{count: n}\meta{keylist}
4749 \item {\rstyle $\{$}\meta{keylist}{\rstyle $\}$} put keylist in a group --- \index{group}|=|\meta{keylist}
4750 \end{syntax}
4751
4752 \subsubsection{Defining steps}
4753 \label{ref:defining-steps}
4754
4755 You can define your own steps, both long and short, or even redefine predefined steps. Note,
4756 though, that it is not advisable to redefine long steps, as their definitions are interdependent;
4757 redefining short steps is always ok, however, as they are never used in the code of the package.
4758
4759 \begin{syntax}
4760 \indexitem{node key>define long step}|=|\meta{name}\meta{options}\meta{nodewalk}
4761
4762 Define a long-form step named \meta{name} as equivalent to \meta{nodewalk}. \meta{options} control the exact behaviour or the defined step.
4763
4764 \let\outerleftmargin\leftmargin
4765 \begin{syntax}
4766 \item\indexdef{option of=define long step>n args}|=|\meta{number}\hfill |0|
4767 \item\indexdef{option of=define long step>make for}|=|\meta{boolean}\hfill |true|
4768
4769 Should we make a \index{for step} prefix for the step?
4770 \item\indexdef{option of=define long step>strip fake steps}|=|\meta{boolean}\hfill |true|
4771
4772 Imagine that \meta{nodewalk} ends with fake steps. Now, fake steps are usually just a computational tool, so we normally wouldn't want the current node after the walk to be one of them. As far as the outer world is concerned, we want the node to end at the last real step. However, simply appending \index{step>last valid} to our style will not work. Imagine that the nodewalk results in no steps. In this case, we'd want to remain at the origin of our empty nodewalk. However, imagine further that the (outer) step just before the empty nodewalk was fake. Then \index{step>last valid} will not step to the correct node: instead of staying at the origin, it will go to the node that the last real step prior to our nodewalk stepped to. In case there was no such real step, we'd even step to the invalid node (normally getting an error).
4773
4774 Defining the step using |strip fake steps| ensures the correct behaviour described
4775 above. Set |strip fake steps=false| only when the fake steps at the end of the nodewalk are
4776 important to you.
4777
4778 \begin{advise}
4779 \item See also nodewalk key \index{nodewalk key>strip fake steps}.
4780 \end{advise}
4781
4782 \end{syntax}
4783
4784 \begin{forestexample}[index={define long step,option of=define long step>n args,conditional>if,step>n,while,readonly option>n,next}]
4785 \forestset{
4786 ~define long step~={children from to}{n args=2}{
4787 if={#1>#2}{}{n=#1,while={n()<#2}{next}}
4788 }
4789 }
4790 \begin{forest}
4791 for children from to={2}{5}{draw}
4792 [root[1][2][3][4][5][6]]
4793 \end{forest}
4794 \end{forestexample}
4795
4796
4797 \indexitem{node key>define short step}|=|\meta{token: short step}\meta{n args}\meta{nodewalk}
4798
4799 Define short step taking $n$ arguments as the given \meta{nodewalk}. Refer to the arguments in the usual way, via |#1|, \dots.
4800
4801 To (re)define braces, |{}|, write |define short step={group}{1}{...}|.
4802
4803 \indexitem{handler>nodewalk style}|=|\meta{nodewalk}
4804
4805 \meta{nodewalk key}|/.nodewalk style=|\meta{nodewalk} is a shorthand for\\
4806 |for_nodewalk={|\meta{nodewalk key}|/.style=|\meta{nodewalk}|}{}|.
4807
4808 \end{syntax}
4809
4810
4811 \subsection{Conditionals}
4812 \label{ref:conditionals}
4813
4814 All conditionals take arguments \meta{true keylist} and \meta{false keylist}. The interpretation of
4815 the keys in these keylists depends on the environment the conditional appears in. If it is a part
4816 of a nodewalk specification, the keys are taken to be nodewalk keys (\S\ref{ref:nodewalks}),
4817 otherwise node keys (\S\ref{ref:node-keys}).
4818
4819 All the conditionals can be nested safely.
4820
4821 \begin{syntax}
4822 \indexitem{conditional>if}|=|\index{forestmath=condition}\meta{true keylist}\meta{false keylist}
4823
4824 If \index{forestmath=condition} evaluates to |true| (non-zero), \meta{true keylist} is processed (in
4825 the context of the current node); otherwise, \meta{false keylist} is processed.
4826
4827 For a detailed description of |pgfmath| expressions, see \cite[part VI]{tikzpgf2.10}. (In short:
4828 write the usual mathematical expressions.)
4829
4830 In the following example, \index{conditional>if} is used to orient the arrows from the smaller
4831 number to the greater, and to color the odd and even numbers differently. (Style |random_tree| is
4832 defined in the front page example.)
4833
4834 \forestset{random tree/.style n args={3}{% #1=max levels, #2=max children, #3=max content
4835 content/.pgfmath={random(0,#3)},
4836 if={#1>0}{repeat={random(0,#2)}{append={[,random tree={#1-1}{#2}{#3}]}}}{}}}
4837 \begin{forestexample}[index={before typesetting nodes,for step,descendants,conditional>if,content,edge,edge label,tree},index>={!},point=if]
4838 \pgfmathsetseed{314159}
4839 \begin{forest}
4840 before typesetting nodes={
4841 for descendants={
4842 if={content()>content("!u")}{edge=->}{
4843 if={content()<content("!u")}{edge=<-}{}},
4844 edge label/.wrap pgfmath arg=
4845 {node[midway,above,sloped,font=\scriptsize]{+#1}}
4846 {int(abs(content()-content("!u")))}
4847 },
4848 for tree={circle,if={mod(content(),2)==0}
4849 {fill=yellow}{fill=green}}
4850 }
4851 [,random tree={3}{3}{100}]
4852 \end{forest}
4853 \end{forestexample}
4854
4855
4856
4857
4858 \indexitem{word prefix=option>conditional>if=\meta{option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4859
4860 This simple conditional is defined for every \meta{option} (except boolean options, see below): if
4861 \meta{value} equals the value of the option at the current node, \meta{true keylist} is executed;
4862 otherwise, \meta{false keylist}.
4863
4864 \indexitem{word prefix=boolean option>conditional>if=\meta{boolean option}}|=|\meta{true keylist}\meta{false keylist}
4865
4866 Execute \meta{true keylist} if \meta{boolean option} is true; otherwise, execute \meta{false
4867 keylist}.
4868
4869 \indexitem{word prefix=toks option>conditional>if in=\meta{toks option}}|=|\meta{toks}\meta{true keylist}\meta{false
4870 keylist}
4871
4872 Checks if \meta{toks} occurs in the option value; if it does, \meta{true keylist} are executed,
4873 otherwise \meta{false keylist}.
4874
4875 This conditional is defined only for \meta{toks} options, see \S\ref{sec:option-setting}.
4876
4877
4878
4879 \indexitem[set={
4880 index format={result=if \protect\meta{dimen option}\protect\greaterthan,pgfkey},
4881 print format={result/.option=argument,+result={if\ },result+={>}, pgfkey},
4882 }]{conditional>if dimen GT=\protect\meta{dimen option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4883 \itemnosep
4884 \indexitem[set={
4885 index format={result=if \protect\meta{dimen option}<,pgfkey},
4886 print format={result/.option=argument,+result={if\ },result+={<}, pgfkey},
4887 }]{conditional>if dimen LT=\protect\meta{dimen option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4888 \itemnosep
4889 \indexitem[set={
4890 index format={result=if \protect\meta{count option}\protect\greaterthan,pgfkey},
4891 print format={result/.option=argument,+result={if\ },result+={>}, pgfkey},
4892 }]{conditional>if count GT=\protect\meta{count option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4893 \itemnosep
4894 \indexitem[set={
4895 index format={result=if \protect\meta{count option}<,pgfkey},
4896 print format={result/.option=argument,+result={if\ },result+={<}, pgfkey},
4897 }]{conditional>if count LT=\protect\meta{count option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4898 \itemnosep
4899 \indexitem[set={
4900 index format={result=if \protect\meta{dimen register}\protect\greaterthan,pgfkey},
4901 print format={result/.option=argument,+result={if\ },result+={>}, pgfkey},
4902 }]{conditional>if dimen register GT=\protect\meta{dimen register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4903 \itemnosep
4904 \indexitem[set={
4905 index format={result=if \protect\meta{dimen register}<,pgfkey},
4906 print format={result/.option=argument,+result={if\ },result+={<}, pgfkey},
4907 }]{conditional>if dimen register LT=\protect\meta{dimen register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4908 \itemnosep
4909 \indexitem[set={
4910 index format={result=if \protect\meta{count register}\protect\greaterthan,pgfkey},
4911 print format={result/.option=argument,+result={if\ },result+={>}, pgfkey},
4912 }]{conditional>if count register GT=\protect\meta{count register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4913 \itemnosep
4914 \indexitem[set={
4915 index format={result=if \protect\meta{count register}<,pgfkey},
4916 print format={result/.option=argument,+result={if\ },result+={<}, pgfkey},
4917 }]{conditional>if count register LT=\protect\meta{count register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4918
4919 If the current value of the dimen/count option/register is greater/less than or equal to
4920 \meta{value}, execute \meta{true keylist}; else, execute \meta{false keylist}.
4921
4922
4923 \indexitem{conditional>if nodewalk valid}|=|\meta{keylist: test nodewalk}\meta{true keylist}\meta{false keylist}
4924
4925 If the test nodewalk finished on a valid node, \meta{true keylist} is processed (in the context of
4926 the current node); otherwise, \meta{false keylist} is processed.
4927
4928 \indexitem{conditional>if nodewalk empty}|=|\meta{keylist: test nodewalk}\meta{true keylist}\meta{false keylist}
4929
4930 If the test nodewalk contains no (real) steps, \meta{true keylist} is processed (in the context of
4931 the current node); otherwise, \meta{false keylist} is processed.
4932
4933 \indexitem{conditional>if current nodewalk empty}|=|\meta{true keylist}\meta{false keylist}
4934
4935 If the current nodewalk contains no (real) steps, \meta{true keylist} is processed (in the context of
4936 the current node); otherwise, \meta{false keylist} is processed.
4937
4938 \indexitem{conditional>if in saved nodewalk}|=|\meta{nodewalk}\meta{toks: nodewalk name}\meta{true keylist}\meta{false keylist}
4939
4940 If the node at the end of \meta{nodewalk} occurs in the saved nodewalk, \meta{true keylist} is
4941 processed (in the context of the current node); otherwise, \meta{false keylist} is processed.
4942
4943 \indexitem{propagator>if have delayed}|=|\meta{true keylist}\meta{false keylist} If any options were
4944 delayed in the current cycle (more precisely, up to the point of the execution of this key),
4945 process \meta{true keylist}, otherwise process \meta{false keylist}. (\index{delay n} will
4946 trigger ``true'' for the intermediate cycles.)
4947
4948 This key assumes that the processing order of the innermost invocation of \index{process
4949 keylist} or \index{process keylist'} is given by \index{processing order}. If this is not
4950 the case, explicitely supply the processing order using \index{if have delayed'}.
4951
4952 \indexitem{propagator>if have delayed'}|=|\meta{nodewalk}\meta{true keylist}\meta{false keylist}
4953 Like \index{if have delayed}, but assume the processing order given by \meta{nodewalk}.
4954
4955 \end{syntax}
4956
4957
4958
4959 The following keys are shortcuts: they execute their corresponding |if ...| conditional for every
4960 node in the subtree of the current node (including the node itself). In other words:
4961
4962 \begin{center}
4963 |where ...|\meta{arg$_1$}\dots\meta{arg$_n$}|/.style={for tree={if ...=|\meta{arg$_1$}\dots\meta{arg$_n$}|}}|
4964 \end{center}
4965
4966 \begin{advise}
4967 \item Except in special circumstances, you probably don't want to embed keys from the \index{where
4968 option} family within a \index{for step=\index{tree}}, as this results in two nested loops. It
4969 is more usual to use an \index{conditional>if} family key there. For an example where using
4970 \index{where option} actually does the wrong thing, see question
4971 \href{http://tex.stackexchange.com/questions/167978/smaller-roofs-for-forest}{Smaller roofs for
4972 forest} on \TeX\ Stackexchange.
4973 \end{advise}
4974
4975 \begin{syntax}
4976 \indexitem{conditional>where}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4977 \itemnosep
4978 \indexitem{word prefix=option>conditional>where=\meta{option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4979 \itemnosep
4980 \indexitem{word prefix=boolean option>conditional>where=\meta{boolean option}}|=|\meta{true keylist}\meta{false keylist}
4981 \itemnosep
4982 \indexitem{word prefix=toks option>conditional>where in=\meta{toks option}}|=|\meta{toks}\meta{true keylist}\meta{false keylist}
4983 \itemnosep
4984 \indexitem[set={
4985 index format={result=where \protect\meta{dimen option}\protect\greaterthan,pgfkey},
4986 print format={result/.option=argument,+result={where\ },result+={>}, pgfkey},
4987 }]{conditional>where dimen GT=\protect\meta{dimen option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4988 \itemnosep
4989 \indexitem[set={
4990 index format={result=where \protect\meta{dimen option}<,pgfkey},
4991 print format={result/.option=argument,+result={where\ },result+={<}, pgfkey},
4992 }]{conditional>where dimen LT=\protect\meta{dimen option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4993 \itemnosep
4994 \indexitem[set={
4995 index format={result=where \protect\meta{count option}\protect\greaterthan,pgfkey},
4996 print format={result/.option=argument,+result={where\ },result+={>}, pgfkey},
4997 }]{conditional>where count GT=\protect\meta{count option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
4998 \itemnosep
4999 \indexitem[set={
5000 index format={result=where \protect\meta{count option}<,pgfkey},
5001 print format={result/.option=argument,+result={where\ },result+={<}, pgfkey},
5002 }]{conditional>where count LT=\protect\meta{count option}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
5003 \itemnosep
5004 \indexitem[set={
5005 index format={result=where \protect\meta{dimen register}\protect\greaterthan,pgfkey},
5006 print format={result/.option=argument,+result={where\ },result+={>}, pgfkey},
5007 }]{conditional>where dimen register GT=\protect\meta{dimen register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
5008 \itemnosep
5009 \indexitem[set={
5010 index format={result=where \protect\meta{dimen register}<,pgfkey},
5011 print format={result/.option=argument,+result={where\ },result+={<}, pgfkey},
5012 }]{conditional>where dimen register LT=\protect\meta{dimen register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
5013 \itemnosep
5014 \indexitem[set={
5015 index format={result=where \protect\meta{count register}\protect\greaterthan,pgfkey},
5016 print format={result/.option=argument,+result={where\ },result+={>}, pgfkey},
5017 }]{conditional>where count register GT=\protect\meta{count register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
5018 \itemnosep
5019 \indexitem[set={
5020 index format={result=where \protect\meta{count register}<,pgfkey},
5021 print format={result/.option=argument,+result={where\ },result+={<}, pgfkey},
5022 }]{conditional>where count register LT=\protect\meta{count register}}|=|\meta{value}\meta{true keylist}\meta{false keylist}
5023 \itemnosep
5024 \indexitem{conditional>where nodewalk valid}|=|\meta{toks: nodewalk name}\meta{true keylist}\meta{false keylist}
5025 \itemnosep
5026 \indexitem{conditional>where nodewalk empty}|=|\meta{toks: nodewalk name}\meta{true keylist}\meta{false keylist}
5027 \itemnosep
5028 \indexitem{conditional>where in saved nodewalk}|=|\meta{nodewalk}\meta{toks: nodewalk name}\meta{true keylist}\meta{false keylist}
5029 \end{syntax}
5030
5031
5032 \subsection{Loops}
5033 \label{ref:loops}
5034
5035 All loops take a \meta{keylist} argument. The interpretation of the keys in these keylists depends
5036 on the environment the loop appears in. If it is a part of a nodewalk specification,
5037 the keys are taken to be nodewalk keys (\S\ref{ref:nodewalks}), otherwise node keys
5038 (\S\ref{ref:node-keys}).
5039
5040 All loops can be nested safely.
5041
5042
5043 \begin{syntax}
5044
5045 \indexitem{loop>repeat}|=|\meta{number}\meta{keylist}
5046
5047 The \meta{keylist} is processed \meta{number} times.
5048
5049 The \meta{number} expression is evaluated using |pgfmath|.
5050
5051 \indexitem{loop>while}|=|\index{forestmath=condition}\meta{keylist}
5052 \itemnosep
5053 \indexitem{loop>do while}|=|\index{forestmath=condition}\meta{keylist}
5054 \itemnosep
5055 \indexitem{loop>until}|=|\index{forestmath=condition}\meta{keylist}
5056 \itemnosep
5057 \indexitem{loop>do until}|=|\index{forestmath=condition}\meta{keylist}
5058
5059 \keyname{while} loops cycle while the condition is true, \keyname{until} loops terminate when the
5060 condition becomes true.
5061
5062 The \keyname{do} variants check the condition after processing the \meta{keylist}; thus, the
5063 keylist is executed at least once. The variants without the \keyname{do} prefix check the
5064 condition before processing the \meta{keylist}, which might therefore not be processed at all.
5065
5066 When \index{forestmath=condition} is an empty string, condition \index{valid} is implicitely used,
5067 and \meta{keylist} is implicitely embedded in \index{nodewalk key>on invalid}|=fake|. Thus, the |while|
5068 loops will cycle until they ``walk out of the tree'', and |until| loops will cycle until they
5069 ``walk into the tree.''
5070
5071 \begin{advise}
5072 \item If a loop ``walks out of the tree'', you can get it back in using \index{step>last valid} or
5073 \index{nodewalk key>strip fake steps}.
5074 \end{advise}
5075
5076
5077 \begin{forestexample}[index={root',content,step>n,delay,for step,nodewalk,do until}]
5078 \pgfmathsetseed{1234}
5079 \begin{forest}
5080 try/.style={root',content+={#1,\ },n=#1},
5081 delay={
5082 for nodewalk={~do until~={}{try/.pgfmath={random(1,20)}},draw}{},
5083 },
5084 [tried:\ [1][2][3][4][5]]
5085 \end{forest}
5086 \end{forestexample}
5087
5088 \indexitem{loop>while nodewalk valid}|=|\meta{nodewalk}\meta{keylist}
5089 \itemnosep
5090 \indexitem{loop>do while nodewalk valid}|=|\meta{nodewalk}\meta{keylist}
5091 \itemnosep
5092 \indexitem{loop>until nodewalk valid}|=|\meta{nodewalk}\meta{keylist}
5093 \itemnosep
5094 \indexitem{loop>do until nodewalk valid}|=|\meta{nodewalk}\meta{keylist}
5095 \itemnosep
5096 \indexitem{loop>while nodewalk empty}|=|\meta{nodewalk}\meta{keylist}
5097 \itemnosep
5098 \indexitem{loop>do while nodewalk empty}|=|\meta{nodewalk}\meta{keylist}
5099 \itemnosep
5100 \indexitem{loop>until nodewalk empty}|=|\meta{nodewalk}\meta{keylist}
5101 \itemnosep
5102 \indexitem{loop>do until nodewalk empty}|=|\meta{nodewalk}\meta{keylist}
5103
5104 \meta{nodewalk} is embedded within \index{nodewalk key>on invalid}|=fake|.
5105
5106
5107 \indexitem(0){node key>break}|=|$n$ Break out of the loop.
5108
5109 The loop is only exited after all the keys in the current cycle have been processed.
5110
5111 The optional argument $n$ ($n\geq0$) specifies which level of embedding to break from; the default
5112 is to break out of the innermost loop.
5113
5114 \indexitem(0){pgfmath>forestloopcount}([$n$])
5115
5116 How many times has the loop repeated until now?
5117
5118 The optional argument $n$ ($n\geq0$) specifies the level of embedding to provide information for;
5119 the default is to count the repetitions of the current, most deeply embedded loop.
5120
5121 \end{syntax}
5122
5123
5124 \subsection{Dynamic tree}
5125 \label{ref:dynamic}
5126
5127 The following keys can be used to change the geometry of the tree by creating new nodes and
5128 integrating them into the tree, moving and copying nodes around the tree, and removing nodes from
5129 the tree.
5130
5131 The \meta{node} that will be (re)integrated into the tree can be specified in the following ways:
5132 \begin{syntax}
5133 \item \meta{empty}: uses the last non-integrated (i.e.\ created/removed/replaced) node.
5134 \begin{advise}
5135 \item This node can also be referred to using nodewalk step \index{last dynamic node}.
5136 \item The list of all such nodes is automatically saved in named nodewalk \indexdef{named
5137 nodewalk>dynamic nodes}, to be \index{load}ed when needed.
5138 \end{advise}
5139 \item \meta{node}: a new node is created using the given bracket representation (the node may
5140 contain children, i.e.\ a tree may be specified), and used as the argument to the key.
5141
5142 The bracket representation must be enclosed in brackets, which will usually be enclosed in
5143 braces to prevent them being parsed while parsing the ``host tree.''
5144 \begin{advise}
5145 \item Unlike the bracket representation in a \index{environment>forest} environment, the bracket
5146 representation of a dynamically created node \emph{must} start with |[|. Specifically, it cannot
5147 begin with a preamble or the action character.
5148 \end{advise}
5149 \item \index{relative node name}: the node \meta{relative node name} resolves to will be used.
5150 \end{syntax}
5151
5152 A dynamic tree operation is made in two steps:
5153 \begin{itemize}
5154 \item If the argument is given by a \meta{node} argument, the new node is created immediately,
5155 i.e.\ while the dynamic tree key is being processed. Any options of the new node are
5156 implicitely \index{delay}ed.
5157 \item The requested changes in the tree structure are actually made between the cycles of keylist
5158 processing.
5159 \end{itemize}
5160
5161 \begin{advise}
5162 \item Such a two-stage approach is employed because changing the tree structure during the dynamic
5163 tree key processing would lead to an unmanageable order of keylist processing.
5164 \item A consequence of this approach is that nested dynamic tree keys take several cycles to
5165 complete. Therefore, be careful when using \index{delay} and dynamic tree keys simultaneously: in
5166 such a case, it is often safer to use \index{before typesetting nodes} instead of \index{delay},
5167 see example (\ref{ex:append}), and it is also possible to define additional stages, see
5168 \S\ref{sec:workflow}.
5169 \item Examples: title page (in style |random tree|) and (\ref{ex:niceemptynodes}) (in style
5170 |xlist|).
5171 \end{advise}
5172
5173 Here is the list of dynamic tree keys:
5174
5175 \begin{syntax}
5176 \indexitem{dynamic tree>append}|=|\meta{empty}\OR|[|\meta{node}|]|\OR\meta{relative node name}
5177
5178 The specified node becomes the new final child of the current node. If the specified node had a
5179 parent, it is first removed from its old position.
5180
5181 \begin{forestexample}[label=ex:append,point=append,index={append,delay,for step,tree,readonly option>n,content,readonly option>n',repeat}]
5182 \begin{forest}
5183 before typesetting nodes={for tree={
5184 if n=1{content=L}
5185 {if n'=1{content=R}
5186 {content=C}}}}
5187 [,repeat=2{append={[
5188 ,repeat=3{append={[]}}
5189 ]}}]
5190 \end{forest}
5191 \end{forestexample}
5192
5193 \indexitem{dynamic tree>create}|=[|\meta{node}|]|
5194
5195 Create a new node. The new node becomes the last node.
5196
5197 \indexitem{dynamic tree>create'}|=[|\meta{node}|]|
5198
5199 Create a new node and process its given options immediately. The new node becomes the last node.
5200
5201 \indexitem{dynamic tree>insert after}|=|\meta{empty}\OR|[|\meta{node}|]|\OR\meta{relative node name}
5202
5203 The specified node becomes the new following sibling of the current node. If the specified node had a
5204 parent, it is first removed from its old position.
5205
5206 \indexitem{dynamic tree>insert before}|=|\meta{empty}\OR|[|\meta{node}|]|\OR\meta{relative node name}
5207
5208 The specified node becomes the new previous sibling of the current node. If the specified node had a
5209 parent, it is first removed from its old position.
5210
5211 \indexitem{dynamic tree>prepend}|=|\meta{empty}\OR|[|\meta{node}|]|\OR\meta{relative node name}
5212
5213 The specified node becomes the new first child of the current node. If the specified node had a
5214 parent, it is first removed from its old position.
5215
5216 \indexitem{dynamic tree>remove}
5217
5218 The current node is removed from the tree and becomes the last node.
5219
5220 The node itself is not deleted: it is just not integrated in the tree anymore. Removing the root
5221 node has no effect.
5222
5223 \indexitem{dynamic tree>replace by}|=|\meta{empty}\OR|[|\meta{node}|]|\OR\meta{relative node name}
5224
5225 The current node is replaced by the specified node. The current node becomes the last node.
5226
5227 If the specified node is a new node containing a dynamic tree key, it can refer to the replaced
5228 node by the \meta{empty} specification. This works even if multiple replacements are made.
5229
5230 If \keyname{replace by} is used on the root node, the ``replacement'' becomes the root node
5231 (\index{set root} is used).
5232
5233 \end{syntax}
5234
5235 If given an existing node, most of the above keys \emph{move} this node
5236 (and its subtree, of course). Below are the versions of these operations which rather \emph{copy}
5237 the node: either the whole subtree (|'|) or just the node itself (|''|).
5238 \begin{syntax}
5239 \indexitem{dynamic tree>append'}, \indexdef{dynamic tree>insert after'}, \indexdef{dynamic tree>insert before'}, \indexdef{dynamic tree>prepend'},
5240 \indexdef{dynamic tree>replace by'}
5241
5242 Same as versions without |'| (also the same arguments), but it is the copy of the specified node
5243 and its subtree that is integrated in the new place.
5244 \indexitem{dynamic tree>append''}, \indexdef{dynamic tree>insert after''}, \indexdef{dynamic tree>insert before''}, \indexdef{dynamic tree>prepend''},
5245 \indexdef{dynamic tree>replace by''}
5246
5247 Same as versions without |''| (also the same arguments), but it is the copy of the specified node
5248 (without its subtree) that is integrated in the new place.
5249
5250 \begin{advise}
5251 \item You might want to \index{delay} the processing of the copying operations, giving the
5252 original nodes the chance to process their keys first!
5253 \end{advise}
5254
5255 \indexitem{dynamic tree>copy name template}|=|\meta{empty}\OR\meta{macro definition} \hfill\meta{empty}
5256
5257 Defines a template for constructing the \index{option>name} of the copy from the name of the
5258 original. \meta{macro definition} should be either empty (then, the \index{option>name} is
5259 constructed from the \index{readonly option>id}, as usual), or an expandable macro taking one argument (the
5260 name of the original).
5261
5262 \begin{forestexample}
5263 \begin{forest}
5264 copy name template={copy of #1}
5265 [CP,delay={prepend'=subject}
5266 [VP[DP,name=subject[D][NP]][V'[V][DP]]]]
5267 \draw[->,dotted] (subject)--(copy of subject);
5268 \end{forest}
5269 \end{forestexample}
5270
5271 \indexitem{dynamic tree>set root}|=|\meta{empty}\OR|[|\meta{node}|]|\OR\meta{relative node name}
5272
5273 The specified node becomes the new \emph{formal} root of the tree.
5274
5275 Note: If the specified node has a parent, it is \emph{not} removed from it. The node becomes the
5276 root only in the sense that the default implementation of stage-processing will consider it a
5277 root, and thus typeset/pack/draw the (sub)tree rooted in this root. The processing of keys such
5278 as \index{for step=\index{step>parent}} and \index{for step=\index{root}} is not affected: \index{for step=\index{root}} finds the
5279 real, geometric root of the current node. To access the formal root, use nodewalk step
5280 \index{root'}, or the corresponding propagator \index{for step=\index{root'}}.
5281
5282 \indexitem{dynamic tree>sort}, \indexdef{dynamic tree>sort'} Sort the children of the current node,
5283 using the currently active sort key specified in \index{sort by} (see
5284 \S\ref{ref:nodewalk-operations}). |sort| sorts in ascending and |sort'| in descending order.
5285
5286 \end{syntax}
5287
5288
5289 \subsection{Handlers}
5290 \label{ref:handlers}
5291
5292 Handlers are a powerful mechanism of |pgfkeys|, documented in \citep[\S82.3.5]{tikzpgf3.0.0}.
5293 Handlers defined by \foRest; perform a computation and invoke the handled key with its result. The
5294 simple handlers are documented in this section: for \index{handler>process}, see
5295 \S\ref{ref:argument-processor}; for aggregate function handlers, see
5296 \S\ref{ref:aggregate-functions}.
5297
5298 \begin{syntax}
5299 \indexitem{handler>option}|=|\meta{option}
5300
5301 The result is the value of \meta{option} at the current node.
5302
5303 \indexitem{handler>register}|=|\meta{register}
5304
5305 The result is the value of \meta{register}.
5306
5307 \indexitem{handler>pgfmath}|=|\meta{pgfmath expression}
5308
5309 The result is the evaluation of \meta{pgfmath expression} in the context of the current node.
5310
5311 \begin{advise}
5312 \item
5313 If you only need to access an option or register value, using \index{handler>option} or
5314 \index{handler>register} is much faster than using \keyname{.pgfmath}.
5315 \end{advise}
5316
5317 \indexitem{handler>wrap value}|=|\meta{macro definition}
5318
5319 The result is the (single) expansion of the given
5320 \meta{macro definition}. The defined macro takes one parameter. The current value of the
5321 handled option will be passed as that parameter.
5322
5323 \indexitem{handler>wrap $n$ pgfmath args}|=|\meta{macro definition}\meta{arg $1$}\dots\meta{arg $n$}
5324
5325 The result is the (single) expansion of the given \meta{macro definition}. The defined macro
5326 takes $n$ parameters, where $n\in\{2,\dots,8\}$. Expressions \meta{arg $1$} to \meta{arg $n$}
5327 are evaluated using |pgfmath| and passed as arguments to the defined macro.
5328
5329 \indexitem{handler>wrap pgfmath arg}|=|\meta{macro definition}\meta{arg}
5330
5331 Like \index{wrap $n$ pgfmath args} would work for $n=1$.
5332
5333
5334 \end{syntax}
5335
5336 \subsection{Argument processor}
5337 \label{ref:argument-processor}
5338
5339 For a gentle(r) introduction to the argument processor, see \S\ref{tut:wrapping}.
5340
5341 The argument processor takes a sequence of instructions and an arbitrary number of arguments and
5342 transforms the given arguments according to the instructions. This is the generic form of a process
5343 expression:
5344
5345 \begin{syntax}
5346 \item \indexdef{meta>process} = \meta{instructions}\meta{arg $1$}\dots\meta{arg $n$}
5347 \end{syntax}
5348
5349 There are three ways to invoke the argument processor: via handler \index{handler>process}, as one
5350 of the two alternatives of a \index{forestmath} expression and recursively, by its instruction
5351 \index{processor>P}.
5352
5353 \begin{syntax}
5354
5355 \indexitem{handler>process}|=|\index{meta>process}
5356
5357 The result of the computation is passed on to the handled key as a sequence of arguments. When the
5358 argument processor is invoked this way, any number of items can be returned.\footnote{For backward
5359 compatibility, \index{handler>process} is also available as \indexdef{handler>process args}.}
5360
5361 \item \indexdef{meta>forestmath} = \meta{pgfmath}\OR|>|\index{meta>process}
5362
5363 In words, a \index{forestmath} expression is either a \meta{pgfmath} expression or an argument
5364 processor expression (\index{meta>process}) prefixed by |>|.
5365
5366 In other words, \FoRest; accepts an argument processor expression anywhere it accepts a
5367 \meta{pgfmath} expression.\footnote{The only exceptions to the above rule are handler
5368 \index{pgfmath} and argument processor instruction \index{processor>P}.} To indicate that we're
5369 providing an argument processor expression, we prefix it with |>|.
5370
5371 When the argument processor is invoked this way, it should return a single item.
5372
5373 \end{syntax}
5374
5375
5376 \begin{table}
5377 \centering
5378 \tikzexternaldisable
5379 \bracketset{action character=!}%
5380 \begin{forest}
5381 phantom,
5382 for tree={
5383 grow'=0, no edge, inner sep=0, outer sep=0,
5384 },
5385 delay={
5386 sort by={>O+t+c{content}},
5387 sort,
5388 },
5389 before typesetting nodes={
5390 for children={
5391 content={\index{processor>#1}},
5392 for children={
5393 content+={\phantom{(%)
5394 }}}}},
5395 define long step={from to}{n args=2}{
5396 tempcounta=#2,
5397 n=#1,
5398 while/.process=Rw{tempcounta}{n()<##1}{next}
5399 },
5400 draw tree stage/.style={
5401 for root'={
5402 if n children=0{% so that we don't get an error on the first run
5403 }{
5404 draw tree processing order/.nodewalk style={branch={{from to={1}{round(n_children()/3)}},tree}}, draw tree, TeX={~~},
5405 draw tree processing order/.nodewalk style={branch={{from to={1+round(n_children()/3)}{2*round(n_children()/3)}},tree}}, draw tree, TeX={~~},
5406 draw tree processing order/.nodewalk style={branch={{from to={1+2*round(n_children()/3)}{n_children()}},tree}}, draw tree,
5407 }
5408 }
5409 }
5410 [!\bigbadprocesslist]
5411 \end{forest}%
5412 \caption{Argument processor instructions}
5413 \label{tab:allargprocins}
5414 \end{table}
5415
5416
5417 The syntax of argument processor is a cross between |expl3|'s function argument specification and a
5418 Turing machine, spiced with a bit of reversed Polish notation. ;-)
5419
5420 Think of \meta{instructions} as a program and \meta{arg $1$}\dots\meta{arg $n$} as the data that
5421 this program operates on.
5422
5423 If you're familiar with Turing machines: like a Turing machine, the argument processor has a notion
5424 of a head; unlike a Turing machine, the argument processor head is positioned not over some
5425 argument, but between two arguments. If you're not familiar with Turing machines: imagine the
5426 arguments as items on a tape and the argument processor as a head that is always located between
5427 some two items. As the head is between two arguments, we can talk about the arguments on the left
5428 and the arguments on the right.
5429
5430 In general, an instruction will take some items from the left and some from the right (deleting them
5431 from the tape), perform some computation and insert the result on the tape, some result items to the
5432 left and some to the right. However, most instructions simply take an item from the right, do
5433 something with it, and put the (single-item) result to the left; in effect, the head is moved one
5434 item to the right. At the beggining, all the arguments are always on the right, so the general idea
5435 is that the program will walk through the given arguments, processing them in order.
5436
5437 Descriptions of individual instructions, given below, contain (at the right edge of the page) the
5438 argument specification, which tells us about the number of input and output items and the movement
5439 of the head. The input and output are separated by an arrow ($\longrightarrow$), and the green eye
5440 (\textcolor{darkgreen}{\eye}) signifies the position of the head with respect to the (input or
5441 output) items.
5442
5443 For example, instruction \index{processor>O}, which converts an option name into the option value,
5444 exemplifies the most common scenario: it takes one argument from the right and puts the result to
5445 the left (in other words, the head moves one item to the right). Wrapping instrucion
5446 \index{processor>w} is more complicated. Given instruction \index{processor>w}$n$, the argument
5447 processor takes one argument from the right (the wrapping macro body) and $n$ items from the left
5448 (which become the arguments of the wrapping macro), and puts the resulting item to the left.
5449 Comparisons and boolean operations are the instructions resembling the reverse Polish notation: they
5450 take the arguments from the left and put the result to the left, as well. Finally, it is worth
5451 mentioning instructions \index{processor>noop} and \index{processor>+}, which simply move the head
5452 to the right and left, respectively; given that the usual movement of the head is to the right,
5453 \index{processor>+} can be thought of as a process-the-argument-again instruction.
5454
5455
5456 Before we finally list the available instructions, some notes:
5457 \begin{itemize}
5458 \item \meta{Instructions} may be given in braces or not. If not, everything until the first opening
5459 brace is considered to be an instruction.
5460 \item An argument item (\meta{arg$_k$}) is a standard \TeX\ macro argument: either a token or a
5461 braced token list. (The obvious exception: \meta{arg$_1$} needs to be braced if it follows
5462 braceless instructions.)
5463 \item Spaces in \meta{instructions} and between arguments are ignored. Format your \index{handler>process}
5464 as you wish!
5465 \item Instructions followed by [$n$] below take an optional numeric modifier.
5466 \begin{itemize}
5467 \item The modifier should be given within the instruction string itself, immediately following the
5468 instruction. In particular, no spaces are allowed there. (Sorry for the little white lie
5469 above.) The number should not be enclosed in braces, even if it is more than one digit long.
5470 \item This modifier is always optional: its default value varies from instruction to instruction.
5471 (Providing $0$ means to use the default.)
5472 \item Unless noted otherwise, the optional numerical argument $n$ instruct the argument processor
5473 to repeat the previous instruction $n$ times (by default, 1). For example,
5474 \index{processor>O}|3| is equivalent to
5475 \index{processor>O}\index{processor>O}\index{processor>O}.
5476 \end{itemize}
5477 \end{itemize}
5478
5479 \makeatletter
5480 \NewDocumentEnvironment{indexitemprocessinstruction}{
5481 D(){} % default
5482 O{} % \index []
5483 m % instruction char
5484 o % form of instruction char, if different from #3
5485 D(){} % instruction modifiers
5486 m % first line
5487 >{\ReverseBoolean} s % typeset processor signature?
5488 >{\SplitArgument {3} {&} } m % processor signature
5489 }{%
5490 \write\@auxout{\unexpanded{\gappto\bigbadprocesslist{[{#3}[{#6}]]}}}%
5491 \IfValueTF{#4}{%
5492 \indexitem(#1)[set={form={#4},index form={#4{\protect\ \protect\rm\protect\scriptsize (#6)}},#2}]{processor>#3}#5 #6%
5493 }{%
5494 \indexitem(#1)[set={index form={#3{\protect\ \protect\rm\protect\scriptsize (#6)}},#2}]{processor>#3}#5 #6%
5495 }%
5496 \IfBooleanT{#7}{\hfill\processorsignature#8}%
5497
5498 }{}
5499 \makeatother
5500
5501 \newcommand\processorsignature[4]{%
5502 #1 \textcolor{darkgreen}{\eye} #2
5503 $\longrightarrow$
5504 #3 \textcolor{darkgreen}{\eye} #4%
5505 }
5506
5507
5508 \begin{syntax}
5509
5510 \begin{indexitemprocessinstruction}[index key=_]{noop}[\_]([$n$]){no-op}
5511 {&\meta{arg}&\meta{arg}&}
5512
5513 The argument is not processed, but simply skipped over. In other words, this instruction only
5514 moves the head one item to the right. (This is like |expl3|'s argument specifier |n|.)
5515
5516 $n$ means repetition.
5517
5518 When the end of the instructions is reached, any remaining arguments on the right are processed
5519 using this no-op instruction.
5520
5521 \end{indexitemprocessinstruction}
5522
5523 \begin{indexitemprocessinstruction}{o}([$n$]){expand \protect\emph{o}nce}
5524 {&\meta{arg}&\meta{result}&}
5525
5526 \meta{arg} is expanded once. (This is like |expl3|'s argument specifier |o|).
5527
5528 The operation is repeated $n$ times (default, one) without moving the head between the
5529 repetition. For example, |o3| expands the argument three times (and then moves the head right).
5530 \end{indexitemprocessinstruction}
5531
5532 \begin{indexitemprocessinstruction}{x}{fully e\protect\emph{x}pand}
5533 {&\meta{arg}&\meta{result}&}
5534
5535 \meta{arg} is fully expanded using |\edef|. (This is like |expl3|'s argument specifier |x|.)
5536 \end{indexitemprocessinstruction}
5537
5538 \begin{indexitemprocessinstruction}{O}([$n$]){\protect\emph{o}ption}
5539 {&\meta{option}&\meta{result}&}
5540
5541 \meta{option}=\alternative{\meta{option name},\meta{relative node name}\texttt{.}\meta{option name}}
5542
5543 In the former case, \meta{result} is the value of option at the current node, in the latter, the
5544 value of option at the node referred to by \meta{relative node name}.
5545
5546 $n$ means repetition.
5547
5548 \end{indexitemprocessinstruction}
5549
5550 \begin{indexitemprocessinstruction}{R}([$n$]){\protect\emph{r}egister}
5551 {&\meta{register}&\meta{result}&}
5552
5553 \meta{result} is the value of register \meta{register}.
5554
5555 $n$ means repetition.
5556
5557 \end{indexitemprocessinstruction}
5558
5559 \begin{indexitemprocessinstruction}{p}([$n$]){\protect\emph{p}rocess}
5560 {&\index{meta>process}&\meta{result}&}
5561
5562 Execute an embedded call of the argument processor.
5563 The embedded argument processor may return any number of items.
5564
5565 $n$ means repetition.
5566
5567 \begin{forestexample}[index={processor>p,processor>O,processor>w,processor>noop,grow',forked edges,content,handler>process}]
5568 \begin{forest}
5569 grow'=0, phantom,
5570 delay={for children={
5571 content/.process={_O= ? ~p~}
5572 {}{content}
5573 {_{No content was given, so there's nothing to do.}}
5574 {Ow1{content}{We have content (##1), so we compute:
5575 $##1+42=\the\numexpr ##1+42$}}
5576 }}
5577 [[][3][][5]]
5578 \end{forest}
5579 \end{forestexample}
5580
5581
5582 \end{indexitemprocessinstruction}
5583
5584 \begin{indexitemprocessinstruction}{P}([$n$]){\protect\emph{p}gfmath}
5585 {&\meta{pgfmath}&\meta{result}&}
5586
5587 \meta{result} is the result of evaluating \meta{pgfmath expr} using |\pgfmathparse|.
5588
5589 $n$ means repetition.
5590
5591 Combining \index{processor>P} and \index{processor>w}, \index{handler>process} is capable of anything
5592 \index{wrap $n$ pgfmath args} can do. Even better, as we can combine pgfmath and non-pgfmath
5593 methods, computations that use \index{handler>process} can be (much!) faster. Study the following
5594 examples to see how less and less pgfmath is used to achieve the same result --- but note that
5595 such extreme antipgfmathism probably only makes sense for style/package developers in computations
5596 that get performed many times.
5597
5598 \begin{forestexample}[index={handler>process,processor>w,processor>O,processor>W,processor>P,processor>+}]
5599 \begin{forest}
5600 [,grow'=east, where level=1{}{phantom,ignore,ignore edge}
5601 [(a),delay={content/.wrap 4 pgfmath args={#1 $#2*#3=#4$}
5602 {content}{content("!1")}{content("!2")}{int(content("!1")*content("!2"))}}
5603 [6][7]]
5604 [(b),delay={content/.process={O OO~P~ w4}
5605 {content}
5606 {!1.content}{!2.content}{int(content("!1")*content("!2"))}
5607 {#1 $#2*#3=#4$}}
5608 [6][7]]
5609 [(c),delay={content/.process={O OO ~W2+P~ w4}
5610 {content}
5611 {!1.content}{!2.content}{int(#1*#2)}
5612 {#1 $#2*#3=#4$}}
5613 [6][7]]
5614 [(d),delay={content/.process={O OO ~W2+n~ w4}
5615 {content}
5616 {!1.content}{!2.content}{#1*#2}
5617 {#1 $#2*#3=#4$}}
5618 [6][7]]
5619 ]
5620 \end{forest}
5621 \end{forestexample}
5622
5623
5624 \end{indexitemprocessinstruction}
5625
5626 \begin{indexitemprocessinstruction}{n}([$n$]){\protect\emph{n}umexpr}
5627 {&\meta{numexpr}&\meta{result}&}
5628
5629 \meta{result} is the result of evaluating \meta{dimexpr} using e\TeX's |\number\numexpr|.
5630
5631 $n$ means repetition.
5632
5633 \end{indexitemprocessinstruction}
5634
5635 \begin{indexitemprocessinstruction}{d}([$n$]){\protect\emph{d}imexpr}
5636 {&\meta{dimexpr}&\meta{result}&}
5637
5638 \meta{result} is the result of evaluating \meta{dimexpr} using e\TeX's |\the\dimexpr|.
5639
5640 $n$ means repetition.
5641
5642 \end{indexitemprocessinstruction}
5643
5644 \begin{indexitemprocessinstruction}{+}([$n$]){chain instructions}
5645 {\meta{arg}&&&\meta{arg}}
5646
5647 This action allows one to ``process the same argument more than once''. It does not process the
5648 current argument (in fact, there need not be any current argument), but rather moves the last
5649 result back in the argument queue. In other words, our machine's head moves one step left. You
5650 can also imagine it as an inverse of \index{processor>noop}.
5651
5652 $n$ means repetition.
5653
5654 \end{indexitemprocessinstruction}
5655
5656 \begin{forestexample}[index={handler>process,processor>O,processor>noop}]
5657 \begin{forest}
5658 test/.style n args={3}{align=center,
5659 content={The value of my option \texttt{#1} is \texttt{#2}.\\#3}}
5660 [~fit~,delay={test/.process={O ~O+O~}{content}~{content}~{Yes it is!}}]
5661 \end{forest}
5662 \end{forestexample}
5663
5664
5665 \begin{indexitemprocessinstruction}{w}([$n$]){(consuming) \protect\emph{w}rap}
5666 {\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&\meta{macro body}&\meta{result}&}
5667 \end{indexitemprocessinstruction}
5668 \itemnosep[2pt]
5669 \begin{indexitemprocessinstruction}{W}([$n$]){(non-consuming) \protect\emph{w}rap}
5670 {\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&\meta{macro body}&
5671 \meta{arg$_{1}$}\dots\meta{arg$_{n}$}\meta{result}&}
5672
5673 Defines a temporary macro with $n$ undelimited arguments using the \meta{macro body} given on the
5674 right and expands it (once). The arguments given to the temporary macro are taken from the left:
5675 \meta{arg$_{1}$}\dots\meta{arg$_{n}$}. The result of the expansion is stored as \meta{result} to
5676 the right.
5677
5678 With |w|, \meta{arg$_{1}$}\dots\meta{arg$_{n}$} are ``consumed'', i.e.\ they are removed from the
5679 result list on the left. |W| keeps \meta{arg$_{1}$}\dots\meta{arg$_{n}$} in the result list.
5680
5681 Default $n$ is 1. (Specifying $n>9$ raises an error.)
5682 \end{indexitemprocessinstruction}
5683
5684 \begin{indexitemprocessinstruction}[index key=\&]{and}[\&]([$n$]){boolean ``and''}*{}
5685 \end{indexitemprocessinstruction}
5686 \itemnosep[2pt]
5687 \begin{indexitemprocessinstruction}[index key=\&or]{or}[\protect\indexpipe]([$n$]){boolean ``or''}
5688 {\protect\meta{arg$_{1}$}\protect\meta{arg$_{2}$}&&\meta{result}&}
5689
5690 \meta{result} is a boolean conjunction/disjunction of $n$ arguments. The arguments are taken from
5691 the left. They should be numbers (positive integers): |0| means false, any other number means
5692 true. The \meta{result} is always |0| or |1|.
5693
5694 Default $n$ is 2.
5695 \end{indexitemprocessinstruction}
5696
5697 \begin{indexitemprocessinstruction}[index key=!]{not}[!]{boolean ``not''}
5698 {\meta{arg}&&\meta{result}&}
5699
5700 \meta{result} is a boolean negation of the argument. The argument is taken from the left. It
5701 should be a number (positive integer): |0| means false, any other number means true. The
5702 \meta{result} is always |0| or |1|.
5703 \end{indexitemprocessinstruction}
5704
5705 \begin{indexitemprocessinstruction}{?}{conditional (if \protect\dots\ then \protect\dots\ else)}
5706 {\meta{condition}&\meta{true arg}\meta{false arg}&&\meta{result}}
5707
5708 \meta{result} is \meta{true arg} is \meta{condition} is true (non-zero), otherwise \meta{false
5709 arg}.
5710
5711 The condition is taken from the left. The true and false arguments are expected on the right,
5712 where the winner is left as well.
5713 \end{indexitemprocessinstruction}
5714
5715 \begin{indexitemprocessinstruction}[index key={=}]{equal}[=]{comparison: $\protect\meta{arg$_{1}$}=\protect\meta{arg$_{2}$}$?}*{}
5716 \end{indexitemprocessinstruction}
5717 \itemnosep[1pt]
5718 \begin{indexitemprocessinstruction}[index key={<}]{lt}[<]{comparison: $\protect\meta{arg$_{1}$}<\protect\meta{arg$_{2}$}$?}*{}
5719 \end{indexitemprocessinstruction}
5720 \itemnosep[1pt]
5721 \begin{indexitemprocessinstruction}[index key={<<}]{gt}[\protect\greaterthan]{comparison: $\protect\meta{arg$_{1}$}\protect\greaterthan\protect\meta{arg$_{2}$}$?}
5722 {\meta{arg$_{1}$}\meta{arg$_{2}$}&&\meta{result}&}
5723
5724 Compare \meta{arg$_{1}$} and \meta{arg$_{2}$}, returning |1| (true) if \meta{arg$_{1}$} is equal
5725 to / less than / greater than \meta{arg$_{2}$}, |0| (false) otherwise.
5726
5727 The arguments are taken from the left. They can be either numbers, dimensions, text or token
5728 lists. Both arguments are expected to be of the same type. The type of comparison is determined
5729 by the type of the result returned by the last instruction.
5730 \index{processor>O}/\index{processor>R} look up the type of option/register to determine the type
5731 (booleans are numbers and keylists are toks). Text type must be marked explicitely using
5732 \index{processor>t}.
5733
5734 Comparison is carried out using |\ifnum| for numbers, |\ifdim| for dimensions (this includes
5735 unitless decimals returned by pgfmath) and |\pdfstrcmp|\footnote{\texttt{\string\pdfstrcmp}
5736 expands its arguments.} for text --- for these three types, all three comparison operators are
5737 supported. For generic token lists, only |=| makes sense and is carried out using |\ifx|.
5738
5739 In the following example, (a) performs lexicographical comparison because we have marked |21| as
5740 text; (b) and (c) perform numeric comparison: in (b), the type is automatically determined from
5741 the type of register \indexex{tempcounta}, in (c) |21| is marked manually using \index{processor>n}.
5742
5743 \begin{forestexample}[index={if,processor>gt,processor>lt}]
5744 \forestset{
5745 tempcounta=100,
5746 TeX/.process={Rw1}{tempcounta}{$#1>21$?\ },
5747 TeX={(a)\ }, if={>{Rt>}{tempcounta}{21}}{TeX=yes}{TeX=no},TeX={,\ },
5748 TeX={(b)\ }, if={>{_R<}{21}{tempcounta}}{TeX=yes}{TeX=no},TeX={,\ },
5749 TeX={(c)\ }, if={>{Rn>}{tempcounta}{21}}{TeX=yes}{TeX=no},
5750 }
5751 \end{forestexample}
5752
5753 \end{indexitemprocessinstruction}
5754
5755 \begin{indexitemprocessinstruction}{t}{mark as \protect\emph{t}ext}
5756 {&\meta{arg}&\meta{arg}&}
5757
5758 The result is not changed, only its type is changed to text. This is relevant only for
5759 comparisons --- both argument processor's comparisons \index{processor>equal}, \index{processor>gt}
5760 and \index{processor>lt} and sort keys (see \index{sort by}).
5761 \end{indexitemprocessinstruction}
5762
5763 \begin{indexitemprocessinstruction}{c}{to lowercase}
5764 {&\meta{arg}&\meta{result}&}
5765 \end{indexitemprocessinstruction}
5766
5767 \begin{indexitemprocessinstruction}{C}{to uppercase}
5768 {&\meta{arg}&\meta{result}&}
5769 \end{indexitemprocessinstruction}
5770
5771 \begin{indexitemprocessinstruction}{-}{toggle ascending/descending order (negate)}
5772 {\meta{arg}&&\meta{result}&}
5773
5774 If the argument is of the text type, its sorting order is changed from ascending to descending or
5775 vice versa.
5776
5777 For any numerical argument type (number, dimension, unitless dimension), the argument is actually
5778 negated, which obviously has the same effect on sorting.
5779
5780 For generic type arguments, this operation is a no-op.
5781 \end{indexitemprocessinstruction}
5782
5783 \begin{indexitemprocessinstruction}{u}{\protect\emph{u}ngroup}
5784 {&\meta{arg}&&\meta{item$_1$}\dots\meta{item$_n$}}
5785
5786 As every \TeX\ undelimited macro argument, \meta{arg} is a list of tokens or braced token lists.
5787 This instruction puts those items back to the right as ``separate arguments''.
5788 \end{indexitemprocessinstruction}
5789
5790 \begin{indexitemprocessinstruction}{s}([$n$]){(consuming) \protect\emph{s}ave}
5791 {\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&&&}
5792 \end{indexitemprocessinstruction}
5793 \itemnosep[2pt]
5794 \begin{indexitemprocessinstruction}{S}([$n$]){(non-consuming) \protect\emph{s}ave}
5795 {\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&&\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&}
5796
5797 Saves the last $n$ arguments from the left into a ``special place''.
5798
5799 With |s|, \meta{arg$_{1}$}\dots\meta{arg$_{n}$} are ``consumed'', i.e.\ they are removed from the
5800 result list on the left. |S| keeps \meta{arg$_{1}$}\dots\meta{arg$_{n}$} in the result list.
5801
5802 Default $n$ is 1.
5803 \end{indexitemprocessinstruction}
5804
5805 \begin{indexitemprocessinstruction}{l}([$n$]){(consuming) \protect\emph{l}oad}
5806 {&&\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&}
5807 \end{indexitemprocessinstruction}
5808 \itemnosep[2pt]
5809 \begin{indexitemprocessinstruction}{L}([$n$]){(non-consuming) \protect\emph{l}oad}
5810 {&&\meta{arg$_{1}$}\dots\meta{arg$_{n}$}&}
5811
5812 Loads last $n$ arguments from the ``special place'' to the left.
5813
5814 With |l|, \meta{arg$_{1}$}\dots\meta{arg$_{n}$} are ``consumed'', i.e.\ they are removed from the
5815 special place. |S| keeps \meta{arg$_{1}$}\dots\meta{arg$_{n}$} in the special place.
5816
5817 The default $n$ is 0 and indicates that the entire special place should be loaded.
5818 \end{indexitemprocessinstruction}
5819
5820 \begin{indexitemprocessinstruction}{r}{\protect\emph{r}everse (key)list}
5821 {&\meta{list}&\meta{result}&}
5822
5823 \meta{list} should be a comma-separated list (\emph{not} a name of a keylist option or register).
5824 \meta{result} contains the same elements in the reverse order.
5825 \end{indexitemprocessinstruction}
5826
5827 \end{syntax}
5828
5829
5830
5831
5832
5833 \subsection{Aggregate functions}
5834 \label{ref:aggregate-functions}
5835
5836 Aggregate functions walk a nodewalk and use the information found in the visited nodes to calculate
5837 something.
5838
5839 All aggregate functions are available both as key handlers and |pgfmath| functions.
5840
5841
5842
5843 \begin{syntax}
5844 \indexitem{aggregate>count}|=|\meta{nodewalk},
5845 \indexdef[form={aggregate_count}]{pgfmath>aggregate count}|("|\meta{nodewalk}|")|
5846
5847 Store the number of nodes visited in the nodewalk into the handled option.
5848
5849 \indexitem{aggregate>sum}|=|\index{forestmath}\meta{nodewalk},
5850 \indexdef[form={aggregate_sum}]{pgfmath>aggregate sum}|("|\index{forestmath}|","|\meta{nodewalk}|")|
5851 \itemnosep
5852
5853 \indexitem{aggregate>average}|=|\index{forestmath}\meta{nodewalk},
5854 \indexdef[form={aggregate_average}]{pgfmath>aggregate average}|("|\index{forestmath}|","|\meta{nodewalk}|")|
5855 \itemnosep
5856
5857 \indexitem{aggregate>product}|=|\index{forestmath}\meta{nodewalk},
5858 \indexdef[form={aggregate_product}]{pgfmath>aggregate product}|("|\index{forestmath}|","|\meta{nodewalk}|")|
5859 \itemnosep
5860
5861 \indexitem{aggregate>min}|=|\index{forestmath}\meta{nodewalk},
5862 \indexdef[form={aggregate_min}]{pgfmath>aggregate min}|("|\index{forestmath}|","|\meta{nodewalk}|")|
5863 \itemnosep
5864
5865 \indexitem{aggregate>max}|=|\index{forestmath}\meta{nodewalk},
5866 \indexdef[form={aggregate_max}]{pgfmath>aggregate max}|("|\index{forestmath}|","|\meta{nodewalk}|")|
5867
5868 Calculate the value of the given \index{forestmath} expression at each visited node. Store the sum /
5869 average / product / minimum / maximum of these values into the handled option (handlers) or return
5870 it (pgfmath functions).
5871
5872 \indexitem{aggregate>aggregate}|=|\index{forestmath=start value}\index{forestmath=every
5873 step}\index{forestmath=after walk}\meta{nodewalk}
5874 \itemnosep
5875 \indexitem{pgfmath>aggregate}|("|\index{forestmath=start value}|","|\index{forestmath=every step}|","|\index{forestmath=after walk}|","|\meta{nodewalk}|")|
5876
5877 The generic aggregate function. First, register \index{aggregate result} is set to
5878 \index{forestmath=start value}. Then, the given nodewalk is walked. After each step of the
5879 \meta{nodewalk}, \index{forestmath=every step} expression is evaluated in the context of the new
5880 current node and stored into \index{aggregate result}. After the walk, the current node is reset to
5881 the origin. \index{forestmath=after walk} expression is then evaluated in its context and stored
5882 into \index{aggregate result} as the final result.
5883
5884 Use \index{aggregate result} and \index{aggregate n} in the \index{forestmath} expressions to refer to
5885 the current result value and step number.
5886
5887 \indexitem{register>aggregate n}|=|\meta{count} the current step number
5888
5889 In the every-step expression of an aggregate function, refers to the (real) step number in the
5890 aggregate's \meta{nodewalk}. In the after-walk expression, refers to the total number of (real)
5891 steps made.
5892
5893 \indexitem{register>aggregate result}|=|\meta{toks} the current value of the result
5894
5895 This register is where the intermediate results are stored.
5896
5897 \indexitem{register>aggregate value}|=|\meta{toks} the value of the expression at the current node
5898
5899 This only applies to special aggregates like \index{aggregate>sum}, not to the generic
5900 \index{aggregate>aggregate}.
5901
5902 \indexitem{node key>aggregate postparse}|=|\alternative{none,int,print,macro}
5903
5904 Roughly speaking, how should the result be formatted? For details, see \citep[\S89]{tikzpgf3.0.0}.
5905 Applies only to |pgfmath| versions of aggregate functions, i.e.\ not to the |'| variants.
5906
5907 \begin{syntax}
5908 \item\indexdef{value of=aggregate postparse>none}
5909 No formatting.
5910 \item\indexdef{value of=aggregate postparse>int}
5911 The result is an integer.
5912 \item\indexdef{value of=aggregate postparse>print}
5913 Use |pgf|'s number printing extension, see \citep[\S93]{tikzpgf3.0.0}.
5914 \item\indexdef{value of=aggregate postparse>macro}
5915 Use a custom macro. Specify the macro using \indexdef{node key>aggregate postparse macro}|=|\meta{cs}.
5916 \end{syntax}
5917
5918 \end{syntax}
5919
5920 Example 1. Randomly generate the content of leaves. The content of a parent is the sum of its
5921 children's content. Note how we use \indexex{tree children-first} to proceed in a bottom-up
5922 fashion.
5923
5924 \begin{forestexample}[index={delay,aggregate postparse,for step,tree children-first,if option,n children,content,pgfmath,sum,step>children}]
5925 \begin{forest}
5926 delay={
5927 aggregate postparse=int,
5928 for tree children-first={
5929 if n children=0
5930 {content/.pgfmath={random(0,100)}}
5931 {content/~.sum~={content}{children}}
5932 }
5933 }
5934 [[[[][]][]][[][][[][][]]][[][[][]]]]
5935 \end{forest}
5936 \end{forestexample}
5937
5938 Example 2: nested aggregate functions. We are given the black numbers. The inner aggregate, the
5939 sum of children, is applied at every blue node. (See how we actually display the blue numbers by
5940 storing \index{aggregate value} to \index{content}.) The outer aggregate stores the maximum blue
5941 number into the red root.
5942
5943 \begin{forestexample}
5944 \begin{forest}
5945 delay={
5946 aggregate postparse=int,
5947 content/~.max~=%
5948 {~aggregate_sum~("content","children")}%
5949 {every step={content/.register=~aggregate value~},children}%
5950 } [ [[1][2][3]] [[3][4][5]] [[2][3][4]] ]
5951 \end{forest}
5952 \end{forestexample}
5953
5954 Example 3: calculate root mean square of children using the generic \index{aggregate>aggregate} handler.
5955
5956 \begin{forestexample}
5957 \begin{forest}
5958 delay={
5959 content/~.aggregate~=
5960 {0}{~aggregate_result~()+content()^2}{sqrt(~aggregate_result~/~aggregate_n~)}
5961 {children}
5962 }
5963 [[0][1][2][3][4]]
5964 \end{forest}
5965 \end{forestexample}
5966
5967 \subsection{Relative node names}
5968 \label{ref:relative-node-names}
5969
5970 \begin{syntax}
5971 \indexitem{meta>relative node name}|=|[\meta{forest node name}][\indexdef[set={code}]>{!}\meta{nodewalk}]
5972
5973 \meta{relative node name} refers to the \foRest; node at the end of the \meta{nodewalk}
5974 starting at node named \meta{forest node name}. If \meta{forest node name} is omitted, the walk
5975 starts at the current node. If \meta{nodewalk} is omitted, the ``walk'' ends at the start
5976 node. (Thus, an empty \meta{relative node name} refers to the current node.)
5977
5978 The \meta{nodewalk} inherits its history from the outer nodewalk (if there is one). Its every-step
5979 keylist is empty.
5980 \end{syntax}
5981
5982 Relative node names can be used in the following contexts:
5983 \begin{itemize}
5984 \item \FoRest;'s |pgfmath| option functions (\S\ref{ref:pgfmath}) take a relative node name as
5985 their argument, e.g.\ |content("!u")| and |content("!parent")| refer to the content of the
5986 parent node.
5987 \item An option of a non-current node can be set by \meta{relative node name}|.|\meta{option
5988 name}|=|\meta{value}, see \S\ref{sec:option-setting}.
5989 \item The |forest| coordinate system, both explicit and implicit; see \S\ref{ref:forest-cs}.
5990 \end{itemize}
5991
5992 \subsection{The \texttt{forest} coordinate system}
5993 \label{ref:forest-cs}
5994
5995 Unless package options \index{tikzcshack} is set to |false|, \TikZ;'s implicit node coordinate
5996 system \citep[\S13.2.3]{tikzpgf2.10} is hacked to accept relative node names.\footnote{Actually,
5997 the hack can be switched on and off on the fly, using \cmdname{i}\keyname{foresttikzcshack}.}.
5998
5999 The explicit \texttt{forest} coordinate system is called simply |forest| and used like this:
6000 |(forest_cs:|\meta{forest cs spec}|)|; see \citep[\S13.2.5]{tikzpgf2.10}. \meta{forest cs spec}
6001 is a keylist; the following keys are accepted.
6002
6003 \begin{syntax}
6004 \indexitem{forest cs>name}|=|\meta{node name} The node with the given name becomes the current node. The
6005 resulting point is its (node) anchor.
6006 \indexitem{forest cs>id}|=|\meta{node id} The node with the given name becomes the current node. The
6007 resulting point is its (node) anchor.
6008 \indexitem{forest cs>go}|=|\meta{nodewalk} Walk the given nodewalk, starting at the current node. The
6009 node at the end of the walk becomes the current node. The resulting point is its (node) anchor.
6010 The embedded \meta{nodewalk} inherits history from the outer nodewalk.
6011 \indexitem{forest cs>anchor}|=|\meta{anchor} The resulting point is the given anchor of the current node.
6012 \indexitem{forest cs>l}|=|\meta{dimen} \vspace{-\parskip}
6013 \indexitem{forest cs>s}|=|\meta{dimen} Specify the \index{option>l} and \index{option>s}
6014 coordinate of the resulting point.
6015
6016 The coordinate system is the node's ls-coordinate system: its origin is at its (node) anchor; the
6017 l-axis points in the direction of the tree growth at the node, which is given by option
6018 \index{grow}; the s-axis is orthogonal to the l-axis; the positive side is in the
6019 counter-clockwise direction from |l| axis.
6020
6021 The resulting point is computed only after both \index{option>l} and \index{option>s} were given.
6022 \item Any other key is interpreted as a \index{relative node name}[.\meta{anchor}].
6023 \end{syntax}
6024
6025
6026 \subsection{Anchors}
6027 \label{sec:anchors}
6028
6029 \FoRest; defines several anchors which can be used with any \TikZ; node belonging to a \FoRest;
6030 tree (manually added \TikZ; nodes are thus excluded).
6031
6032 \newcommand\indexdefneganchor[1]{\indexdef[index key=#1]{anchor>-#1}}
6033 \begin{syntax}
6034 \indexitem{anchor>parent anchor}\itemnosep
6035 \indexitem{anchor>child anchor}\itemnosep
6036 \indexitem{anchor>anchor}
6037
6038 These anchors point to coordinates determined by node options \index{option>parent anchor},
6039 \index{option>child anchor} and \index{option>anchor}.
6040
6041 \indexitem{anchor>parent}, \indexdef{anchor>parent'}, \indexdefneganchor{parent}, \indexdefneganchor{parent'}\itemnosep
6042 \indexitem{anchor>parent first}, \indexdef{anchor>parent first'}, \indexdefneganchor{parent first}, \indexdefneganchor{parent first'}\itemnosep
6043 \indexitem{anchor>first}, \indexdef{anchor>first'}\itemnosep
6044 \indexitem{anchor>children first}, \indexdef{anchor>children first'}, \indexdefneganchor{children first}, \indexdefneganchor{children first'}\itemnosep
6045 \indexitem{anchor>children}, \indexdef{anchor>children'}, \indexdefneganchor{children}, \indexdefneganchor{children'}\itemnosep
6046 \indexitem{anchor>children last}, \indexdef{anchor>children last'}, \indexdefneganchor{children last}, \indexdefneganchor{children last'}\itemnosep
6047 \indexitem{anchor>last}, \indexdef{anchor>last'}\itemnosep
6048 \indexitem{anchor>parent last}, \indexdef{anchor>parent}, \indexdefneganchor{parent last},\indexdefneganchor{parent last'}
6049
6050 Growth direction based anchors.
6051
6052 \TikZ;'s ``compass anchors'' |east|, |north| etc.\ resolve to coordinates on the border of the
6053 node facing east, north etc.\ (for the shapes that define these anchors). The above \FoRest;'s
6054 anchors are similar in that they also resolve to coordinates on the border of the node. However,
6055 the ``cardinal directions'' are determined by the \index{grow}th direction of the tree in the node
6056 and its parent:
6057
6058 \begin{itemize}
6059 \item anchor |parent| faces the parent node (or, in case of the root, where the parent would be);
6060 \item anchor |children| faces the children (or, in case of a node without children, where the children would be);
6061 \item anchor |first| faces the first child (or \dots\ you get it, right?);
6062 \item anchor |last| faces the last child (or \dots\ you know!).
6063 \end{itemize}
6064 Combinations like |children_first| work like combinations of compass directions, e.g.\
6065 |north_west|, but note that
6066 \begin{itemize}
6067 \item when |first| and |last| are combined with |parent| into |parent_first| and |parent_last|,
6068 they refer to the first and last child of the parent node, i.e.\ siblings of the current node.
6069 \end{itemize}
6070
6071 While |first| and |last| always point in opposite directions, |parent| and |children| do not do so
6072 if the \index{grow}th direction of the tree changes in the node, i.e.\ if the node's \index{grow}
6073 differs from it's parent's \index{grow}. Thus in general, it is useful to have anchors |-parent|
6074 and |-children|, which point in the opposite directions as |parent| and |children|, respectively,
6075 and their combinations with |first| and |last|.
6076
6077 The |'| variants refer precisely to
6078 the point where the cardinal growth direction intersects the border. Variants without |'| snap to
6079 the closest compass anchor of the node.
6080
6081 These anchors work as expected even if the node is \index{rotate}d, or if the
6082 children are \index{reversed}.
6083
6084 For simple examples, see definitions of \index{sn edges} and \index{roof}; for more involved
6085 examples, see the \reflibrary{edges} library.
6086 \end{syntax}
6087
6088 \begin{forestexample}[layout=tree on top]
6089 \def\redorblue#1{\expandafter\redorbluei#1\END}%
6090 \def\redorbluei#1#2\END{\expandafter\ifx#1-red\else blue\fi}%
6091 \forestset{
6092 draw anchors/.style n args=3{% #1=above, #2=below, #3='-variant of anchor?
6093 tikz={
6094 \foreach \a in {first,last,parent first,parent last,children,children last,#1}
6095 {\fill[](.\a#3)circle[radius=1pt] node[above,font=\tiny,color=\redorblue\a]{\a#3};}
6096 \foreach \a in {-parent first,-parent,-parent last,-children,-children first,#2}
6097 {\fill[](.\a#3)circle[radius=1pt] node[below,font=\tiny,color=\redorblue\a]{\a#3};}
6098 }
6099 },
6100 draw anchors/.default={parent,children first}{-children last}{},
6101 }
6102 \begin{forest}
6103 for tree={
6104 minimum width=10em, minimum height=13ex, s sep+=5em,
6105 draw, draw anchors,
6106 font=\tt, delay={content/.process=OOw2{grow}{reversed}{grow\ifnum#2=1'\fi=#1}}
6107 }
6108 [
6109 [,rotate=20,draw anchors={parent,children first}{-children last}{'}]
6110 [,for tree={grow'=0}, l sep+=5em, draw anchors={-children last}{parent,children first}{}
6111 [,rotate=-60]
6112 []
6113 ]
6114 ]
6115 \end{forest}
6116 \end{forestexample}
6117
6118 \subsection{Additional \texttt{pgfmath} functions}
6119 \label{ref:pgfmath}
6120
6121 For every option and register, \foRest; defines a |pgfmath| function with the same name, with the
6122 proviso that the name might be mangled in order to conform to |pgfmath|'s naming rules. Specifically,
6123 all non-alphanumeric characters in the option/register name and the initial number, if
6124 the name starts with one, are replaced by an underscore |__| in the |pgfmath| function name.
6125
6126 Pgfmath functions corresponding to options take one argument, a \index{relative node name}
6127 (see~\S\ref{ref:relative-node-names}) expression, making it possible to refer to option values of
6128 non-current nodes. The \meta{relative node name} expression must be enclosed in double quotes in
6129 order to
6130 prevent pgfmath evaluation: for example, to refer to the content of the parent, write
6131 \index{content}|("|\index>{!}|u")|. To refer to the option of the current node, use empty parentheses:
6132 \index{content}|()|.\footnote{In most cases, the parentheses are optional, so \texttt{content}
6133 is ok. A known case where this doesn't work is preceding an operator: \texttt{l+1cm} will fail.}
6134
6135 If the \index{relative node name} resolves to the invalid node, these functions will an return empty
6136 token list (for \meta{toks} options), 0pt (for \meta{dimen} options) or 0 (for \meta{count}
6137 options).
6138
6139 Note that the nodewalk in the relative node name inherits its history from the outer nodewalk (if
6140 there is one), so strange but useful constructions like the following are possible.
6141
6142 \begin{forestexample}[index={tikz,wrap pgfmath arg,nodewalk,back,b,ancestors,register>every step}]
6143 \begin{forest}
6144 for tree={no edge},
6145 before typesetting nodes={
6146 for nodewalk={
6147 c,
6148 every step={
6149 tikz/.wrap pgfmath arg=
6150 {\draw[<-] ()--(#1);}
6151 {name("~!b~")}
6152 },
6153 21{up1},ancestors
6154 }{}
6155 },
6156 [1[2[3]][4[5]]]
6157 \end{forest}
6158 \end{forestexample}
6159
6160 Boolean function \indexdef{pgfmath>valid} returns true if the node's \index{readonly option>id}$\neq0$, i.e.\ if the node is a real, valid node; see \S\ref{ref:spatial-propagators} and \S\ref{ref:nodewalks}. Boolean function \indexdef{pgfmath>invalid} is a negation of |valid|.
6161
6162 \begin{syntax}
6163 \indexitem{pgfmath>min_l}|=(|\meta{nodewalk: node}|,|\meta{nodewalk: context node}|)| \itemnosep
6164 \indexitem{pgfmath>min_s}|=(|\meta{nodewalk: node}|,|\meta{nodewalk: context node}|)| \itemnosep
6165 \indexitem{pgfmath>max_l}|=(|\meta{nodewalk: node}|,|\meta{nodewalk: context node}|)| \itemnosep
6166 \indexitem{pgfmath>max_s}|=(|\meta{nodewalk: node}|,|\meta{nodewalk: context node}|)|
6167
6168 These functions return the minimum/maximum value of \index{option>l}/\index{option>s} of node at the end of \meta{nodewalk:
6169 node} in the context (i.e.\ growth direction) of node at the end of \meta{nodewalk: context
6170 node}.
6171 \end{syntax}
6172
6173 Three string functions are also added to |pgfmath|: \indexdef{pgfmath>strequal} tests the equality of
6174 its two arguments; \indexdef{pgfmath>instr} tests if the first string is a substring of the second one;
6175 \indexdef{pgfmath>strcat} joins an arbitrary number of strings.
6176
6177 \bigskip
6178
6179 Some random notes on |pgfmath|: \begin{enumerate*}[(i)]
6180 \item |&&|, \verb!||! and |!| are boolean ``and'', ``or'' and ``not'', respectively.
6181 \item The equality operator (for numbers and dimensions) is |==|, \emph{not} |=|.
6182 \end{enumerate*} And some examples:
6183
6184 \begin{forestexample}[layout=tree on top,index={for step,tree,grow',calign,option>l,l sep,option>child
6185 anchor,option>anchor,fit,tier,readonly option>level,delay,before typesetting nodes,content,wrap $n$ pgfmath args,pgfmath},index>={!}]
6186 \begin{forest}
6187 for tree={grow'=0,calign=first,l=0,l sep=2em,child anchor=west,anchor=base
6188 west,fit=band,tier/.pgfmath=~level~()},
6189 fullpath/.style={if n=0{}{content/.wrap 2
6190 pgfmath args={##1/##2}{~content~("!u")}{~content~()}}},
6191 delay={for tree=fullpath,content=/},
6192 before typesetting nodes={for tree={content=\strut#1}}
6193 [
6194 [home
6195 [joe
6196 [\TeX]]
6197 [saso
6198 [\TeX]]
6199 [a user with a long name
6200 [\TeX]]]
6201 [usr]]
6202 \end{forest}
6203 \end{forestexample}
6204
6205 \begin{forestexample}[point=instr,index={delay,for step,tree,conditional>if,content,n children}]
6206 % mark non-phrasal terminal nodes
6207 \begin{forest}
6208 delay={for tree={if=
6209 {!instr("P",~content~) && ~n_children~==0}
6210 {fill=yellow}
6211 {}
6212 }}
6213 [CP[DP][C'[C][TP[DP][T'[T][VP[DP][V'[V][DP]]]]]]]
6214 \end{forest}
6215 \end{forestexample}
6216
6217 {\def\useforestlibrary#1{}%
6218 \begin{forestexample}[point=instr,index={where option,n children,tier,content,no edge,tikz},index>={!}]
6219 % roof terminal phrases
6220 \useforestlibrary{linguistics}
6221 % ...
6222 \begin{forest}
6223 delay={where n children=0{tier=word,
6224 if={~instr~("P",~content~("!u"))}{roof}{}
6225 }{}},
6226 [VP[DP[Mary]][V'[V[loves]][DP[her cat]]]]
6227 \end{forest}
6228 \end{forestexample}}
6229
6230
6231 \subsection{Standard node}
6232 \label{ref:standard-node}
6233
6234 \begin{syntax}
6235 \indexitem{macro>forestStandardNode}\meta{node}\meta{environment fingerprint}\meta{calibration
6236 procedure}\meta{exported options}
6237
6238 This macro defines the current \emph{standard node}. The standard node declares some options as
6239 \emph{exported}. When a new node is created, the values of the exported options are initialized
6240 from the standard node. At the beginning of every \index{forest} environment, it is checked whether
6241 the \emph{environment fingerprint} of the standard node has changed. If it did, the standard
6242 node is \emph{calibrated}, adjusting the values of exported options. The \emph{raison d'etre} for
6243 such a system is given in \S\ref{tut:defaults}.
6244
6245 In \meta{node}, the standard node's content and possibly other options are specified, using the
6246 usual bracket representation. The \meta{node}, however, \emph{must not contain children}. The
6247 default: \texttt{[dj]}.
6248
6249 The \meta{environment fingerprint} must be an expandable macro definition. It's expansion
6250 should change whenever the calibration is necessary.
6251
6252 \meta{calibration procedure} is a keylist (processed in the |/forest| path) which calculates the
6253 values of exported options.
6254
6255 \meta{exported options} is a comma-separated list of exported options.
6256
6257 This is how the default standard node is created:
6258 \begin{lstlisting}
6259 \forestStandardNode[dj]
6260 {%
6261 \forestOve{\csname forest@id@of@standard node\endcsname}{content},%
6262 \the\ht\strutbox,\the\pgflinewidth,%
6263 \pgfkeysvalueof{/pgf/inner ysep},\pgfkeysvalueof{/pgf/outer ysep},%
6264 \pgfkeysvalueof{/pgf/inner xsep},\pgfkeysvalueof{/pgf/outer xsep}%
6265 }
6266 {
6267 l sep={\the\ht\strutbox+\pgfkeysvalueof{/pgf/inner ysep}},
6268 l={l_sep()+abs(max_y()-min_y())+2*\pgfkeysvalueof{/pgf/outer ysep}},
6269 s sep={2*\pgfkeysvalueof{/pgf/inner xsep}}
6270 }
6271 {l sep,l,s sep}
6272 \end{lstlisting}
6273 \end{syntax}
6274
6275 \subsection{Externalization}
6276 \label{ref:externalization}
6277
6278 Externalized tree pictures are compiled only once. The result of the compilation is saved into a
6279 separate |.pdf| file and reused on subsequent compilations of the document. If the code of the
6280 tree (or the context, see below) is changed, the tree is automatically recompiled.
6281
6282 Externalization is enabled by:
6283 \begin{lstlisting}
6284 \usepackage[~external~]{forest}
6285 ~\tikzexternalize~
6286 \end{lstlisting}
6287 Both lines are necessary. \TikZ;'s externalization library is automatically loaded if necessary.
6288
6289 \begin{syntax}
6290 \indexitem{node key>external/optimize} Parallels \keyname{/tikz/external/optimize}: if |true| (the
6291 default), the processing of non-current trees is skipped during the embedded compilation.
6292 \indexitem{node key>external/context} If the expansion of the macro stored in
6293 this option changes, the tree is recompiled.
6294 \indexitem{node key>external/depends on macro}|=|\meta{cs} Adds the definition of macro \meta{cs} to
6295 \keyname{external/context}. Thus, if the definition of \meta{cs} is changed, the tree will be
6296 recompiled.
6297 \end{syntax}
6298
6299 \foRest; respects or is compatible with several (not all) keys and commands of \TikZ;'s
6300 externalization library. In particular, the following keys and commands might be useful; see
6301 \cite[\S32]{tikzpgf2.10}.
6302 \begin{itemize}
6303 \item\keyname{/tikz/external/remake next}
6304 \item\keyname{/tikz/external/prefix}
6305 \item\keyname{/tikz/external/system call}
6306 \item\cmdname{tikzexternalize}
6307 \item\cmdname{tikzexternalenable}
6308 \item\cmdname{tikzexternaldisable}
6309 \end{itemize}
6310 \FoRest; does not disturbe the externalization of non-\foRest; pictures. (At least it
6311 shouldn't \dots)
6312
6313 The main auxiliary file for externalization has suffix |.for|. The externalized pictures have
6314 suffices |-forest-|$n$ (their prefix can be set by \keyname{/tikz/external/prefix}, e.g.\ to a
6315 subdirectory). Information on all trees that were ever externalized in the document (even if
6316 they were changed or deleted) is kept. If you need a ``clean'' |.for| file, delete it and
6317 recompile. Deleting |-forest-|$n$|.pdf| will result in recompilation of a specific tree.
6318
6319 Using \keyname{draw tree} and \keyname{draw tree'} multiple times \emph{is} compatible with
6320 externalization, as is drawing the tree in the box (see \index{draw tree box}). If you are
6321 trying to externalize a \index{forest} environment which utilizes \index{TeX} to produce a
6322 visible effect, you will probably need to use \index{TeX'} and/or \index{TeX''}.
6323
6324 \setcounter{CodelineNo}{0}
6325 \DocInput{forest-libs.dtx}
6326
6327 \section{Gallery}
6328 \label{sec:gallery}
6329
6330 \subsection{Decision tree}
6331 \label{sec:example-decision-tree}
6332
6333 The following example was inspired by a question on \TeX\ Stackexchange:
6334 \href{http://tex.stackexchange.com/questions/39103/how-to-change-the-level-distance-in-tikz-qtree-for-one-level-only}{How to change the level distance in tikz-qtree for one level only?}. The question is about |tikz-qtree|: how to adjust the level distance for the first level only, in order to avoid first-level labels crossing the parent--child edge. While this example solves the problem (by manually shifting the offending labels; see \texttt{elo} below), it does more: the preamble is setup so that inputing the tree is very easy.
6335
6336 \begin{forestexample}[layout=tree on top,index={if option,readonly option>n,no edge,tikz,strequal,strcat,option>child anchor,option>parent
6337 anchor,option>anchor,anchor>anchor,calign,for step,tree,s sep,option>l,n children,declare toks,delay,content,before typesetting nodes,descendants,keylist+=tikz,wrap pgfmath arg,wrap $n$ pgfmath args,split option},index>={!}]
6338 \forestset{
6339 declare toks={elo}{}, % Edge Label Options
6340 anchors/.style={anchor=#1,child anchor=#1,parent anchor=#1},
6341 dot/.style={tikz+={\fill (.child anchor) circle[radius=#1];}},
6342 dot/.default=2pt,
6343 decision edge label/.style n args=3{
6344 edge label/.expanded={node[midway,auto=#1,anchor=#2,\forestoption{elo}]{\strut$\unexpanded{#3}$}}
6345 },
6346 decision/.style={if n=1
6347 {decision edge label={left}{east}{#1}}
6348 {decision edge label={right}{west}{#1}}
6349 },
6350 decision tree/.style={
6351 for tree={
6352 s sep=0.5em,l=8ex,
6353 if n children=0{anchors=north}{
6354 if n=1{anchors=south east}{anchors=south west}},
6355 math content,
6356 },
6357 anchors=south, outer sep=2pt,
6358 dot=3pt,for descendants=dot,
6359 delay={for descendants={~split option~={content}{;}{content,decision}}},
6360 }
6361 }
6362 \begin{forest} decision tree
6363 [N,plain content
6364 [I;{p_1=0.5},plain content,elo={yshift=4pt}
6365 [{5,1};a]
6366 [II;b,plain content
6367 [{1,2};m]
6368 [{2,3};n]
6369 ]
6370 ]
6371 [II;{p_2=0.5},plain content,elo={yshift=4pt}
6372 [;c
6373 [{1,0};z]
6374 [{2,2};t]
6375 ]
6376 [;d
6377 [{3,1};z]
6378 [{0,0};t]
6379 ]
6380 ] {\draw[dashed](!1.anchor)--(!2.anchor) node[pos=0.5,above]{I};}
6381 ]
6382 \end{forest}
6383 \end{forestexample}
6384
6385 \setcounter{CodelineNo}{0}
6386 \DocInput{forest-index.dtx}
6387
6388 \section{Past, present and future}
6389 \label{sec:changes}
6390
6391 \paragraph{Roadmap} What's planned for future releases?
6392 \begin{itemize}
6393 \item filling up the libraries
6394 \item faster externalization
6395 \item custom-edge aware packing algorithm and a more flexible (successor of) \index{calign}
6396 \item support for specialized |forest| environments, including:
6397 \begin{itemize}
6398 \item selectable input parser,
6399 \item namespaces (different function, different options),
6400 \item better support for different output types.
6401 \end{itemize}
6402 In short, everything you need to make \foRest; your favourite spreadsheet! ;-)
6403 \item code cleanup and extraction of sub-packages possibly useful to other package writers
6404 \end{itemize}
6405
6406 \subsection{Changelog}
6407 \label{sec:changelog}
6408
6409 First of all, the list of all \index{compat} key values for backward compatibility, and their
6410 groupings. Remember, compat values that reside in styles with suffix |-most| are harmless: they will
6411 not disrupt the new functionality of the package. But take care when using stuff which only resides
6412 in |-all| styles.
6413
6414 \lstinputregion{forest-compat.sty}{compat_keys}
6415
6416 \newcommand\compatitem[2]{\item[,,in \texttt{-#1}]\texttt{compat=}\indexdef{value of=compat>#2}}
6417
6418 \subsubsection{v2.1}
6419
6420 \begin{description}
6421 \item[v2.1.5 (2017/07/14)] \mbox{}
6422 Minor improvements:
6423 \begin{itemize}
6424 \item Smarter \index{baseline} defaults for the \reflibrary{linguistics} library.
6425 \item Yield warning when the \index{baseline} is set to a node that is not drawn (e.g.\ a
6426 \index{phantom} node).
6427 \end{itemize}
6428
6429 \item[v2.1.4 (2017/02/02)] \mbox{}
6430
6431 Performance:
6432 \begin{itemize}
6433 \item Reimplement some internals of the packing algorithm to avoid consuming the string pool in
6434 documents with many trees. (We're about 10\% slower now, but (depending on the document) the
6435 memory usage can drop up to five times!)
6436 \end{itemize}
6437
6438 Bugfixes:
6439 \begin{itemize}
6440 \item Fix aggregate function \index{aggregate>count}.
6441 \item Provide a workaround for a PGF bug: for coordinate-shaped nodes, |\positionnodelater|
6442 provides dimensions with |pt| in a wrong catcode, so \index{max y} and friends did not work for
6443 such nodes.
6444 \end{itemize}
6445
6446 \item[v2.1.3 (2017/01/27)] \mbox{}
6447
6448 Bugfixes:
6449 \begin{itemize}
6450 \item Update \index{nice empty nodes} to use \index{for step=\index{current and siblings}}.
6451 \end{itemize}
6452
6453 \item[v2.1.2 (2016/12/31)] \mbox{}
6454
6455 Bugfixes:
6456 \begin{syntax}
6457 \compatitem{all}{2.1.1-loops}
6458 A level of hash doubling was unnecessarily introduced for the \meta{keylist} argument of all
6459 loops (\S\ref{ref:loops}), and the \meta{nodewalk} argument of \index{process keylist'} and
6460 \index{process delayed}. Use this key to revert to the old behaviour.
6461 \end{syntax}
6462
6463 Minor improvements:
6464 \begin{itemize}
6465 \item Implemented key \index{also}.
6466 \end{itemize}
6467
6468 \item[v2.1.1 (2016/12/18)] \mbox{}
6469
6470 Minor improvements:
6471 \begin{itemize}
6472 \item Implemented argument processor instruction \index{processor>p}.
6473 \end{itemize}
6474
6475 Bugfixes:
6476 \begin{itemize}
6477 \item Argument processor instruction \index{processor>u} introduced an extra layer of braces
6478 around each result item.
6479 \item Argument processor instructions \index{processor>l} and \index{processor>L} did not always
6480 load the desided number of arguments.
6481 \item Argument processor instructions \index{processor>and} and \index{processor>or} were taking
6482 the arguments from the start of the left side instead of its end.
6483 \end{itemize}
6484
6485 \item[v2.1 (2016/12/05)] \mbox{}
6486
6487 Backward incompatible changes (with a \index{compat} key):
6488 \begin{syntax}
6489 \compatitem{all}{2.0-edges}
6490 This compat key groups the three changes listed below: the final two depend on the first, so you
6491 will probably want to revert them all or none.
6492 \begin{syntax}
6493 \compatitem{all}{2.0-anchors}
6494 This is really a bugfix. Growth direction based anchors \index{anchor>parent},
6495 \index{anchor>parent first} and \index{anchor>parent last} were not facing to the direction of the
6496 parent if the growth direction of the tree changed at the node.
6497 \compatitem{all}{2.0-forkededge}
6498 \compatitem{all}{2.0-folder}
6499 Update the code of keys \index{forked edge} (and friends) and \index{folder} from the
6500 \reflibrary{edges} library to reflect the above bugfix.
6501 \end{syntax}
6502 \compatitem{all}{2.0-delayn} Fixing yet another bug in \index{delay n}! The number of cycles was
6503 reevaluated at each cycle. Now it is computed immediately, and fixed. Use this key to revert to
6504 the old behaviour.
6505 \end{syntax}
6506
6507 Performance:
6508 \begin{itemize}
6509 \item Substantially enhance the argument processor (\S\ref{ref:argument-processor}), including the
6510 ability to use it as a drop-in replacement for |pgfmath|.
6511 \item Internally, avoid using |\pgfmathparse| and friends whereever possible.
6512 \item Implement a fast set of macros to determine if a |pgfmath| expression is just a \meta{count}
6513 or \meta{dimen} expression.
6514 \item Optimize \index{split option} and \index{split register}.
6515 \end{itemize}
6516 Minor improvements:
6517 \begin{itemize}
6518 \item Allow \index{relative node name}s in \index{handler>option}.
6519 \item Make aggregate functions (\S\ref{ref:aggregate-functions}) nestable and implement their
6520 |pgfmath| versions.
6521 \item Implement
6522 \index{if dimen GT=\meta{dimen option}}, \index{if dimen LT=\meta{dimen option}},
6523 \index{if count GT=\meta{count option}}, \index{if count LT=\meta{count option}},
6524 \index{where dimen GT=\meta{dimen option}}, \index{where dimen LT=\meta{dimen option}},
6525 \index{where count GT=\meta{count option}} and \index{where count LT=\meta{count option}},
6526 \item Implement \index{if current nodewalk empty}.
6527 \item Implement nodewalk steps \index{leaves}, \index{-level} and \index{-level'}.
6528 \item Implement nodewalk operation \index{unique}.
6529 \item Implement \index{nodewalk key>on invalid} values \index{value of=on invalid>error if real} and \index{value of=on invalid>last valid}, remove value |step| (no \index{compat} key, as it was broken and useless).
6530 \item Implement `-` anchors (\index{anchor>-parent} etc.).
6531 \item Implement \index{save and restore register}.
6532 \item Implement \index{handler>nodewalk style}.
6533 \item Implement \index{forestloopcount}.
6534 \item Allow multiple occurrences of package option \index{compat}.
6535 %\item Implement \index{foresttypeouttrees}.
6536 %\item Implement \index{show register}.
6537 \end{itemize}
6538
6539 Bugfixes:
6540 \begin{itemize}
6541 \item Fix a bug in externalization (|\forest@file@copy| set |\endlinechar| to |-1|, which caused
6542 problems for several packages, e.g. |biblatex|).
6543 \item Fix a bug in \index{delay n}: the number of cycles was reevaluated at each cycle.
6544 \item Fix a bug in \index{fixed edge angles}.
6545 \item Fix \index{compat} key values \index{value of=compat>silent}, \index{value of=compat>1.0-forstep} and \index{value of=compat>1.0-stages}.
6546 \item Fix invocations of spatial propagators \index{for step=\index{step>nodewalk}} and \index{for step=\index{step>Nodewalk}} and \index{node key>Nodewalk}.
6547 \item Fix invocations of \index{for step=group}, \index{for step=next on tier} and \index{for step=previous on tier}.
6548 \item Fix behaviour of \index{for step=next on tier}, \index{for step=previous on tier} and \index{for step=to tier} on arrival to the invalid node.
6549 \item Fix problems with interaction between \index{folder} and \index{forked edges}.
6550 \end{itemize}
6551
6552 \end{description}
6553
6554 \subsubsection{v2.0}
6555
6556
6557 \begin{description}
6558 \item[v2.0.3 (2016/04/03)] \mbox{}
6559
6560 Backward incompatible changes (with a \index{compat} key):
6561 \begin{syntax}
6562 \compatitem{all}{2.0.2-delayn}
6563 \compatitem{all}{2.0.2-wrapnpgfmathargs}
6564
6565 This is really a bugfix: keys \index{delay n} and \index{wrap $n$ pgfmath args} (for $n\geq 2$)
6566 were introducing two layers of hash doubling. Now this confusing behaviour is gone, but as
6567 finding the correct number of hashes is always a tough job, \index{compat} keys are provided.
6568 \end{syntax}
6569
6570 Improvements:
6571
6572 \begin{itemize}
6573 \item Rework \index{draw tree edge} so that by default, an edge is drawn only it both its node and
6574 its node's parent are drawn. And yes, implement \index{if node drawn}.
6575 \item Implement circularity detection in dynamic node operations.
6576 \item Implement debug categories and debugging of dynamic node operations.
6577 \item Declare some further |tempdim...| registers.
6578 \item Make option \index{readonly option>id} accessible via \index{forestoption}.
6579 \end{itemize}
6580
6581 Bugfixes:
6582
6583 \begin{itemize}
6584 \item Execute \index{tikz} code for all (including phantom) nodes. (The feature of ignoring
6585 phantom nodes was introduced in v2.0.2, but turns out it was a bad idea: for example, having a
6586 phantom root with some tikz code is not uncommon.)
6587 \item Keys \index{label} and \index{pin} now \emph{append} to option \index{tikz}, as makes sense.
6588 \item Fix nodewalk steps \index{filter} and \index{branch} so that they can be embedded under
6589 nodewalk operations. (Uh, and recategorize them as operations themselves.)
6590 \item Execute \index{before packing node} even when the node has no children.
6591 \item \index{step>level}|<={0}{...}| now works as expected.
6592 \item Re-setting the node name to the same value doesn't yield an error anymore.
6593 \item Don't add the separator when adding the first element to a keylist option or register.
6594 \item Copy externalization files in TeX (don't rely on |\write18|).
6595 \item Consistently store dimen options and registers with |pt|s of catcode other.
6596 \item Properly initialize readonly count options (\index{readonly option>n}, \index{readonly option>n'}, \index{n children} and
6597 \index{readonly option>level}).
6598 \item Fix some typos.
6599 \end{itemize}
6600
6601 \item[v2.0.2 (2016/03/04)] \mbox{}
6602
6603 Backward incompatible changes:
6604 \begin{itemize}
6605 \item The semantics of the parenthesized optional argument to \index{forest} environment and
6606 \index{Forest} macro has changed. The argument was introduced in v2.0.0: if present, it
6607 redefined \index{style>stages} style for the current environment/macro. This argument is now
6608 generalized to allow further (pre-\index{style>stages}) customization in future versions of the
6609 package. To temporarily redefine \index{style>stages}, write |(|\index{option of=forest>stages}|={...})|.
6610 \end{itemize}
6611
6612 New functionality:
6613 \begin{itemize}
6614 \item Key \index{last dynamic node} and named nodewalk \index{dynamic nodes}.
6615 \item An optional argument to \index{useforestlibrary} to pass package options to libraries.
6616 \item Handler \index{nodewalk style}.
6617 \item Keys \index{draw tree node'}, \index{draw tree edge'} and \index{draw tree tikz'}.
6618 \end{itemize}
6619
6620 Bugfixes:
6621 \begin{itemize}
6622 \item Fixed \index{replace by} when applied to the root node.
6623 \item Registers are now initialized to an empty string, 0pt, or 0.
6624 \item Packing doesn't destroy the current pgfpath anymore.
6625 \item \index{forestStandardNode} now uses \index{name'}.
6626 \item \index{draw tree edge} now respects \index{phantom}.
6627 \end{itemize}
6628
6629 \item[v2.0.1 (2016/02/20)] \mbox{}
6630
6631 New functionality:
6632 \begin{itemize}
6633 \item \index{current and siblings}, \index{current and siblings reversed}
6634 \item Add |*| argument to \index{useforestlibrary}.
6635 \end{itemize}
6636
6637 Bugfixes:
6638 \begin{itemize}
6639 \item Correctly mangle option/register names to pgfmath names (\S\ref{ref:pgfmath}).
6640 \item Refer to parent (not node) anchor in \index{calign}|=|\index{edge midpoint}.
6641 \item Accept key \index{history} in \index{step>Nodewalk} config.
6642 \end{itemize}
6643 \item[v2.0.0 (2016/01/30)] \mbox{}\footnote{The year of the release date in the package was wrong \dots \ 2015.}
6644
6645 Backwards incompatible changes (\emph{without} a \index{compat} key --- sorry!):
6646 \begin{itemize}
6647 \item The unintended and undocumented way to specify defaults using |\forestset{.style={...}}|
6648 (see question
6649 \href{http://tex.stackexchange.com/questions/167972/making-a-certain-tree-style-the-default-for-forest}{Making
6650 a certain tree style the default for forest} at \TeX\ SE) does not work anymore. (Actually, it
6651 has never truly worked, and that's why it has not \index{compat} key.) Use \index{default
6652 preamble}.
6653 \item Renamed augmented assignment operator \meta{option}|-| for prepending to \meta{toks} and
6654 \meta{keylist} options \index{+toks=\meta{option}}\index[not print]{+keylist}. A new
6655 \index{keylist-=\meta{option}} is defined for keylist options and means ``delete key from keylist.''
6656 \item Short nodewalk steps are not simply styles anymore: use \index{define short step} to
6657 define them.
6658 \end{itemize}
6659
6660 Backwards incompatible changes with a \index{compat} key:
6661
6662 \begin{syntax}
6663 \compatitem{all}{1.0-stages}
6664
6665 Processing of \index{given options}, which is now exposed, and the new keylists \index{default
6666 preamble} and \index{preamble} is now included at the start of the default \index{style>stages}
6667 style. When changing \index{style>stages}, the instruction to process these keylists must now be
6668 given explicitely.
6669
6670 \compatitem{all}{1.0-forstep}
6671
6672 In v1.0, a spatial propagator \index{for step=\meta{step}} could never fail. This turned out to
6673 be difficult to debug. In this version, when a propagator steps ``out of the tree'', an error
6674 is raised by default. Check out \index{option of=Nodewalk>on invalid} to learn how to simulate
6675 the old behaviour without using this compatibility key.
6676
6677 \compatitem{all}{1.0-rotate}
6678
6679 This version of the package introduces
6680 option \index{rotate} and \index{autoforward}s it to \index{node options}. This is needed to
6681 handle the new \foRest; anchors (\S\ref{sec:anchors}). However, in some rare cases (like the
6682 tree on the title page of this manual) it can lead to a discrepancy between the versions, as the
6683 time when the value given to \index{rotate} is processed is different. |1.0-rotate| removes
6684 option \index{rotate}.
6685
6686 \compatitem{all}{1.0-name}
6687
6688 Documentation of v1.0 requested that node names be unique, but this was not enforced by the
6689 package, sometimes leading to errors. v2.0 enforces node name uniqueness. If this causes
6690 problems, use this compatibility key. In most cases using \index{name'} instead of
6691 \index{option>name} should fix the problem without using compatibility mode.
6692
6693 \item These keys have been renamed:
6694
6695 \begin{tabularx}{\linewidth}{lll}
6696 old&new&\index{compat} key {\small (all but the last are in \texttt{-most})}\\\hline
6697 \keyname{node walk}&\index{for step=nodewalk}\footnote{Nodewalks are much improved in v2.0, so some syntax and keys are different than in v1.0!}&\indexdef{value of=compat>1.0-nodewalk}\\
6698 \keyname{for}&\index{for step=\index{group}}&\indexdef{value of=compat>1.0-for}\\
6699 \keyname{for all next}&\index{for step=\index{following siblings}}&\indexdef{value of=compat>1.0-forall}\\
6700 \keyname{for all previous}&\index{for step=\index{preceding siblings}}&\indexdef{value of=compat>1.0-forall}\\
6701 \keyname{for ancestors'}&\index{for step=\index{current and ancestors}}&\indexdef{value of=compat>1.0-ancestors}\\
6702 (\keyname{for}) \keyname{linear next}&(\index{for step}) \index{next node}&\indexdef{value of=compat>1.0-linear}\\
6703 (\keyname{for}) \keyname{linear previous}&(\index{for step}) \index{previous node}&\indexdef{value of=compat>1.0-linear}\\
6704 \keyname{triangle}&\index{roof} (library \reflibrary{linguistics})&\indexdef{value of=compat>1.0-triangle}\\
6705 \keyname{/tikz/fit to tree}&\index{fit to}\keyname{=}\index{tree}\footnote{The v1.0 key \keyname{/tikz/fit to tree} also set \keyname{inner sep=0}; the v2.0 key \index{fit to} does not do that.}&\indexdef{value of=compat>1.0-fittotree}\\
6706 \keyname{begin forest}, \keyname{end forest}&none (use \index{style>stages})&\index{1.0-stages}\\
6707 \keyname{end forest}, \keyname{end forest}&none (use \index{style>stages})&\index{1.0-stages}\\
6708 \end{tabularx}
6709 \end{syntax}
6710
6711 Good news:
6712 \begin{itemize}
6713 \item Added temporal propagators \index{before packing node} and \index{after packing node}.
6714 \item \emph{Much} improved nodewalks, see \S\ref{ref:nodewalks} and \S\ref{ref:spatial-propagators}.
6715 \item Implemented looping mechanisms and more conditionals, see \S\ref{ref:conditionals}.
6716 \item Implemented library support and started filling up the libraries:
6717 \begin{itemize}
6718 \item \reflibrary{linguistics}: \index{sn edges}, \index{nice empty nodes}, \index{draw
6719 brackets}, \index{c-commanded} and \index{c-commanders}
6720 \item \reflibrary{edges}: \index{forked edges} and \index{folder}
6721 \end{itemize}
6722 \item Implemented aggregate functions, see \S\ref{ref:aggregate-functions}.
6723 \item Added key \index{default preamble}.
6724 \item Implemented anchors \index{anchor>parent}, \index{anchor>children}, \index{anchor>first},
6725 \index{anchor>last}, etc.
6726 \item Added key \index{split} and friends.
6727 \item Implemented sorting of children, see \S\ref{ref:dynamic}.
6728 \item Introduced registers, see \S\ref{sec:options-and-registers}.
6729 \item Implemented handlers \index{handler>option}, \index{handler>register} and \index{process args}.
6730 \item Implemented several friends to \index{process keylist}, introduced \index{processing order}s
6731 and \index{draw tree method}.
6732 \item Added the optional argument |(|\meta{stages}|)| to the \index{forest} environment and
6733 \index{Forest} macro.
6734 \item Implemented \index{autoforward}ing.
6735 \item Implemented flexible handling of unknown keys using \index{unknown to}.
6736 \item Implemented |pgfmath| functions \index{pgfmath>min_l}, \index{pgfmath>max_l}, \index{pgfmath>min_s}, \index{pgfmath>max_s}.
6737 \item Implemented augmented assignment operator \index{keylist-=\meta{keylist option}} for removing keys from keylists.
6738 \item Implemented a generalized \index{fit to} key.
6739 \item Implemented a very slow \foRest;-based indexing system (used to index this documentation)
6740 and included it in the gallery (\S\ref{sec:forest-index}).
6741 \item Added some minor keys: \index{edge path'}, \index{node format'}, \index{create'} and \index{plain content}.
6742 \item Added some developer keys: \index{copy command key}, \index{typeout}.
6743 \end{itemize}
6744
6745 Bugfixes:
6746 \begin{itemize}
6747 \item In computation of numeric tree-structure info, when called for a non-root node.
6748 \item \TikZ;'s externalization internals (signature of
6749 |\tikzexternal@externalizefig@systemcall@uptodatecheck|) have changed: keep up to date,
6750 though only formally.
6751 \item \index{delay} was not behaving additively.
6752 \item \index{option>name}, \index{alias} and \index{baseline} didn't work properly when
6753 setting them for a non-current node.
6754 \item Augmented assignments for count options were leaking `.0pt'.
6755 \item \index{create} didn't work properly in some cases.
6756 \item \keyname{triangle} (now \index{roof} in \reflibrary{linguistics}) didn't use |cycle| in the edge path
6757 \end{itemize}
6758
6759 \end{description}
6760
6761 \subsubsection{v1.0}
6762
6763 \begin{description}
6764 \item[v1.0.10 (2015/07/22)] \mbox{}
6765 \begin{compactitem}
6766 \item Bugfix: a left-over debugging |\typeout| command was interfering with a |forest| within |tabular|, see \href{http://tex.stackexchange.com/questions/256509/odd-incompatibility-between-multi-line-forest-nodes-and-tabular}{this question on TeX.SE}.
6767 \item A somewhat changed versioning scheme \dots
6768 \end{compactitem}
6769 \item[v1.09 (2015/07/15)] \mbox{}
6770 \begin{compactitem}
6771 \item Bugfix: child alignment was not done in nodes with a single child, see \href{http://tex.stackexchange.com/questions/255309/elementary-forest-question-meaning-of-calign-parent-anchor-and-child-anchor}{this question on TeX.SE}.
6772 \end{compactitem}
6773 \item[v1.08 (2015/07/10)] \mbox{}
6774 \begin{compactitem}
6775 \item Fix externalization (compatibility with new |tikz| features).
6776 \end{compactitem}
6777 \item[v1.07 (2015/05/29)] \mbox{}
6778 \begin{compactitem}
6779 \item Require package |elocalloc| for local boxes, which were previously defined by package |etex|.
6780 \end{compactitem}
6781 \item[v1.06 (2015/05/04)] \mbox{}
6782 \begin{compactitem}
6783 \item Load |etex| package: since v2.1a, |etoolbox| doesn't do it anymore.
6784 \end{compactitem}
6785 \item[v1.05 (2014/03/07)] \mbox{}
6786 \begin{compactitem}
6787 \item Fix the node boundary code for rounded rectangle. (Patch contributed by Paul Gaborit.)
6788 \end{compactitem}
6789 \item[v1.04 (2013/10/17)] \mbox{}
6790 \begin{compactitem}
6791 \item Fixed an \href{http://tex.stackexchange.com/questions/138986/error-using-tikzexternalize-with-forest/139145}{externalization bug}.
6792 \end{compactitem}
6793 \item[v1.03 (2013/01/28)] \mbox{}
6794 \begin{compactitem}
6795 \item Bugfix: options of dynamically created nodes didn't get processed.
6796 \item Bugfix: the bracket parser was losing spaces before opening braces.
6797 \item Bugfix: a family of utility macros dealing with affixing token lists was not expanding
6798 content correctly.
6799 \item Added style \index{math content}.
6800 \item Replace key \keyname{tikz preamble} with more general \index{begin draw} and
6801 \index{end draw}.
6802 \item Add keys \keyname{begin forest} and \keyname{end forest}.
6803 \end{compactitem}
6804 \item[v1.02 (2013/01/20)] \mbox{}
6805 \begin{compactitem}
6806 \item Reworked style \index{style>stages}: it's easier to modify the processing flow now.
6807 \item Individual stages must now be explicitely called in the context of some (usually root)
6808 node.
6809 \item Added \index{delay n} and \index{if have delayed}.
6810 \item Added (experimental) \index{pack'}.
6811 \item Added reference to the \href{https://github.com/sasozivanovic/forest-styles}{style
6812 repository}.
6813 \end{compactitem}
6814 \item[v1.01 (2012/11/14)] \mbox{}
6815
6816 \begin{compactitem}
6817 \item Compatibility with the |standalone| package: temporarily disable the effect of
6818 |standalone|'s package option |tikz| while typesetting nodes.
6819 \item Require at least the [2010/08/21] (v2.0) release of package |etoolbox|.
6820 \item Require version [2010/10/13] (v2.10, rcs-revision 1.76) of \PGF;/\TikZ;. Future
6821 compatibility: adjust to the change of the ``not yet positioned'' node name (2.10 |@|
6822 $\rightarrow$ 2.10-csv |PGFINTERNAL|).
6823 \item Add this changelog.
6824 \end{compactitem}
6825 \item[v1.0 (2012/10/31)] First public version
6826 \end{description}
6827
6828
6829
6830 \subsection{Known bugs}
6831 \label{sec:bugs}
6832
6833 If you find a bug (there are bound to be some \dots), please contact
6834 me at \href{mailto:[email protected]}{[email protected]}.
6835
6836 \subsubsection*{System requirements}
6837
6838 This package requires \LaTeX\ and e\TeX. If you use something
6839 else: sorry.
6840
6841 The requirement for \LaTeX\ might be dropped in the future, when I get some time and energy for a
6842 code-cleanup (read: to remedy the consequences of my bad programming practices and general
6843 disorganization).
6844
6845 The requirement for e\TeX\ will probably stay. If nothing else, \foRest; is heavy on boxes: every
6846 node requires its own \dots\ and consequently, I have freely used e\TeX\ constructs in the code
6847 \dots
6848
6849 \subsubsection*{\PGF; internals}
6850
6851 \FoRest; relies on some details of \PGF; implementation, like the name
6852 of the ``not yet positioned'' nodes. Thus, a new bug might appear with the development of \PGF;.
6853 If you notice one, please let me know.
6854
6855 \subsubsection*{Edges cutting through sibling nodes}
6856 \label{sec:cutting-edge}
6857
6858 In the following example, the R--B edge crosses the AAA node, although \index{ignore edge} is
6859 set to the default |false|.
6860 \begin{forestexample}[index={calign,{value of=calign>first},align,{value of=align>center},base,{value of=base>bottom}}]
6861 \begin{forest}
6862 calign=first
6863 [R[AAAAAAAAAA\\AAAAAAAAAA\\AAAAAAAAAA,align=center,base=bottom][B]]
6864 \end{forest}
6865 \end{forestexample}
6866 This happens because s-distances between the adjacent children are
6867 computed before child alignment (which is obviously the correct order in the general case), but
6868 child alignment non-linearly influences the edges. Observe that the with a different value of
6869 \index{calign}, the problem does not arise.
6870 \begin{forestexample}[index={calign,{value of=calign>last},align,{value of=align>center},base,{value of=base>bottom}}]
6871 \begin{forest}
6872 calign=last
6873 [R[AAAAAAAAAA\\AAAAAAAAAA\\AAAAAAAAAA,align=center,base=bottom][B]]
6874 \end{forest}
6875 \end{forestexample}
6876 While it would be possible to fix the situation after child alignment (at least for some child
6877 alignment methods), I have decided against that, since the distances between siblings would soon
6878 become too large. If the AAA node in the example above was large enough, B could easily be pushed
6879 off the paper. The bottomline is, please use manual adjustment to fix such situations.
6880
6881 \subsubsection*{Orphans}
6882 \label{sec:orphans}
6883
6884 If the \index{option>l} coordinates of adjacent children are too different (as a result of manual adjustment or
6885 tier alignment), the packing algorithm might have nothing so say about the desired distance
6886 between them: in this sense, node C below is an ``orphan.''
6887 \begin{forestexample}[index={for step,tree,s sep,option>l,dimen*}]
6888 \begin{forest}
6889 for tree={s sep=0,draw},
6890 [R[A][B][C,l*=2][D][E]]
6891 \end{forest}
6892 \end{forestexample}
6893 To prevent orphans from ending up just anywhere, I have decided to vertically align them with
6894 their preceding sibling --- although I'm not certain that's really the best solution. In other
6895 words, you can rely that the sequence of s-coordinates of siblings is non-decreasing.
6896
6897 The decision also influences a similar situation illustrated below. The packing algorithm puts
6898 node E immediately next to B (i.e.\ under C): however, the monotonicity-retaining mechanism then
6899 vertically aligns it with its preceding sibling, D.
6900 \begin{forestexample}[index={for step,tree,s sep,tier}]
6901 \begin{forest}
6902 for tree={s sep=0,draw},
6903 [R[A[B,tier=bottom]][C][D][E,tier=bottom]]
6904 \end{forest}
6905 \end{forestexample}
6906
6907 Obviously, both examples also create the situation of an edge crossing some sibling node(s).
6908 Again, I don't think anything sensible can be done about this, in general.
6909
6910
6911 \subsection{Acknowledgements}
6912
6913 This package has turned out to be much more successful and widespread than I could have ever
6914 imagined and I want to thank all the users for the trust. Many of you have also contributed to the
6915 package in some way: by providing comments and ideas, sending patches, reporting bugs and so on. To
6916 you, I'm doubly grateful! I will not even try to list you all here, as the list is getting too long
6917 for me to maintain, but I do want to mention one person, a member of the friendly community at the
6918 excellent and indispensable \href{http://tex.stackexchange.com}{\TeX\ -- \LaTeX\ Stack Exchange} and
6919 the author of the very first \foRest;-based package,
6920 \href{http://ctan.org/pkg/prooftrees}{Prooftrees}: without |cfr|'s uncountable questions, answers,
6921 bug reports and ideas, \foRest; would be a much poorer package indeed.
6922
6923
6924
6925 \addcontentsline{toc}{section}{References}
6926 \bibliography{tex}
6927 \bibliographystyle{plain}
6928
6929 \newpage
6930 \phantomsection
6931 \addcontentsline{toc}{section}{\indexname}
6932 \addtocontents{toc}{\protect\setbox0=\protect\vbox{\protect\iffalse}\protect\fi}
6933 \PrintIndex
6934 %\addtocontents{toc}{\protect\iffalse{\protect\fi}}
6935 %http://tex.stackexchange.com/questions/10291/addtocontents-at-end-of-document-not-getting-written-to-toc-file
6936 \makeatletter
6937 \immediate\write\@auxout{\noexpand\@writefile{toc}{\noexpand\iffalse{\noexpand\fi}}}
6938 \makeatother
6939
6940
6941
6942 \end{document}
6943
6944 %%% Local Variables:
6945 %%% mode: latex
6946 %%% fill-column: 100
6947 %%% TeX-command-default: "Make PDF"
6948 %%% TeX-master: t
6949 %%% End: