summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex
blob: 25825dc52c792164c680bfd6f1bb88abd97c7f3d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Key Management}
\label{section-keys}

This section describes the package |pgfkeys|. It is loaded
automatically by both \pgfname\ and \tikzname.

\begin{package}{pgfkeys}
  This package can be used independently of \pgfname. Note that no
  other package of \pgfname\ needs to be loaded (so neither the
  emulation layer nor the system layer is needed). The Con\TeX t
  abbreviation is |pgfkey| if |pgfmod| is not loaded.                   % pgfkey --> pgfkeys?
\end{package}



\subsection{Introduction}

\subsubsection{Comparison to Other Packages}

The |pgfkeys| package defines a key--value management system that is in
some sense similar to the more light-weight |keyval| system and the
improved |xkeyval| system. However, |pgfkeys| uses a slightly
different philosophy than these systems and it will coexist peacefully
with both of them.

The main differences between |pgfkeys| and |xkeyval| are the
following:

\begin{itemize}
\item |pgfkeys| organizes keys in a tree, while |keyval| and |xkeyval|
  use families. In |pgfkeys| the families correspond to the root
  entries of the key tree.
\item |pgfkeys| has no save-stack impact (you will have to read the
  \TeX Book very carefully to appreciate this).
\item |pgfkeys| is slightly slower than |keyval|, but not much.
\item |pgfkeys| supports styles. This means that keys can just stand
  for other keys (which can stand for other keys in turn or which can
  also just execute some code). \tikzname\ uses this mechanism heavily.
\item |pgfkeys| supports multi-argument key code. This can, however,
  be emulated in |keyval|.
\item |pgfkeys| supports handlers. These are call-backs that are
  called when a key is not known. They are very flexible, in fact even
  defining keys in different ways is handled by, well, handlers.
\end{itemize}


\subsubsection{Quick Guide to Using the Key Mechanism}

The following quick guide to \pgfname's key mechanism only treats the
most commonly used features. For an in-depth discussion of what is
going on, please consult the remainder of this section.

Keys are organized in a large tree that is reminiscent of the Unix
file tree. A typical key might be, say, |/tikz/coordinate system/x|
or just |/x|. Again as in Unix, when you specify keys you can provide
the complete path of the key, but you usually just provide the name of
the key (corresponding to the file name without any path) and the path
is added automatically.

Typically (but not necessarily) some code is associated with a key. To
execute this code, you use the |\pgfkeys| command. This command takes
a list of so-called key--value pairs. Each pair is of the form
\meta{key}|=|\meta{value}. For each pair the |\pgfkeys| command will
execute the code stored for the \meta{key} with its parameter set to
\meta{value}.

Here is a typical example of how the |\pgfkeys| command is used:
\begin{codeexample}[code only]
\pgfkeys{/my key=hallo,/your keys/main key=something\strange,
         key name without path=something else}
\end{codeexample}

Now, to set the code that is stored in a key you do not need to learn
a new command. Rather, the |\pgfkeys| command can also be used to set
the code of a key. This is done using so-called \emph{handlers}. They
look like keys whose names look like ``hidden files in Unix'' since
they start with a dot. The handler for setting the code of a key is
appropriately called |/.code| and it is used as follows:
\begin{codeexample}[]
\pgfkeys{/my key/.code=The value is '#1'.}
\pgfkeys{/my key=hi!}
\end{codeexample}
As you can see, in the first line we defined the code for the key
|/my key|. In the second line we executed this code with the parameter
set to |hi!|.

There are numerous handlers for defining a key. For instance, we can
also define a key whose value actually consists of more than one
parameter.
\begin{codeexample}[]
\pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.}
\pgfkeys{/my key={a1}{a2}}
\end{codeexample}

We often want to have keys where the code is called with some default
value if the user does not provide a value. Not surprisingly, this is
also done using a handler, this time called |/.default|.
\begin{codeexample}[]
\pgfkeys{/my key/.code=(#1)}
\pgfkeys{/my key/.default=hello}
\pgfkeys{/my key=hallo,/my key}
\end{codeexample}

The other way round, it is also possible to specify that a value
\emph{must} be specified, using a handler called
|/.value required|. Finally, you can also require that no value
\emph{may} be specified using |/.value forbidden|.

All keys for a package like, say, \tikzname\ start with the path
|/tikz|. We obviously do not like to write this path down every
time we use a key (so we do not have to write things like
|\draw[/tikz/line width=1cm]|). What we need is to somehow ``change
the default path to a specific location.'' This is done using the
handler |/.cd| (for ``change directory''). Once this handler has been
used on a key, all subsequent keys {\itshape in the current call of
  |\pgfkeys| only} are automatically prefixed with this path, if
necessary.

Here is an example:
\begin{codeexample}[code only]
\pgfkeys{/tikz/.cd,line width=1cm,line cap=round}
\end{codeexample}
This makes it easy to define commands like |\tikzset|, which could be
defined as follows (the actual definition is a bit faster, but the
effect is the same):
\begin{codeexample}[code only]
\def\tikzset#1{\pgfkeys{/tikz/.cd,#1}}
\end{codeexample}

When a key is handled, instead of executing some code, the key can
also cause further keys to be executed. Such keys will be called
\emph{styles}. A style is, in essence, just a key list that should be
executed whenever the style is executed. Here is an example:
\begin{codeexample}[]
\pgfkeys{/a/.code=(a:#1)}
\pgfkeys{/b/.code=(b:#1)}
\pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}}
\pgfkeys{/my style=wow}
\end{codeexample}
As the above example shows, styles can also be paramaterized, just like
the normal code keys.

As a typical use of styles, suppose we wish to set up the key |/tikz|
so that it will change the default path to |/tikz|. This can be
achieved as follows:
\begin{codeexample}[code only]
\pgfkeys{/tikz/.style=/tikz/.cd}
\pgfkeys{tikz,line width=1cm,draw=red}
\end{codeexample}

Note that when |\pgfkeys| is executed, the default path is set
to~|/|. This means that the first |tikz| will be completed to
|/tikz|. Then |/tikz| is a style and, thus, replaced by |/tikz/.cd|,
which changes the default path to |/tikz|. Thus, the |line width| is
correctly prefixed with |/tikz|.

\subsection{The Key Tree}

The |pgfkeys| package organizes keys in a so-called \emph{key
  tree}. This tree will be familiar to anyone who has used a Unix
operating system: A key is addressed by a path, which consists of
different parts separated by slashes. A typical key might be
|/tikz/line width| or just |/tikz| or something more complicated like
|/tikz/cs/x/.store in|.

Let us fix some further terminology: Given a key like |/a/b/c|, we
call the part leading up the last slash (|/a/b|) the \emph{path} of
the key. We call everything after the last slash (|c|) the \emph{name}
of the key (in a file system this would be the file name).

We do not always wish to specify keys completely. Instead, we usually
specify only part of a key (typically only the name) and the
\emph{default path} is then added to the key at the front. So, when
the default path is |/tikz| and you
refer to the (partial) key |line width|, the actual key that is used
is |/tikz/line width|. There is a simple rule for deciding whether a
key is a partial key or a full key: If it starts with a slash, then it
is a full key and it is not modified; if it does not start with
a slash, then the default path is automatically prefixed.

Note that the default path is not the same as a search path. In
particular, the default path is just a single path. When a partial key
is given, only this single default path is prefixed; |pgfkeys| does
not try to look up the key in different parts of a search path. It is,
however, possible to emulate search paths, but a much more
complicated mechanism must be used.

When you set keys (to be explained in a moment), you can freely mix
partial and full keys and you can change the default path. This makes
it possible to temporarily use keys from another part of the key tree
(this turns out to be a very useful feature).

Each key (may) store some \emph{tokens} and there exist commands,
described below, for setting, getting, and changing the tokens stored
in a key. However, you will only very seldom use these commands
directly. Rather, the standard way of using keys is the |\pgfkeys|
command or some command that uses it internally like, say,
|\tikzset|. So, you may wish to skip the following commands and
continue with the next subsection.

\begin{command}{\pgfkeyssetvalue\marg{full key}\marg{token text}}
  Stores the \meta{token text} in the \meta{full key}. The \meta{full key}
  may not be a partial key, so no default-path-adding is done. The
  \meta{token text} can be arbitrary tokens and may even contain things
  like |#| or unbalanced \TeX-ifs.
\begin{codeexample}[]
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
\pgfkeysvalueof{/my family/my key}
\end{codeexample}

  The setting of a key is always local to the current \TeX\ group.
\end{command}

\begin{command}{\pgfkeyslet\marg{full key}\marg{macro}}
  Performs a |\let| statement so the \meta{full key} points to the
  contents of \meta{macro}.
\begin{codeexample}[]
\def\helloworld{Hello, world!}
\pgfkeyslet{/my family/my key}{\helloworld}
\pgfkeysvalueof{/my family/my key}
\end{codeexample}
  You should never let a key be equal to |\relax|. Such a key may or
  may not be indistinguishable from an undefined key.
\end{command}

\begin{command}{\pgfkeysgetvalue\marg{full key}\marg{macro}}
  Retrieves the tokens stored in the \meta{full key} and lets
  \meta{macro} be equal to these tokens. If the key has
  not been set, the \meta{macro} will be equal to |\relax|.
\begin{codeexample}[]
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
\pgfkeysgetvalue{/my family/my key}{\helloworld}
\helloworld
\end{codeexample}
\end{command}

\begin{command}{\pgfkeysvalueof\marg{full key}}
  Inserts the value stored in \meta{full key} at the current position
  into the text.

\begin{codeexample}[]
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
\pgfkeysvalueof{/my family/my key}
\end{codeexample}
\end{command}


\begin{command}{\pgfkeysifdefined\marg{full key}\marg{if}\marg{else}}
  Checks whether this key was previously set using either
  |\pgfkeyssetvalue| or |\pgfkeyslet|. If so, the code in \meta{if} is
  executed, otherwise the code in \meta{else}.

  This command will use e\TeX's |\ifcsname| command, if available, for
  efficiency. This means, however, that it may behave differently for
  \TeX\ and for e\TeX\ when you set keys to |\relax|. For this reason
  you should not do so.
\begin{codeexample}[]
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
\pgfkeysifdefined{/my family/my key}{yes}{no}
\end{codeexample}
\end{command}


\subsection{Setting Keys}

Settings keys is done using a powerful command called |\pgfkeys|. This
command takes a list of so-called \emph{key--value pairs}. These are
pairs of the form \meta{key}|=|\meta{value}. The principle idea is the
following: For each pair in the list, some \emph{action} is
taken. This action can be one of the following:

\begin{enumerate}
\item A command is executed whose argument(s) are \meta{value}. This
  command is stored in a special subkey of \meta{key}.
\item The \meta{value} is stored in the \meta{key} itself.
\item If the key's name (the part after the last slash) is a known
  \emph{handler}, then this handler will take care of the key.
\item If the key is totally unknown, one of several possible
  \emph{unknown key handlers} is called.
\end{enumerate}

Additionally, if the \meta{value} is missing, a default value may or
may not be substituted. Before we plunge into all the details,
let us have a quick look at the command itself.

\begin{command}{\pgfkeys\marg{key list}}
  The \meta{key list} should be a list of key--value pairs, separated
  by commas. A key--value pair can have the following two forms:
  \meta{key}|=|\meta{value} or just \meta{key}. Any spaces around the
  \meta{key} or around the \meta{value} are removed. It is permissible
  to surround both the \meta{key} or the \meta{value} in curly braces,
  which are also removed. Especially putting the \meta{value} in curly
  braces needs to be done quite often, namely whenever the \meta{value}
  contains an equal-sign or a comma.

  The key--value pairs in the list are handled in the order they
  appear. How this handling is done, exactly, is described in the rest
  of this section.

  If a \meta{key} is a partial key, the current value of the default
  path is prefixed to the \meta{key} and this ``upgraded'' key is
  then used. The default path is just the root path |/| when the first
  key is handled, but it may change later on. At the end of the
  command, the default path is reset to the value it had before this
  command was executed.

  Calls of this command may be nested. Thus, it is permissible to call
  |\pgfkeys| inside the code that is executed for a key. Since the
  default path is restored after a call of |\pgfkeys|, the default
  path will not change when you call |\pgfkeys| while executing code
  for a key (which is exactly what you want).
\end{command}

\begin{command}{\pgfqkeys\marg{default path}\marg{key list}}
  This command has the same effect as |\pgfkeys{|\meta{default
      path}|/.cd,|\meta{key list}|}|, it is only marginally
  quicker. This command should not be used in user code, but rather in
  commands like |\tikzset| or |\pgfset| that get called very often.
\end{command}

\begin{command}{\pgfkeysalso\marg{key list}}
  This command has exactly the same effect as |\pgfkeys|, only the
  default path is not modified before or after the keys are being
  set. This command is mainly intended to be called by the code that
  is being processed for a key.
\end{command}

\begin{command}{\pgfqkeysalso\marg{default path}\marg{key list}}
  This command has the same effect as |\pgfkeysalso{|\meta{default
      path}|/.cd,|\meta{key list}|}|, it is only quicker. Changing the
  default path inside a |\pgfkeyalso| is dangerous, so use with
  care. A rather safe place to call this command is at the beginning
  of a \TeX\ group.
\end{command}


\subsubsection{First Char Syntax Detection}
\label{sec:pgf:first:char:syntax}

Usually, keys are of the form \meta{key}|=|\meta{value} and how such
keys are handled is discussed in the rest of this section. However, it
is also possible to setup a different syntax for certain parts of the
input to |\pgfkeys|. Since this is a rather advanced option, most
readers may wish to skip the following discussion upon first reading;
it is discussed here because this special syntax detection is the very
first thing that is done when a key is processed, before any of the
following operations are performed.

The |\pgfkeys| command and its variants decompose their input into a
list of \meta{string}s that are separated by commas. By default, each
such \meta{string} must either have the form \meta{key}|=|\meta{value}
or of the form \meta{key} with the value-part missing. However, you
might wish to interpret some of these strings differently. For
instance, when a \meta{string} has the form |"|\meta{text}|"|, you
might wish the \meta{string} to be interpreted as if one had written
|label text={|\meta{text}|}|. Then, people could write
\begin{codeexample}[code only]
\myset{red, "main valve", thick}
\end{codeexample}
instead of the more cumbersome
\begin{codeexample}[code only]
\myset{red, label text=main valve, thick}
\end{codeexample}
An example where such a syntax reinterpretation is done is the
|quotes| library, which allows you to write things like
\begin{codeexample}[]
\tikz \graph { a ->["1" red] b ->["0"] c };
\end{codeexample}
\noindent instead of the somewhat longer
\begin{codeexample}[]
\tikz \graph { a ->[edge node={node[red,auto]{1}}] b ->[edge label=0] c };
\end{codeexample}

In order to detect whether a \meta{string} has a special syntax, you
can request that the \emph{first character} of \meta{string} is
analysed by the key parser. If this first character matches a
character that has been flagged as a special character, the
\meta{string} is not interpreted as a usual key--value pair. Instead,
\meta{string} is passed as a parameter to a special macro that should
take care of the \meta{string}. After this macro has finished, the
parsing continues with the \meta{next string} in the list.

In order to setup a special syntax handling for \meta{strings} that
begin with a certain character, two things need to be done:
\begin{enumerate}
\item First, the whole first char syntax detection must be ``switched
  on,'' since, by default, it is turned off for efficiency reasons
  (the overhead is rather small, however). This is done by setting the
  following key:
  \begin{key}{/handlers/first char syntax=\opt{\meta{true or false}}
      (default true, initially false)}
  \end{key}
\item Second, in order to handle strings starting with a certain
  \meta{character} in a special way, you need to store a macro in the
  following key:
  \begin{key}{/handlers/first char syntax/\meta{meaning of character}}
    The \meta{meaning of character} should be the text that \TeX's
    command |\meaning| returns for a macro that has been |\let| to the
    \meta{character}. For instance, when strings starting with |"|
    should be treated in a special way, the \meta{meaning of
      character} would be the string |the character "| since this is
    what \TeX\ writes when you say
\begin{codeexample}[]
\let\mycharacter="
\meaning\mycharacter  
\end{codeexample}
    Now, the key |/handlers/first char syntax/|\meta{meaning of
      character} should be setup (using |\pgfkeyssetvalue| or using
    the |.initial| handler) to store a \meta{macro name}.

    If this is the case and if \meta{string} starts with the
    \meta{character} (blanks at the beginning of \meta{string} are
    deleted prior to this test), then \meta{macro name} is called with
    \meta{string} as its argument.
  \end{key}
\end{enumerate}

Let us now have a look at an example. We install two handlers, one for
strings starting with |"| and one for strings starting with |<|.

\begin{codeexample}[]
\pgfkeys{
  /handlers/first char syntax=true,
  /handlers/first char syntax/the character "/.initial=\myquotemacro,
  /handlers/first char syntax/the character </.initial=\mypointedmacro,
}

\def\myquotemacro#1{Quoted: #1. }
\def\mypointedmacro#1{Pointed: #1. }

\ttfamily \pgfkeys{"foo", <bar>}
\end{codeexample}

Naturally, in the above examples, the two handling macros did not do
something particularly exciting. In the next example, we setup a more
elaborate macro that mimics a small part the behaviour of the |quotes|
library, only for single quotes:

\begin{codeexample}[]
\pgfkeys{
  /handlers/first char syntax=true,
  /handlers/first char syntax/the character '/.initial=\mysinglequotemacro
}

\def\mysinglequotemacro#1{\pgfkeysalso{label={#1}}}

\tikz \node [circle, 'foo', draw] {bar};
\end{codeexample}

Note that in the above example, the macro |\mysinglequotemacro| gets
passed the complete string, including the single quotes. It is the job
of the macro to get rid of them, if this is necessary.

The first char syntax detection allows you to perform rather powerful
transformations on the syntax of keys -- provided you can ``pin down''
the syntax on the first character. In the following example, you can
write expressions in parentheses in front of a key--value pair and the
pair will only be executed when the expression evaluates to true:

\begin{codeexample}[]
\pgfkeys{
  /handlers/first char syntax=true,
  /handlers/first char syntax/the character (/.initial=\myparamacro
}

\def\myparamacro#1{\myparaparser#1\someendtext}
\def\myparaparser(#1)#2\someendtext{
  \pgfmathparse{#1}
  \ifx\pgfmathresult\onetext
    \pgfkeysalso{#2}
  \fi
}
\def\onetext{1}

\foreach \i in {1,...,4}
  \tikz \node [draw, thick, rectangle, (pi>\i) circle, (pi>\i*2) draw=red] {x};
\end{codeexample}


\subsubsection{Default Arguments}

The arguments of the |\pgfkeys| command can either be of the form
\meta{key}|=|\meta{value} or of the form \meta{key} with the
value-part missing. In the second case, the |\pgfkeys| will try to
provide a \emph{default value} for the \meta{value}. If such a default
value is defined, it will be used as if you had written
\meta{key}|=|\meta{default value}.

In the following, the details of how default values are determined is
described; however, you should normally use the handlers |/.default|
and |/.value required| as described in
Section~\ref{section-default-handlers} and you may wish to skip
the following details.

When |\pgfkeys| encounters a \meta{key} without an equal-sign, the
following happens:
\begin{enumerate}
\item The input is replaced by \meta{key}|=\pgfkeysnovalue|. In
  particular, the commands |\pgfkeys{my key}| and
  |\pgfkeys{my key=\pgfkeysnovalue}| have exactly the same effect and
  you can ``simulate'' a missing value by providing the value
  |\pgfkeysnovalue|, which is sometimes useful.
\item If the \meta{value} is |\pgfkeysnovalue|, then it is checked
  whether the subkey \meta{key}|/.@def| exists. For instance, if you
  write |\pgfkeys{/my key}|, then it is checked whether the key
  |/my key/.@def| exists.
\item If the key \meta{key}|/.@def| exists, then the tokens stored in
  this key are used as \meta{value}.
\item If the key does not exist, then |\pgfkeysnovalue| is used as the
  \meta{value}.
\item At the end, if the \meta{value} is now equal to
  |\pgfkeysvaluerequired|, then the code  (or something fairly equivalent)
  |\pgfkeys{/errors/value required=|\meta{key}|{}}|
  is executed. Thus, by changing this key you can change the error
  message that is printed or you can handle the missing value in some
  other way.
\end{enumerate}



\subsubsection{Keys That Execute Commands}
\label{section-key-code}

After the transformation process described in the previous subsection,
we arrive at a key of the form \meta{key}=\meta{value}, where
\meta{key} is a full key. Different things can now happen, but always
the macro |\pgfkeyscurrentkey| will have been set up to expand to the
text of the \meta{key} that is currently being processed.

The first things that is tested is whether the key \meta{key}|/.@cmd|
exists. If this is the case, then it is assumed that this key stores
the code of a macro and this macro is executed. The argument of this
macro is \meta{value} directly followed by |\pgfeov|, which stands for
``end of value.'' The \meta{value} is not surrounded by braces. After
this code has been executed, |\pgfkeys| continues with the next key in
the \meta{key list}.

It may seem quite peculiar that the macro stored in the key
\meta{key}|/.@cmd| is not simply executed with the argument
|{|\meta{value}|}|. However, the approach taken in the |pgfkeys|
packages allows for more flexibility. For instance, assume that you
have a key that expects a \meta{value} of the form
``\meta{text}|+|\meta{more text}'' and wishes to store \meta{text} and
\meta{more text} in two different macros. This can be achieved as
follows:
\begin{codeexample}[]
\def\mystore#1+#2\pgfeov{\def\a{#1}\def\b{#2}}
\pgfkeyslet{/my key/.@cmd}{\mystore}
\pgfkeys{/my key=hello+world}

|\a| is \a, |\b| is \b.
\end{codeexample}

Naturally, defining the code to be stored in a key in the above manner
is too awkward. The following commands simplify things a bit, but the
usual manner of setting up code for a key is to use one of the
handlers described in Section~\ref{section-code-handlers}.

\begin{command}{\pgfkeysdef\marg{key}\marg{code}}
  This command temporarily defines a \TeX-macro with the argument list
  |#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this
  macro. The net effect of all this is that you have then set up code
  for the key \meta{key} so that when you write
  |\pgfkeys{|\meta{key}|=|\meta{value}|}|, then the \meta{code} is
  executed with all occurrences of |#1| in \meta{code} being replaced
  by \meta{value}. (This behaviour is quite similar to the
  |\define@key| command of |keyval| and |xkeyval|).

\begin{codeexample}[]
\pgfkeysdef{/my key}{#1, #1.}
\pgfkeys{/my key=hello}
\end{codeexample}
\end{command}

\begin{command}{\pgfkeysedef\marg{key}\marg{code}}
  This command works like |\pgfkeysdef|, but it uses |\edef| rather
  than |\def| when defining the key macro. If you do not know the
  difference between the two, then you will not need this command;
  and if you know the difference, then you will know when you need this
  command.
\end{command}

\begin{command}{\pgfkeysdefnargs\marg{key}\marg{argument count}\marg{code}}
  This command works like |\pgfkeysdef|, but it allows you to provide
  an arbitrary \meta{argument count} between $0$ and $9$ (inclusive).

\begin{codeexample}[]
\pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}}
\pgfkeys{/my key=
    {hello}
    {world}}

|\a| is `\a', |\b| is `\b'.
\end{codeexample}
	The resulting key will expect exactly \marg{argument count} arguments.
\end{command}
\begin{command}{\pgfkeysedefnargs\marg{key}\marg{argument count}\marg{code}}
  The |\edef| version of |\pgfkeysdefnargs|.
\end{command}

\begin{command}{\pgfkeysdefargs\marg{key}\marg{argument pattern}\marg{code}}
  This command works like |\pgfkeysdefnargs|, but it allows you to provide
  an arbitrary \meta{argument pattern} rather than just a number of arguments.

\begin{codeexample}[]
\pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}}
\pgfkeys{/my key=hello+world}

|\a| is \a, |\b| is \b.
\end{codeexample}
	Note that |\pgfkeysdefnargs| is \emph{better} when it comes to simple argument \emph{counts}\footnote{When the resulting keys are used, the \texttt{defnargs} variant allows spaces between arguments whereas the \texttt{defargs} variant does not; it considers the spaces as part of the argument.}.
\end{command}

\begin{command}{\pgfkeysedefargs\marg{key}\marg{argument pattern}\marg{code}}
  The |\edef| version of |\pgfkeysdefargs|.
\end{command}


\subsubsection{Keys That Store Values}

Let us continue with what happens when |\pgfkeys| processes the
current key and  the subkey \meta{key}|/.@cmd| is not defined. Then
it is checked whether the \meta{key} itself exists (has been
previously assigned a value using, for instance,
|\pgfkeyssetvalue|). In this case, the tokens stored in \meta{key} are
replaced by \meta{value} and |\pgfkeys| proceeds with the next key in
the \meta{key list}.


\subsubsection{Keys That Are Handled}
\label{section-key-handlers}

If neither the \meta{key} itself nor the subkey \meta{key}|/.@cmd| are
defined, then the \meta{key} cannot be processed ``all by itself.''
Rather, a \meta{handler} is needed for this key. Most of the power of
|pgfkeys| comes from the proper use of such handlers.

Recall that the \meta{key} is always a full key (if it was not
originally, it has already been upgraded at this point to a full
key). It decomposed into  two parts:

\begin{enumerate}
\item The \meta{path} of \meta{key} (everything
  before the last slash) is stored in the macro |\pgfkeyscurrentpath|.
\item The \meta{name} of \meta{key} (everything
  after the last slash) is stored in the macro |\pgfkeyscurrentname|.

  It is recommended (but not necessary) that the name of a handler
  starts with a dot (but not with |.@|), so that they are easy to
  detect for the reader.
\end{enumerate}

(For efficiency reasons, these two macros are only set up at this point;
so when code is executed for a key in the ``usual'' manner then these
macros are not set up.)

The |\pgfkeys| command now checks whether the key
|/handlers/|\meta{name}|/.@cmd| exists. If so, it should store a command
and this command is executed exactly in the same manner as described
in Section~\ref{section-key-code}.
Thus, this code gets the \meta{value} that was originally intended for
\meta{key} as its argument, followed by |\pgfeov|.
It is the job of the handlers to do something useful with the
\meta{value}.

For an example, let us write a handler that will output the value
stored in a key to the log file. We call this handler
|/.print to log|. The idea is that when someone tries to use the key
|/my key/.print to log|, then this key will not be defined and the
handler gets executed. The handler will then have access to the
path-part of the key, which is |/my key|, via the macro
|\pgfkeyscurrentpath|. It can then lookup which value is stored in
this key and print it.

\begin{codeexample}[code only]
\pgfkeysdef{/handlers/.print to log}
{%
  \pgfkeysgetvalue{\pgfkeyscurrentpath}{\temp}
  \writetolog{\temp}
}
\pgfkeyssetvalue{/my key}{Hi!}
...
\pgfkeys{/my key/.print to log}
\end{codeexample}
The above code will print |Hi!| in the log, provided the macro
|\writetolog| is set up appropriately.

For a more interesting handler, let us program a handler that will
set up a key so that when the key is used, some code is executed. This
code is given as \meta{value}. All the handler must do is to call
|\pgfkeysdef| for the path of the key (which misses the handler's
name) and assign the parameter value to it.
\begin{codeexample}[]
\pgfkeysdef{/handlers/.my code}{\pgfkeysdef{\pgfkeyscurrentpath}{#1}}
\pgfkeys{/my key/.my code=(#1)}
\pgfkeys{/my key=hallo}
\end{codeexample}

There are some parameters for handled keys which prove to be useful in some (possibly rare) special cases:
\begin{key}{/handler config=\mchoice{all,only existing,full or existing} (initially all)}
  Changes the initial configuration how key handlers will be used.

  This configuration is for advanced users and rarely necessary.

  \begin{description}
  \item[\texttt{all}]
    The preconfigured setting |all| works as described above and
    imposes no restriction on the key setting process.

  \item[\texttt{only existing}]
    The value |only existing| modifies the algorithm for handled keys
    as follows: a handler \meta{key name}|/.|\meta{handler} will be
    executed only if \meta{key name} is either a key which stores its
    value directly or a command key for which |/.@cmd| exists. If
    \meta{key name} does \emph{not} exist already, the complete string
    \meta{key name}|/.|\meta{handler} is considered to be an unknown
    key and the procedure described in the next section applies (for
    the path of \meta{key name}).
\begin{codeexample}[]
% Define a test key and error handlers:
\pgfkeys{/the/key/.code={Initial definition. }}
\pgfkeys{/handlers/.unknown/.code={Unknown key `\pgfkeyscurrentkey'. }}

% calling the test key yields 'Initial definition. ':
\pgfkeys{/the/key}

% Change configuration:
\pgfkeys{/handler config=only existing}

% allowed: key *re*-definition:
\pgfkeys{/the/key/.code={Re-Definition. }}
% calling the key yields 'Re-Definition. ':
\pgfkeys{/the/key}

% not allowed: definition of new keys:
% this checks for '/the/other key/.unknown'
% and '/handlers/.unknown'
% and yields finally
% 'Unknown key `/the/other key/.code`'
\pgfkeys{/the/other key/.code={New definition. }}
\end{codeexample}
    It is necessary to exclude some key handlers from this
    procedure. Altogether, the detailed procedure is as follows:
    \begin{enumerate}
    \item If a handled key like |/a path/a key/.a handler=value| is
      encountered, it is checked whether the handler should be
      invoked. This is the case if
      \begin{itemize}
      \item An exception from |only existing| for this key exists (see below),
      \item The key |/a path/a key| exists already -- either directly as
        storage key or with the |.@cmd| suffix.
      \end{itemize}
    \item If the check passes, everything works as before.
    \item If the check fails, the complete key will be considered to be
      unknown. In that case, the handling of unknown keys as described
      in the next section applies. There, the current key path will be
      set to |/a path| and the current key's name to |key/.a handler|.
    \end{enumerate}

    A consequence of this configuration is to provide more meaningful
    processing of handled keys if a search path for keys is in effect,
    see section~\ref{sec:pgf:unknown:keys} for an example.

  \item[\texttt{full or existing}] Finally, the choice
    |full or existing| is a variant of |only existing|: it works in
    the same way
    for keys which do not have a full key path. For example, the style

    |\pgfkeys{/my path/.cd,key/.style={|$\dotsc$|}}|

    can only be redefined: it doesn't have a full path, so the
    |only existing| mechanism applies. But the style
	
    |\pgfkeys{/my path/key/.style={|$\dotsc$|}}|

    will still work. This allows users to override the |only existing|
    feature if they know what they're doing (and provide full key
    paths).
  \end{description}
\end{key}

\begin{key}{/handler config/only existing/add exception=\marg{key
      handler name}}
  Allows to add exceptions to the |/handler config=only existing|
  feature. Initially exceptions for the key handlers
  |/.cd|, |/.try|, |/.retry|, |/.lastretry| and |/.unknown| are
  defined. The value \marg{key handler name} should be the name of a
  key handler.
\end{key}



\subsubsection{Keys That Are Unknown}
\label{sec:pgf:unknown:keys}

For some keys, neither the key, nor its |.@cmd| subkey nor
a handler is defined. In this case, it is checked whether
the key \meta{current path}|/.unknown/.@cmd| exists. Thus, when you try to
use the key |/tikz/strange|, then it is checked whether
|/tikz/.unknown/.@cmd| exists. If this key exists (which it does), it is
executed. This code can then try to make sense of the key. For
instance, the handler for \tikzname\ will try to interpret the key's
name as a color or as an arrow specification or as a \pgfname\
option.

You can set up unknown key handlers for your own keys by simply setting
the code of the key \meta{my path prefix}|/.unknown|. This also allows
you to set up ``search paths.'' The idea is that you would like keys to
be searched not only in a single default path, but in
several. Suppose, for instance, that you would like keys to be
searched
for in |/a|, |/b|, and |/b/c|. We set up a key |/my search path| for
this:
\begin{codeexample}[code only]
\pgfkeys{/my search path/.unknown/.code=
  {%
    \let\searchname=\pgfkeyscurrentname%
    \pgfkeysalso{%
      /a/\searchname/.try=#1,
      /b/\searchname/.retry=#1,
      /b/c/\searchname/.retry=#1%
    }%
  }%
}
\pgfkeys{/my search path/.cd,foo,bar}
\end{codeexample}
In the above code, |foo| and |bar| will be searched for in the three
directories  |/a|, |/b|, and |/b/c|. Before you start implementing
search paths using this pattern, consider the |/.search also| handler
discussed below.

If the key \meta{current path}|/.unknown/.@cmd| does not exist, the
handler |/handlers/.unknown| is invoked instead, which is always
defined and which prints an error message by default.

\subsubsection{Search Paths And Handled Keys}

There is one special case which occurs in the search path example
above. What happens if we want to change a style? For example,
\begin{codeexample}[code only]
\pgfkeys{/my search path/.cd,custom/.style={variables}}
\end{codeexample}
\noindent could mean a style in |/my search path/|, |/a/|, |/b/| or
even |/b/c/|!

Due to the rules for handled keys, the answer is
|/my search path/custom/.style={variables}|.
It may be useful to modify this default behavior. One useful thing
would be to search for \emph{existing} styles named |custom| and
redefine them. For example, if a style |/b/custom| exists, the
assignment |custom/.style={variables}| should probably redefine
|/b/custom| instead of |/my search path/custom|. This can be done
using |handler config|:
\begin{codeexample}[]
\pgfkeys{/my search path/.unknown/.code=
  {%
    \let\searchname=\pgfkeyscurrentname%
    \pgfkeysalso{%
      /a/\searchname/.try=#1,
      /b/\searchname/.retry=#1,
      /b/c/\searchname/.retry=#1%
    }%
  }%
}

% Let's define /b/custom here:
\pgfkeys{/b/custom/.code={This is `\pgfkeyscurrentkey'. }}

% Reconfigure treatment of key handlers:
\pgfkeys{/handler config=only existing}

% The search path procedure will find /b/custom
% -> leads to This is `/b/custom'
\pgfkeys{/my search path/.cd,custom}

% Due to the reconfiguration, this will find /b/custom instead of
% defining /my search path/custom:
\pgfkeys{/my search path/.cd,custom/.append code={Modified. }}

% So using the search path, we again find /b/custom which
% leads to This is `/b/custom' Modified
\pgfkeys{/my search path/.cd,custom}
\end{codeexample}

A slightly different approach to search paths can be realized using
the |/.search also| key handler, see below.


\subsection{Key Handlers}

We now describe which key handlers are defined by default. You can
also define new ones as described in Section~\ref{section-key-handlers}.


\subsubsection{Handlers for Path Management}

\begin{handler}{{.cd}}
  This handler causes the default path to be set to \meta{key}. Note that
  the default path is reset at the beginning of each call to
  |\pgfkeys| to be equal to~|/|.

  \example |\pgfkeys{/tikz/.cd,...}|
\end{handler}

\begin{handler}{{.is family}}
\label{section-is family-handler}
  This handler sets up things such that when \meta{key} is executed, then
  the current path is set to \meta{key}. A typical use is the following:
\begin{codeexample}[code only]
\pgfkeys{/tikz/.is family}
\pgfkeys{tikz,line width=1cm}
\end{codeexample}
  The effect of this handler is the same as if you had written
  \meta{key}|/.style=|\meta{key}|/.cd|, only the code produced by the
  |/.is family| handler is quicker.
\end{handler}



\subsubsection{Setting Defaults}
\label{section-default-handlers}

\begin{handler}{{.default}|=|\meta{value}}
  Sets the default value of \meta{key} to \meta{value}. This means
  that whenever no value is provided in a call to |\pgfkeys|, then
  this \meta{value} will be used instead.

  \example |\pgfkeys{/width/.default=1cm}|
\end{handler}

\begin{handler}{{.value required}}
  This handler causes the error message key |/erros/value required| to
  be issued whenever the \meta{key} is used without a value.

  \example |\pgfkeys{/width/.value required}|
\end{handler}

\begin{handler}{{.value forbidden}}
  This handler causes the error message key |/erros/value forbidden|
  to be issued whenever the \meta{key} is used with a value.

  This handler works be adding code to the code of the key. This means
  that you have to define the key first before you can use this
  handler.
\begin{codeexample}[code only]
\pgfkeys{/my key/.code=I do not want an argument!}
\pgfkeys{/my key/.value forbidden}

\pgfkeys{/my key}     % Ok
\pgfkeys{/my key=foo} % Error
\end{codeexample}
\end{handler}


\subsubsection{Defining Key Codes}
\label{section-code-handlers}

A number of handlers exist for defining the code of keys.

\begin{handler}{{.code}|=|\meta{code}}
  This handler executes |\pgfkeysdef| with the parameters \meta{key}
  and \meta{code}. This means that, afterwards, whenever the
  \meta{key} is used, the \meta{code} gets executed. More precisely,
  when \meta{key}|=|\meta{value} is encountered in a key list,
  \meta{code} is executed with any occurrence of |#1| replaced by
  \meta{value}. As always, if no \meta{value} is given, the default
  value is used, if defined, or the special value |\pgfkeysnovalue|.

  It is permissible that \meta{code} calls the command |\pgfkeys|. It
  is also permissible the \meta{code} calls the command
  |\pgfkeysalso|, which is useful for styles, see below.

\begin{codeexample}[code only]
\pgfkeys{/par indent/.code={\parindent=#1},/par indent/.default=2em}
\pgfkeys{/par indent=1cm}
...
\pgfkeys{/par indent}
\end{codeexample}
\end{handler}

\begin{handler}{{.ecode}|=|\meta{code}}
  This handler works like |/.code|, only the command |\pgfkeysedef| is
  used.
\end{handler}


\begin{handler}{{.code 2 args}|=|\meta{code}}
  This handler works like |/.code|, only two arguments rather than one
  are expected when the \meta{code} is executed. This means that when
  \meta{key}|=|\meta{value} is encountered in a key list, the
  \meta{value} should consist of two arguments. For instance,
  \meta{value} could be |{first}{second}|. Then \meta{code} is
  executed with any occurrence of |#1| replaced |first| and any
  occurrence of |#2| replaced by |second|.

\begin{codeexample}[code only]
\pgfkeys{/page size/.code 2 args={\paperheight=#2\paperwidth=#1}}
\pgfkeys{/page size={30cm}{20cm}}
\end{codeexample}
  The second argument is optional: if it is not provided, it will be the empty string.

  Because of the special way the \meta{value} is parsed, if you set
  \meta{value} to, for instance, |first| (without any braces), then
  |#1| will be set to |f| and |#2| will be set to |irst|.
\end{handler}

\begin{handler}{{.ecode 2 args}|=|\meta{code}}
  This handler works like |/.code 2 args|, only an |\edef| is used
  rather than a |\def| to define the macro.
\end{handler}


\begin{handler}{{.code n args}|=|\marg{argument count}\marg{code}}
  This handler also works like |/.code|, but you can now specify a
  number of arguments between $0$ and $9$ (inclusive).
\begin{codeexample}[]
\pgfkeys{/a key/.code n args={2}{First=`#1', Second=`#2'}}
\pgfkeys{/a key={A}{B}}
\end{codeexample}
  In contrast to |/.code 2 args|, there must be exactly \meta{argument
    count} arguments, not more and not less and these arguments should
  be properly delimited.
\end{handler}

\begin{handler}{{.ecode n args}|=|\marg{argument count}\marg{code}}
  This handler works like |/.code n args|, only an |\edef| is used
  rather than a |\def| to define the macro.
\end{handler}

\begin{handler}{{.code args}|=|\marg{argument pattern}\marg{code}}
  This handler is the most flexible way to define a |/.code| key: you
  can now specify an arbitrary \meta{argument pattern}. Such a pattern
  is a usual \TeX\ macro pattern. For instance, suppose \meta{argument
  pattern} is |(#1/#2)| and \meta{key}|=|\meta{value} is encountered
  in a key list with \meta{value} being |(first/second)|. Then
  \meta{code} is executed with any occurrence of |#1| replaced |first|
  and any occurrence of |#2| replaced by |second|. So, the actual
  \meta{value} is matched against the \meta{argument pattern} in the
  standard \TeX\ way.

\begin{codeexample}[code only]
\pgfkeys{/page size/.code args={#1 and #2}{\paperheight=#2\paperwidth=#1}}
\pgfkeys{/page size=30cm and 20cm}
\end{codeexample}
	
  Note that |/.code n args| should be preferred in case you need just a number
  of arguments (when the resulting keys are used, |/.code n args|
  gobbles spaces between the arguments whereas |/.code args| considers
  spaces to be part of the argument).
\end{handler}

\begin{handler}{{.ecode args}|=|\marg{argument pattern}\marg{code}}
  This handler works like |/.code args|, only an |\edef| is used
  rather than a |\def| to define the macro.
\end{handler}


There are also handlers for modifying existing keys.

\begin{handler}{{.add code}|=|\marg{prefix code}\marg{append code}}
  This handler adds code to an existing key. The \meta{prefix code} is
  added to the code stored in \meta{key}|/.@cmd| at the beginning, the
  \meta{append code} is added to this code at the end. Either can be
  empty. The argument list of \meta{code} cannot be changed using this
  handler. Note that both \meta{prefix code} and \meta{append code}
  may contain parameters like |#2|.

\begin{codeexample}[code only]
\pgfkeys{/par indent/.code={\parindent=#1}}
\newdimen\myparindent
\pgfkeys{/par indent/.add code={}{\myparindent=#1}}
...
\pgfkeys{/par indent=1cm} % This will set both \parindent and
                          % \myparindent to 1cm
\end{codeexample}
\end{handler}

\begin{handler}{{.prefix code}|=|\meta{prefix code}}
  This handler is a shortcut for \meta{key}|/.add code={|\meta{prefix
      code}|}{}|. That is, this handler adds the \meta{prefix code} at
  the beginning of the code stored in \meta{key}|/.@cmd|.
\end{handler}

\begin{handler}{{.append code}|=|\meta{append code}}
  This handler is a shortcut for \meta{key}|/.add code={}{|\meta{append
      code}|}{}|.
\end{handler}


\subsubsection{Defining Styles}

The following handlers allow you to define \emph{styles}. A style is a
key list that is processed whenever the style is given as a key in a
key list. Thus, a style ``stands for'' a certain key value
list. Styles can be parameterized just like normal code.

\begin{handler}{{.style}|=|\meta{key list}}
  This handler sets things up so that whenever \meta{key}|=|\meta{value} is
  encountered in a key list, then the \meta{key list}, with every
  occurrence of |#1| replaced by \meta{value}, is processed
  instead. As always, if no \meta{value} is given, the default
  value is used, if defined, or the special value |\pgfkeysnovalue|.

  You can achieve the same effect by writing
  \meta{key}|/.code=\pgfkeysalso{|\meta{key list}|}|. This means, in
  particular, that the code of a key could also first execute some
  normal code and only then process some further keys.

\begin{codeexample}[code only]
\pgfkeys{/par indent/.code={\parindent=#1}}
\pgfkeys{/no indent/.style={/par indent=0pt}}
\pgfkeys{/normal indent/.style={/par indent=2em}}
\pgfkeys{/no indent}
...
\pgfkeys{/normal indent}
\end{codeexample}
  The following example shows a parameterized style ``in action''.
\begin{codeexample}[]
\begin{tikzpicture}[outline/.style={draw=#1,fill=#1!20}]
  \node [outline=red]            {red box};
  \node [outline=blue] at (0,-1) {blue box};
\end{tikzpicture}
\end{codeexample}
\end{handler}

\begin{handler}{{.estyle}|=|\meta{key list}}
  This handler works like |/.style|, only the \meta{code} is set using
  |\edef| rather than |\def|. Thus, all macros in the \meta{code} are
  expanded prior to saving the style.
\end{handler}

For styles the corresponding handlers as for normal code exist:

\begin{handler}{{.style 2 args}|=|\meta{key list}}
  This handler works like |/.code 2 args|, only for styles. Thus, the
  \meta{key list} may contain occurrences of both |#1| and |#2| and
  when the style is used, two parameters must be given as
  \meta{value}.
\begin{codeexample}[code only]
\pgfkeys{/paper height/.code={\paperheight=#1},/paper width/.code={\paperwidth=#1}}
\pgfkeys{/page size/.style 2 args={/paper height=#1,/paper width=#2}}
\pgfkeys{/page size={30cm}{20cm}}
\end{codeexample}
\end{handler}

\begin{handler}{{.estyle 2 args}|=|\meta{key list}}
  This handler works like |/.style 2 args|, only an |\edef| is used
  rather than a |\def| to define the macro.
\end{handler}

\begin{handler}{{.style args}|=|\marg{argument pattern}\marg{key list}}
  This handler works like |/.code args|, only for styles.
\end{handler}

\begin{handler}{{.estyle args}|=|\marg{argument pattern}\marg{code}}
  This handler works like |/.ecode args|, only for styles.
\end{handler}

\begin{handler}{{.style n args}|=|\marg{argument count}\meta{key list}}
	This handler works like |/.code n args|, only for styles. Here, \meta{key list} may depend on all \meta{argument count} parameters.
\end{handler}

\begin{handler}{{.add style}|=|\marg{prefix key list}\marg{append key list}}
  This handler works like |/.add code|, only for styles. However, it is
  permissible to add styles to keys that have previously been set
  using  |/.code|. (It is also permissible to add normal \meta{code} to
  a key that has previously been set using |/.style|). When you add a
  style to a key that was previously set using |/.code|, the following
  happens: When \meta{key} is processed, the \meta{prefix key list}
  will be processed first, then the \meta{code} that was previously
  stored in \meta{key}|/.@cmd|, and then the keys in \meta{append key
    list} are processed.
\begin{codeexample}[code only]
\pgfkeys{/par indent/.code={\parindent=#1}}
\pgfkeys{/par indent/.add style={}{/my key=#1}}
...
\pgfkeys{/par indent=1cm} % This will set \parindent and
                          % then execute /my key=#1
\end{codeexample}
\end{handler}

\begin{handler}{{.prefix style}|=|\meta{prefix key list}}
  Works like |/.add style|, but only for the prefix key list.
\end{handler}

\begin{handler}{{.append style}|=|\meta{append key list}}
  Works like |/.add style|, but only for the append key list.
\end{handler}


\subsubsection{Defining Value-, Macro-, If- and Choice-Keys}

For some keys, the code that should be executed for them is rather
``specialized.'' For instance, it happens often that the code for a
key just sets a certain \TeX-if to true or false. For these cases,
predefined handlers make it easier to install the necessary code.

However, we start with some handlers that are used to manage the value
that is directly stored in a key.

\begin{handler}{{.initial}|=|\meta{value}}
  This handler sets the value of \meta{key} to \meta{value}. Note that
  no subkeys are involved. After this handler has been used, by the
  rules governing keys, you can subsequently change the value of the
  \meta{key} by just writing \meta{key}|=|\meta{value}. Thus, this
  handler is used to set the initial value of key.

\begin{codeexample}[code only]
\pgfkeys{/my key/.initial=red}
% "/my key" now stores the value "red"
\pgfkeys{/my key=blue}
% "/my key" now stores the value "blue"
\end{codeexample}

  Note that with this configuration, writing |\pgfkeys{/my key}| will not
  have the effect you might expect (namely that |blue| is inserted
  into the main text). Rather, |/my key| will be promoted to
  |/my key=\pgfkeysnovalue| and, thus, |\pgfkeysnovalue| will be
  stored in |/my key|.

  To retrieve the value stored in a key, the handler |/.get| is used.
\end{handler}

\begin{handler}{{.get}|=|\meta{macro}}
  Executes a |\let| command so that \meta{macro} contains the contents
  stored in \meta{key}.

\begin{codeexample}[]
\pgfkeys{/my key/.initial=red}
\pgfkeys{/my key=blue}
\pgfkeys{/my key/.get=\mymacro}
\mymacro
\end{codeexample}
\end{handler}

\begin{handler}{{.add}|=|\marg{prefix value}\marg{append value}}
  Adds the \meta{prefix value} and the beginning and the \meta{append
    value} at the end of the value stored in \meta{key}.
\end{handler}

\begin{handler}{{.prefix}|=|\marg{prefix value}}
  Adds the \meta{prefix value} and the beginning of the value stored in \meta{key}.
\end{handler}

\begin{handler}{{.append}|=|\marg{append value}}
  Adds the \meta{append value} at the end of the value stored in \meta{key}.
\end{handler}

\begin{handler}{{.link}|=|\meta{another key}}
  Stores the value |\pgfkeysvalueof{|\meta{another key}|}| in the
  \meta{key}. The idea is that when you expand the \meta{key}, the
  value of \meta{another key} is expanded instead. This corresponds
  loosely to the notion of soft links in Unix, hence the name.
\end{handler}

The next handler is useful for the common situation where
\meta{key}|=|\meta{value} should cause the \meta{value} to be stored
in some macro. Note that, typically, you could just as well store the
value in the key itself.

\begin{handler}{{.store in}|=|\meta{macro}}
  This handler has the following effect: When you write
  \meta{key}|=|\meta{value}, the code
  |\def|\meta{macro}|{|\meta{value}|}| is executed. Thus, the given
  value is ``stored'' in the \meta{macro}.
\begin{codeexample}[]
\pgfkeys{/text/.store in=\mytext}
\def\a{world}
\pgfkeys{/text=Hello \a!}
\def\a{Gruffalo}
\mytext
\end{codeexample}
\end{handler}

\begin{handler}{{.estore in}|=|\meta{macro}}
  This handler is similar to |/.store in|, only the code
  |\edef|\meta{macro}|{|\meta{value}|}| is used. Thus, the
  macro-expanded version of \meta{value} is stored in the
  \meta{macro}.
\begin{codeexample}[]
\pgfkeys{/text/.estore in=\mytext}
\def\a{world}
\pgfkeys{/text=Hello \a!}
\def\a{Gruffalo}
\mytext
\end{codeexample}
\end{handler}

In another common situation a key is used to set a \TeX-if to true or
false.

\begin{handler}{{.is if}|=|\meta{\TeX-if name}}
  This handler has the following effect: When you write
  \meta{key}|=|\meta{value}, it is first checked that \meta{value} is
  |true| or |false| (the default is |true| if no \meta{value} is
  given). If this is not the case, the error key
  |/errors/boolean expected| is executed. Otherwise,
  the code |\|\meta{\TeX-if name}\meta{value} is executed, which sets
  the \TeX-if accordingly.
\begin{codeexample}[]
\newif\iftheworldisflat
\pgfkeys{/flat world/.is if=theworldisflat}
\pgfkeys{/flat world=false}
\iftheworldisflat
  Flat
\else
  Round?
\fi
\end{codeexample}
\end{handler}

The next handler deals with the problem when a
\meta{key}|=|\meta{value} makes sense only for a small set of possible
\meta{value}s. For instance, the line cap can only be |rounded| or
|rect| or |butt|, but nothing else. For this situation the following
handler is useful.

\begin{handler}{{.is choice}}
  This handler sets things up so that writing \meta{key}|=|\meta{value}
  will cause the subkey \meta{key}|/|\meta{value} to be executed. So,
  each of the different possible choices should be given by a subkey
  of \meta{key}.
\begin{codeexample}[code only]
\pgfkeys{/line cap/.is choice}
\pgfkeys{/line cap/round/.style={\pgfsetbuttcap}}
\pgfkeys{/line cap/butt/.style={\pgfsetroundcap}}
\pgfkeys{/line cap/rect/.style={\pgfsetrectcap}}
\pgfkeys{/line cap/rectangle/.style={/line cap=rect}}
...
\draw [/line cap=butt] ...
\end{codeexample}
  If the subkey \meta{key}|/|\meta{value} does not exist, the error
  key |/errors/unknown choice value| is executed.
\end{handler}


\subsubsection{Expanded and Multiple Values}

When you write \meta{key}|=|\meta{value}, you usually wish to use the
\meta{value} ``as is.'' Indeed, great care is taken to ensure that you
can even use things like |#1| or unbalanced \TeX-ifs inside
\meta{value}. However, sometimes you want the \meta{value} to be
expanded before it is used. For instance, \meta{value} might be a
macro name like |\mymacro| and you do not want |\mymacro| to be used
as the macro, but rather the \emph{contents} of |\mymacro|. Thus,
instead of using \meta{value}, you wish to use whatever \meta{value}
expands to. Instead of using some fancy |\expandafter| hackery, you
can use the following handlers:

\begin{handler}{{.expand once}|=|\meta{value}}
  This handler expands \meta{value} once (more precisely, it executes
  an |\expandafter| command on the first token of \meta{value}) and
  then process the resulting \meta{result} as if you had written
  \meta{key}|=|\meta{result}. Note that if \meta{key} contains a
  handler itself, this handler will be called normally.
\begin{codeexample}[]
\def\a{bottom}
\def\b{\a}
\def\c{\b}

\pgfkeys{/key1/.initial=\c}
\pgfkeys{/key2/.initial/.expand once=\c}
\pgfkeys{/key3/.initial/.expand twice=\c}
\pgfkeys{/key4/.initial/.expanded=\c}

\def\a{{\ttfamily\string\a}}
\def\b{{\ttfamily\string\b}}
\def\c{{\ttfamily\string\c}}

\begin{tabular}{ll}
Key 1:& \pgfkeys{/key1} \\
Key 2:& \pgfkeys{/key2} \\
Key 3:& \pgfkeys{/key3} \\
Key 4:& \pgfkeys{/key4}
\end{tabular}
\end{codeexample}
\end{handler}

\begin{handler}{{.expand twice}|=|\meta{value}}
  This handler works like saying \meta{key}|/.expand once/.expand once=|\meta{value}.
\end{handler}

\begin{handler}{{.expanded}|=|\meta{value}}
  This handler will completely expand \meta{value} (using |\edef|)
  before processing \meta{key}|=|\meta{result}.
\end{handler}

\begin{handler}{{.list}|=|\meta{comma-separated list of values}}
  This handler causes the key to be used repeatedly, namely once for
  every element of the list of values. Note that the list of values
  should typically be surrounded by braces since, otherwise, \TeX\
  will not be able to tell whether a comma starts a new key or a new
  value.

  The \meta{list of values} is processed using the |\foreach|
  statement, so you can use the |...| notation.
\begin{codeexample}[]
\pgfkeys{/foo/.code=(#1)}
\pgfkeys{/foo/.list={a,b,0,1,...,5}}
\end{codeexample}
\end{handler}



\subsubsection{Handlers for Forwarding}

\begin{handler}{{.forward to}|=|\meta{another key}}
  This handler causes the \meta{key} to ``forward'' its argument to
  \meta{another key}. When the \meta{key} is used, its normal code
  will be executed first. Then, the value is (additionally) passed to
  \meta{another key}. If the \meta{key} has not yet been defined prior
  to the use of |.forward to|, it will be defined then (and do nothing by
  itself, expect for forwarding it to \meta{key name}). The
  \meta{another key} must be a fully qualified key name. 
\begin{codeexample}[]
\pgfkeys{
  /a/.code=(a:#1),
  /b/.code=(b:#1),
  /b/.forward to=/a,
  /c/.forward to=/a
}
\pgfkeys{/b=1} \pgfkeys{/c=2}
\end{codeexample}
\end{handler}


\begin{handler}{{.search also}=\marg{path list}}
  A style which installs a |/.unknown| handler into \meta{key}. This
  |/.unknown| handler will then search for unknown keys in every path
  provided in \marg{path list}.

\begin{codeexample}[]
% define a key:
\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}

% set up a search path:
\pgfkeys{/main path/.search also={/secondary path}}

% try searching for `option=value' in '/main path':
% -> this finds `/secondary path/option'!
\pgfkeys{/main path/.cd,option=value}
\end{codeexample}

  The |/.search also| handler follows the strategy
  \begin{enumerate}
  \item If a user provides a fully qualified key which could not be
    found, for example the full string |/main path/option|, it assume
    that the user knew what she is doing -- and does \emph{not} continue
    searching for |an option| in \marg{path list}.
  \item If a user provides only the key's name, for example |option|
    and |option| cannot be found in the current default path (which is
    |/main path| in our example above), the current default path is
    set to the next element in \marg{path list} (which is
    |/secondary path| here) and |\pgfkeys| will be restarted.

    This will be iterated until either a match has been found or all
    elements in \marg{path list} have been tested.
  \item If all elements in \marg{path list} have been checked and the
    key is still unknown, the fall-back handler |/handlers/.unknown|
    will be invoked.
  \end{enumerate}
\begin{codeexample}[]
% define a key:
\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}

% set up a search path:
\pgfkeys{/main path/.search also={/secondary path}}

% try searching for `option=value' in '/main path':
% -> this finds `/secondary path/option'!
\pgfkeys{/main path/.cd,option=value}

% negative example:
% try searching for fully qualified key /main path/option.
% This won't be handled by .search also.
\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}%
\pgfkeys{/main path/.cd,/main path/option=value}
\end{codeexample}

  Please note that the strategy of |/.search also| is different from
  the first example provided in section~\ref{sec:pgf:unknown:keys}
  ``Unknown Keys'' because |/.search also| only applies to keys
  that are not fully qualified.
	
  For those who are familiar with |\pgfkeys|, the actual
  implementation of |/.search also| might be interesting:
  \begin{enumerate}
  \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to
\begin{codeexample}[code only]
\pgfkeys{/path/.unknown/.code={%
        \ifpgfkeysaddeddefaultpath
            % only process keys for which no full path has been
            % provided:
            \pgfkeyssuccessfalse
            \let\pgfkeys@searchalso@name =\pgfkeyscurrentkeyRAW
            \ifpgfkeyssuccess
            \else
                % search with /tikz as default path:
                \pgfqkeys{/tikz}{\pgfkeys@searchalso@name={#1}}%
            \fi
        \else
            \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
            \pgfutilnext
        \fi
    }
}
\end{codeexample}
  \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
\begin{codeexample}[code only]
\pgfkeys{/path/.unknown/.code={%
        \ifpgfkeysaddeddefaultpath
            \pgfkeyssuccessfalse
            \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
            \ifpgfkeyssuccess
            \else
                % step 1: search in /tikz with .try:
                \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try={#1}}%
            \fi
            \ifpgfkeyssuccess
            \else
                % step 2: search in /pgf (without .try!):
                \pgfqkeys{/pgf}{\pgfkeys@searchalso@name={#1}}%
            \fi
        \else
            \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
            \pgfutilnext
        \fi
    }
}
\end{codeexample}
  \end{enumerate}

  To also enable searching for styles (or other handled keys),
  consider changing the configuration for handled keys to
  |/hander config=full or existing| when you use |/.search also|,
  that is, use
\begin{codeexample}[code only]
\pgfkeys{
   /main path/.search also={/secondary path},
   /handler config=full or existing}
\end{codeexample}
\end{handler}


\subsubsection{Handlers for Testing Keys}

\begin{handler}{{.try}|=|\meta{value}}
  This handler causes the same things to be done as if
  \meta{key}|=|\meta{value} had been written instead. However, if
  neither \meta{key}|/.@cmd| nor the key itself is defined, no
  handlers will be called. Instead,
  the execution of the key just stops. Thus, this handler will ``try''
  to use the key, but no further action is taken when the key is not
  defined.

  The \TeX-if |\||ifpgfkeyssuccess| will be set according to whether
  the \meta{key} was successfully executed or not.
\begin{codeexample}[]
\pgfkeys{/a/.code=(a:#1)}
\pgfkeys{/b/.code=(b:#1)}
\pgfkeys{/x/.try=hmm,/a/.try=hallo,/b/.try=welt}
\end{codeexample}
\end{handler}

\begin{handler}{{.retry}|=|\meta{value}}
  This handler works just like |/.try|, only it will not do anything if
  |\||ifpgfkeyssuccess| is false. Thus, this handler will only retry
  to set a key if ``the last attempt failed''.
\begin{codeexample}[]
\pgfkeys{/a/.code=(a:#1)}
\pgfkeys{/b/.code=(b:#1)}
\pgfkeys{/x/.try=hmm,/a/.retry=hallo,/b/.retry=welt}
\end{codeexample}
\end{handler}

\begin{handler}{{.lastretry}|=|\meta{value}}
	This handler works like |/.retry|, only it will invoke the usual handlers for unknowns keys if |\||ifpgfkeyssuccess| is false. Thus, this handler will only try to set a key if ``the last attempt failed''. Furthermore, this here is the last such attempt.
\end{handler}


\subsubsection{Handlers for Key Inspection}

\begin{handler}{{.show value}}
  This handler executes a |\show| command on the value stored in
  \meta{key}. This is useful mostly for debugging.

  \example |\pgfkeys{/my/obscure key/.show value}|
\end{handler}

\begin{handler}{{.show code}}
  This handler executes a |\show| command on the code stored in
  \meta{key}|/.@cmd|. This is useful mostly for debugging.

  \example |\pgfkeys{/my/obscure key/.show code}|
\end{handler}

The following key is not a handler, but it also commonly used for
inspecting things:
\begin{key}{/utils/exec=\meta{code}}
  This key will simply execute the given \meta{code}.

  \example |\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}|
\end{key}


\subsection{Error Keys}

In certain situations errors can occur, like using an undefined
key. In these situations error keys are executed. They should store a
macro that gets two arguments: The first is the offending key
(possibly only after macro expansion), the second is the value that
was passed as a parameter (also possibly only after macro expansion).

Currently, error keys are simply executed. In the future it might be a
good idea to have different subkeys that are executed depending on the
language currently set so that users get a localized error message.

\begin{key}{/errors/value required=\marg{offending key}\marg{value}}
  This key is executed whenever an \meta{offending key} is used
  without a value when a value is actually required.
\end{key}

\begin{key}{/errors/value forbidden=\marg{offending key}\marg{value}}
  This key is executed whenever a key is used with a value when a
  value is actually forbidden.
\end{key}

\begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}}
  This key is executed whenever a key set up using |/.is if| gets called
  with a \meta{value} other than |true| or |false|.
\end{key}

\begin{key}{/errors/unknown choice value=\marg{offending key}\marg{value}}
  This key is executed whenever a choice is used as a \meta{value} for
  a key set up using the |/.is choice| handler that is not defined.
\end{key}

\begin{key}{/errors/unknown key=\marg{offending key}\marg{value}}
  This key is executed whenever a key is unknown and no specific
  |/.unknown| handler is found.
\end{key}

\input pgfmanual-en-pgfkeysfiltered.tex