diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /usergrps/uktug/baskervi/4_3/keyval.tex |
Initial commit
Diffstat (limited to 'usergrps/uktug/baskervi/4_3/keyval.tex')
-rw-r--r-- | usergrps/uktug/baskervi/4_3/keyval.tex | 158 |
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 |