3 % $Id: mdwkey.dtx,v 1.1 2003/09/05 16:09:56 mdw Exp $
5 % Parsing key/value pairs
7 % (c) 2003 Mark Wooding
9 %----- Revision history -----------------------------------------------------
11 % $Log: mdwkey.dtx,v $
12 % Revision 1.1 2003/09/05 16:09:56 mdw
18 % \begin{meta-comment} <general public licence>
20 %% mdwkey package -- yet another key/value parser
21 %% Copyright (c) 2003 Mark Wooding
24 %% This program is free software; you can redistribute it and/or modify
25 %% it under the terms of the GNU General Public License as published by
26 %% the Free Software Foundation; either version 2 of the License, or
27 %% (at your option) any later version.
29 %% This program is distributed in the hope that it will be useful,
30 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
31 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
32 %% GNU General Public License for more details.
34 %% You should have received a copy of the GNU General Public License
35 %% along with this program; if not, write to the Free Software
36 %% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
41 % \begin{meta-comment} <Package preamble>
42 %<+package&!plain>\NeedsTeXFormat{LaTeX2e}
43 %<+package&!plain>\ProvidesPackage{mdwkey}
44 %<+package&!plain> [2003/08/21 1.0 key/value parser]
52 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
53 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
54 %% Digits \0\1\2\3\4\5\6\7\8\9
55 %% Exclamation \! Double quote \" Hash (number) \#
56 %% Dollar \$ Percent \% Ampersand \&
57 %% Acute accent \' Left paren \( Right paren \)
58 %% Asterisk \* Plus \+ Comma \,
59 %% Minus \- Point \. Solidus \/
60 %% Colon \: Semicolon \; Less than \<
61 %% Equals \= Greater than \> Question mark \?
62 %% Commercial at \@ Left bracket \[ Backslash \\
63 %% Right bracket \] Circumflex \^ Underscore \_
64 %% Grave accent \` Left brace \{ Vertical bar \|
65 %% Right brace \} Tilde \~}
71 % \begin{meta-comment}
75 \describespackage{mdwkey}
81 %^^A-------------------------------------------------------------------------
82 % \section{User's guide}
84 % This is a key/value-pair parser, rather like the one in David Carlisle's
85 % \package{keyval} package but a little more powerful. There's no problem
86 % with having both in the same program.
88 % \subsection{Terminology}
90 % A \emph{key-value pair} is a pair \syntax{<key> `=' <value>}, where the
91 % \lit{=} appears at the topmost bracing level. A \emph{tag} is just a
92 % single \syntax{<key>}. A \emph{list} is a sequence of key-value pairs and
93 % tags separated by commas \lit{,} at the topmost bracing level. A \<key> or
94 % \<value> has a leading and/or trailing space removed, if there are any, and
95 % if the whole thing is enclosed in braces, then the braces are removed.
97 % \begin{itemize} \synshorts
98 % \item "foo = bar" is a key-value pair. The key is `foo' and the value is
100 % \item `{foo = bar}' is a tag. The key is `foo = bar'.
101 % \item `foo = { bar }' is a key-value pair. The key is `foo' and
102 % the value is ` bar ' (with the leading and trailing spaces).
103 % \item `foo = { bar }x' is a key-value pair. The key is `foo' and
104 % the value is `{ bar }x'.
105 % \item `one, two' is a list of two tags, `one' and `two'.
106 % \item `one, {two, three}' is a list of two tags, `one' and `two, three'.
108 % There is no way to get an unmatched brace into a \<key> or \<value> without
109 % stupid catcode tricks.
111 % \subsection{Using the system}
113 % \DescribeMacro\mkdef
114 % New key names, and what to do when they're encountered, is all defined
115 % using |\mkdef|. Keys are gathered into \emph{groups}, so that lots of
116 % people can use the system without treading on their toes. I recommend that
117 % people use \syntax{<package-name>":"<label>} for their group names.
119 % There's a lot which can be done using |\mkdef|.
120 % \begin{itemize} \synshorts
121 % \item "\\mkdef{"<group>"}{"<key>"}{"<stuff>"}" will perform <stuff> when
122 % <key> is given a value: the value is available as "#1" in <stuff>.
123 % \item "\\mkdef{"<group>"}{"<key>"}["<default>"]{"<stuff>"}" is the same,
124 % but additionally if <key> is found as a tag, then treat it as if we found
125 % <key>"={"<default>"}" instead.
126 % \item "\\mkdef{"<group>"}{"<key>"}*{"<stuff>"}" will perform <stuff> when
127 % <key> is found as a tag.
128 % \item "\\mkdef*{"<group>"}{"<stuff>"}" will perform <stuff> when an unknown
129 % key (one for which there is no specific definition in this group) is
130 % given a value: the key is available as "#1" and the value as "#2" in
132 % \item "\\mkdef*{"<group>"}["<default>"]{"<stuff>"}" is the same, but
133 % additionally if an unknown key is found as a tag then treat it as if
134 % it had been assigned the value <default> instead.
135 % \item "\\mkdef*{"<group>"}*{"<stuff>"}" will perform <stuff> when an
136 % unknown key is found as a tag: the key is available as "#1" in <stuff>.
139 % \DescribeMacro\mkparse
140 % All that remains now is to learn how to use the thing. Once you have a
141 % list, you can say \syntax{"\\mkparse{"<group>"}{"<list>"}"} to perform all
142 % the appropriate actions. (This will mess up |\toks0| and |\next@| and some
143 % other standard scratch macros.)
145 %^^A-------------------------------------------------------------------------
147 % \section{Implementation}
153 % \subsection{Provide bits of \LaTeX\ for plain \TeX}
155 % This lot is the infrastructure needed to make the macros work under Plain
160 \edef\done{\catcode`\noexpand\@=\the\catcode`\@}
163 \def\@firstoftwo#1#2{#1}
164 \def\@firstofthree#1#2#3{#1}
165 \def\@secondoftwo#1#2{#2}
166 \def\@ifnextchar#1#2#3{%
168 \ifx\char@#1\expandafter\@firstoftwo%
169 \else\expandafter\@secondoftwo\fi{#2}{#3}%
173 \def\@ifn@i{\futurelet\char@\@ifn@ii}
175 \ifx\char@\@sptoken\expandafter\@ifn@i\else%
176 \expandafter\next@\fi%
180 \ifx\char@*\expandafter\@firstofthree%
181 \else\expandafter\@secondoftwo\fi{#1}{#2}%
183 \futurelet\char@\next@%
185 \def\@namedef#1{\expandafter\def\csname#1\endcsname}
186 \def\PackageError#1#2#3{\errhelp{#3}\errmessage{#1 error: #2}\errhelp{}}
190 % \subsection{Removing spaces}
192 % \begin{macro}{\withoutspaces}
194 % Saying \syntax{"\\withoutspaces{"<macro>"}{"<stuff>"}"} calls \<macro>,
195 % passing it the argument which is \<stuff>, shorn of (a) a single leading
196 % and/or space token, and (b) a single layer of |{|\ldots|}| grouping, if
197 % present. This improves over \package{keyval}'s attempt by being a little
198 % simpler and only stripping off one layer of braces.
201 \def\q@delim{\q@delim}
204 \def\withoutspaces##1##2{%
205 \def\next@{##1}\futurelet\char@\wsp@i##2%
206 \q@delim#1\q@delim\q@delim\relax%
209 \ifx\char@\@sptoken\expandafter\wsp@ii%
210 \else\expandafter\wsp@iii\fi%
212 \def\wsp@ii#1{\wsp@iii}
213 \def\wsp@iii##1#1\q@delim##2\relax{\wsp@iv##1\q@delim\relax}
214 \def\wsp@iv##1\q@delim##2\relax{\next@{##1}}
220 % \begin{macro}{\withoutspacesdef}
222 % As a trivial but useful application of the above,
223 % \syntax{"\\withoutspacesdef{"<name>"}{"<stuff>"}"} defines \<name> as a
224 % macro containing \<stuff> with a leading and trailing space deleted and a
225 % level of bracing removed.
228 \def\withoutspacesdef#1#2{\withspaces\toks@{#2}\edef#1{\the\toks@}}
233 % \subsection{Parsing key/value lists}
235 % \begin{macro}{\mkparse}
237 % The main parser macro. Stash some information away and then start on the
244 \mk@loop!#2,\q@delim,\relax%
248 % And already the subtlety begins. Note that there's a leading \lit{!} at
249 % the front of the token list. This prevents our delimited argument from
250 % being entirely brace-enclosed, which in turn stops \TeX\ from removing it
251 % until we're good and ready.
253 % This doesn't trap empty items -- that happens later.
257 \expandafter\def\expandafter\next@\expandafter{\@gobble#1}%
258 \ifx\next@\q@delim\expandafter\mk@x%
259 \else\mk@i#1=\q@delim\expandafter\mk@loop\expandafter!\fi%
261 \def\mk@x#1\relax{\relax}
264 % Now we have to split an entry into a key and a value. If we have
265 % \<key>|=|\<value> then |#1| = |!|\<key> and |#2| = \<value>|=|; if we have
266 % only \<key>, then |#1| = |!|\<key> as before, and |#2| is empty. The first
267 % thing to do is strip the |!| and spaces from |#1|. If |#2| is empty then
268 % we're done with this stage and can just call |\mk@k| with what we've got;
269 % otherwise we swap the trailing |=| on |#2| for a leading |!| and strip that
270 % off, and then call |\mk@kv| with the answer.
273 \def\mk@i#1=#2\q@delim{%
274 \expandafter\withoutspaces\expandafter%
275 \mk@ii\expandafter{\@gobble#1}{#2}%
278 \ifx\q@delim#2\q@delim\mk@k{#1}%
279 \else\mk@iii{#1}!#2\q@delim\fi%
281 \def\mk@iii#1#2=\q@delim{%
282 \expandafter\withoutspaces\expandafter%
283 \mk@iv\expandafter{\@gobble#2}{#1}%
285 \def\mk@iv#1#2{\mk@kv{#2}{#1}}
288 % We just have \<key>, shorn of spaces and outer braces. If it's empty then
289 % the whole entry was empty and we should ignore it. Otherwise, if there's a
290 % defined command for handling the token then we use that; if not, then we
291 % look for a general unknown-key command. If nothing works, we raise an
296 \ifx\q@delim#1\q@delim\else%
297 \expandafter\let\expandafter\next@\csname\mk@!#1\endcsname%
299 \expandafter\let\expandafter\next@\csname\mk@*!\endcsname%
300 \ifx\next@\relax\mk@err{#1}%
307 % We have a \<key> and a \<value>, both stripped of spaces and braces. If
308 % there's a command for this key, then give it the value; otherwise look for
309 % a general unknown-key-with-value command. If nothing works, raise an
314 \expandafter\let\expandafter\next@\csname\mk@=#1\endcsname%
316 \expandafter\let\expandafter\next@\csname\mk@*=\endcsname%
317 \ifx\next@\relax\mk@err{#1}%
318 \else\next@{#1}{#2}\fi%
323 % How to raise an error. Not so difficult.
327 \PackageError{mdwkey}{Key `#1' not found in group `\mk@group'}{%
328 I've never heard of the key you tried to set. I'm going to ignore it.
335 % \subsection{Defining keys}
337 % \begin{macro}{\mkdefkey}
339 % This is all quite dull, really. I tried to merge the two cases, but it
340 % failed because I can't pass around macro parameter names through
341 % |\@ifnextchar| and their friends. If anyone has any bright ideas, I'd be
345 \def\mkdef{\@ifstar\mkdef@star@\mkdef@}
350 {\mkdef@iii{#1}{#2}}%
353 \def\mkdef@i#1#2{\@namedef{mk$#1$=#2}##1}
354 \def\mkdef@ii#1#2{\@namedef{mk$#1$!#2}}
355 \def\mkdef@iii#1#2[#3]{%
357 \expandafter\edef\csname mk$#1$!#2\endcsname%
358 {\expandafter\noexpand\csname mk$#1$=#2\endcsname{\the\toks@}}%
359 \@namedef{mk$#1$=#2}##1%
363 {\mkdef@star@ii{#1}}%
365 {\mkdef@star@iii{#1}}%
366 {\mkdef@star@i{#1}}}%
368 \def\mkdef@star@i#1{\@namedef{mk$#1$*=}##1##2}
369 \def\mkdef@star@ii#1{\@namedef{mk$#1$*!}##1}
370 \def\mkdef@star@iii#1[#2]{%
372 \expandafter\edef\csname mk$#1$*!\endcsname##1%
373 {\expandafter\noexpand\csname mk$#1$*=\endcsname{##1}{\the\toks@}}%
374 \@namedef{mk$#1$*=}##1##2%
380 % And with that, we're done.
387 % \hfill Mark Wooding, \today