mdw@git.distorted.org.uk Git - mdwtools/blob - mdwkey.dtx

   1 % \begin{meta-comment} <general public licence>
   2 %%
   3 %% mdwkey package -- yet another key/value parser
   4 %% Copyright (c) 2003 Mark Wooding
   5 %<*package>
   6 %%
   7 %% This file is part of the `mdwtools' LaTeX package collection.
   8 %%
   9 %% `mdwtools' is free software: you can redistribute it and/or modify it
  10 %% under the terms of the GNU General Public License as published by the
  11 %% Free Software Foundation; either version 2 of the License, or (at your
  12 %% option) any later version.
  13 %%
  14 %% `mdwtools' is distributed in the hope that it will be useful, but
  15 %% WITHOUT ANY WARRANTY; without even the implied warranty of
  16 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 %% General Public License for more details.
  18 %%
  19 %% You should have received a copy of the GNU General Public License
  20 %% along with `mdwtools'.  If not, write to the Free Software Foundation,
  21 %% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  22 %</package>
  23 %%
  24 % \end{meta-comment}
  25 %
  26 % \begin{meta-comment} <Package preamble>
  27 %<+package&!plain>\NeedsTeXFormat{LaTeX2e}
  28 %<+package&!plain>\ProvidesPackage{mdwkey}
  29 %<+package&!plain>                [2020/09/06 1.14.0 Key/value parser]
  30 % \end{meta-comment}
  31 %
  32 % \CheckSum{316}
  33 %\iffalse
  34 %<*package>
  35 %\fi
  36 %% \CharacterTable
  37 %%  {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
  38 %%   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
  39 %%   Digits        \0\1\2\3\4\5\6\7\8\9
  40 %%   Exclamation   \!     Double quote  \"     Hash (number) \#
  41 %%   Dollar        \$     Percent       \%     Ampersand     \&
  42 %%   Acute accent  \'     Left paren    \(     Right paren   \)
  43 %%   Asterisk      \*     Plus          \+     Comma         \,
  44 %%   Minus         \-     Point         \.     Solidus       \/
  45 %%   Colon         \:     Semicolon     \;     Less than     \<
  46 %%   Equals        \=     Greater than  \>     Question mark \?
  47 %%   Commercial at \@     Left bracket  \[     Backslash     \\
  48 %%   Right bracket \]     Circumflex    \^     Underscore    \_
  49 %%   Grave accent  \`     Left brace    \{     Vertical bar  \|
  50 %%   Right brace   \}     Tilde         \~}
  51 %%
  52 %\iffalse
  53 %</package>
  54 %\fi
  55 %
  56 % \begin{meta-comment}
  57 %
  58 %<*driver>
  59 \input{mdwtools}
  60 \describespackage{mdwkey}
  61 \mdwdoc
  62 %</driver>
  63 %
  64 % \end{meta-comment}
  65 %
  66 %^^A-------------------------------------------------------------------------
  67 % \section{User's guide}
  68 %
  69 % This is a key/value-pair parser, rather like the one in David Carlisle's
  70 % \package{keyval} package but a little more powerful.  There's no problem
  71 % with having both in the same program.
  72 %
  73 % \subsection{Terminology}
  74 %
  75 % A \emph{key-value pair} is a pair \syntax{<key> `=' <value>}, where the
  76 % \lit{=} appears at the topmost bracing level.  A \emph{tag} is just a
  77 % single \syntax{<key>}.  A \emph{list} is a sequence of key-value pairs and
  78 % tags separated by commas \lit{,} at the topmost bracing level.  A \<key> or
  79 % \<value> has a leading and/or trailing space removed, if there are any, and
  80 % if the whole thing is enclosed in braces, then the braces are removed.
  81 % Examples:
  82 % \begin{itemize} \synshorts
  83 % \item "foo = bar" is a key-value pair.  The key is `foo' and the value is
  84 %   `bar'.
  85 % \item `{foo = bar}' is a tag.  The key is `foo = bar'.
  86 % \item `foo = { bar }' is a key-value pair.  The key is `foo' and
  87 %   the value is ` bar ' (with the leading and trailing spaces).
  88 % \item `foo = { bar }x' is a key-value pair.  The key is `foo' and
  89 %   the value is `{ bar }x'.
  90 % \item `one, two' is a list of two tags, `one' and `two'.
  91 % \item `one, {two, three}' is a list of two tags, `one' and `two, three'.
  92 % \end{itemize}
  93 % There is no way to get an unmatched brace into a \<key> or \<value> without
  94 % stupid catcode tricks.
  95 %
  96 % \subsection{Using the system}
  97 %
  98 % \DescribeMacro\mkdef
  99 % New key names, and what to do when they're encountered, is all defined
 100 % using |\mkdef|.  Keys are gathered into \emph{groups}, so that lots of
 101 % people can use the system without treading on their toes.  I recommend that
 102 % people use \syntax{<package-name>":"<label>} for their group names.
 103 %
 104 % There's a lot which can be done using |\mkdef|.
 105 % \begin{itemize} \synshorts
 106 % \item "\\mkdef{"<group>"}{"<key>"}{"<stuff>"}" will perform <stuff> when
 107 %   <key> is given a value: the value is available as "#1" in <stuff>.
 108 % \item "\\mkdef{"<group>"}{"<key>"}["<default>"]{"<stuff>"}" is the same,
 109 %   but additionally if <key> is found as a tag, then treat it as if we found
 110 %   <key>"={"<default>"}" instead.
 111 % \item "\\mkdef{"<group>"}{"<key>"}*{"<stuff>"}" will perform <stuff> when
 112 %   <key> is found as a tag.
 113 % \item "\\mkdef*{"<group>"}{"<stuff>"}" will perform <stuff> when an unknown
 114 %   key (one for which there is no specific definition in this group) is
 115 %   given a value: the key is available as "#1" and the value as "#2" in
 116 %   <stuff>.
 117 % \item "\\mkdef*{"<group>"}["<default>"]{"<stuff>"}" is the same, but
 118 %   additionally if an unknown key is found as a tag then treat it as if
 119 %   it had been assigned the value <default> instead.
 120 % \item "\\mkdef*{"<group>"}*{"<stuff>"}" will perform <stuff> when  an
 121 %   unknown key is found as a tag: the key is available as "#1" in <stuff>.
 122 % \end{itemize}
 123 %
 124 % \DescribeMacro\mkparse
 125 % All that remains now is to learn how to use the thing.  Once you have a
 126 % list, you can say \syntax{"\\mkparse{"<group>"}{"<list>"}"} to perform all
 127 % the appropriate actions.  (This will mess up |\toks0| and |\next@| and some
 128 % other standard scratch macros.)
 129 %
 130 %^^A-------------------------------------------------------------------------
 131 % \implementation
 132 % \section{Implementation}
 133 %
 134 %    \begin{macrocode}
 135 %<*package|macro>
 136 %    \end{macrocode}
 137 %
 138 % \subsection{Provide bits of \LaTeX\ for plain \TeX}
 139 %
 140 % This lot is the infrastructure needed to make the macros work under Plain
 141 % \TeX.
 142 %
 143 %    \begin{macrocode}
 144 %<*plain>
 145 \edef\done{\catcode`\noexpand\@=\the\catcode`\@}
 146 \catcode`\@=11
 147 \def\@gobble#1{}
 148 \def\@firstoftwo#1#2{#1}
 149 \def\@firstofthree#1#2#3{#1}
 150 \def\@secondoftwo#1#2{#2}
 151 \def\@ifnextchar#1#2#3{%
 152   \def\next@{%
 153     \ifx\char@#1\expandafter\@firstoftwo%
 154     \else\expandafter\@secondoftwo\fi{#2}{#3}%
 155   }%
 156   \@ifn@i%
 157 }
 158 \def\@ifn@i{\futurelet\char@\@ifn@ii}
 159 \def\@ifn@ii{%
 160   \ifx\char@\@sptoken\expandafter\@ifn@i\else%
 161   \expandafter\next@\fi%
 162 }
 163 \def\@ifstar#1#2{%
 164   \def\next@{%
 165     \ifx\char@*\expandafter\@firstofthree%
 166     \else\expandafter\@secondoftwo\fi{#1}{#2}%
 167   }%
 168   \futurelet\char@\next@%
 169 }
 170 \def\@namedef#1{\expandafter\def\csname#1\endcsname}
 171 \def\PackageError#1#2#3{\errhelp{#3}\errmessage{#1 error: #2}\errhelp{}}
 172 %</plain>
 173 %    \end{macrocode}
 174 %
 175 % \subsection{Removing spaces}
 176 %
 177 % \begin{macro}{\withoutspaces}
 178 %
 179 % Saying \syntax{"\\withoutspaces{"<macro>"}{"<stuff>"}"} calls \<macro>,
 180 % passing it the argument which is \<stuff>, shorn of (a) a single leading
 181 % and/or space token, and (b) a single layer of |{|\ldots|}| grouping, if
 182 % present.  This improves over \package{keyval}'s attempt by being a little
 183 % simpler and only stripping off one layer of braces.
 184 %
 185 %    \begin{macrocode}
 186 \def\q@delim{\q@delim}
 187 \def\next@#1{%
 188 \let\@sptoken=#1
 189 \def\withoutspaces##1##2{%
 190   \def\next@{##1}\futurelet\char@\wsp@i##2%
 191   \q@delim#1\q@delim\q@delim\relax%
 192 }
 193 \def\wsp@i{%
 194   \ifx\char@\@sptoken\expandafter\wsp@ii%
 195   \else\expandafter\wsp@iii\fi%
 196 }
 197 \def\wsp@ii#1{\wsp@iii}
 198 \def\wsp@iii##1#1\q@delim##2\relax{\wsp@iv##1\q@delim\relax}
 199 \def\wsp@iv##1\q@delim##2\relax{\next@{##1}}
 200 }\next@{ }
 201 %    \end{macrocode}
 202 %
 203 % \end{macro}
 204 %
 205 % \begin{macro}{\withoutspacesdef}
 206 %
 207 % As a trivial but useful application of the above,
 208 % \syntax{"\\withoutspacesdef{"<name>"}{"<stuff>"}"} defines \<name> as a
 209 % macro containing \<stuff> with a leading and trailing space deleted and a
 210 % level of bracing removed.
 211 %
 212 %    \begin{macrocode}
 213 \def\withoutspacesdef#1#2{\withspaces\toks@{#2}\edef#1{\the\toks@}}
 214 %    \end{macrocode}
 215 %
 216 % \end{macro}
 217 %
 218 % \subsection{Parsing key/value lists}
 219 %
 220 % \begin{macro}{\mkparse}
 221 %
 222 % The main parser macro.  Stash some information away and then start on the
 223 % main loop.
 224 %
 225 %    \begin{macrocode}
 226 \def\mkparse#1#2{%
 227   \def\mk@group{#1}%
 228   \def\mk@{mk$#1$}%
 229   \mk@loop!#2,\q@delim,\relax%
 230 }
 231 %    \end{macrocode}
 232 %
 233 % And already the subtlety begins.  Note that there's a leading \lit{!} at
 234 % the front of the token list.  This prevents our delimited argument from
 235 % being entirely brace-enclosed, which in turn stops \TeX\ from removing it
 236 % until we're good and ready.
 237 %
 238 % This doesn't trap empty items -- that happens later.
 239 %
 240 %    \begin{macrocode}
 241 \def\mk@loop#1,{%
 242   \expandafter\def\expandafter\next@\expandafter{\@gobble#1}%
 243   \ifx\next@\q@delim\expandafter\mk@x%
 244   \else\mk@i#1=\q@delim\expandafter\mk@loop\expandafter!\fi%
 245 }
 246 \def\mk@x#1\relax{\relax}
 247 %    \end{macrocode}
 248 %
 249 % Now we have to split an entry into a key and a value.  If we have
 250 % \<key>|=|\<value> then |#1| = |!|\<key> and |#2| = \<value>|=|; if we have
 251 % only \<key>, then |#1| = |!|\<key> as before, and |#2| is empty.  The first
 252 % thing to do is strip the |!| and spaces from |#1|.  If |#2| is empty then
 253 % we're done with this stage and can just call |\mk@k| with what we've got;
 254 % otherwise we swap the trailing |=| on |#2| for a leading |!| and strip that
 255 % off, and then call |\mk@kv| with the answer.
 256 %
 257 %    \begin{macrocode}
 258 \def\mk@i#1=#2\q@delim{%
 259   \expandafter\withoutspaces\expandafter%
 260     \mk@ii\expandafter{\@gobble#1}{#2}%
 261 }
 262 \def\mk@ii#1#2{%
 263   \ifx\q@delim#2\q@delim\mk@k{#1}%
 264   \else\mk@iii{#1}!#2\q@delim\fi%
 265 }
 266 \def\mk@iii#1#2=\q@delim{%
 267   \expandafter\withoutspaces\expandafter%
 268     \mk@iv\expandafter{\@gobble#2}{#1}%
 269 }
 270 \def\mk@iv#1#2{\mk@kv{#2}{#1}}
 271 %    \end{macrocode}
 272 %
 273 % We just have \<key>, shorn of spaces and outer braces.  If it's empty then
 274 % the whole entry was empty and we should ignore it.  Otherwise, if there's a
 275 % defined command for handling the token then we use that; if not, then we
 276 % look for a general unknown-key command.  If nothing works, we raise an
 277 % error.
 278 %
 279 %    \begin{macrocode}
 280 \def\mk@k#1{%
 281   \ifx\q@delim#1\q@delim\else%
 282     \expandafter\let\expandafter\next@\csname\mk@!#1\endcsname%
 283     \ifx\next@\relax%
 284       \expandafter\let\expandafter\next@\csname\mk@*!\endcsname%
 285       \ifx\next@\relax\mk@err{#1}%
 286       \else\next@{#1}\fi%
 287     \else\next@\fi%
 288   \fi%
 289   }
 290 %    \end{macrocode}
 291 %
 292 % We have a \<key> and a \<value>, both stripped of spaces and braces.  If
 293 % there's a command for this key, then give it the value; otherwise look for
 294 % a general unknown-key-with-value command.  If nothing works, raise an
 295 % error.
 296 %
 297 %    \begin{macrocode}
 298 \def\mk@kv#1#2{%
 299   \expandafter\let\expandafter\next@\csname\mk@=#1\endcsname%
 300   \ifx\next@\relax%
 301     \expandafter\let\expandafter\next@\csname\mk@*=\endcsname%
 302     \ifx\next@\relax\mk@err{#1}%
 303     \else\next@{#1}{#2}\fi%
 304   \else\next@{#2}\fi%
 305 }
 306 %    \end{macrocode}
 307 %
 308 % How to raise an error.  Not so difficult.
 309 %
 310 %    \begin{macrocode}
 311 \def\mk@err#1{%
 312   \PackageError{mdwkey}{Key `#1' not found in group `\mk@group'}{%
 313     I've never heard of the key you tried to set.  I'm going to ignore it.
 314   }
 315 }
 316 %    \end{macrocode}
 317 %
 318 % \end{macro}
 319 %
 320 % \subsection{Defining keys}
 321 %
 322 % \begin{macro}{\mkdefkey}
 323 %
 324 % This is all quite dull, really.  I tried to merge the two cases, but it
 325 % failed because I can't pass around macro parameter names through
 326 % |\@ifnextchar| and their friends.  If anyone has any bright ideas, I'd be
 327 % delighted.
 328 %
 329 %    \begin{macrocode}
 330 \def\mkdef{\@ifstar\mkdef@star@\mkdef@}
 331 \def\mkdef@#1#2{%
 332   \@ifstar%
 333     {\mkdef@ii{#1}{#2}}%
 334     {\@ifnextchar[%
 335       {\mkdef@iii{#1}{#2}}%
 336       {\mkdef@i{#1}{#2}}}%
 337 }
 338 \def\mkdef@i#1#2{\@namedef{mk$#1$=#2}##1}
 339 \def\mkdef@ii#1#2{\@namedef{mk$#1$!#2}}
 340 \def\mkdef@iii#1#2[#3]{%
 341   \toks@{#3}%
 342   \expandafter\edef\csname mk$#1$!#2\endcsname%
 343     {\expandafter\noexpand\csname mk$#1$=#2\endcsname{\the\toks@}}%
 344   \@namedef{mk$#1$=#2}##1%
 345 }
 346 \def\mkdef@star@#1{%
 347   \@ifstar%
 348     {\mkdef@star@ii{#1}}%
 349     {\@ifnextchar[%
 350       {\mkdef@star@iii{#1}}%
 351       {\mkdef@star@i{#1}}}%
 352 }
 353 \def\mkdef@star@i#1{\@namedef{mk$#1$*=}##1##2}
 354 \def\mkdef@star@ii#1{\@namedef{mk$#1$*!}##1}
 355 \def\mkdef@star@iii#1[#2]{%
 356   \toks@{#2}%
 357   \expandafter\edef\csname mk$#1$*!\endcsname##1%
 358     {\expandafter\noexpand\csname mk$#1$*=\endcsname{##1}{\the\toks@}}%
 359   \@namedef{mk$#1$*=}##1##2%
 360 }
 361 %    \end{macrocode}
 362 %
 363 % \end{macro}
 364 %
 365 % And with that, we're done.
 366 %
 367 %    \begin{macrocode}
 368 %<+plain>\done
 369 %</package|macro>
 370 %    \end{macrocode}
 371 %
 372 % \hfill Mark Wooding, \today
 373 %
 374 % \Finale
 375 %
 376 \endinput