summaryrefslogtreecommitdiff
path: root/usergrps/uktug/baskervi/4_3/keyval.tex
diff options
context:
space:
mode:
Diffstat (limited to 'usergrps/uktug/baskervi/4_3/keyval.tex')
-rw-r--r--usergrps/uktug/baskervi/4_3/keyval.tex158
1 files changed, 158 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/4_3/keyval.tex b/usergrps/uktug/baskervi/4_3/keyval.tex
new file mode 100644
index 0000000000..e72b4b35ae
--- /dev/null
+++ b/usergrps/uktug/baskervi/4_3/keyval.tex
@@ -0,0 +1,158 @@
+\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