summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-keyval.html
blob: 6ca8497270c6803f8967ac7abc05cc2a1b78041b (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
<head>
<title>UK TeX FAQ -- question label keyval</title>
</head><body>
<h3>Key-value input for macros and package options</h3>
<p/>When we discussed 
<a href="FAQ-moren9.html">extending the number of arguments to a macro</a>, we
suggested that large numbers of arguments, distinguished only by their
position, aren&rsquo;t very kind to the user, and that a package such as
<i>keyval</i> offers a more attractive user interface.  We now
consider the packages that the macro programmer might use, to create
such a user interface.
<p/>The simplest key-value processor remains <i>keyval</i>; it has a
command <code>\</code><code>define@key</code> to declare a key and a <em>handler</em> to
process it, and a macro <code>\</code><code>setkeys</code> to offer values to the handler
of one or more keys.  Thus:
<blockquote>
<pre>
\define@key{my}{foo}{Foo is #1\par}
\define@key{my}{bar}[99]{Bar is #1\par}
...
\setkeys{my}{foo=3,bar}
</pre>
</blockquote><p>
will produce output saying:
<blockquote>
  Foo is 3<br/>
  Bar is 99
</blockquote><p>
This has defined two keys &lsquo;<code>foo</code>&rsquo; and &lsquo;<code>bar</code>&rsquo; in family
&lsquo;<code>my</code>&rsquo;, and then executed them, the first with argument
&lsquo;<code>3</code>&rsquo; and the second with no argument, so that the default
value of &lsquo;<code>99</code>&rsquo; is picked up.  In effect, the two calls to
<code>\</code><code>define@key</code> are simply defining commands, as (for example):
<blockquote>
<pre>
\newcommand{\KV@my@foo}[1]{Foo is #1}
</pre>
</blockquote><p>
(the definition of <code>\</code><code>KV@my@bar</code> is similar, but trickier).  The
command <code>\</code><code>setkeys</code> knows how to find those commands when it needs to
process each key &mdash; it is easy to regurgitate the structure of the
command name, with family name (&lsquo;<code>my</code>&rsquo;, here) after the first
&lsquo;<code>@</code>&rsquo;, and the key name after the second &lsquo;<code>@</code>&rsquo;.  (The
&lsquo;<code>KV</code>&rsquo; part is fixed, in <i>keyval</i>.)
<p/>These simple commands are enough, in fact, to process the botanical
example offered as replacement for multi-argument commands in 
<a href="FAQ-moren9.html">the question mentioned above</a>, or the
optional arguments of the <code>\</code><code>includegraphics</code> command of the
<i>graphicx</i> package.  (The last is, in fact, what
<i>keyval</i> was designed to do.)
<p/>However, we need more if we&rsquo;re to to have package options in
&lsquo;key-value&rsquo; form.  Packages like <i>hyperref</i> have enormously
complicated package options which need key-value processing at
<code>\</code><code>ProcessOptions</code> time: <i>keyval</i> can&rsquo;t do that on its own.
<p/>Heiko Oberdiek&rsquo;s <i>kvoptions</i> package comes to our help: it
enables the programmer to declare class or package options that
operate as key and value pairs.  The package defines commands
<code>\</code><code>DeclareBoolOption</code> for options whose value should be either
<em>true</em> or <em>false</em>, and <code>\</code><code>DeclareStringOption</code> for all
other options that have a value.  Keys are declared using
<i>keyval</i> and may remain available for use within the document,
or may be &lsquo;cancelled&rsquo; to avoid confusion.  If you have loaded
<i>kvoptions</i>, the LaTeX kernel&rsquo;s <code>\</code><code>DeclareOption</code> becomes
<code>\</code><code>DeclareVoidOption</code> (it&rsquo;s an option with no value), and
<code>\</code><code>DeclareOption*</code> becomes <code>\</code><code>DeclareDefaultOption</code>.
<p/>Heiko also provides <i>kvsetkeys</i> which is a more robust version
of <i>setkeys</i>, with some of the rough edges made smoother.
<p/>Hendri Adriaens&rsquo; <i>xkeyval</i> offers more flexibility than
the original <i>keyval</i> and is more robust than the original,
too.  Like <i>kvoptions</i>, the package also has mechanisms to
allow class and package options in key-value form (macros
<code>\</code><code>DeclareOptionX</code>, <code>\</code><code>ExecuteOptionsX</code> and <code>\</code><code>ProcessOptionsX</code>.
<i>Pstricks</i> bundle packages use a <i>xkeyval</i> derivative
called <i>pst-xkey</i> for their own key-value manipulation.

<p/>The (widely-respected) <i>pgf</i> graphics package has its own
key-value package called <i>pgfkeys</i>.  The documentation of the
package (part of the huge <i>pgf</i> manual, in part 5,
&ldquo;utilities&rdquo;) contains a useful comparison with other key-value
systems; some notable differences are:
<ul>
<li> key organisation: <i>pgfkeys</i> uses a tree structure, while
  <i>keyval</i> and <i>xkeyval</i> both associate keys with a family;
<li> <i>pgfkeys</i> supports multi-argument key code; and
<li> <i>pgfkeys</i> can support call-backs when an unknown key
  appears (these things are called <em>handlers</em>.
</ul>
Keys are organized in a tree that is reminiscent of the Unix fille
tree.  A typical key might be, <i>/tikz/coordinate system/x</i> or
just <i>/x</i>.  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.  So a <code>\</code><code>pgfkeys</code> command might be:
<blockquote>
<pre>
\pgfkeys{/my key=hello,/your keys/main key=something\strange,
  key name without path=something else}
</pre>
</blockquote><p>

and for each key mentioned, the associated code will be executed.
... and that code is also set up using <code>\</code><code>pgfkeys</code>:
<blockquote>
<pre>
\pgfkeys{/my key/.code=The value is '#1'.}
</pre>
</blockquote><p>
after which
<blockquote>
<pre>
\pgfkeys{/my key=hi!}
</pre>
</blockquote><p>
will produce just
<blockquote>
  The value is &rsquo;hi!&rsquo;.
</blockquote><p>
The manual goes on, showing how to define a key with two arguments,
how to provide default value for a key, and how to define aliases for
particular key sequences (which are called &ldquo;styles&rdquo;).  All in all,
it seems a well thought-out system, offering a lot of flexibility that
isn&rsquo;t available with the other keys packages.  However, there seems to
be no mechanism for using <i>pgfkeys</i> keys as part of the
options of another package, in the way that <i>kvoptions</i> does.
<p/>Another key-value system that&rsquo;s part of larger set of macros is
<i>scrbase</i>, which uses the facilities of <i>keyval</i> to
build a larger set of facilities, originally for use within the
<i>KOMA-script</i> bundle.  For English-speaking authors, there are
difficulties from the German-only documentation; however, from a
partial translation available to the author of this answer, a summary
is possible.  The package may build on the facilities either of
<i>kyeval</i> or of <i>xkeyval</i>, and builds its functionality
on the structure of the &lsquo;key family&rsquo;.  The user may define family
&lsquo;members&rsquo; and keys are defined relative to the members.  (For example,
the package <i>scrbase</i> is part of the <i>KOMA-script</i>
bundle; so its keys are all members of the <i>scrbase.sty</i>
family within the <i>KOMA</i> family.  The function
<code>\</code><code>FamilyProcessOptions</code> allows the programmer to decode the options
of the package in terms of the package&rsquo;s key family.  Note that there
is no special provision made for &ldquo;traditional&rdquo; package options, as
in the <i>kvoptions</i> package.
<p/>This brief summary was guided by input from two sources: a draft article
for <i>TUGboat</i> by Joseph Wright, and the partial translation of the
documentation of package <i>scrbase</i> prepared by Philipp
Stephani.  At Joseph&rsquo;s suggestion, discussion of his <i>keys3</i>
package, which is designed for use with the experimental LaTeX3,
has been omitted.
<dl>
<dt><tt><i>keyval.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/required/graphics.zip">macros/latex/required/graphics</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/required/graphics/">browse the directory</a>)
<dt><tt><i>kvoptions.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>)
<dt><tt><i>kvsetkeys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/oberdiek.zip">macros/latex/contrib/oberdiek</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/oberdiek/">browse the directory</a>)
<dt><tt><i>pgfkeys.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/graphics/pgf.zip">graphics/pgf</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/graphics/pgf/">browse the directory</a>)
<dt><tt><i>scrbase.sty</i></tt><dd>Distributed as part of <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/koma-script.zip">macros/latex/contrib/koma-script</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/koma-script/">browse the directory</a>)
<dt><tt><i>xkeyval.sty</i></tt><dd><a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/xkeyval.zip">macros/latex/contrib/xkeyval</a> (or <a href="http://www.tex.ac.uk/www.tex.ac.uk  tex-archive/macros/latex/contrib/xkeyval/">browse the directory</a>)
</dl>
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=keyval">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=keyval</a>
</body>