path: root/macros/latex/contrib/keyval2e/keyval2e-guide.tex

\documentclass[
  use-a4-paper,
  use-10pt-font,
  final-version,
  use-UK-English,
  fancy-section-headings,
  frame-section-numbers,
  para-abstract-style,
  input-config-file,
  no-hyperref-messages
]{amltxdoc}

\hfuzz1pt
\makeatletter
\WrapQuotes
\makeindex

\begin{document}

\begin{frontmatter}
\title{The \texttt{\color{blue}keyval2e} Package\titleref{t1}}
\titlenotes[t1]{%
  The package is available at \url{\titleurltext}. This user manual
  corresponds to version~0.0.2.
}
\subtitle{Robust and fast key parser}
\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/keyval2e/}
\author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}

\end{frontmatter}

\begin{xwmshade}[fillcolor=white,framecolor=orange,framerule=1pt,framesep=2pt,
  width=1.0\hsize]\tableofcontents
\end{xwmshade}


\docsection(sec:introduction){Introduction}

\lletter{T}{he \pkg'{keyval2e}} provides lightweight and robust facilities for creating and managing keys. Its machinery isn't as extensive as that of, \eg, \pkg'{ltxkeys} but it is equally robust. Ease of use and speed of processing are the two main motives of this package. Some, indeed many, applications of the key-value syntax (while they call for robustness) don't require the full armor of key-value processing as found in, \eg, the \pkg'{ltxkeys}. This package was prompted by a subscriber's post on \comptexttex in August 2011.

In the \pkg'{keyval2e}, command, boolean, and choice keys can be created using only one command (\fx{\kve@definekeys}). Keys can be initialized with their default values (with the command \fx{\kve@setdefaults}) as soon as they are created, or at any time. And in any run the default values of keys can be used to set keys that have no current values. The latter task is accomplished by the command \fx{\kve@setafterdefaults}, meaning \quoted{set keys with their current user-supplied values after the absent keys (\ie, those without current values) have been initialized/set with their default values}.

Keys can be set with the re-entrant command \fx{\kve@setkeys}, but this will not automatically set up the absent keys (\ie, keys not submitted to the command in its current run) with their default values. To set keys up with their default values, the user has to call \fx{\kve@setdefaults} or \fx{\kve@setafterdefaults}.

The \pkg'{keyval2e} has no provision for processing package or class options. See the \pkg'{ltxkeys} for this service. I have seen users who require the services of keys only in documents, and not in package or class files. And some package authors still use \latex's native option processing schemes. For those authors, the \pkg'{keyval2e} may be used to process keys (but not options) in package and class files. Since the \pkg'{catoptions} is loaded by the \pkg'{keyval2e} and the former has a robust and extensive options parsing scheme, it may be used for the options processing requirements of the user.

The \pkg'{keyval2e} provides handy tools for creating commands based on the infrastructure of keys. See the file \file{keyval2e-examples} for examples. The so-called \quoted{key commands} (see \pkg'{keycommand, skeycommand}) can be created rather easily with the facilities of this package.

The \pkg'{keyval} provides a simple and widely used interface, but it is not robust, in the sense that it strips off outer curly braces in key values. Also, it has no means to automatically call up default key values after the keys have been defined. Moreover, it automatically redefines existing keys.


\docsection{Package options}

The \pkg'{keyval2e} currently has no options.


\docsection{User commands}

As previously mentioned in \amref{sec:introduction}, the \pkg'{keyval2e} can be used to directly define only command and boolean keys. Choice keys can, however, be created indirectly as command keys by using the \fx{\kve@checkchoice} command (see \amref{sec:utilities}). For the user, the only difference between command and ordinary keys is that command keys define macros to hold the user input, making command keys more attractive than ordinary keys.

The only key-defining command in this package is \fx{\kve@definekeys}. This command distinguishes a boolean key from command keys by the default value of the boolean key. Therefore, all boolean keys must have default values in the set \fnz*{true,false}, otherwise they will be treated as command keys. Command keys may have no default values and no callbacks.

\start+{newmacro}[\kve@definekeys, \kve@setkeys, etc]
\kve@definekeys[|A(pref)]{|A(fam)}[|A(mp)]{%
  |A(key-1)/|A(dft-1)/|A(cbk-1),
  ...,
  |A(key-n)/|A(dft-n)/|A(cbk-n)
}

\kve@definekeys|*[|A(pref)]{|A(fam)}[|A(mp)]{%
  |A(key-1)/|A(dft-1)/|A(cbk-1),
  ...,
  |A(key-n)/|A(dft-n)/|A(cbk-n)
}

\kve@setkeys[|A(pref)]{|A(fam)}[|A(na)]{|A(keyval)}

\kve@setdefaults[|A(pref)]{|A(fam)}[|A(na)]

\kve@setafterdefaults[|A(pref)]{|A(fam)}[|A(na)]{|A(keyval)}
\finish{newmacro}
\fxim*{\kve@definekeys,\kve@setkeys,\kve@setdefaults,\kve@setafterdefaults}

Here, \ang{pref} is the optional key prefix (its default is \fx{KV}), \ang{fam} is the mandatory family, \ang{mp} is the key-value-holding macro prefix (its default is \fx{kvmp@}), \ang{dft-i} is the default value of key \quotedfx{i}, \ang{cbk-i} is the callback (\ie, the function that will be executed when the key is set) of key \quotedfx{i}, and \ang{keyal} is a list of \keyval pairs.

\ang{na} is a comma-separated list of keys that should be ignored, ie, not set in the current run of setting keys\footnote{When setting keys, undefined keys are reported by the \pkg'{keyval2e} as undefined and are not saved as \quoted{remaining keys}, unlike in the \pkg'{ltxkeys}. Moreover, there are no \quoted{undefined key handlers} and no \quoted{handled keys} in this package. Please see the \pkg'{ltxkeys} for these features.}. \mpkey will hold the current value of \ang{key}. The key macro (\ie, the macro that holds the key's callback) is always \preffamkey.

The \stform of the command \fx{\kve@definekeys} will define only definable keys, in the sense of \latex's \hx{\newcommand}. In that case the commands \mpkey must also be unique, \ie, not previously defined. The plain form \fx{\kve@definekeys} will always define the key, whether or not the key already exists; existing keys will thus be overwritten in this case.

You can use \quotedfx{#1} in \ang{cbk} to access the user-supplied value of the current key. Also the macros \ffx'{\currpref, \currfam, \currkey, \currval, \currkeyval} are always available when setting keys and may be called in \ang{cbk} at key definition time.

\Note The list parser for the command \fx{\kve@definekeys} is \qcomma. Hence, if you have literal comma in \ang{cbk}, the \ang{cbk} has to be enclosed in curly braces. Leading and trailing spaces in the elements are removed in the internal processing. Explicit spaces (\ie, those needed by the key user) will therefore need to be wrapped in curly braces.

The command \fx{\kve@setdefaults} will set all the keys in the given family \ang{fam} and prefix \ang{pref} with their default values. All boolean keys (\ie, those with a default in the set \fnz*{true,false}) will be initialized with a default value of \fx{false}. This is to avoid premature toggling of the state of such keys. The command \fxis{\kve@setwithdefaults}{\kve@setdefaults} is an alias for \fx{\kve@setdefaults}.

\Note After the keys have been defined, they are automatically set with their default values using the command \fx{\kve@setdefaults}. This provides default definitions for immediate use.

The command \fx{\kve@setafterdefaults} will set the given \keyval pairs after initializing to default values all those keys (in the given family and prefix) that are not listed in the accompanying \keyval list. This provides a mechanism for (re)initialing to default values those keys that don't have values in \keyval. This type of (re)initialization is often required in the deployment of keys---since the immediate past user values of the keys may no longer be valid. It is useful to have a handy way of accomplishing this task semi-automatically.


\docsubsection(sec:utilities){Utility macros}

The following macros are utilities.

\start{newmacro}[\kve@checkchoice]
\kve@checkchoice{|A(teststring)}{|A(nominations)}{|A(nomatch)}
\finish{newmacro}
\fxim*{\kve@checkchoice}

The expandable command \fx{\kve@checkchoice} can be used to create choice keys as command keys. The \ang{nominations} have the syntax

\start'{macro}[Nominations and callbacks]
|A(nom-1)|R(:)|A(cbk-1),...,|A(nom-n)|R(:)|A(cbk-n)
\finish{macro}

Here, please note the \qcolon, which separates \ang{nom} from \ang{cbk}. \ang{cbk-i} will be executed if \ang{nom-i} matches \ang{teststring}. The first match found takes priority over subsequent matches. The fallback \ang{nomatch} will be executed if \ang{teststring} doesn't match any of the \ang{nom}'s.

\start{newmacro}[\kve@checkbool]
\kve@checkbool{|A(val)}{|A(true)}{|A(false)}
\finish{newmacro}
\fxim*{\kve@checkbool}

This checks if \ang{val} is an admissible value of a boolean, namely, if it is in the set \fnz*{true,false}. If \ang{val} is valid, the text \ang{true} will be executed; otherwise \ang{false} will be executed.

\Note The user-supplied values of all boolean keys are automatically checked by this command. Hence, the user doesn't have to call this command repeatedly to confirm the validity of values of boolean keys.

\start{newmacro}[\kve@keyvalerr]
\kve@keyvalerr
\finish{newmacro}
\fxim*{\kve@keyvalerr}

This is a parameterless command that uses \ffx'{\currkey,\currval} internally. It simply generates an error to indicate that the current value of a key is invalid. It will indicate the key name and the truncated version of the key value that is invalid.


\docsection(sec:examples){Examples}

\start{example}[\kve@definekeys]
|R(\kve@definekeys)[KV]{fam}[mp@]{%
  |com(keya and keyb are boolean keys. They will call \kve@checkbool)
  |com(internally to check the user input for them. keya has no callback:)
  keya/true,
  keyb/false/\ifmp@keyb\def\x{found}\else\def\x{not found}\fi,
  |com(keyc is a choice key:)
  keyc/left/|R(\kve@checkchoice){#1}{left:\let\x\flushleft,
    right:\let\x\flushright}{|R(\kve@keyvalerr)},
  |com(keyd has no default. Therefore, it can't be set without a user value.)
  |com(In |fx(\kve@setdefaults) we set it with a default value of `empty', but)
  |com(its user must always provide a value for it:)
  keyd,
  |com(keyone has an empty default value. This doesn't mean `no default':)
  keyone//\ifnullTF{#1}{\def\x{empty}}{\def\x{#1}},
  |com(keytwo has no callback:)
  keytwo/+,
  |com(keythree has a braced default value:)
  keythree/{left}/\def\y##1{`para-scientific gobbledegook' ##1},
  |com(keyfour sets keyone |(see |amref(nte:reentrance)|):)
  keyfour/left/|R(\kve@setkeys)[KV]{fam}{keyone=#1},
}
\finish{example}

Remember that after the keys have been defined, they are automatically set with their default values using the command \fx{\kve@setdefaults}.

\begin{note}
\label{nte:reentrance}
The type of re-entrance staged by key \fx{keyfour} above should in general be done with care, otherwise you could end up with infinite re-entrance. Therefore, the package sets a re-entrance limit of 4, to alert the user to the probability that an infinite loop has been created by him in using \fx{\kve@setkeys}. In the unlikely event that you need to exceed this limit, then please turn to the \pkg'{ltxkeys}.
\end{note}

The following command says \quoted{set the given keys with their current values, after the absent keys of the given family and prefix have been set up with their default values}. Keys with current values will not be set with their default values:

\start{example}[\kve@setafterdefaults]
\kve@setafterdefaults[KV]{fam}{keyone=+,keytwo=abc,keythree=+,keyfour=xax}
\finish{example}

Please see \file{keyval2e-examples} for the fuller version of the following example:

\start+{example}[Creating a key command]
\documentclass{minimal}
\usepackage{keyval2e}
\makeatletter
\kve@definekeys|*[KV]{fam}[mp@]{%
  keyone/+,
  keytwo/+,
  keythree/+,
  keyfour/+
}
\def\fourplus{+,+,+,+}
\newcommand{\test}[2]{%
  |R(\kve@setafterdefaults)[KV]{fam}{#2}%
  \edef\tempa{\mp@keyone,\mp@keytwo,\mp@keythree,\mp@keyfour}%
  Test #1: *\texttt{\tempa}*%
  \ifxTF\tempa\fourplus{All values are defaults}{At least one value is set}%
}
\begin{document}
\ttfamily\noindent
\test{A}{}\\
\test{B}{keythree=+}\\
\test{C}{keythree=a}\\
\end{document}
\finish{example}


\docsection(sec:version-hist){Version history}

The \stsign on the right-hand side of the following lists means the subject features in the package but is not reflected anywhere in this user guide.

\begin{versionhist}
  \begin{version}{0.0.2}{2011/08/22}
  \item Automatically call \fx{\kve@checkbool} when setting boolean keys \vsecref{sec:utilities}
  \item Raise error for keys that have no user input and no default value \vsecref{sec:examples}
  \end{version}
  \begin{version}{0.0.1a}{2011/08/14}
  \item Completed the user guide\vsecref*
  \end{version}
  \begin{version}{0.0.1}{2011/08/13}
  \item First public release\vsecref*
  \end{version}
\end{versionhist}

\newpage
\indexpreamble{Index numbers refer to page numbers.}
\indexpreambleformat{\centering}
\indexcolumns\tw@
\printindex

\end{document}