\title{The \textsf{keyval} package}
\author[David Carlisle]{David Carlisle\\carlisle@cs.man.ac.uk}
\begin{Article}
\MakeShortVerb{|}
\newenvironment{macro}[1]{}{}
\section{Introduction}
This article describes a \LaTeXe\ package implementing a system of
defining and using sets of parameters, which are activated using the
syntax \meta{key}=\meta{value}. It is distributed with the
\LaTeXe\ standard graphics / color packages which are
available on the CTAN archives in |macros/latex2e/packages/graphics|.
It is important to stress that although the \LaTeX3 project intends
to support interfaces of this kind, the present package is \emph{not}
in any sense a preview of \LaTeX3.

When a `keyval' system is set up in a \LaTeX\ package,
a set of macros is defined for each keyword that is needed; this is
called whenever the parameter appears in a parameter list. For
instance, if the set |dpc| is to have the keyword |scale|, then the
author might write:
\begin{quote}
 | \define@key{dpc}{scale}{scale ({\tt\string#1})}|
\end{quote}
The first argument of |\define@key| is the name of the set of keywords
being used, the second is the keyword, and the third is the macros
to call. These will be given as |#1| the \meta{value}
specified by the user.

Normally it is an error to omit the `=\meta{value}'; however if an
optional \meta{value} is supplied when the keyword is defined, then
just the keyword need be supplied. Thus, after
\begin{quote}
|\define@key{dpc}{clip}[true]{...}|
\end{quote}
\noindent the user can type `|clip = true|' or `|clip = false|' or
just `|clip|', which is the same as `|clip = true|'

To use these keywords, we call |\setkeys| with a comma
separated list of settings, each of the form
\meta{key}=\meta{value}, or just \meta{key}. Any white space around
the `|=|' and `|,|' is ignored.

As the \meta{key} is passed as a macro argument, if it consists
entirely of a |{ }| group, the outer  braces are stripped off. Thus
|,key=foo,| and |,key={foo},| are equivalent. This fact enables one to
`hide' any commas or equals signs that must appear in the value. \ie
in |foo={1,2,3},bar=4|, |foo| gets the value |1,2,3| --- the comma after
|1| does not terminate the keyval pair, as it is `hidden' by the
braces.

Empty entries, with nothing between the commas, are silently ignored.
This means that it is not an error to have a comma after the last
term, or before the first.

\section{Example}

We may extend the examples above to give  a `fake' graphics
inclusion macro, with a syntax similar to that used in the psfig
macros.

\makeatletter

|\dpcgraphics| has one optional argument which is passed through
|\setkeys|, and one mandatory argument, the filename. It actually
just typesets its arguments, for demonstration.

\newcommand{\dpcgraphics}[2][]{{\setkeys{dpc}{#1}INPUT: #2}}

\define@key{dpc}{scale}{scale ({\tt\string#1\relax})\\}
\define@key{dpc}{height}{height ({\tt#1})\\}
\define@key{dpc}{width}{width ({\tt#1})\\}
\define@key{dpc}{bb}{bounding box ({\tt#1})\\}
\define@key{dpc}{clip}[true]{clip ({\tt\string#1\relax})\\}
\makeatother

The declared keys are: |scale|, |height|, |width|, |bb|,
and |clip|. Except for the last, they must all be given a value if
used.

Note how in the following, any white space arround |=| or |,| is
ignored, as are the `empty' arguments caused by extra commas. Note
also that each macro receives {\em exactly\/} the tokens that you
specify as arguments, no premature expansion is done.

\begin{verbatim}
\newcommand{\dpcgraphics}[2][]{%
   {\setkeys{dpc}{#1}INPUT: #2}}

\define@key{dpc}{height}{%
  height ({\tt#1})\\}
\define@key{dpc}{width}{%
  width ({\tt#1})\\}
\define@key{dpc}{bb}{%
  bounding box ({\tt#1})\\}
\define@key{dpc}{scale}{%
  scale ({\tt\string#1\relax})\\}
\define@key{dpc}{clip}[true]{%
  clip ({\tt\string#1\relax})\\}
\end{verbatim}

\begin{minipage}{.4\textwidth}
\begin{verbatim}
\def\scalemacro{9}
\dpcgraphics
[ height =4in, ,
  width = 3in,
  scale = \scalemacro,
  bb = 20 20 300 400 ,
  clip,
 ]{aaa}
\end{verbatim}
\end{minipage}
\hfill
\begin{minipage}{.4\textwidth}
\def\scalemacro{9}
\dpcgraphics
[ height =4in, ,
  width = 3in,
  scale = \scalemacro ,
  bb = 20 20 300 400 ,
  clip ,
 ]{aaa}
\end{minipage}


\section{The Internal Interface}
A declaration of the form:
\begin{quote}
|\define@key{family}{key}{...}|
\end{quote}
\noindent defines a macro |\KV@prefix@key| with one argument. When used in a
keyval list, the macro receives the value as its argument.

A declaration of the form:
\begin{quote}
|\define@key{family}{key}[default]{...}|
\end{quote}
\noindent defines a macro |\KV@family@key| as above; however, it also
defines the macro |\KV@family@key@default| as a macro with no
arguments, and definition\\ |\KV@family@key{default}|.

Thus if macros are defined using |\define@key|, the use of a key with
no value \ldots|,foo,|\ldots\ is always equivalent to the use of the
key with some value, \ldots|,foo=default,|\ldots. However, a package
writer may wish that the `default' behaviour for some key is not
directly equivalent to using that key with a value (in particular, as
pointed out to me by Timothy Van Zandt, you may wish to omit error
checking on the default value as you know it is correct.) In these
cases one simply needs to define the two macros
|\KV@|\meta{family}|@key| and |\KV@|\meta{family}|@key@default|
directly using |\def| (or |\newcommand|). I do not supply a user
interface for this type of definition, but it is supported in the
sense that I will try to ensure that any future upgrades of this
package do not break styles making use of these `low level'
definitions.

\end{Article}
\endinput