summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex
blob: d0c7e7898d092cae9f3fbd3b9b2cbd3e287519cb (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
\documentclass[
  use-a4-paper,
  use-10pt-font,
  final-version,
  use-UK-English,
  fancy-section-headings,
  frame-section-numbers,
  para-abstract-style,
  input-config-file,
  no-hyperref-messages
]{amltxdoc}

\hfuzz1pt
\makeatletter
\WrapQuotes
\makeindex

\begin{document}

\begin{frontmatter}
\title{The \texttt{\color{blue}keyval2e} Package\titleref{t1}}
\titlenotes[t1]{%
  The package is available at \iftogTF{pdf}{\url{\@titleurl}}
  {\url{\@shorttitleurl}}. This user manual corresponds to version~0.0.1a.
}
\subtitle{Robust and fast key parser}
\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/keyval2e/}
\shorttitleurl{http://www.ctan.org/}
\author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}

\end{frontmatter}

\begin{xwmshade}[fillcolor=white,framecolor=orange,framerule=1pt,framesep=2pt,
  width=1.0\hsize]\tableofcontents
\end{xwmshade}


\docsection{Introduction}

The \pkg'{keyval2e} provides lightweight and robust facilities for creating and managing keys. Its machinery isn't as extensive as that of, \eg, \pkg'{ltxkeys} but it is equally robust. Ease of
use and speed of processing are the two main motives of this package. Some, indeed many, applications of the key-value syntax (while they call for robustness) don't require the full armor of key-value processing as found in, \eg, the \pkg'{ltxkeys}. This package was prompted by a subscriber's post on \comptexttex in August 2011.

In the \pkg'{keyval2e}, ordinary, boolean, and choice keys can be created using only one command (\fx{\kve@definekeys}). Keys can be initialized with their default values (with the command \fx{\kve@setdefaults}) as soon as they are created, or at any time. And in any run the default values of keys can be used to set keys that have no current values. The latter task is accomplished by the command \fx{\kve@setafterdefaults}, meaning \quoted{set keys with the current values after those without current values have been initialized/set with their default values}. Normally, keys are set with the re-entrant command \fx{\kve@setkeys}.

The \pkg'{keyval2e} has no service for processing package or class options. See the \pkg'{ltxkeys} for this service. I have seen users who require the services of keys only in documents, and not in package or class files. And some package authors still use \latex's native option processing schemes. For those authors, the \pkg'{keyval2e} may be used to process keys (but not options) in package and class files.

The \pkg'{keyval} provides a simple and widely used interface, but it is not robust, in the sense that it strips off outer curly braces in key values. Also, it has no means to automatically call up default key values after the keys have been defined. Moreover, it automatically redefines existing keys.


\docsection{Package options}

The \pkg'{keyval2e} currently has no options.


\docsection{User commands}

\start+{newmacro}[\kve@definekeys, \kve@setkeys, etc]
\kve@definekeys[|A(pref)]{|A(fam)}[|A(mp)]{%
  |A(key-1)/|A(defa-1)/|A(callback-1),
  ...,
  |A(key-n)/|A(defa-n)/|A(callback-n)
}

\kve@definekeys|*[|A(pref)]{|A(fam)}[|A(mp)]{%
  |A(key-1)/|A(defa-1)/|A(callback-1),
  ...,
  |A(key-n)/|A(defa-n)/|A(callback-n)
}

\kve@setkeys[|A(pref)]{|A(fam)}[na]{|A(keyval)}

\kve@setdefaults[|A(pref)]{|A(fam)}[|A(na)]

\kve@setafterdefaults[|A(pref)]{|A(fam)}[|A(na)]{|A(keyval)}
\finish{newmacro}
\fxim*{\kve@definekeys,\kve@setkeys,\kve@setdefaults,\kve@setafterdefaults}

Here, \ang{pref} is the optional key prefix (default \fx{KV}), \ang{fam} is the mandatory family, \ang{mp} is the key-value-holding macro prefix (default \fx{kvmp@}), \ang{defa-i} is the default value of key \quotedfx{i}, \ang{callback-i} is the callback (\ie, the function that will be executed when the key is set) of key \quotedfx{i}, and \ang{keyal} is a list of \keyval pairs.

\ang{na} is a comma-separated list of keys that should be ignored, ie, not set in the current run of setting keys\footnote{When setting keys, undefined keys are reported by the \pkg'{keyval2e} as undefined and are not saved as \quoted{remaining keys}. Moreover, there are no \quoted{undefined key handlers} and no \quoted{handled keys} in this package. Please see the \pkg'{ltxkeys} for these facilities.}. \mpkey will hold the current value of \ang{key}. The key macro (\ie, the one that holds the key's callback) is always \preffamkey.

The \stform of the command \fx{\kve@definekeys} will define only definable keys, in the sense of \latex's \hx{\newcommand}. In that case the commands \mpkey must also be unique, \ie, not previously defined. The plain form \fx{\kve@definekeys} will always define the key, whether or not the key already exists; existing keys will thus be overwritten in this case.

You can use \fx{#1} in \ang{callback} to access the value of the current key. Also the macros \ffx'{\currpref, \currfam, \currkey, \currval, \currkeyval} are always available when setting keys and may be called in \ang{callback}.

The command \fx{\kve@setdefaults} will set all the keys in the given family \ang{fam} and prefix \ang{pref} with their default values. All boolean keys (\ie, those with a default in the set \boolset) will be initialized with a default value of \fx{false}. This is to avoid premature toggling of the state of such keys. The command \fxis{\kve@setwithdefaults}{\kve@setdefaults} is an alias for \fx{\kve@setdefaults}.

\Note After the keys have been defined, they are automatically set with their default values using the command \fx{\kve@setdefaults}. This provides default definitions for immediate use.

The command \fx{\kve@setafterdefaults} will set the given \keyval pairs after initializing to default values all those keys (in the given family and prefix) that are not listed in the accompanying \keyval list. This provides a mechanism for (re)initialing to default values those keys that don't have values in \keyval. This type of (re)initialization is often required in the deployment of keys, and it is useful to have a handy way of accomplishing this semi-automatically.


\docsubsection{Utility macros}

The following macros are utilities.

\start{newmacro}[\kve@checkchoice]
\kve@checkchoice{|A(teststring)}{|A(nominations)}{|A(nomatch)}
\finish{newmacro}
\fxim*{\kve@checkchoice}

The \ang{nominations} have the syntax

\start'{macro}[Nominations and callbacks]
|A(nom-1)|R(:)|A(callback-1),...,|A(nom-n)|R(:)|A(callback-n)
\finish{macro}

Here, please note the \qcolon, which separates \ang{nom} from \ang{callback}. \ang{callback-i} will be executed if \ang{nom-i} matches \ang{teststring}. The first match found takes priority over subsequent matches. The fallback \ang{nomatch} will be executed if \ang{teststring} doesn't match any of the \ang{nom}'s.

\start{newmacro}[\kve@checkbool]
\kve@checkbool{|A(val)}{|A(true)}{|A(false)}
\finish{newmacro}
\fxim*{\kve@checkbool}

This checks if \ang{val} is an admissible value of a boolean, namely, if it is in the set \boolset. If \ang{val} is valid, the text \ang{true} will be executed; otherwise \ang{false} will be executed.

\start{newmacro}[\kve@keyvalerr]
\kve@keyvalerr
\finish{newmacro}
\fxim*{\kve@keyvalerr}

This is a parameterless command that uses \ffx'{\currkey,\currval} internally. It simply generates an error to indicate that the current value of a key is invalid. It will indicate the key name and the truncated version of the key value that is invalid.


\docsection{Examples}

\start{example}[\kve@definekeys]
|R(\kve@definekeys)[KV]{fam}[mp@]{%
  |com(keya and keyb are boolean keys:)
  keya/true/|R(\kve@checkbool){#1}{\def\result{OK}}{|R(\kve@keyvalerr)},
  keyb/false/|R(\kve@checkbool){#1}{%
      \usename{@tempswa#1}%
      \if@tempswa\def\x{found}\else\def\x{not-found}\fi
    }{%
      \kve@keyvalerr
    },
  |com(keyc is a choice key:)
  keyc/left/|R(\kve@checkchoice){#1}{left:\let\x\flushleft,
    right:\let\x\flushright}{|R(\kve@keyvalerr)},
  keyd/right/\def\x##1{#1xx##1},
  |com(keyone has an empty default value:)
  keyone//\ifx\\#1\\\def\x{no-val}\else\def\x{#1}\fi,
  |com(keytwo has no callback:)
  keytwo/+,
  |com(keythree has a braced default value:)
  keythree/{left}/|R(\kve@setkeys)[KV]{fam}{keyone=#1}
}
\finish{example}

Remember that after the keys have been defined, they are automatically set with their default values using the command \fx{\kve@setdefaults}.

The following command says \quoted{set the current keys with their current values, after the defaults have been set up}. Keys with current values will not be set with their default values:

\start{example}[\kve@setafterdefaults]
\kve@setafterdefaults[KV]{fam}{keyone=+,keytwo=abc,keythree=+,keyfour=xax}
\finish{example}

Please see the example file for the fuller version of the following example:

\start+{example}[Creating a key command]
\documentclass{minimal}
\usepackage{keyval2e}
\makeatletter
|R(\kve@definekeys)[KV]{fam}[mp@]{%
  keyone/+,
  keytwo/+,
  keythree/+,
  keyfour/+
}
\def\fourplus{+,+,+,+}
\newcommand{\test}[2]{%
  |R(\kve@setafterdefaults)[KV]{fam}{#2}%
  \edef\tempa{\mp@keyone,\mp@keytwo,\mp@keythree,\mp@keyfour}%
  Test #1: *\texttt{\tempa}*%
  \ifxTF\tempa\fourplus{All values are defaults}{At least one value is set}%
}
\begin{document}
\ttfamily\noindent
\test{A}{}\\
\test{B}{keythree=+}\\
\test{C}{keythree=a}\\
\end{document}
\finish{example}


\docsection(sec:version-hist){Version history}

The \stsign on the right-hand side of the following lists means the subject features in the package but is not reflected anywhere in this user guide.

\begin{versionhist}
  \begin{version}{0.0.1}{2011/08/13}
  \item First public release.\vsecref*
  \end{version}
  \begin{version}{0.0.1a}{2011/08/14}
  \item Completed the user guide.\vsecref*
  \end{version}
\end{versionhist}

\newpage
\indexpreamble{Index numbers refer to page numbers.}
\indexpreambleformat{\centering}
\indexcolumns\tw@
\printindex

\end{document}