keyval2e 0.0.2 (26aug11)

git-svn-id: svn://tug.org/texlive/trunk@23698 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 107 insertions, 59 deletions

diff --git a/Master/texmf-dist/doc/latex/keyval2e/README b/Master/texmf-dist/doc/latex/keyval2e/README
index 960feb21869..93c794d5d15 100644
--- a/Master/texmf-dist/doc/latex/keyval2e/README
+++ b/Master/texmf-dist/doc/latex/keyval2e/README
@@ -2,7 +2,7 @@ This is the README file for the keyval2e package.
 
 VERSION
 
-Version 0.0.1a, August 2011
+Version 0.0.2, August 2011
 
 SUMMARY
 
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.pdf b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.pdf
new file mode 100644
index 00000000000..62ecefd3517
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.pdf
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex
index 6af05f802a4..a13274b3e20 100644
--- a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-examples.tex
@@ -1,39 +1,67 @@
-\documentclass{minimal}
+% keyval2e.sty examples, version 0.0.2, August 2011
+
+\documentclass{article}
 \usepackage{keyval2e,color}
 \makeatletter
 \kve@definekeys[KV]{fam}[mp@]{%
-  keyone/+/\ifstrcmpTF{#1}{+}{\def\userinput{#1}}{\def\userinput{???}},
+  keyone/+/\ifstrcmpTF{#1}{+}{\def\userinput{#1}}{\def\userinput{not `+'}},
   keytwo/+,
   keythree/+,
-  keyfour/+
+  keyfour/+,
+  keyfive/true/\ifmp@keyfive\def\x{keyfive is 'true'}\else
+    \def\x{keyfive is 'false'}\fi,
+  keysix/true
 }
+
+% \show\ifmp@keyfive
+
+% The starred variant of \kve@definekeys gives error for the
+% already defined key 'keyone':
+% \kve@definekeys*[KV]{fam}[mp@]{keyone/+}
+
+% Changing the family and macro-prefix makes 'keyone' definable again:
+\kve@definekeys*[KV]{famx}[mpx@]{keyone/+}
+
 \def\fourplus{+,+,+,+}
 \newcommand*\putmany[2][*]{%
-  \@tempcnta\z@
+  \begingroup
+  \toks@{}\@tempcnta\z@
   \loop
-  \advance\@tempcnta\@ne#1%
+  \advance\@tempcnta\@ne
+  \toks@\expandafter{\the\toks@#1}%
   \ifnum\@tempcnta<#2\relax
   \repeat
+  \expandafter\endgroup\the\toks@
 }
 \newcommand{\testa}[2]{%
   \kve@setafterdefaults[KV]{fam}{#2}%
   \edef\tempa{\mp@keyone,\mp@keytwo,\mp@keythree,\mp@keyfour}%
-  Test #1: \textcolor{red}{*} \texttt{\tempa} \textcolor{red}{*}%
-  \space\ifxTF\tempa\fourplus{All values are defaults\putmany[\space]{2}}%
-    {At least one value is set}%
-  \@spaces\textcolor{red}{||} keyone's value: \userinput
+  \noindent
+  \vbox{%
+    \hsize\dimexpr1.1\hsize\relax\leftskip=-1.5cm
+    \def\redstar{\textcolor{red}{*}}\ttfamily
+    Test #1: \redstar\space\texttt{\tempa}\space\redstar\space
+    \ifxTF\tempa\fourplus
+      {All values are defaults\putmany[\space]{2}}%
+      {At least one value is set}%
+    \@spaces\textcolor{red}{||} keyone's value: \userinput
+  }%
 }
 \newcommand{\testb}[2][]{\testa{#2}{#1}}
+
 \begin{document}
 
-\ttfamily\noindent
+\title{The \texttt{\color{blue}keyval2e} Package \\Examples}
+\maketitle
+
 \testa{Aa}{}\\
-\testa{Ba}{keyone=+,keythree=+}\\
-\testa{Ca}{keytwo=  +,keythree=a}\\
-\testa{Da}{keyone=b,keythree=a,keyfour=+}\\
+\testa{Ba}{keyone=+,  keythree=+}\\
+\testa{Ca}{keytwo=+,  keythree=a}\\
+\testa{Da}{keyone=b,  keythree=a,keyfour=+}\\
+
 \testb{Ab}\\
-\testb[keyone=  +,keythree=+]{Bb}\\
-\testb[keytwo=+,keythree=a]{Cb}\\
-\testb[keyone=b,keytwo=+,keythree=a]{Db}\\
+\testb[keyone=+,  keythree=+]{Bb}\\
+\testb[keytwo=+,  keythree=a]{Cb}\\
+\testb[keyone=b,  keytwo=+,keythree=a]{Db}\\
 
 \end{document} 
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf
index fc2af6ccbc2..61a4720964f 100644
--- a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.pdf
diff --git a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex
index d0c7e7898d0..99883c7d157 100644
--- a/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex
+++ b/Master/texmf-dist/doc/latex/keyval2e/keyval2e-guide.tex
@@ -20,12 +20,11 @@
 \begin{frontmatter}
 \title{The \texttt{\color{blue}keyval2e} Package\titleref{t1}}
 \titlenotes[t1]{%
-  The package is available at \iftogTF{pdf}{\url{\@titleurl}}
-  {\url{\@shorttitleurl}}. This user manual corresponds to version~0.0.1a.
+  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/}
-\shorttitleurl{http://www.ctan.org/}
 \author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}
 
 \end{frontmatter}
@@ -35,14 +34,17 @@
 \end{xwmshade}
 
 
-\docsection{Introduction}
+\docsection(sec:introduction){Introduction}
 
-The \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.
+\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}, ordinary, 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 the current values after those without current values have been initialized/set with their default values}. Normally, keys are set with the re-entrant command \fx{\kve@setkeys}.
+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}.
 
-The \pkg'{keyval2e} has no service 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.
+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.
 
@@ -54,20 +56,24 @@ 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(defa-1)/|A(callback-1),
+  |A(key-1)/|A(dft-1)/|A(cbk-1),
   ...,
-  |A(key-n)/|A(defa-n)/|A(callback-n)
+  |A(key-n)/|A(dft-n)/|A(cbk-n)
 }
 
 \kve@definekeys|*[|A(pref)]{|A(fam)}[|A(mp)]{%
-  |A(key-1)/|A(defa-1)/|A(callback-1),
+  |A(key-1)/|A(dft-1)/|A(cbk-1),
   ...,
-  |A(key-n)/|A(defa-n)/|A(callback-n)
+  |A(key-n)/|A(dft-n)/|A(cbk-n)
 }
 
-\kve@setkeys[|A(pref)]{|A(fam)}[na]{|A(keyval)}
+\kve@setkeys[|A(pref)]{|A(fam)}[|A(na)]{|A(keyval)}
 
 \kve@setdefaults[|A(pref)]{|A(fam)}[|A(na)]
 
@@ -75,22 +81,24 @@ The \pkg'{keyval2e} currently has no options.
 \finish{newmacro}
 \fxim*{\kve@definekeys,\kve@setkeys,\kve@setdefaults,\kve@setafterdefaults}
 
-Here, \ang{pref} is the optional key prefix (default \fx{KV}), \ang{fam} is the mandatory family, \ang{mp} is the key-value-holding macro prefix (default \fx{kvmp@}), \ang{defa-i} is the default value of key \quotedfx{i}, \ang{callback-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.
+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}. Moreover, there are no \quoted{undefined key handlers} and no \quoted{handled keys} in this package. Please see the \pkg'{ltxkeys} for these facilities.}. \mpkey will hold the current value of \ang{key}. The key macro (\ie, the one that holds the key's callback) is always \preffamkey.
+\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 \fx{#1} in \ang{callback} to access the 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{callback}.
+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 \boolset) 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}.
+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, and it is useful to have a handy way of accomplishing this semi-automatically.
+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{Utility macros}
+\docsubsection(sec:utilities){Utility macros}
 
 The following macros are utilities.
 
@@ -99,20 +107,22 @@ The following macros are utilities.
 \finish{newmacro}
 \fxim*{\kve@checkchoice}
 
-The \ang{nominations} have the syntax
+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(callback-1),...,|A(nom-n)|R(:)|A(callback-n)
+|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{callback}. \ang{callback-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.
+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 \boolset. If \ang{val} is valid, the text \ang{true} will be executed; otherwise \ang{false} will be executed.
+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
@@ -122,46 +132,52 @@ This checks if \ang{val} is an admissible value of a boolean, namely, if it is i
 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{Examples}
+\docsection(sec:examples){Examples}
 
 \start{example}[\kve@definekeys]
 |R(\kve@definekeys)[KV]{fam}[mp@]{%
-  |com(keya and keyb are boolean keys:)
-  keya/true/|R(\kve@checkbool){#1}{\def\result{OK}}{|R(\kve@keyvalerr)},
-  keyb/false/|R(\kve@checkbool){#1}{%
-      \usename{@tempswa#1}%
-      \if@tempswa\def\x{found}\else\def\x{not-found}\fi
-    }{%
-      \kve@keyvalerr
-    },
+  |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)},
-  keyd/right/\def\x##1{#1xx##1},
-  |com(keyone has an empty default value:)
-  keyone//\ifx\\#1\\\def\x{no-val}\else\def\x{#1}\fi,
+  |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}/|R(\kve@setkeys)[KV]{fam}{keyone=#1}
+  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}.
 
-The following command says \quoted{set the current keys with their current values, after the defaults have been set up}. Keys with current values will not be set with their default values:
+\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 the example file for the fuller version of the following 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
-|R(\kve@definekeys)[KV]{fam}[mp@]{%
+\kve@definekeys|*[KV]{fam}[mp@]{%
   keyone/+,
   keytwo/+,
   keythree/+,
@@ -188,11 +204,15 @@ Please see the example file for the fuller version of the following example:
 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.1}{2011/08/13}
-  \item First public release.\vsecref*
+  \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*
+  \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}