# The keyreader package

A robust interface to xkeyval package

Ahmed Musa

# Abstract

The keyreader package provides robustness and some extensions to the xkeyval package. It preserves braces in key values throughout parsing and saves estate when defining keys. Also, the command \(\backslash\)kredsteys allows unbalanced conditionals to be parsed as values of keys. Furthermore, when the command \(\backslash\)kreddefinekeys is used, keys are initialized as soon as they are defined, and, unlike in the xkeyval package, admissible alternate values of choice keys can have individual callbacks. The looping macros of the xkeyval package are redefined, to increase robustness. The command \(\backslash\)define@key of the xkeyval package has had two of its subordinate commands redefined, to offset a complaint about the grabbing of the key's callback when defining keys with \(\backslash\)define@key. This user manual assumes that the reader is familiar with some of the functions and user interfaces of the xkeyval package.

This work (i. e., all the files in the keyreader package bundle) may be distributed and/or modified under the conditions of the LaTeX Project Public License (LCPL), either version 1.3 of this license or any later version.

The LCPL maintenance status of this software is 'author-maintained.' This software is provided 'as it is,' without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

The keyreader package predated the ltxkeys package and was developed to make key parsing by the xkeyval package robust (in the sense of preserving outer braces in key values throughoutparsing and enabling the parsing of key values with unbalanced conditionals), as well as reduce the amount of typing that is required for defining several keys. To achieve robustness in key parsing, the \setkeys command of the xkeyval package has been patched and renamed \krdsetkeys. The xkeyval package's \setkeys remains unchanged, to avoid breaking existing codes that rely on it's current form. Some other low-level commands of xkeyval package have been patched and renamed. The keyreader package provides commands for compactly defining and setting all types of key (ordinary, command, boolean, and choice). Also, the keyreader package introduces the concept of callbacks for the alternate/admissible values of choice keys defined via the command \krddefinekeys. Moreover, when \krddefinekeys is used, keys are automatically set/initialized as soon as they are defined. This provides default definitions for the key macros and functions. Boolean keys are initialized with a value of false irrespective of their default values.

The keyreader package has been used as a development platform for the ltxkeys package because the xkeyval package, on which the keyreader package is based, has been quite stable for some years, its inherent shortcomings not withstanding. Has the user ever tried to pass to xkeyval package's \setkeys an unbalanced conditional as the value of a key? He/she will quickly be hit by the error message! Incomplete \ifx; all text was ignored after line...,' or something similar. This limitation has been removed by the keyreader package.

The syntax for defining keys is:

New macro: \krddefinekeys

\krddefinekeys*[(kprefix)]{\(\kfamily)}[(mprefix)]{(keylist)}

The optional \(\kprefix\) and mandatory \(\kfamily\) have unambiguous connotations. The optional \(\kprefix\) is the macro prefix, in the parlance of the xkeyval package. The default values of \(\kprefix\) and \(\kprefix\) are KRD and krdmp@, respectively.

In the case of ordinary, command and boolean keys, \(\keylist\) has the syntax

\[\{\] Syntax of key keylist

\[\{\] \[\langle\)keytype-1\(\rangle/\langle\)keyname-1\(\rangle/\langle\)default-1\(\rangle/\langle\)callback-1\(\rangle\); \[\langle\)keytype-2\(\rangle/\langle\)keyname-2\(\rangle/\langle\)default-2\(\rangle/\langle\)callback-2\(\rangle\); \[\ldots\] \[\langle\)keytype-n\(\rangle/\langle\)keyname-n\(\rangle/\langle\)default-n\(\rangle/\langle\)callback-n\(\rangle\); \[\}\}\]

The list parser for \(\langle\)keylist\(\rangle\) is invariably semicolon ';'. Hence, if the user has semicolon ';' in \(\langle\)callback\(\rangle\), it has to be wrapped in curly braces, to hide it from TeX's scanner. \(\langle\)keytype\(\rangle\) can be any member of the list \(\{\)ord (ordinary key), cmd (command key), bool (boolean key), choice (choice key)\(\}\).

For choice keys, \(\langle\)keylist\(\rangle\) has the syntax

\[\{\] Syntax of key keylist

\[\langle\)keytype-1\(\rangle/\langle\)keyname-1\(\rangle/\langle\)default-1\(\rangle/\langle\)alt\(\rangle/\langle\)callback-1\(\rangle\);10 \keytype-2)/\keyname-2)/(default-2)/\at)/(callback-2);
11...
12 \keytype-n)/\keyname-n)/(default-n)/(alt)/(callback-n);
13 } ```
The _alternate values_ (also called _nominations_ or _admissible list of user input_) \alt) has the syntax
```
1{value-1).do=(callback-1),
13 (value-2).do=(callback-2),
14...
15 (value-n).do=(callback-n), ```
The list parser in this case is invariably comma ','.

The star (\(\star\)) sign on \krddefinekeys is an optional suffix. If it is present, then only definable (i. e., non-existent) keys will be defined. The existence of a key depends on \kprefix) and \kfamily), since keys are name-spaced.

**Note 2.1**: Choice keys defined by \krddefinekeys are of the starred (\(\star\)) variant of choice keys (see the xkeyval package guide). Hence they will always convert the user input into lowercase before matching it against the alternate/admissible list of values specified at key definition time. The matching, as done by \krdsetkeys, is catcode-agnostic.

### Setting keys

The command \krdsetkeys is a more robust counterpart of the xkeyval package's \setkeys, in the sense that it preserves all outer braces in the values of keys and allows the parsing of key values with unbalanced conditionals. The new command \krdsetkeys has the same syntax as the original \setkeys of the xkeyval package, namely
```
1{krdsetkeys++[(kprefix)]{{families}}{(na)}{(\key)={value}}} ```

As usual, the star (\(\star\)) and plus sign (\(\star\)) are optional suffixes. The starred (\(\star\)) variant will save all undeclared keys in the list \kKY@rm, possibly for setting later with the command \setrmkeys, and will not report any unknown key as undeclared. The plus (\(\star\)) variant will set the given keys in all the given families, instead of in just one family. The combination \++ will set the listed keys in all the given families and append unknown keys to the container \kKY@rm. \na is the list of keys that shouldn't be set in the current run.

The command \krdsetkeys isn't exactly xkeyval package's \setkeys, since the former is more robust and avoids the selective sanitization of \key=\value list that is done by \setkeys. The macro \krdsetkeys 'normalizes' the \key=\value or comma-separated key list. Therefore, users of the keyreader package should always call the command \krdsetkeys instead of \setkeys. Both have the same user interface. The \setkeys command of the xkeyval package's remains unchanged.

The xkeyval package's command \setrmkeys, which sets'remaining keys,' has also been modified to \krdsetrmkeys, while keeping \setrmkeys unchanged. Users of the keyreader package should use \krdsetrmkeys in place of \setrmkeys.



\rule[-\dp0]{wd0}{the\dimexpr\ht0+\dp0\relax}%
10\llap{\raisebox{\hashdowsize}}{box0\hskip\hashdowsize}}%
10\endgroup
10\hspace{-1mm}
11\makeatother
11\begin{document}
11\ebox{ebox[ebox1]}
11\ebox{framecolor=gray,boxsize=2cm,align=right}[ebox2]
11\ebox{shadow=false,boxsize=1.5cm,align=left}[ebox3]
11\ebox{framecolor=gray,size=1pt,framecolor=gray,shadowcolor=blue}[ebox4]
11\ebox{box{frame=false,shadow,shadowcolor=yellow,framesize=.5pt]{ebox5}
11\end{document}} ```

Figure 1: Output of example 2.3

The command \krddisablekeys has the same use syntax as the \disable@keys command of the xkeyval package, but will issue an error (instead of a warning) when an attempt is made to set a disabled key.

The commands \krdDeclareOption, \krdExecuteOptions and \krdProcessOptions are aliases for \DeclareOptionX, \ExecuteOptionsX and \ProcessOptionsX of the xkeyval package.

## 3 Version history

The following change history highlights significant changes that affect user utilities and interfaces; changes of technical nature are not documented in this section.

**Version 0.4b[2012/01/14]**

The command \krdsetkeys can now parse key values with unbalanced conditionals.

**Version 0.4a[2011/12/23]**

The key list in \krddefinekeys shouldn't have been normalized with respect to forward slash (/).

**Version 0.4[2011/12/20]**

Several of the former functions of the package have been transferred to the ltxkeys package with even more robustness. The package now provides mainly a compact and robust interface to the features of the xkeyval package.

**Version 0.3[2011/03/26]**

Bug fix.

**Version 0.2**: [2011/02/25]

The interface for defining new keys now accepts conditionals in key macros/functions.

A mechanism is provided for automatic setting up and execution of key functions with default key values.
**Version 0.1**: [2010/01/10]

First public release.

