Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-pgfkeys.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Key Management}
12 \label{section-keys}
13
14 This section describes the package |pgfkeys|. It is loaded automatically by
15 both \pgfname\ and \tikzname.
16
17 \begin{package}{pgfkeys}
18 This package can be used independently of \pgfname. Note that no
19 other package of \pgfname\ needs to be loaded (so neither the
20 emulation layer nor the system layer is needed). The Con\TeX t
21 abbreviation is |pgfkey| \todosp{pgfkey --> pgfkeys?} if |pgfmod| is not loaded.
22 \end{package}
23
24
25 \subsection{Introduction}
26
27 \subsubsection{Comparison to Other Packages}
28
29 The |pgfkeys| package defines a key--value management system that is in some
30 sense similar to the more light-weight |keyval| system and the improved
31 |xkeyval| system. However, |pgfkeys| uses a slightly different philosophy than
32 these systems and it will coexist peacefully with both of them.
33
34 The main differences between |pgfkeys| and |xkeyval| are the following:
35 %
36 \begin{itemize}
37 \item |pgfkeys| organizes keys in a tree, while |keyval| and |xkeyval|
38 use families. In |pgfkeys| the families correspond to the root
39 entries of the key tree.
40 \item |pgfkeys| has no save-stack impact (you will have to read the \TeX
41 Book very carefully to appreciate this).
42 \item |pgfkeys| is slightly slower than |keyval|, but not much.
43 \item |pgfkeys| supports styles. This means that keys can just stand for
44 other keys (which can stand for other keys in turn or which can also
45 just execute some code). \tikzname\ uses this mechanism heavily.
46 \item |pgfkeys| supports multi-argument key code. This can, however, be
47 emulated in |keyval|.
48 \item |pgfkeys| supports handlers. These are call-backs that are called
49 when a key is not known. They are very flexible, in fact even
50 defining keys in different ways is handled by, well, handlers.
51 \end{itemize}
52
53
54 \subsubsection{Quick Guide to Using the Key Mechanism}
55
56 The following quick guide to \pgfname's key mechanism only treats the most
57 commonly used features. For an in-depth discussion of what is going on, please
58 consult the remainder of this section.
59
60 Keys are organized in a large tree that is reminiscent of the Unix file tree. A
61 typical key might be, say, |/tikz/coordinate system/x| or just |/x|. Again as
62 in Unix, when you specify keys you can provide the complete path of the key,
63 but you usually just provide the name of the key (corresponding to the file
64 name without any path) and the path is added automatically.
65
66 Typically (but not necessarily) some code is associated with a key. To execute
67 this code, you use the |\pgfkeys| command. This command takes a list of
68 so-called key--value pairs. Each pair is of the form \meta{key}|=|\meta{value}.
69 For each pair the |\pgfkeys| command will execute the code stored for the
70 \meta{key} with its parameter set to \meta{value}.
71
72 Here is a typical example of how the |\pgfkeys| command is used:
73 %
74 \begin{codeexample}[code only]
75 \pgfkeys{/my key=hallo,/your keys/main key=something\strange,
76 key name without path=something else}
77 \end{codeexample}
78
79 Now, to set the code that is stored in a key you do not need to learn a new
80 command. Rather, the |\pgfkeys| command can also be used to set the code of a
81 key. This is done using so-called \emph{handlers}. They look like keys whose
82 names look like ``hidden files in Unix'' since they start with a dot. The
83 handler for setting the code of a key is appropriately called |/.code| and it
84 is used as follows:
85 %
86 \begin{codeexample}[]
87 \pgfkeys{/my key/.code=The value is '#1'.}
88 \pgfkeys{/my key=hi!}
89 \end{codeexample}
90 %
91 As you can see, in the first line we defined the code for the key |/my key|. In
92 the second line we executed this code with the parameter set to |hi!|.
93
94 There are numerous handlers for defining a key. For instance, we can also
95 define a key whose value actually consists of more than one parameter.
96 %
97 \begin{codeexample}[]
98 \pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.}
99 \pgfkeys{/my key={a1}{a2}}
100 \end{codeexample}
101
102 We often want to have keys where the code is called with some default value if
103 the user does not provide a value. Not surprisingly, this is also done using a
104 handler, this time called |/.default|.
105 %
106 \begin{codeexample}[]
107 \pgfkeys{/my key/.code=(#1)}
108 \pgfkeys{/my key/.default=hello}
109 \pgfkeys{/my key=hallo,/my key}
110 \end{codeexample}
111
112 The other way round, it is also possible to specify that a value \emph{must} be
113 specified, using a handler called |/.value required|. Finally, you can also
114 require that no value \emph{may} be specified using |/.value forbidden|.
115
116 All keys for a package like, say, \tikzname\ start with the path |/tikz|. We
117 obviously do not like to write this path down every time we use a key (so we do
118 not have to write things like |\draw[/tikz/line width=1cm]|). What we need is
119 to somehow ``change the default path to a specific location''. This is done
120 using the handler |/.cd| (for ``change directory''). Once this handler has been
121 used on a key, all subsequent keys {\itshape in the current call of |\pgfkeys|
122 only} are automatically prefixed with this path, if necessary.
123
124 Here is an example:
125 %
126 \begin{codeexample}[code only]
127 \pgfkeys{/tikz/.cd,line width=1cm,line cap=round}
128 \end{codeexample}
129 %
130 This makes it easy to define commands like |\tikzset|, which could be defined
131 as follows (the actual definition is a bit faster, but the effect is the same):
132 %
133 \begin{codeexample}[code only]
134 \def\tikzset#1{\pgfkeys{/tikz/.cd,#1}}
135 \end{codeexample}
136
137 When a key is handled, instead of executing some code, the key can also cause
138 further keys to be executed. Such keys will be called \emph{styles}. A style
139 is, in essence, just a key list that should be executed whenever the style is
140 executed. Here is an example:
141 %
142 \begin{codeexample}[]
143 \pgfkeys{/a/.code=(a:#1)}
144 \pgfkeys{/b/.code=(b:#1)}
145 \pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}}
146 \pgfkeys{/my style=wow}
147 \end{codeexample}
148 %
149 As the above example shows, styles can also be parameterized, just like the
150 normal code keys.
151
152 As a typical use of styles, suppose we wish to set up the key |/tikz| so that
153 it will change the default path to |/tikz|. This can be achieved as follows:
154 %
155 \begin{codeexample}[code only]
156 \pgfkeys{/tikz/.style=/tikz/.cd}
157 \pgfkeys{tikz,line width=1cm,draw=red}
158 \end{codeexample}
159
160 Note that when |\pgfkeys| is executed, the default path is set to~|/|. This
161 means that the first |tikz| will be completed to |/tikz|. Then |/tikz| is a
162 style and, thus, replaced by |/tikz/.cd|, which changes the default path to
163 |/tikz|. Thus, the |line width| is correctly prefixed with |/tikz|.
164
165
166 \subsection{The Key Tree}
167
168 The |pgfkeys| package organizes keys in a so-called \emph{key tree}. This tree
169 will be familiar to anyone who has used a Unix operating system: A key is
170 addressed by a path, which consists of different parts separated by slashes. A
171 typical key might be |/tikz/line width| or just |/tikz| or something more
172 complicated like |/tikz/cs/x/.store in|.
173
174 Let us fix some further terminology: Given a key like |/a/b/c|, we call the
175 part leading up the last slash (|/a/b|) the \emph{path} of the key. We call
176 everything after the last slash (|c|) the \emph{name} of the key (in a file
177 system this would be the file name).
178
179 We do not always wish to specify keys completely. Instead, we usually specify
180 only part of a key (typically only the name) and the \emph{default path} is
181 then added to the key at the front. So, when the default path is |/tikz| and
182 you refer to the (partial) key |line width|, the actual key that is used is
183 |/tikz/line width|. There is a simple rule for deciding whether a key is a
184 partial key or a full key: If it starts with a slash, then it is a full key and
185 it is not modified; if it does not start with a slash, then the default path is
186 automatically prefixed.
187
188 \emph{Remark:} The above rule is actually a definition, hence the corresponding
189 sufficiency conditions hold. That is, if it is a full key, then it starts with
190 a slash; if it is a partial key, then it does not start with a slash. Moreover,
191 a path always starts with a slash.
192
193 Note that the default path is not the same as a search path. In particular, the
194 default path is just a single path. When a partial key is given, only this
195 single default path is prefixed; |pgfkeys| does not try to look up the key in
196 different parts of a search path. It is, however, possible to emulate search
197 paths, but a much more complicated mechanism must be used.
198
199 When you set keys (to be explained in a moment), you can freely mix partial and
200 full keys and you can change the default path. This makes it possible to
201 temporarily use keys from another part of the key tree (this turns out to be a
202 very useful feature).
203
204 Each key (may) store some \emph{tokens} and there exist commands, described
205 below, for setting, getting, and changing the tokens stored in a key. However,
206 you will only very seldom use these commands directly. Rather, the standard way
207 of using keys is the |\pgfkeys| command or some command that uses it internally
208 like, say, |\tikzset|. So, you may wish to skip the following commands and
209 continue with the next subsection.
210
211 \begin{command}{\pgfkeyssetvalue\marg{full key}\marg{token text}}
212 Stores the \meta{token text} in the \meta{full key}. The \meta{full key}
213 may not be a partial key, so no default-path-adding is done. The
214 \meta{token text} can be arbitrary tokens and may even contain things like
215 |#| or unbalanced \TeX-ifs.
216 %
217 \begin{codeexample}[]
218 \pgfkeyssetvalue{/my family/my key}{Hello, world!}
219 \pgfkeysvalueof{/my family/my key}
220 \end{codeexample}
221
222 The setting of a key is always local to the current \TeX\ group.
223 \end{command}
224
225 \begin{command}{\pgfkeyssetevalue\marg{full key}\marg{token text}}
226 The |\edef| version of |\pgfkeyssetvalue|.
227 \end{command}
228
229 \begin{command}{\pgfkeyslet\marg{full key}\marg{macro}}
230 Performs a |\let| statement so the \meta{full key} points to the contents
231 of \meta{macro}.
232 %
233 \begin{codeexample}[]
234 \def\helloworld{Hello, world!}
235 \pgfkeyslet{/my family/my key}{\helloworld}
236 \pgfkeysvalueof{/my family/my key}
237 \end{codeexample}
238 %
239 You should never let a key be equal to |\relax|. Such a key may or may not
240 be indistinguishable from an undefined key.
241 \end{command}
242
243 \begin{command}{\pgfkeysgetvalue\marg{full key}\marg{macro}}
244 Retrieves the tokens stored in the \meta{full key} and lets \meta{macro} be
245 equal to these tokens. If the key has not been set, the \meta{macro} will
246 be equal to |\relax|.
247 %
248 \begin{codeexample}[]
249 \pgfkeyssetvalue{/my family/my key}{Hello, world!}
250 \pgfkeysgetvalue{/my family/my key}{\helloworld}
251 \helloworld
252 \end{codeexample}
253 %
254 \end{command}
255
256 \begin{command}{\pgfkeysvalueof\marg{full key}}
257 Inserts the value stored in \meta{full key} at the current position into the
258 text. It expands to an alias of the primitive |\relax| if the key is undefined.
259 %
260 \begin{codeexample}[]
261 \pgfkeyssetvalue{/my family/my key}{Hello, world!}
262 \pgfkeysvalueof{/my family/my key}
263 \end{codeexample}
264 %
265 \emph{Note:} It is an error to assign to the result of the expansion of
266 |\pgfkeysvalueof|, not only semantically but in recent versions of \pgfname\
267 also logically. To set the value of a key \emph{always} use the appropriate
268 interfaces, e.g.\ |\pgfkeyssetvalue|.
269 \end{command}
270
271 \begin{command}{\pgfkeysifdefined\marg{full key}\marg{if}\marg{else}}
272 Checks whether this key was previously set using either |\pgfkeyssetvalue|
273 or |\pgfkeyslet|. If so, the code in \meta{if} is executed, otherwise the
274 code in \meta{else}.
275 %
276 \begin{codeexample}[]
277 \pgfkeyssetvalue{/my family/my key}{Hello, world!}
278 \pgfkeysifdefined{/my family/my key}{yes}{no}
279 \end{codeexample}
280 %
281 \end{command}
282
283
284 \subsection{Setting Keys}
285
286 Setting keys is done using a powerful command called |\pgfkeys|. This command
287 takes a list of so-called \emph{key--value pairs}. These are pairs of the form
288 \meta{key}|=|\meta{value}. The principal idea is the following: For each pair
289 in the list, some \emph{action} is taken. This action can be one of the
290 following:
291 %
292 \begin{enumerate}
293 \item A command is executed whose argument(s) are \meta{value}. This
294 command is stored in a special subkey of \meta{key}.
295 \item The \meta{value} is stored in the \meta{key} itself.
296 \item If the key's name (the part after the last slash) is a known
297 \emph{handler}, then this handler will take care of the key.
298 \item If the key is totally unknown, one of several possible \emph{unknown
299 key handlers} is called.
300 \end{enumerate}
301
302 Additionally, if the \meta{value} is missing, a default value may or may not be
303 substituted. Before we plunge into all the details, let us have a quick look at
304 the command itself.
305
306 \begin{command}{\pgfkeys\marg{key list}}
307 The \meta{key list} should be a list of key--value pairs, separated by
308 commas. A key--value pair can have the following two forms:
309 \meta{key}|=|\meta{value} or just \meta{key}. Any spaces around the
310 \meta{key} or around the \meta{value} are removed. It is permissible to
311 surround both the \meta{key} or the \meta{value} in curly braces, which are
312 also removed. Especially putting the \meta{value} in curly braces needs to
313 be done quite often, namely whenever the \meta{value} contains an
314 equal-sign or a comma.
315
316 The key--value pairs in the list are handled in the order they appear. How
317 this handling is done, exactly, is described in the rest of this section.
318
319 If a \meta{key} is a partial key, the current value of the default path is
320 prefixed to the \meta{key} and this ``upgraded'' key is then used. The
321 default path is just the root path |/| when the first key is handled, but
322 it may change later on. At the end of the command, the default path is
323 reset to the value it had before this command was executed.
324
325 Calls of this command may be nested. Thus, it is permissible to call
326 |\pgfkeys| inside the code that is executed for a key. Since the default
327 path is restored after a call of |\pgfkeys|, the default path will not
328 change when you call |\pgfkeys| while executing code for a key (which is
329 exactly what you want).
330 \end{command}
331
332 \begin{command}{\pgfqkeys\marg{default path}\marg{key list}}
333 This command has the same effect as |\pgfkeys{|\meta{default
334 path}|/.cd,|\meta{key list}|}|, it is only marginally quicker. This command
335 should not be used in user code, but rather in commands like |\tikzset| or
336 |\pgfset| that get called very often.
337 \end{command}
338
339 \begin{command}{\pgfkeysalso\marg{key list}}
340 This command has exactly the same effect as |\pgfkeys|, only the default
341 path is not modified before or after the keys are being set. This command
342 is mainly intended to be called by the code that is being processed for a
343 key.
344 \end{command}
345
346 \begin{command}{\pgfqkeysalso\marg{default path}\marg{key list}}
347 This command has the same effect as |\pgfkeysalso{|\meta{default
348 path}|/.cd,|\meta{key list}|}|, it is only quicker. Changing the default
349 path inside a |\pgfkeyalso| is dangerous, so use with care. A rather safe
350 place to call this command is at the beginning of a \TeX\ group.
351 \end{command}
352
353
354 \subsubsection{First Char Syntax Detection}
355 \label{sec:pgf:first:char:syntax}
356
357 Usually, keys are of the form \meta{key}|=|\meta{value} and how such keys are
358 handled is discussed in the rest of this section. However, it is also possible
359 to setup a different syntax for certain parts of the input to |\pgfkeys|. Since
360 this is a rather advanced option, most readers may wish to skip the following
361 discussion upon first reading; it is discussed here because this special syntax
362 detection is the very first thing that is done when a key is processed, before
363 any of the following operations are performed.
364
365 The |\pgfkeys| command and its variants decompose their input into a list of
366 \meta{string}s that are separated by commas. By default, each such
367 \meta{string} must either have the form \meta{key}|=|\meta{value} or of the
368 form \meta{key} with the value-part missing. However, you might wish to
369 interpret some of these strings differently. For instance, when a \meta{string}
370 has the form |"|\meta{text}|"|, you might wish the \meta{string} to be
371 interpreted as if one had written |label text={|\meta{text}|}|. Then, people
372 could write
373 %
374 \begin{codeexample}[code only]
375 \myset{red, "main valve", thick}
376 \end{codeexample}
377 %
378 instead of the more cumbersome
379 %
380 \begin{codeexample}[code only]
381 \myset{red, label text=main valve, thick}
382 \end{codeexample}
383 %
384 An example where such a syntax reinterpretation is done is the |quotes|
385 library, which allows you to write things like
386 %
387 \begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
388 \tikz \graph { a ->["1" red] b ->["0"] c };
389 \end{codeexample}
390 %
391 \noindent instead of the somewhat longer
392 %
393 \begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
394 \tikz \graph { a ->[edge node={node[red,auto]{1}}] b ->[edge label=0] c };
395 \end{codeexample}
396
397 In order to detect whether a \meta{string} has a special syntax, you can
398 request that the \emph{first character} of \meta{string} is analysed by the key
399 parser. If this first character matches a character that has been flagged as a
400 special character, the \meta{string} is not interpreted as a usual key--value
401 pair. Instead, \meta{string} is passed as a parameter to a special macro that
402 should take care of the \meta{string}. After this macro has finished, the
403 parsing continues with the \meta{next string} in the list.
404
405 In order to setup a special syntax handling for \meta{strings} that begin with
406 a certain character, two things need to be done:
407 %
408 \begin{enumerate}
409 \item First, the whole |first char syntax| detection must be ``switched on'',
410 since, by default, it is turned off for efficiency reasons (the
411 overhead is rather small, however). This is done by setting the
412 following key:
413 %
414 \begin{key}{/handlers/first char syntax=\opt{\meta{true or false}} (default true, initially false)}
415 \end{key}
416 \item Second, in order to handle strings starting with a certain
417 \meta{character} in a special way, you need to store a macro in the
418 following key:
419 %
420 \begin{key}{/handlers/first char syntax/\meta{meaning of character}}
421 The \meta{meaning of character} should be the text that \TeX's
422 command |\meaning| returns for a macro that has been |\let| to the
423 \meta{character}. For instance, when strings starting with |"|
424 should be treated in a special way, the \meta{meaning of character}
425 would be the string |the character "| since this is what \TeX\
426 writes when you say
427 %
428 \begin{codeexample}[]
429 \let\mycharacter="
430 \meaning\mycharacter
431 \end{codeexample}
432 %
433 Now, the key |/handlers/first char syntax/|\meta{meaning of
434 character} should be setup (using |\pgfkeyssetvalue| or using the
435 |.initial| handler) to store a \meta{macro name}.
436
437 If this is the case and if \meta{string} starts with the
438 \meta{character} (blanks at the beginning of \meta{string} are
439 deleted prior to this test), then \meta{macro name} is called with
440 \meta{string} as its argument.
441 \end{key}
442 \end{enumerate}
443
444 Let us now have a look at an example. We install two handlers, one for strings
445 starting with |"| and one for strings starting with |<|.
446 %
447 \begin{codeexample}[]
448 \pgfkeys{
449 /handlers/first char syntax=true,
450 /handlers/first char syntax/the character "/.initial=\myquotemacro,
451 /handlers/first char syntax/the character </.initial=\mypointedmacro,
452 }
453
454 \def\myquotemacro#1{Quoted: #1. }
455 \def\mypointedmacro#1{Pointed: #1. }
456
457 \ttfamily \pgfkeys{"foo", <bar>}
458 \end{codeexample}
459
460 Naturally, in the above examples, the two handling macros did not do something
461 particularly exciting. In the next example, we setup a more elaborate macro
462 that mimics a small part the behavior of the |quotes| library, only for single
463 quotes:
464 %
465 \begin{codeexample}[]
466 \pgfkeys{
467 /handlers/first char syntax=true,
468 /handlers/first char syntax/the character '/.initial=\mysinglequotemacro
469 }
470
471 \def\mysinglequotemacro#1{\pgfkeysalso{label={#1}}}
472
473 \tikz \node [circle, 'foo', draw] {bar};
474 \end{codeexample}
475
476 Note that in the above example, the macro |\mysinglequotemacro| gets passed the
477 complete string, including the single quotes. It is the job of the macro to get
478 rid of them, if this is necessary.
479
480 The first char syntax detection allows you to perform rather powerful
481 transformations on the syntax of keys -- provided you can ``pin down'' the
482 syntax on the first character. In the following example, you can write
483 expressions in parentheses in front of a key--value pair and the pair will only
484 be executed when the expression evaluates to true:
485 %
486 \begin{codeexample}[]
487 \pgfkeys{
488 /handlers/first char syntax=true,
489 /handlers/first char syntax/the character (/.initial=\myparamacro
490 }
491
492 \def\myparamacro#1{\myparaparser#1\someendtext}
493 \def\myparaparser(#1)#2\someendtext{
494 \pgfmathparse{#1}
495 \ifx\pgfmathresult\onetext
496 \pgfkeysalso{#2}
497 \fi
498 }
499 \def\onetext{1}
500
501 \foreach \i in {1,...,4}
502 \tikz \node [draw, thick, rectangle, (pi>\i) circle, (pi>\i*2) draw=red] {x};
503 \end{codeexample}
504
505
506 \subsubsection{Default Arguments}
507
508 The arguments of the |\pgfkeys| command can either be of the form
509 \meta{key}|=|\meta{value} or of the form \meta{key} with the value-part
510 missing. In the second case, the |\pgfkeys| will try to provide a \emph{default
511 value} for the \meta{value}. If such a default value is defined, it will be
512 used as if you had written \meta{key}|=|\meta{default value}.
513
514 In the following, the details of how default values are determined is
515 described; however, you should normally use the handlers |/.default| and
516 |/.value required| as described in Section~\ref{section-default-handlers} and
517 you may wish to skip the following details.
518
519 When |\pgfkeys| encounters a \meta{key} without an equal-sign, the following
520 happens:
521 %
522 \begin{enumerate}
523 \item The input is replaced by \meta{key}|=\pgfkeysnovalue|. In particular,
524 the commands |\pgfkeys{my key}| and
525 % FIXME: there is a bug in the pretty printer ... fix it and get rid of '||' here:
526 |\pgfkeys{my key=||\pgfkeysnovalue}| have exactly the same effect and
527 you can ``simulate'' a missing value by providing the value
528 |\pgfkeysnovalue|, which is sometimes useful.
529 \item If the \meta{value} is |\pgfkeysnovalue|, then it is checked whether
530 the subkey \meta{key}|/.@def| exists. For instance, if you write
531 |\pgfkeys{/my key}|, then it is checked whether the key |/my key/.@def|
532 exists.
533 \item If the key \meta{key}|/.@def| exists, then the tokens stored in this
534 key are used as \meta{value}.
535 \item If the key does not exist, then |\pgfkeysnovalue| is used as the
536 \meta{value}.
537 \item At the end, if the \meta{value} is now equal to
538 |\pgfkeysvaluerequired|, then the code (or something fairly equivalent)
539 |\pgfkeys{/errors/value required=|\meta{key}|{}}| is executed. Thus, by
540 changing this key you can change the error message that is printed or
541 you can handle the missing value in some other way.
542 \end{enumerate}
543
544
545 \subsubsection{Keys That Execute Commands}
546 \label{section-key-code}
547
548 After the transformation process described in the previous subsection, we
549 arrive at a key of the form \meta{key}=\meta{value}, where \meta{key} is a full
550 key. Different things can now happen, but always the macro |\pgfkeyscurrentkey|
551 will have been set up to expand to the text of the \meta{key} that is currently
552 being processed.
553
554 The first things that is tested is whether the key \meta{key}|/.@cmd| exists.
555 If this is the case, then it is assumed that this key stores the code of a
556 macro and this macro is executed. The argument of this macro is \meta{value}
557 directly followed by |\pgfeov|, which stands for ``end of value''. The
558 \meta{value} is not surrounded by braces. After this code has been executed,
559 |\pgfkeys| continues with the next key in the \meta{key list}.
560
561 It may seem quite peculiar that the macro stored in the key \meta{key}|/.@cmd|
562 is not simply executed with the argument |{|\meta{value}|}|. However, the
563 approach taken in the |pgfkeys| packages allows for more flexibility. For
564 instance, assume that you have a key that expects a \meta{value} of the form
565 ``\meta{text}|+|\meta{more text}'' and wishes to store \meta{text} and
566 \meta{more text} in two different macros. This can be achieved as follows:
567 %
568 \begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}]
569 \def\mystore#1+#2\pgfeov{\def\a{#1}\def\b{#2}}
570 \pgfkeyslet{/my key/.@cmd}{\mystore}
571 \pgfkeys{/my key=hello+world}
572
573 |\a| is `\a', |\b| is `\b'.
574 \end{codeexample}
575
576 Naturally, defining the code to be stored in a key in the above manner is too
577 awkward. The following commands simplify things a bit, but the usual manner of
578 setting up code for a key is to use one of the handlers described in
579 Section~\ref{section-code-handlers}.
580
581 \begin{command}{\pgfkeysdef\marg{key}\marg{code}}
582 This command temporarily defines a \TeX-macro with the argument list
583 |#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this macro. The
584 net effect of all this is that you have then set up code for the key
585 \meta{key} so that when you write |\pgfkeys{|\meta{key}|=|\meta{value}|}|,
586 then the \meta{code} is executed with all occurrences of |#1| in
587 \meta{code} being replaced by \meta{value}. (This behavior is quite
588 similar to the |\define@key| command of |keyval| and |xkeyval|).
589 %
590 \begin{codeexample}[]
591 \pgfkeysdef{/my key}{#1, #1.}
592 \pgfkeys{/my key=hello}
593 \end{codeexample}
594 \end{command}
595
596 \begin{command}{\pgfkeysedef\marg{key}\marg{code}}
597 This command works like |\pgfkeysdef|, but it uses |\edef| rather than
598 |\def| when defining the key macro. If you do not know the difference
599 between the two, then you will not need this command; and if you know the
600 difference, then you will know when you need this command.
601 \end{command}
602
603 \begin{command}{\pgfkeysdefnargs\marg{key}\marg{argument count}\marg{code}}
604 This command works like |\pgfkeysdef|, but it allows you to provide an
605 arbitrary \meta{argument count} between $0$ and $9$ (inclusive).
606 %
607 \begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}]
608 \pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}}
609 \pgfkeys{/my key=
610 {hello}
611 {world}}
612
613 |\a| is `\a', |\b| is `\b'.
614 \end{codeexample}
615 %
616 The resulting key will expect exactly \marg{argument count} arguments.
617 \end{command}
618 %
619 \begin{command}{\pgfkeysedefnargs\marg{key}\marg{argument count}\marg{code}}
620 The |\edef| version of |\pgfkeysdefnargs|.
621 \end{command}
622
623 \begin{command}{\pgfkeysdefargs\marg{key}\marg{argument pattern}\marg{code}}
624 This command works like |\pgfkeysdefnargs|, but it allows you to provide an
625 arbitrary \meta{argument pattern} rather than just a number of arguments.
626 %
627 \begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}]
628 \pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}}
629 \pgfkeys{/my key=hello+world}
630
631 |\a| is `\a', |\b| is `\b'.
632 \end{codeexample}
633 %
634 Note that |\pgfkeysdefnargs| is \emph{better} when it comes to simple
635 argument \emph{counts}\footnote{When the resulting keys are used, the
636 \texttt{defnargs} variant allows spaces between arguments whereas the
637 \texttt{defargs} variant does not; it considers the spaces as part of the
638 argument.}.
639 \end{command}
640
641 \begin{command}{\pgfkeysedefargs\marg{key}\marg{argument pattern}\marg{code}}
642 The |\edef| version of |\pgfkeysdefargs|.
643 \end{command}
644
645
646 \subsubsection{Keys That Store Values}
647
648 Let us continue with what happens when |\pgfkeys| processes the current key and
649 the subkey \meta{key}|/.@cmd| is not defined. Then it is checked whether the
650 \meta{key} itself exists (has been previously assigned a value using, for
651 instance, |\pgfkeyssetvalue|). In this case, the tokens stored in \meta{key}
652 are replaced by \meta{value} and |\pgfkeys| proceeds with the next key in the
653 \meta{key list}.
654
655
656 \subsubsection{Keys That Are Handled}
657 \label{section-key-handlers}
658
659 If neither the \meta{key} itself nor the subkey \meta{key}|/.@cmd| are defined,
660 then the \meta{key} cannot be processed ``all by itself''. Rather, a
661 \meta{handler} is needed for this key. Most of the power of |pgfkeys| comes
662 from the proper use of such handlers.
663
664 Recall that the \meta{key} is always a full key (if it was not originally, it
665 has already been upgraded at this point to a full key). It decomposed into two
666 parts:
667
668 \begin{enumerate}
669 \item The \meta{path} of \meta{key} (everything before the last slash) is
670 stored in the macro |\pgfkeyscurrentpath|.
671 \item The \meta{name} of \meta{key} (everything after the last slash) is
672 stored in the macro |\pgfkeyscurrentname|.
673
674 It is recommended (but not necessary) that the name of a handler starts
675 with a dot (but not with |.@|), so that they are easy to detect for the
676 reader.
677 \end{enumerate}
678
679 (For efficiency reasons, these two macros are only set up at this point; so
680 when code is executed for a key in the ``usual'' manner then these macros are
681 not set up.)
682
683 The |\pgfkeys| command now checks whether the key
684 |/handlers/|\meta{name}|/.@cmd| exists. If so, it should store a command and
685 this command is executed exactly in the same manner as described in
686 Section~\ref{section-key-code}. Thus, this code gets the \meta{value} that was
687 originally intended for \meta{key} as its argument, followed by |\pgfeov|. It
688 is the job of the handlers to do something useful with the \meta{value}.
689
690 For an example, let us write a handler that will output the value stored in a
691 key to the log file. We call this handler |/.print to log|. The idea is that
692 when someone tries to use the key |/my key/.print to log|, then this key will
693 not be defined and the handler gets executed. The handler will then have access
694 to the path-part of the key, which is |/my key|, via the macro
695 |\pgfkeyscurrentpath|. It can then lookup which value is stored in this key and
696 print it.
697 %
698 \begin{codeexample}[code only]
699 \pgfkeysdef{/handlers/.print to log}
700 {%
701 \pgfkeysgetvalue{\pgfkeyscurrentpath}{\temp}
702 \writetolog{\temp}
703 }
704 \pgfkeyssetvalue{/my key}{Hi!}
705 ...
706 \pgfkeys{/my key/.print to log}
707 \end{codeexample}
708 %
709 The above code will print |Hi!| in the log, provided the macro |\writetolog| is
710 set up appropriately.
711
712 For a more interesting handler, let us program a handler that will set up a key
713 so that when the key is used, some code is executed. This code is given as
714 \meta{value}. All the handler must do is to call |\pgfkeysdef| for the path of
715 the key (which misses the handler's name) and assign the parameter value to it.
716 %
717 \begin{codeexample}[]
718 \pgfkeysdef{/handlers/.my code}{\pgfkeysdef{\pgfkeyscurrentpath}{#1}}
719 \pgfkeys{/my key/.my code=(#1)}
720 \pgfkeys{/my key=hallo}
721 \end{codeexample}
722
723 There are some parameters for handled keys which prove to be useful in some
724 (possibly rare) special cases:
725 %
726 \begin{key}{/handler config=\mchoice{all,only existing,full or existing} (initially all)}
727 Changes the initial configuration how key handlers will be used.
728
729 This configuration is for advanced users and rarely necessary.
730 %
731 \begin{description}
732 \item[\texttt{all}] The preconfigured setting |all| works as described
733 above and imposes no restriction on the key setting process.
734 \item[\texttt{only existing}] The value |only existing| modifies the
735 algorithm for handled keys as follows: a handler \meta{key
736 name}|/.|\meta{handler} will be executed only if \meta{key name} is
737 either a key which stores its value directly or a command key for
738 which |/.@cmd| exists. If \meta{key name} does \emph{not} exist
739 already, the complete string \meta{key name}|/.|\meta{handler} is
740 considered to be an unknown key and the procedure described in the
741 next section applies (for the path of \meta{key name}).
742 %
743 \begin{codeexample}[]
744 % Define a test key and error handlers:
745 \pgfkeys{/the/key/.code={Initial definition. }}
746 \pgfkeys{/handlers/.unknown/.code={Unknown key `\pgfkeyscurrentkey'. }}
747
748 % calling the test key yields 'Initial definition. ':
749 \pgfkeys{/the/key}
750
751 % Change configuration:
752 \pgfkeys{/handler config=only existing}
753
754 % allowed: key *re*-definition:
755 \pgfkeys{/the/key/.code={Re-Definition. }}
756 % calling the key yields 'Re-Definition. ':
757 \pgfkeys{/the/key}
758
759 % not allowed: definition of new keys:
760 % this checks for '/the/other key/.unknown'
761 % and '/handlers/.unknown'
762 % and yields finally
763 % 'Unknown key `/the/other key/.code`'
764 \pgfkeys{/the/other key/.code={New definition. }}
765 \end{codeexample}
766 %
767 It is necessary to exclude some key handlers from this procedure.
768 Altogether, the detailed procedure is as follows:
769 %
770 \begin{enumerate}
771 \item If a handled key like |/a path/a key/.a handler=value| is
772 encountered, it is checked whether the handler should be
773 invoked. This is the case if
774 %
775 \begin{itemize}
776 \item An exception from |only existing| for this key
777 exists (see below),
778 \item The key |/a path/a key| exists already -- either
779 directly as storage key or with the |.@cmd| suffix.
780 \end{itemize}
781 %
782 \item If the check passes, everything works as before.
783 \item If the check fails, the complete key will be considered
784 to be unknown. In that case, the handling of unknown keys
785 as described in the next section applies. There, the
786 current key path will be set to |/a path| and the current
787 key's name to |key/.a handler|.
788 \end{enumerate}
789
790 A consequence of this configuration is to provide more meaningful
791 processing of handled keys if a search path for keys is in effect,
792 see section~\ref{sec:pgf:unknown:keys} for an example.
793 \item[\texttt{full or existing}] Finally, the choice |full or existing|
794 is a variant of |only existing|: it works in the same way for keys
795 which do not have a full key path. For example, the style
796
797 |\pgfkeys{/my path/.cd,key/.style={|$\dotsc$|}}|
798
799 can only be redefined: it doesn't have a full path, so the
800 |only existing| mechanism applies. But the style
801
802 |\pgfkeys{/my path/key/.style={|$\dotsc$|}}|
803
804 will still work. This allows users to override the |only existing|
805 feature if they know what they're doing (and provide full key
806 paths).
807 \end{description}
808 \end{key}
809
810 \begin{key}{/handler config/only existing/add exception=\marg{key handler name}}
811 Allows to add exceptions to the |/handler config=only existing| feature.
812 Initially exceptions for the key handlers |/.cd|, |/.try|, |/.retry|,
813 |/.lastretry| and |/.unknown| are defined. The value \marg{key handler
814 name} should be the name of a key handler.
815 \end{key}
816
817
818 \subsubsection{Keys That Are Unknown}
819 \label{sec:pgf:unknown:keys}
820
821 For some keys, neither the key, nor its |.@cmd| subkey nor a handler is
822 defined. In this case, it is checked whether the key \meta{current
823 path}|/.unknown/.@cmd| exists. Thus, when you try to use the key
824 |/tikz/strange|, then it is checked whether |/tikz/.unknown/.@cmd| exists. If
825 this key exists (which it does), it is executed. This code can then try to make
826 sense of the key. For instance, the handler for \tikzname\ will try to
827 interpret the key's name as a color or as an arrow specification or as a
828 \pgfname\ option.
829
830 You can set up unknown key handlers for your own keys by simply setting the
831 code of the key \meta{my path prefix}|/.unknown|. This also allows you to set
832 up ``search paths''. The idea is that you would like keys to be searched not
833 only in a single default path, but in several. Suppose, for instance, that you
834 would like keys to be searched for in |/a|, |/b|, and |/b/c|. We set up a key
835 |/my search path| for this:
836 %
837 \begin{codeexample}[code only]
838 \pgfkeys{/my search path/.unknown/.code=
839 {%
840 \let\searchname=\pgfkeyscurrentname%
841 \pgfkeysalso{%
842 /a/\searchname/.try=#1,
843 /b/\searchname/.retry=#1,
844 /b/c/\searchname/.retry=#1%
845 }%
846 }%
847 }
848 \pgfkeys{/my search path/.cd,foo,bar}
849 \end{codeexample}
850 %
851 In the above code, |foo| and |bar| will be searched for in the three
852 directories |/a|, |/b|, and |/b/c|. Before you start implementing search paths
853 using this pattern, consider the |/.search also| handler discussed below.
854
855 If the key \meta{current path}|/.unknown/.@cmd| does not exist, the handler
856 |/handlers/.unknown| is invoked instead, which is always defined and which
857 prints an error message by default.
858
859
860 \subsubsection{Search Paths And Handled Keys}
861
862 There is one special case which occurs in the search path example above. What
863 happens if we want to change a style? For example,
864 %
865 \begin{codeexample}[code only]
866 \pgfkeys{/my search path/.cd,custom/.style={variables}}
867 \end{codeexample}
868 %
869 \noindent could mean a style in |/my search path/|, |/a/|, |/b/| or even
870 |/b/c/|!
871
872 Due to the rules for handled keys, the answer is
873 |/my search path/custom/.style={variables}|. It may be useful to modify this
874 default behavior. One useful thing would be to search for \emph{existing}
875 styles named |custom| and redefine them. For example, if a style |/b/custom|
876 exists, the assignment |custom/.style={variables}| should probably redefine
877 |/b/custom| instead of |/my search path/custom|. This can be done using
878 |handler config|:
879 %
880 \begin{codeexample}[]
881 \pgfkeys{/my search path/.unknown/.code=
882 {%
883 \let\searchname=\pgfkeyscurrentname%
884 \pgfkeysalso{%
885 /a/\searchname/.try=#1,
886 /b/\searchname/.retry=#1,
887 /b/c/\searchname/.retry=#1%
888 }%
889 }%
890 }
891
892 % Let's define /b/custom here:
893 \pgfkeys{/b/custom/.code={This is `\pgfkeyscurrentkey'. }}
894
895 % Reconfigure treatment of key handlers:
896 \pgfkeys{/handler config=only existing}
897
898 % The search path procedure will find /b/custom
899 % -> leads to This is `/b/custom'
900 \pgfkeys{/my search path/.cd,custom}
901
902 % Due to the reconfiguration, this will find /b/custom instead of
903 % defining /my search path/custom:
904 \pgfkeys{/my search path/.cd,custom/.append code={Modified. }}
905
906 % So using the search path, we again find /b/custom which
907 % leads to This is `/b/custom' Modified
908 \pgfkeys{/my search path/.cd,custom}
909 \end{codeexample}
910
911 A slightly different approach to search paths can be realized using the
912 |/.search also| key handler, see below.
913
914
915 \subsection{Key Handlers}
916
917 We now describe which key handlers are defined by default. You can also define
918 new ones as described in Section~\ref{section-key-handlers}.
919
920
921 \subsubsection{Handlers for Path Management}
922
923 \begin{handler}{{.cd}}
924 This handler causes the default path to be set to \meta{key}. Note that the
925 default path is reset at the beginning of each call to |\pgfkeys| to be
926 equal to~|/|.
927
928 \example |\pgfkeys{/tikz/.cd,...}|
929 \end{handler}
930
931 \begin{handler}{{.is family}}
932 \label{section-is family-handler}
933 This handler sets up things such that when \meta{key} is executed, then the
934 current path is set to \meta{key}. A typical use is the following:
935 %
936 \begin{codeexample}[code only]
937 \pgfkeys{/tikz/.is family}
938 \pgfkeys{tikz,line width=1cm}
939 \end{codeexample}
940 %
941 The effect of this handler is the same as if you had written
942 \meta{key}|/.style=|\meta{key}|/.cd|, only the code produced by the
943 |/.is family| handler is quicker.
944 \end{handler}
945
946
947 \subsubsection{Setting Defaults}
948 \label{section-default-handlers}
949
950 \begin{handler}{{.default}|=|\meta{value}}
951 Sets the default value of \meta{key} to \meta{value}. This means that
952 whenever no value is provided in a call to |\pgfkeys|, then this
953 \meta{value} will be used instead.
954
955 \example |\pgfkeys{/width/.default=1cm}|
956 \end{handler}
957
958 \begin{handler}{{.value required}}
959 This handler causes the error message key |/errors/value required| to be
960 issued whenever the \meta{key} is used without a value.
961
962 \example |\pgfkeys{/width/.value required}|
963 \end{handler}
964
965 \begin{handler}{{.value forbidden}}
966 This handler causes the error message key |/errors/value forbidden| to be
967 issued whenever the \meta{key} is used with a value.
968
969 This handler works be adding code to the code of the key. This means that
970 you have to define the key first before you can use this handler.
971 %
972 \begin{codeexample}[code only]
973 \pgfkeys{/my key/.code=I do not want an argument!}
974 \pgfkeys{/my key/.value forbidden}
975
976 \pgfkeys{/my key} % Ok
977 \pgfkeys{/my key=foo} % Error
978 \end{codeexample}
979 %
980 \end{handler}
981
982
983 \subsubsection{Defining Key Codes}
984 \label{section-code-handlers}
985
986 A number of handlers exist for defining the code of keys.
987
988 \begin{handler}{{.code}|=|\meta{code}}
989 This handler executes |\pgfkeysdef| with the parameters \meta{key} and
990 \meta{code}. This means that, afterwards, whenever the \meta{key} is used,
991 the \meta{code} gets executed. More precisely, when
992 \meta{key}|=|\meta{value} is encountered in a key list, \meta{code} is
993 executed with any occurrence of |#1| replaced by \meta{value}. As always,
994 if no \meta{value} is given, the default value is used, if defined, or the
995 special value |\pgfkeysnovalue|.
996
997 It is permissible that \meta{code} calls the command |\pgfkeys|. It is also
998 permissible that \meta{code} calls the command |\pgfkeysalso|, which is
999 useful for styles, see below.
1000 %
1001 \begin{codeexample}[code only]
1002 \pgfkeys{/par indent/.code={\parindent=#1},/par indent/.default=2em}
1003 \pgfkeys{/par indent=1cm}
1004 ...
1005 \pgfkeys{/par indent}
1006 \end{codeexample}
1007 %
1008 \end{handler}
1009
1010 \begin{handler}{{.ecode}|=|\meta{code}}
1011 This handler works like |/.code|, only the command |\pgfkeysedef| is used.
1012 \end{handler}
1013
1014 \begin{handler}{{.code 2 args}|=|\meta{code}}
1015 This handler works like |/.code|, only two arguments rather than one are
1016 expected when the \meta{code} is executed. This means that when
1017 \meta{key}|=|\meta{value} is encountered in a key list, the \meta{value}
1018 should consist of two arguments. For instance, \meta{value} could be
1019 |{first}{second}|. Then \meta{code} is executed with any occurrence of |#1|
1020 replaced |first| and any occurrence of |#2| replaced by |second|.
1021 %
1022 \begin{codeexample}[code only]
1023 \pgfkeys{/page size/.code 2 args={\paperheight=#2\paperwidth=#1}}
1024 \pgfkeys{/page size={30cm}{20cm}}
1025 \end{codeexample}
1026 %
1027 Because of the special way the \meta{value} is parsed, if you set
1028 \meta{value} to, for instance, |first| (without any braces), then |#1| will
1029 be set to |f| and |#2| will be set to |irst|.
1030 \end{handler}
1031
1032 \begin{handler}{{.ecode 2 args}|=|\meta{code}}
1033 This handler works like |/.code 2 args|, only an |\edef| is used rather
1034 than a |\def| to define the macro.
1035 \end{handler}
1036
1037 \begin{handler}{{.code n args}|=|\marg{argument count}\marg{code}}
1038 This handler also works like |/.code|, but you can now specify a number of
1039 arguments between $0$ and $9$ (inclusive).
1040 %
1041 \begin{codeexample}[]
1042 \pgfkeys{/a key/.code n args={2}{First=`#1', Second=`#2'}}
1043 \pgfkeys{/a key={A}{B}}
1044 \end{codeexample}
1045 %
1046 In contrast to |/.code 2 args|, there must be exactly \meta{argument count}
1047 arguments, not more and not less and these arguments should be properly
1048 delimited.
1049 \end{handler}
1050
1051 \begin{handler}{{.ecode n args}|=|\marg{argument count}\marg{code}}
1052 This handler works like |/.code n args|, only an |\edef| is used rather
1053 than a |\def| to define the macro.
1054 \end{handler}
1055
1056 \begin{handler}{{.code args}|=|\marg{argument pattern}\marg{code}}
1057 This handler is the most flexible way to define a |/.code| key: you can now
1058 specify an arbitrary \meta{argument pattern}. Such a pattern is a usual
1059 \TeX\ macro pattern. For instance, suppose \meta{argument pattern} is
1060 |(#1/#2)| and \meta{key}|=|\meta{value} is encountered in a key list with
1061 \meta{value} being |(first/second)|. Then \meta{code} is executed with any
1062 occurrence of |#1| replaced |first| and any occurrence of |#2| replaced by
1063 |second|. So, the actual \meta{value} is matched against the \meta{argument
1064 pattern} in the standard \TeX\ way.
1065 %
1066 \begin{codeexample}[code only]
1067 \pgfkeys{/page size/.code args={#1 and #2}{\paperheight=#2\paperwidth=#1}}
1068 \pgfkeys{/page size=30cm and 20cm}
1069 \end{codeexample}
1070
1071 Note that |/.code n args| should be preferred in case you need just a
1072 number of arguments (when the resulting keys are used, |/.code n args|
1073 gobbles spaces between the arguments whereas |/.code args| considers spaces
1074 to be part of the argument).
1075 \end{handler}
1076
1077 \begin{handler}{{.ecode args}|=|\marg{argument pattern}\marg{code}}
1078 This handler works like |/.code args|, only an |\edef| is used rather than
1079 a |\def| to define the macro.
1080 \end{handler}
1081
1082 There are also handlers for modifying existing keys.
1083
1084 \begin{handler}{{.add code}|=|\marg{prefix code}\marg{append code}}
1085 This handler adds code to an existing key. The \meta{prefix code} is added
1086 to the code stored in \meta{key}|/.@cmd| at the beginning, the \meta{append
1087 code} is added to this code at the end. Either can be empty. The argument
1088 list of \meta{code} cannot be changed using this handler. Note that both
1089 \meta{prefix code} and \meta{append code} may contain parameters like |#2|.
1090 %
1091 \begin{codeexample}[code only]
1092 \pgfkeys{/par indent/.code={\parindent=#1}}
1093 \newdimen\myparindent
1094 \pgfkeys{/par indent/.add code={}{\myparindent=#1}}
1095 ...
1096 \pgfkeys{/par indent=1cm} % This will set both \parindent and
1097 % \myparindent to 1cm
1098 \end{codeexample}
1099 %
1100 \end{handler}
1101
1102 \begin{handler}{{.prefix code}|=|\meta{prefix code}}
1103 This handler is a shortcut for \meta{key}|/.add code={|\meta{prefix
1104 code}|}{}|. That is, this handler adds the \meta{prefix code} at the
1105 beginning of the code stored in \meta{key}|/.@cmd|.
1106 \end{handler}
1107
1108 \begin{handler}{{.append code}|=|\meta{append code}}
1109 This handler is a shortcut for \meta{key}|/.add code={}{|\meta{append
1110 code}|}|.
1111 \end{handler}
1112
1113
1114 \subsubsection{Defining Styles}
1115
1116 The following handlers allow you to define \emph{styles}. A style is a key list
1117 that is processed whenever the style is given as a key in a key list. Thus, a
1118 style ``stands for'' a certain key value list. Styles can be parameterized just
1119 like normal code.
1120
1121 \begin{handler}{{.style}|=|\meta{key list}}
1122 This handler sets things up so that whenever \meta{key}|=|\meta{value} is
1123 encountered in a key list, then the \meta{key list}, with every occurrence
1124 of |#1| replaced by \meta{value}, is processed instead. As always, if no
1125 \meta{value} is given, the default value is used, if defined, or the
1126 special value |\pgfkeysnovalue|.
1127
1128 You can achieve the same effect by writing
1129 \meta{key}|/.code=\pgfkeysalso{|\meta{key list}|}|. This means, in
1130 particular, that the code of a key could also first execute some normal
1131 code and only then process some further keys.
1132 %
1133 \begin{codeexample}[code only]
1134 \pgfkeys{/par indent/.code={\parindent=#1}}
1135 \pgfkeys{/no indent/.style={/par indent=0pt}}
1136 \pgfkeys{/normal indent/.style={/par indent=2em}}
1137 \pgfkeys{/no indent}
1138 ...
1139 \pgfkeys{/normal indent}
1140 \end{codeexample}
1141 %
1142 The following example shows a parameterized style ``in action''.
1143 %
1144 \begin{codeexample}[]
1145 \begin{tikzpicture}[outline/.style={draw=#1,fill=#1!20}]
1146 \node [outline=red] {red box};
1147 \node [outline=blue] at (0,-1) {blue box};
1148 \end{tikzpicture}
1149 \end{codeexample}
1150 %
1151 \end{handler}
1152
1153 \begin{handler}{{.estyle}|=|\meta{key list}}
1154 This handler works like |/.style|, only the \meta{code} is set using
1155 |\edef| rather than |\def|. Thus, all macros in the \meta{code} are
1156 expanded prior to saving the style.
1157 \end{handler}
1158
1159 For styles the corresponding handlers as for normal code exist:
1160
1161 \begin{handler}{{.style 2 args}|=|\meta{key list}}
1162 This handler works like |/.code 2 args|, only for styles. Thus, the
1163 \meta{key list} may contain occurrences of both |#1| and |#2| and when the
1164 style is used, two parameters must be given as \meta{value}.
1165 %
1166 \begin{codeexample}[code only]
1167 \pgfkeys{/paper height/.code={\paperheight=#1},/paper width/.code={\paperwidth=#1}}
1168 \pgfkeys{/page size/.style 2 args={/paper height=#1,/paper width=#2}}
1169 \pgfkeys{/page size={30cm}{20cm}}
1170 \end{codeexample}
1171 %
1172 \end{handler}
1173
1174 \begin{handler}{{.estyle 2 args}|=|\meta{key list}}
1175 This handler works like |/.style 2 args|, only an |\edef| is used rather
1176 than a |\def| to define the macro.
1177 \end{handler}
1178
1179 \begin{handler}{{.style n args}|=|\marg{argument count}\meta{key list}}
1180 This handler works like |/.code n args|, only for styles. Here, \meta{key
1181 list} may depend on all \meta{argument count} parameters.
1182 \end{handler}
1183
1184 \begin{handler}{{.add style}|=|\marg{prefix key list}\marg{append key list}}
1185 This handler works like |/.add code|, only for styles. However, it is
1186 permissible to add styles to keys that have previously been set using
1187 |/.code|. (It is also permissible to add normal \meta{code} to a key that
1188 has previously been set using |/.style|). When you add a style to a key
1189 that was previously set using |/.code|, the following happens: When
1190 \meta{key} is processed, the \meta{prefix key list} will be processed
1191 first, then the \meta{code} that was previously stored in
1192 \meta{key}|/.@cmd|, and then the keys in \meta{append key list} are
1193 processed.
1194 %
1195 \begin{codeexample}[code only]
1196 \pgfkeys{/par indent/.code={\parindent=#1}}
1197 \pgfkeys{/par indent/.add style={}{/my key=#1}}
1198 ...
1199 \pgfkeys{/par indent=1cm} % This will set \parindent and
1200 % then execute /my key=#1
1201 \end{codeexample}
1202 %
1203 \end{handler}
1204
1205 \begin{handler}{{.style args}|=|\marg{argument pattern}\marg{key list}}
1206 This handler works like |/.code args|, only for styles.
1207 \end{handler}
1208
1209 \begin{handler}{{.estyle args}|=|\marg{argument pattern}\marg{code}}
1210 This handler works like |/.ecode args|, only for styles.
1211 \end{handler}
1212
1213 \begin{handler}{{.prefix style}|=|\meta{prefix key list}}
1214 Works like |/.add style|, but only for the prefix key list.
1215 \end{handler}
1216
1217 \begin{handler}{{.append style}|=|\meta{append key list}}
1218 Works like |/.add style|, but only for the append key list.
1219 \end{handler}
1220
1221
1222 \subsubsection{Defining Value-, Macro-, If- and Choice-Keys}
1223
1224 For some keys, the code that should be executed for them is rather
1225 ``specialized''. For instance, it happens often that the code for a key just
1226 sets a certain \TeX-if to true or false. For these cases, predefined handlers
1227 make it easier to install the necessary code.
1228
1229 However, we start with some handlers that are used to manage the value that is
1230 directly stored in a key.
1231
1232 \begin{handler}{{.initial}|=|\meta{value}}
1233 This handler sets the value of \meta{key} to \meta{value}. Note that no
1234 subkeys are involved. After this handler has been used, by the rules
1235 governing keys, you can subsequently change the value of the \meta{key} by
1236 just writing \meta{key}|=|\meta{value}. Thus, this handler is used to set
1237 the initial value of key.
1238 %
1239 \begin{codeexample}[code only]
1240 \pgfkeys{/my key/.initial=red}
1241 % "/my key" now stores the value "red"
1242 \pgfkeys{/my key=blue}
1243 % "/my key" now stores the value "blue"
1244 \end{codeexample}
1245
1246 Note that with this configuration, writing |\pgfkeys{/my key}| will not
1247 have the effect you might expect (namely that |blue| is inserted into the
1248 main text). Rather, |/my key| will be promoted to |/my key=\pgfkeysnovalue|
1249 and, thus, |\pgfkeysnovalue| will be stored in |/my key|.
1250
1251 To retrieve the value stored in a key, the handler |/.get| is used.
1252
1253 \medskip
1254 \emph{Remark:} A key can both store a value and execute commands%
1255 \footnote{This behavior was partially changed in \pgfname{} 3.1.6 and then
1256 restored in 3.1.7. For compatibility reasons, this behavior will not be
1257 changed in future releases anymore.}.
1258 If so, using \meta{key} will \emph{always} execute commands with the passed
1259 value, or the default value |\pgfkeysnovalue| if no value is provided.
1260 Note that the stored value is never used. To update the stored value, the
1261 handler |/.initial| or command |\pgfkeyssetvalue| is used.
1262 %
1263 \begin{codeexample}[]
1264 \pgfkeys{/my key/.initial=red}
1265 \pgfkeys{/my key/.code=#1}
1266 % "/my key" now both stores the value "red" and executes commands
1267 \pgfkeys{/my key=blue}
1268 % "/my key" now still stores the value "red"
1269 \end{codeexample}
1270 %
1271 \end{handler}
1272
1273 \begin{handler}{{.get}|=|\meta{macro}}
1274 Executes a |\let| command so that \meta{macro} contains the contents stored
1275 in \meta{key}.
1276 %
1277 \begin{codeexample}[]
1278 \pgfkeys{/my key/.initial=red}
1279 \pgfkeys{/my key=blue}
1280 \pgfkeys{/my key/.get=\mymacro}
1281 \mymacro
1282 \end{codeexample}
1283 %
1284 \end{handler}
1285
1286 \begin{handler}{{.add}|=|\marg{prefix value}\marg{append value}}
1287 Adds the \meta{prefix value} at the beginning and the \meta{append value}
1288 at the end of the value stored in \meta{key}.
1289 \end{handler}
1290
1291 \begin{handler}{{.prefix}|=|\marg{prefix value}}
1292 Adds the \meta{prefix value} at the beginning of the value stored in
1293 \meta{key}.
1294 \end{handler}
1295
1296 \begin{handler}{{.append}|=|\marg{append value}}
1297 Adds the \meta{append value} at the end of the value stored in \meta{key}.
1298 \end{handler}
1299
1300 \begin{handler}{{.link}|=|\meta{another key}}
1301 Stores the value |\pgfkeysvalueof{|\meta{another key}|}| in the \meta{key}.
1302 The idea is that when you expand the \meta{key}, the value of \meta{another
1303 key} is expanded instead. This corresponds loosely to the notion of soft
1304 links in Unix, hence the name.
1305 \end{handler}
1306
1307 The next handler is useful for the common situation where
1308 \meta{key}|=|\meta{value} should cause the \meta{value} to be stored in some
1309 macro. Note that, typically, you could just as well store the value in the key
1310 itself.
1311
1312 \begin{handler}{{.store in}|=|\meta{macro}}
1313 This handler has the following effect: When you write
1314 \meta{key}|=|\meta{value}, the code |\def|\meta{macro}|{|\meta{value}|}| is
1315 executed. Thus, the given value is ``stored'' in the \meta{macro}.
1316 %
1317 \begin{codeexample}[]
1318 \pgfkeys{/text/.store in=\mytext}
1319 \def\a{world}
1320 \pgfkeys{/text=Hello \a!}
1321 \def\a{Gruffalo}
1322 \mytext
1323 \end{codeexample}
1324 %
1325 \end{handler}
1326
1327 \begin{handler}{{.estore in}|=|\meta{macro}}
1328 This handler is similar to |/.store in|, only the code
1329 |\edef|\meta{macro}|{|\meta{value}|}| is used. Thus, the macro-expanded
1330 version of \meta{value} is stored in the \meta{macro}.
1331 %
1332 \begin{codeexample}[]
1333 \pgfkeys{/text/.estore in=\mytext}
1334 \def\a{world}
1335 \pgfkeys{/text=Hello \a!}
1336 \def\a{Gruffalo}
1337 \mytext
1338 \end{codeexample}
1339 %
1340 \end{handler}
1341
1342 In another common situation a key is used to set a \TeX-if to true or false.
1343
1344 \begin{handler}{{.is if}|=|\meta{\TeX-if name}}
1345 This handler has the following effect: When you write
1346 \meta{key}|=|\meta{value}, it is first checked that \meta{value} is |true|
1347 or |false| (the default is |true| if no \meta{value} is given). If this is
1348 not the case, the error key |/errors/boolean expected| is executed.
1349 Otherwise, the code |\|\meta{\TeX-if name}\meta{value} is executed, which
1350 sets the \TeX-if accordingly.
1351 %
1352 \begin{codeexample}[]
1353 \newif\iftheworldisflat
1354 \pgfkeys{/flat world/.is if=theworldisflat}
1355 \pgfkeys{/flat world=false}
1356 \iftheworldisflat
1357 Flat
1358 \else
1359 Round?
1360 \fi
1361 \end{codeexample}
1362 %
1363 \end{handler}
1364
1365 The next handler deals with the problem when a \meta{key}|=|\meta{value} makes
1366 sense only for a small set of possible \meta{value}s. For instance, the line
1367 cap can only be |rounded| or |rect| or |butt|, but nothing else. For this
1368 situation the following handler is useful.
1369
1370 \begin{handler}{{.is choice}}
1371 This handler sets things up so that writing \meta{key}|=|\meta{value} will
1372 cause the subkey \meta{key}|/|\meta{value} to be executed. So, each of the
1373 different possible choices should be given by a subkey of \meta{key}.
1374 %
1375 \begin{codeexample}[code only]
1376 \pgfkeys{/line cap/.is choice}
1377 \pgfkeys{/line cap/round/.code={\pgfsetroundcap}}
1378 \pgfkeys{/line cap/butt/.code={\pgfsetbuttcap}}
1379 \pgfkeys{/line cap/rect/.code={\pgfsetrectcap}}
1380 \pgfkeys{/line cap/rectangle/.style={/line cap=rect}}
1381 ...
1382 \draw [/line cap=butt] ...
1383 \end{codeexample}
1384 %
1385 If the subkey \meta{key}|/|\meta{value} does not exist, the error key
1386 |/errors/unknown choice value| is executed.
1387 \end{handler}
1388
1389
1390 \subsubsection{Expanded and Multiple Values}
1391
1392 When you write \meta{key}|=|\meta{value}, you usually wish to use the
1393 \meta{value} ``as is''. Indeed, great care is taken to ensure that you can even
1394 use things like |#1| or unbalanced \TeX-ifs inside \meta{value}. However,
1395 sometimes you want the \meta{value} to be expanded before it is used. For
1396 instance, \meta{value} might be a macro name like |\mymacro| and you do not
1397 want |\mymacro| to be used as the macro, but rather the \emph{contents} of
1398 |\mymacro|. Thus, instead of using \meta{value}, you wish to use whatever
1399 \meta{value} expands to. Instead of using some fancy |\expandafter| hackery,
1400 you can use the following handlers:
1401
1402 \begin{handler}{{.expand once}|=|\meta{value}}
1403 This handler expands \meta{value} once (more precisely, it executes an
1404 |\expandafter| command on the first token of \meta{value}) and then process
1405 the resulting \meta{result} as if you had written
1406 \meta{key}|=|\meta{result}. Note that if \meta{key} contains a handler
1407 itself, this handler will be called normally.
1408 %
1409 \begin{codeexample}[]
1410 \def\a{bottom}
1411 \def\b{\a}
1412 \def\c{\b}
1413
1414 \pgfkeys{/key1/.initial=\c}
1415 \pgfkeys{/key2/.initial/.expand once=\c}
1416 \pgfkeys{/key3/.initial/.expand twice=\c}
1417 \pgfkeys{/key4/.initial/.expanded=\c}
1418
1419 \def\a{{\ttfamily\string\a}}
1420 \def\b{{\ttfamily\string\b}}
1421 \def\c{{\ttfamily\string\c}}
1422
1423 \begin{tabular}{ll}
1424 Key 1:& \pgfkeys{/key1} \\
1425 Key 2:& \pgfkeys{/key2} \\
1426 Key 3:& \pgfkeys{/key3} \\
1427 Key 4:& \pgfkeys{/key4}
1428 \end{tabular}
1429 \end{codeexample}
1430 %
1431 \end{handler}
1432
1433 \begin{handler}{{.expand twice}|=|\meta{value}}
1434 This handler works like saying
1435 \meta{key}|/.expand once/.expand once=|\meta{value}.
1436 \end{handler}
1437
1438 \begin{handler}{{.expanded}|=|\meta{value}}
1439 This handler will completely expand \meta{value} (using |\edef|) before
1440 processing \meta{key}|=|\meta{result}.
1441 \end{handler}
1442
1443 \begin{handler}{{.evaluated}|=|\meta{value}}
1444 This handler will evaluate \meta{value} as a mathematical
1445 expression with |\pgfmathparse| and assign \meta{key}|=\pgfmathresult|.
1446 %
1447 \begin{codeexample}[]
1448 \pgfkeys{
1449 /golden ratio/.initial/.evaluated={(1 + sqrt(5))/2},
1450 }
1451 \pgfkeys{/golden ratio}
1452 \end{codeexample}
1453 %
1454 \end{handler}
1455
1456 \begin{handler}{{.list}|=|\meta{comma-separated list of values}}
1457 This handler causes the key to be used repeatedly, namely once for every
1458 element of the list of values. Note that the list of values should
1459 typically be surrounded by braces since, otherwise, \TeX\ will not be able
1460 to tell whether a comma starts a new key or a new value.
1461
1462 The \meta{list of values} is processed using the |\foreach| statement, so
1463 you can use the |...| notation.
1464 %
1465 \begin{codeexample}[]
1466 \pgfkeys{/foo/.code=(#1)}
1467 \pgfkeys{/foo/.list={a,b,0,1,...,5}}
1468 \end{codeexample}
1469 %
1470 \end{handler}
1471
1472
1473 \subsubsection{Handlers for Forwarding}
1474
1475 \begin{handler}{{.forward to}|=|\meta{another key}}
1476 This handler causes the \meta{key} to ``forward'' its argument to
1477 \meta{another key}. When the \meta{key} is used, its normal code will be
1478 executed first. Then, the value is (additionally) passed to \meta{another
1479 key}. If the \meta{key} has not yet been defined prior to the use of
1480 |.forward to|, it will be defined then (and do nothing by itself, expect
1481 for forwarding it to \meta{key name}). The \meta{another key} must be a
1482 fully qualified key name.
1483 %
1484 \begin{codeexample}[]
1485 \pgfkeys{
1486 /a/.code=(a:#1),
1487 /b/.code=(b:#1),
1488 /b/.forward to=/a,
1489 /c/.forward to=/a
1490 }
1491 \pgfkeys{/b=1} \pgfkeys{/c=2}
1492 \end{codeexample}
1493 %
1494 \end{handler}
1495
1496 \begin{handler}{{.search also}=\marg{path list}}
1497 A style which installs a |/.unknown| handler into \meta{key}. This
1498 |/.unknown| handler will then search for unknown keys in every path
1499 provided in \marg{path list}.
1500 %
1501 \begin{codeexample}[]
1502 % define a key:
1503 \pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
1504
1505 % set up a search path:
1506 \pgfkeys{/main path/.search also={/secondary path}}
1507
1508 % try searching for `option=value' in '/main path':
1509 % -> this finds `/secondary path/option'!
1510 \pgfkeys{/main path/.cd,option=value}
1511 \end{codeexample}
1512
1513 The |/.search also| handler follows the strategy
1514 %
1515 \begin{enumerate}
1516 \item If a user provides a fully qualified key which could not be
1517 found, for example the full string |/main path/option|, it assumes
1518 that the user knew what she is doing -- and does \emph{not}
1519 continue searching for |option| in \marg{path list}.
1520 \item If a user provides only the key's name, for example |option| and
1521 |option| cannot be found in the current default path (which is
1522 |/main path| in our example above), the current default path is set
1523 to the next element in \marg{path list} (which is |/secondary path|
1524 here) and |\pgfkeys| will be restarted.
1525
1526 This will be iterated until either a match has been found or all
1527 elements in \marg{path list} have been tested.
1528 \item If all
1529 elements in \marg{path list} have been checked and the key is still
1530 unknown, the fall-back handler |/handlers/.unknown| will be
1531 invoked.
1532 \end{enumerate}
1533 %
1534 \begin{codeexample}[]
1535 % define a key:
1536 \pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
1537
1538 % set up a search path:
1539 \pgfkeys{/main path/.search also={/secondary path}}
1540
1541 % try searching for `option=value' in '/main path':
1542 % -> this finds `/secondary path/option'!
1543 \pgfkeys{/main path/.cd,option=value}
1544
1545 % negative example:
1546 % try searching for fully qualified key /main path/option.
1547 % This won't be handled by .search also.
1548 \pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}%
1549 \pgfkeys{/main path/.cd,/main path/option=value}
1550 \end{codeexample}
1551
1552 Please note that the strategy of |/.search also| is different from the
1553 first example provided in section~\ref{sec:pgf:unknown:keys} ``Unknown
1554 Keys'' because |/.search also| only applies to keys that are not fully
1555 qualified.
1556
1557 For those who are familiar with |\pgfkeys|, the actual implementation of
1558 |/.search also| might be interesting:
1559 %
1560 \begin{enumerate}
1561 \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to
1562 %
1563 \begin{codeexample}[code only]
1564 \pgfkeys{/path/.unknown/.code={%
1565 \def\pgfkeys@searchalso@temp@value{#1}%
1566 \ifpgfkeysaddeddefaultpath
1567 \expandafter\pgfkeys@firstoftwo
1568 \else
1569 \expandafter\pgfkeys@secondoftwo
1570 \fi{%
1571 % only process keys for which no full path has been
1572 % provided:
1573 \pgfkeyssuccessfalse
1574 \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
1575 \ifpgfkeyssuccess
1576 \else
1577 % search with /tikz as default path:
1578 \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.expand once=%
1579 \pgfkeys@searchalso@temp@value}%
1580 \fi
1581 }{%
1582 \pgfkeysgetvalue{/handlers/.unknown/.@cmd}{\pgfkeys@code}%
1583 \expandafter\pgfkeys@code\pgfkeys@searchalso@temp@value\pgfeov
1584 }%
1585 }
1586 }
1587 \end{codeexample}
1588 %
1589 \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
1590 %
1591 \begin{codeexample}[code only]
1592 \pgfkeys{/path/.unknown/.code={%
1593 \def\pgfkeys@searchalso@temp@value{#1}%
1594 \ifpgfkeysaddeddefaultpath
1595 \expandafter\pgfkeys@firstoftwo
1596 \else
1597 \expandafter\pgfkeys@secondoftwo
1598 \fi{%
1599 \pgfkeyssuccessfalse
1600 \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
1601 \ifpgfkeyssuccess
1602 \else
1603 % step 1: search in /tikz with .try:
1604 \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try/.expand once=%
1605 \pgfkeys@searchalso@temp@value}%
1606 \fi
1607 \ifpgfkeyssuccess
1608 \else
1609 % step 2: search in /pgf (without .try!):
1610 \pgfqkeys{/pgf}{\pgfkeys@searchalso@name/.expand once=\pgfkeys@searchalso@}%
1611 \fi
1612 }{%
1613 \pgfkeysgetvalue{/handlers/.unknown/.@cmd}{\pgfkeys@code}%
1614 \expandafter\pgfkeys@code\pgfkeys@searchalso@temp@value\pgfeov
1615 }%
1616 }
1617 }
1618 \end{codeexample}
1619 \end{enumerate}
1620
1621 To also enable searching for styles (or other handled keys), consider
1622 changing the configuration for handled keys to
1623 |/handler config=full or existing| when you use |/.search also|, that is,
1624 use
1625 %
1626 \begin{codeexample}[code only]
1627 \pgfkeys{
1628 /main path/.search also={/secondary path},
1629 /handler config=full or existing}
1630 \end{codeexample}
1631 %
1632 \end{handler}
1633
1634
1635 \subsubsection{Handlers for Testing Keys}
1636
1637 \begin{handler}{{.try}|=|\meta{value}}
1638 This handler causes the same things to be done as if
1639 \meta{key}|=|\meta{value} had been written instead. However, if neither
1640 \meta{key}|/.@cmd| nor the key itself is defined, no handlers will be
1641 called. Instead, the execution of the key just stops. Thus, this handler
1642 will ``try'' to use the key, but no further action is taken when the key is
1643 not defined.
1644
1645 The \TeX-if |\ifpgfkeyssuccess| will be set according to whether the
1646 \meta{key} was successfully executed or not.
1647 %
1648 \begin{codeexample}[]
1649 \pgfkeys{/a/.code=(a:#1)}
1650 \pgfkeys{/b/.code=(b:#1)}
1651 \pgfkeys{/x/.try=hmm,/a/.try=hallo,/b/.try=welt}
1652 \end{codeexample}
1653 %
1654 \end{handler}
1655
1656 \begin{handler}{{.retry}|=|\meta{value}}
1657 This handler works just like |/.try|, only it will not do anything if
1658 |\ifpgfkeyssuccess| is false. Thus, this handler will only retry to set a
1659 key if ``the last attempt failed''.
1660 %
1661 \begin{codeexample}[]
1662 \pgfkeys{/a/.code=(a:#1)}
1663 \pgfkeys{/b/.code=(b:#1)}
1664 \pgfkeys{/x/.try=hmm,/a/.retry=hallo,/b/.retry=welt}
1665 \end{codeexample}
1666 %
1667 \end{handler}
1668
1669 \begin{handler}{{.lastretry}|=|\meta{value}}
1670 This handler works like |/.retry|, only it will invoke the usual handlers
1671 for unknowns keys if |\ifpgfkeyssuccess| is false. Thus, this handler
1672 will only try to set a key if ``the last attempt failed''. Furthermore,
1673 this here is the last such attempt.
1674 \end{handler}
1675
1676
1677 \subsubsection{Handlers for Key Inspection}
1678
1679 \begin{handler}{{.show value}}
1680 This handler executes a |\show| command on the value stored in \meta{key}.
1681 This is useful mostly for debugging.
1682
1683 \example |\pgfkeys{/my/obscure key/.show value}|
1684 \end{handler}
1685
1686 \begin{handler}{{.show code}}
1687 This handler executes a |\show| command on the code stored in
1688 \meta{key}|/.@cmd|. This is useful mostly for debugging.
1689
1690 \example |\pgfkeys{/my/obscure key/.show code}|
1691 \end{handler}
1692
1693 The following key is not a handler, but it also commonly used for inspecting
1694 things:
1695 %
1696 \begin{key}{/utils/exec=\meta{code}}
1697 This key will simply execute the given \meta{code}.
1698
1699 % FIXME: there is a bug in the pretty printer ... fix it!
1700 \example \verb|\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}|
1701 \end{key}
1702
1703
1704 \subsection{Error Keys}
1705
1706 In certain situations errors can occur, like using an undefined key. In these
1707 situations error keys are executed. They should store a macro that gets two
1708 arguments: The first is the offending key (possibly only after macro
1709 expansion), the second is the value that was passed as a parameter (also
1710 possibly only after macro expansion).
1711
1712 Currently, error keys are simply executed. In the future it might be a good
1713 idea to have different subkeys that are executed depending on the language
1714 currently set so that users get a localized error message.
1715
1716 \begin{key}{/errors/value required=\marg{offending key}\marg{value}}
1717 This key is executed whenever an \meta{offending key} is used without a
1718 value when a value is actually required.
1719 \end{key}
1720
1721 \begin{key}{/errors/value forbidden=\marg{offending key}\marg{value}}
1722 This key is executed whenever a key is used with a value when a value is
1723 actually forbidden.
1724 \end{key}
1725
1726 \begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}}
1727 This key is executed whenever a key set up using |/.is if| gets called with
1728 a \meta{value} other than |true| or |false|.
1729 \end{key}
1730
1731 \begin{key}{/errors/unknown choice value=\marg{offending key}\marg{value}}
1732 This key is executed whenever a choice is used as a \meta{value} for a key
1733 set up using the |/.is choice| handler that is not defined.
1734 \end{key}
1735
1736 \begin{key}{/errors/unknown key=\marg{offending key}\marg{value}}
1737 This key is executed whenever a key is unknown and no specific |/.unknown|
1738 handler is found.
1739 \end{key}
1740
1741
1742 \input{pgfmanual-en-pgfkeysfiltered.tex}