summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex')
-rw-r--r--Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex262
1 files changed, 185 insertions, 77 deletions
diff --git a/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex b/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex
index b32563b1091..80ce3f8eb08 100644
--- a/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex
+++ b/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex
@@ -18,8 +18,6 @@
\AfterAfterStartOfDocument{%
\def\amd@sectitlefmt{\centering\Large\sffamily\color{secheadcolor}}%
}
-\useshortdoccmds
-\usepackage{ltxtools-review}
\let\footnote\ltsfootnote
\extrarowheight=2pt
\arrayrulecolor{yellow}
@@ -30,18 +28,17 @@
\title{The \texttt{\color{blue}ltxkeys} Package\titleref{t1,t2}}
\titlenotes[t1,t2]{%
The package is available at \url{\titleurltext}.\sep
- This user manual corresponds to version~0.0.2 of the package.
+ This user manual corresponds to version~0.0.3 of the package.
}
\subtitle{A robust key parser}
\titleurl{http://mirror.ctan.org/macros/latex/contrib/ltxkeys/}
\author{Ahmed Musa\authorref{a1,a2}}
\authornotes[a1,a2]{%
- University of Central Lancashire, Preston, UK.\sep
+ The University of Central Lancashire, Preston, UK.\sep
Email address for all \pkg'{ltxkeys} related matters: \email{amusa22@gmail.com}.
}
\end{frontmatter}
-
\hrule
\vskip 1ex plus 1pt minus 1pt
\begingroup
@@ -50,34 +47,44 @@
\endgroup
\hrule
-\deffootnote{1}{%
+\ltsnewfootnote{1}{%
Because of the multitude of functions provided by the \pkg'{ltxkeys}, it may actually slow down when executing some tasks, depending on the task at hand. The package option \fx{tracingkeys}, for example, does slow down processing. And automatically initiating keys after definition, as done by the commands \ffx'{\ltxkeys@definekeys, \ltxkeys@declarekeys}, also affects processing speed; so does \quoted{launching keys}, which first presets absent keys with their default values before setting the current keys (\ie, keys whose values are provided by the user at the moment of setting keys that belong to a family). Then, as in the \pkg'{xkeyval}, there are the commands for presetting and post-setting keys.
}
-\deffootnote{2}{%
+\ltsnewfootnote{2}{%
Options are also keys, but (from the user's viewpoint) there might be a need to treat options separately when dealing with unknown keys.
}
\docsection(sec:intro){Introduction}
-\lletter{T}{he \pkg'{ltxkeys}} provides facilities for creating and managing keys in the manner of the \pkg'{keyval, xkeyval}, but it is intended to be more robust and faster than these earlier packages. Its robustness emanates from, inter alia, its ability to preserve braces in key values throughout parsing. The need to preserve braces in key values without expecting the user to double braces emerges often in parsing keys. This is the case in, \eg, the \pkg'{xwatermark}, but consider also the possibility of passing all the following options to a package at once, where \quotedtt{layout} is a package or class option or key\footnote{It should be noted that if a value of the demonstrative option \fx{layout} is expandable, then the option can't be passed by \hx{\documentclass} without preloading a robust options parser like \pkg{kvoptions-patch, xkvltxp, catoptions}, or \pkg{ltxkeys} package. The \pkg'{ltxkeys}, unlike the \pkg'{xkeyval}, can be loaded before \hx{\documentclass}.}:
+\lletter{T}{he \pkg'{ltxkeys}} provides facilities for creating and managing keys in the manner of the \pkg'{keyval, xkeyval}, but it is intended to be more robust and faster than these earlier packages. Its robustness emanates from, inter alia, its ability to preserve braces in key values throughout parsing. The need to preserve braces in key values without expecting the user to double braces emerges often in parsing keys. This is the case in, \eg, the \pkg'{xwatermark}, but consider also the possibility of passing all the following options to a package at once, where \quotedtt{layout} is a package or class option or key\footnote{It should be noted that if a value of the demonstrative option \fx{layout} is expandable, then the option can't be passed by \hx{\documentclass} without preloading a robust options parser like \pkg{kvoptions-patch, xkvltxp, catoptions}, or \pkg{ltxkeys} package. In fact, \latex's native options processor can't handle options with values. The \pkg'{ltxkeys}, unlike the \pkg'{xkeyval}, can be loaded before \hx{\documentclass}.}:
-\start'{example}[Braced options]
+\start'{example}[Braced option values]
\pkgoptions{%
opt1=val1,opt2=val2,
layout={left=3cm,right=3cm,top=2.5cm,bottom=2.5cm,include=true}
}
\finish{example}
+As a practical example, the \pkg'{amtools} has the command \fx{\amloadmodules} with the syntax
+
+\start'{example}[Braced key values]
+\amloadmodules{|A(base)}{|A(modules)}
+\finish{example}
+
+where \ang{modules} is a comma-separated \keyval list. Like the above \quotedtt{layout} option, each key of \fx{\amloadmodules} may have a value (representing module options) that is itself a comma-separated \keyval list.
+
+Well, the type of robustness described here isn't actually difficult to implement within the \pkg'{xkeyval}. This is indeed what the \pkg'{combokeys} does: it patches some commands of the \pkg'{xkeyval} to achieve this robustness. That said, we have to indicate that the \pkg'{ltxkeys} implements this robustness intrinsically and it has many more features than the \pkg{xkeyval} and \pkg{combokeys} packages.
+
The \pkg'{ltxkeys} is faster\usefootnote{1} than the \pkg'{xkeyval} mainly because it avoids character-wise parsing of key values (which is called \quoted{selective sanitization} by the \pkg'{xkeyval}). Moreover, it is faster to normalize a comma-separated or \keyval list than trim leading and trailing spaces of each element of the list (as the \pkg'{xkeyval} does), since not all the elements of the list will normally have leading and trailing spaces. In fact, the chances are that only less than 50 percent of the elements of the list will have such spaces. As another example of optimization, anyone familiar with the implementation of the \pkg'{xkeyval} would have noticed that the macro \hx{\XKV@srstate}, which (in order to allow \hx{\setkeys} to be re-entrant) pushes and pops the states of some important functions in the package, loops over all the functions both when pushing and popping. In the \pkg'{ltxkeys}, pushing and popping functions together involve looping over the functions only once. And, unlike in the \pkg'{xkeyval}, higher order functions are undefined as soon as they are no longer needed, to avoid clogging up the stack. No additional looping is required for this.
In setting keys, the \pkg'{ltxkeys} loops over not only families, as in the \pkg'{xkeyval}, but also over key prefixes. The same strategy applies when the \pkg'{ltxkeys} tries to establish if a key is defined or not.
-While some user interfaces of the \pkg'{ltxkeys} are similar to those of the \pkg'{xkeyval}, there are important differences in several areas of syntax, semantics, and internal implementation. The \pkg'{ltxkeys} also provides additional facilities (beyond the \pkg'{xkeyval}) for defining and managing keys. Several types of keys (including ordinary keys, command keys, style keys, choice keys, boolean and biboolean keys) can be efficiently created and managed. In the \pkg'{ltxkeys}, the notions of \quoted{pre-setting} and \quoted{post-setting} keys are similar to those of the \pkg'{xkeyval}. But the \pkg'{ltxkeys} introduces additional concepts in this respect: \quoted{initialized} and \quoted{launched} keys. The latter are special preset keys. The pointer system of the \pkg'{xkeyval}, which was available only at key-setting time, is now also available at key definition time. One more type of pointer (\fx{\needvalue}) has been introduced to require users of \quoted{need-value keys} to supply values for those keys.
+While some user interfaces of the \pkg'{ltxkeys} are similar to those of the \pkg'{xkeyval}, there are important differences in several areas of syntax, semantics, and internal implementation. The \pkg'{ltxkeys} also provides additional facilities (beyond the \pkg'{xkeyval}) for defining and managing keys. Several types of keys (including ordinary keys, command keys, style keys, choice keys, boolean and biboolean keys) can be efficiently created and managed. In the \pkg'{ltxkeys}, the notions of \quoted{pre-setting} and \quoted{post-setting} keys are similar to those of the \pkg'{xkeyval}. But the \pkg'{ltxkeys} introduces additional concepts in this respect: \quoted{initialized} and \quoted{launched} keys. The latter are special preset keys. The pointer system of the \pkg'{xkeyval}, which was available only at key-setting time, is now available also at key definition time. One more type of pointer (\fx{\needvalue}) has been introduced to require users of \quoted{need-value keys} to supply values for those keys.
-Rather than simply issue an error for undefined keys when setting keys, the \pkg'{ltxkeys} provides the \quoted{undefined keys} and \quoted{undefined options} handlers, which are user-customizable. Other new concepts include \quotedlist{definable keys, cross-family keys, option keys, non-option keys, handled keys, pathkeys, key commands, key environments}, accessing the saved value of a key outside \hx{\setkeys} or similar commands, and declaring multiple keys (of all genre) using only one command.
+Rather than simply issue an error for undefined keys when setting keys, the \pkg'{ltxkeys} provides the \quoted{undefined keys} and \quoted{undefined options} handlers, which are user-customizable. Other new concepts include \quotedlist{definable keys, cross-family keys, option keys, non-option keys, handled keys, pathkeys, key commands, key environments}, accessing the saved value of a key outside \hx{\setkeys} or similar commands, and declaring multiple keys and options (of all genre) using only one command.
-It not advisable to alias the commands of the \pkg'{xkeyval} to the commands of the \pkg'{ltxkeys}. There are many existing packages that rely on the \pkg'{xkeyval} and aliasing commands that are used by other packages can cause confusion\footnote{A user of version~0.0.1 of the package had sought to do this.}.
+\ltsnote It is not advisable to alias the commands of the \pkg'{xkeyval} to the commands of the \pkg'{ltxkeys}. There are many existing packages that rely on the \pkg'{xkeyval} and aliasing commands that are used by other packages can cause confusion\footnote{A user of version~0.0.1 of the \pkg'{ltxkeys} had sought to do this.}.
\docsubsection{Motivation}
@@ -87,7 +94,7 @@ What are the \emph{raison d'etre} and origins of the \pkg'{ltxkeys}? Well, I dec
\docsection(sec:packageoptions)<package options>{Package options}
-The package options are listed in \sref{tab:pkgoptions}. The package options can be passed via \hhx{\documentclass, \RequirePackage} or \hx{\usepackage} as follows:
+The package options are listed in \sref{tab:pkgoptions}. The package options can be passed via \hx{\documentclass}\footnote{Passing \pkg'{ltxkeys} options via \hx{\documentclass} implies that the package is loaded after \hx{\documentclass}. As mentioned elsewhere, the \pkg'{ltxkeys} can be loaded before or after \hx{\documentclass}.}, \hx{\RequirePackage} or \hx{\usepackage} as follows:
\start{example}[Package options]
\documentclass[tracingkeys,keyparser={|nv},pathkeys]{article}
@@ -102,16 +109,16 @@ They can also be passed via the command \fx{\ltxkeys@options}:
\finish{newmacro}
\fxim*{\ltxkeys@options}
-\defltablenote{ltxkeys-1}{%
+\newltablenote{ltxkeys-1}{%
The speed of compilation may be affected by this option, but it is recommended at the pre-production stages of developing keys. The option provide some trace functionality and enables the user to, among other things, follow the progress of the \latex run and to see if a key has been defined and/or set/executed more than once in the current run. The \stform+ of the commands \ffx'{\ltxkeys@definekeys, \ltxkeys@declarekeys} will always flag an error if a key is being defined twice, irrespective of the state of the package option \fx{tracingkeys}. The \textltxkey variants (unlike the \textnewkey variants) of key-defining commands don't have this facility, and it may be desirable to know if and when an existing key is being redefined.
}
-\defltablenote{ltxkeys-2}{%
+\newltablenote{ltxkeys-2}{%
Wherever the \qsemicolon is indicated as a list parser in this guide, it can be replaced by any user-specified one character parser via the package option \fx{keyparser}. To avoid confusing the user-supplied parser with internal parsers, it is advisable to enclose the chosen character in curly braces. The braces will be stripped off internally. Please note that some of the characters that may be passed as a list parser may indeed be active; be careful to make them innocent before using them as a list/key parser. My advice is that the user sticks with the \qsemicolon as the key parser: the chances of it being made active by any package is minimal. If you have the chosen parser as literals in the callbacks of your keys, they have to be enclosed in curly braces.
}
-\defltablenote{ltxkeys-3}{%
+\newltablenote{ltxkeys-3}{%
The key-setting commands are \ffx'{\ltxkeys@setkeys,\ltxkeys@setrmkeys,\ltxkeys@setaliaskey}. If you must nest these commands beyond level~4, you have to raise the \fx{keydepthlimit} as a package option. The option \fx{keystacklimit} is an alias for \fx{keydepthlimit}.
}
-\defltablenote{ltxkeys-4}{%
+\newltablenote{ltxkeys-4}{%
The use of an empty prefix will normally result from explicitly declaring the prefix as \fx{[]}, rather than leaving it undeclared. Undeclared prefixes assume the default value of \fx{KV}. An empty family will result from submitting the family as empty balanced curly braces \fx{{}}. If keys lack prefix and/or family, there is a strong risk of confusing key macros/functions. For example, without a prefix and/or family, a key named \fx{width} will have a key macro defined as \fx{\width}, which portents sufficient danger.
}
@@ -130,7 +137,7 @@ They can also be passed via the command \fx{\ltxkeys@options}:
\endfoot
\hline
\endlastfoot
-\fx{tracingkeys} & \hx{false} & The global boolean switch that determines if information should be logged in the transcript for some tasks in the package. \useltablenote[tab:pkgoptions:note1]{ltxkeys-1}\\\hline
+\fx{tracingkeys} & \hx{false} & The global boolean switch that determines if information should be logged in the transcript file for some tasks in the package. \useltablenote[tab:pkgoptions:note1]{ltxkeys-1}\\\hline
\fx{keyparser} & \texttt{;} & The list parser used by some internal loops in defining keys.\useltablenote[tab:pkgoptions:note2]{ltxkeys-2}\\\hline
\fx{keydepthlimit} & \hx{4} & This is used to guard against erroneous infinite re-entrance of the package's key-setting commands. The default value of~4 means that neither of these commands can ordinarily be nested beyond level~4.\useltablenote[tab:pkgoptions:note3]{ltxkeys-3}\\\hline
\fx{reservenopath} & \hx{false} & The \quoted{path} (or roots or bases) of a key is the combination of key prefix, key family and macro prefix, but when dealing with \quoted{pathkeys} (see \sref{sec:pathkeys}) the term excludes the macro prefix. These can be reserved and unreserved by any user by the tools of \sref{sec:reservedpath}. Subsequent users can, at their own risk, override all previously reserved paths by enabling the package's boolean option \fx{reservenopath}.\\\hline
@@ -390,6 +397,8 @@ If \ang{alt} has \quotedfx{/.code} or \quotedfx{/} in it, then it is expected to
etc.
}
+|R(or)
+
{%
choice1|R(/)callback1|R(|A(keyparser))
choice2|R(/)callback2|R(|A(keyparser))
@@ -405,12 +414,14 @@ If the parser is \qsemicolon, then we would have
\start'{example}[Syntaxes of `nominations' for choice keys]
{choice1|R(/.code=)callback1; choice2|R(/.code=)callback2; etc.}
+|R(or)
+
{choice1|R(/)callback1; choice2|R(/)callback2; etc.}
\finish{example}
-This means that if you have \quotedfx{/.code} or \quotedfx{/} in any of the callbacks, it has to be enclosed in curly braces. Please recall that the default value of \ang{keyparser} is \qsemicolon. \fx{keyparser} is a package option. This syntax also implies that if you have the \ang{keyparser} in \ang{defn}, it has to be wrapped in curly braces. The \ang{keyparser} in this syntax could also be \qcomma.
+This means that if you have \quotedfx{/.code} or \quotedfx{/} in any of the callbacks, it has to be enclosed in curly braces! Please recall that the default value of \ang{keyparser} is \qsemicolon. \fx{keyparser} is a package option. This syntax also implies that if you have the \ang{keyparser} in \ang{defn}, it has to be wrapped in curly braces.
-\ltsnote Here is the rule for parsing the \ang{alt} list. First the package checks if the declared key parser (\ie, \ang{keyparser}) is in the \ang{alt} list. If the parser exists in \ang{alt}, then the list is parsed using this parser. Otherwise the list is parsed using comma as the parser. Moreover, the package checks if \quotedfx{.code} separates \ang{choice} from the callback \ang{cbk}. If no \quotedfx{.code} is found, then \quotedfx{/} is assumed to be the separator. But note that when there is no \ang{cbk}, then neither \quotedfx{.code} nor \quotedfx{/} is necessary.
+\ltsnote The \ang{keyparser} in these syntaxes of \quoted{nominations} for choice keys could also be \qcomma, without the need to declare the package option \fx{keyparser} as \qcomma. Here is the rule for parsing the \ang{alt} list. First the package checks if the declared key parser (\ie, \ang{keyparser}) is in the \ang{alt} list. If the parser exists in \ang{alt}, then the list is parsed using this parser. Otherwise the list is parsed using \qcomma as the parser. Moreover, the package checks if \quotedfx{.code} separates \ang{choice} from the callback \ang{cbk}. If no \quotedfx{.code} is found, then \quotedfx{/} is assumed to be the separator. But note that when there is no \ang{cbk} for a nomination, then neither \quotedfx{.code} nor \quotedfx{/} is necessary.
It is possible to refer to the current value of \ang{key} as \fx{#1} in \ang{alt}.
@@ -758,7 +769,7 @@ If the xfamily keys are all of the same type (\ie, only one of the types \fnz{or
|com(On setting `keya', `keyb' and `keyc' will be defined and initialized:)
\ltxkeys@setkeys[KV]{fam}{keya=left}
\finish{example}
-\aidx*{/.code=}
+\aidx*{/.code}
Here is a real-life example that mimics some of the macros of the \pkg'{xwatermark}:
@@ -928,9 +939,9 @@ Schemes like the following are disallowed, to avoid back-linking of \fx{\ltxkeys
\aidx*{key pointers}
\aidxs*{pointers}{key pointers}
-The \ffx'{\savevalue,\usevalue} pointers of the \pkg'{xkeyval} are still available at key setting time, but with increased robustness and optimization. Curly braces in values are preserved throughout, and instead of saving the value of each key tagged with \fx{\savevalue} in a separate macro, we save all such keys and their values in only one macro (for each combination of \ang{pref} and \ang{fam}) and use a fast search technique to find the values when they are needed later (by any key tagged with \fx{\usevalue}).
+The \ffx'{\savevalue,\usevalue} pointers of the \pkg'{xkeyval} are still available at key setting time, but with increased robustness and optimization. Curly braces in values are preserved throughout, and instead of saving the value of each key tagged with \fx{\savevalue} in a separate macro, we save all such keys and their values in only one macro (for each combination of \ang{pref} and \ang{fam}) and use a fast search technique to find the values when they are later needed (by any key tagged with \fx{\usevalue}).
-The pointer \fx{\needvalue} is a new type. It can be used by any key author to prompt the user of the key to always supply a value for the key. The pointers \ffx'{\savevalue,\usevalue,\needvalue} can all be used when defining keys; the pointer \fx{\usevalue} will, however, be ignored when defining keys, until when setting keys. The pointers \ffx'{\savevalue,\usevalue} can both be used when setting keys, but not the pointer \fx{\needvalue}.
+The pointer \fx{\needvalue} is a new type. It can be used by any key author to prompt the user of the key to always supply a value for the key. The pointers \ffx'{\savevalue,\usevalue,\needvalue} can all be called when defining keys. The pointer \fx{\usevalue} will, however, be ignored when defining keys, \ie, if present, it's simply dropped. If required at setting keys, it has to be explicitly indicated there. The pointers \ffx'{\savevalue,\usevalue} can both be used when setting keys, but not the pointer \fx{\needvalue}. The presence of the pointer \fx{\needvalue} when setting keys prompts an error.
Here is an interesting example and proof of concept of pointers:
@@ -995,7 +1006,6 @@ will undefine or emptify the existing save-key list globally.
\ltxkeys@setkeys[KV]{fam}{keya=\usevalue{keyc},keyb=\usevalue{keya}}
\finish{example}
-
\docsubsection(sec:savedvalueofkey)
<saved value of key>{Accessing the saved value of a key}
@@ -1144,7 +1154,7 @@ You can use the macro \fx{\ltxkeys@unknownkeyhandler} to declare to the \pkg'{lt
\finish{newmacro}
\fxim*{\ltxkeys@unknownkeyhandler,\ltxkeys@unknownoptionhandler}
-The callback \ang{cbk} signifies the action to take when an unknown key or option is encountered. The default \ang{cbk} is to log the keys and, in each run, warn the user of the presence of unknown keys. The same \ang{cbk} can be used across key prefixes \ang{prefs} and families \ang{fams}. You can use \fx{#1} (or \fx{\CurrentPref}) in this macro to represent the current key prefix, \fx{#2} (or \fx{\CurrentFam}) for the current family, \fx{#3} (or \fx{\CurrentKey}) for the current key name, and \fx{#4} (or \fx{\CurrentVal}) for the value of the current key. If \fx{\CurrentVal} contains undefined macros or active characters, then attempting to print it may cause problems. Therefore, when making entries in the transcript file, it will sometimes be preferable to use \fx{\InnocentVal} instead of \fx{\CurrentVal}. However, \fx{\InnocentVal} will give only the first eight characters of a key's value.
+The callback \ang{cbk} signifies the action to take when an unknown key or option is encountered. The default \ang{cbk} is to log the keys and, in each run, warn the user of the presence of unknown keys. The same \ang{cbk} can be used across key prefixes \ang{prefs} and families \ang{fams}. You can use \fx{#1} (or \fx{\CurrentPref}) in this macro to represent the current key prefix, \fx{#2} (or \fx{\CurrentFam}) for the current family, \fx{#3} (or \fx{\CurrentKey}) for the current key name, and \fx{#4} (or \fx{\CurrentVal}) for the value of the current key. If \fx{\CurrentVal} contains undefined macros or active characters, then attempting to print it may cause problems. Therefore, when making entries in the transcript file, it will sometimes be preferable to use \fx{\InnocentVal} instead of \fx{\CurrentVal}. However, \fx{\InnocentVal} detokenizes the current key value and, if the value is more than 20 characters, gives only the first 20 characters of a key's value.
The following example provides an unknown key handler for two key prefixes (\ffx'{KVA, KVB}) and two key families (\ffx'{fam1,fam2}):
@@ -1454,7 +1464,6 @@ Here, the key default value \ang{dft} and callback \ang{cbk} can be absent in al
\finish{example}
-
\docsection(sec:executeoption){Executing options}
\start{newmacro}[\ltxkeys@executeoptions]
@@ -1568,7 +1577,6 @@ The commands \ffx'{\val,\ifval,\ifvalTF} can be used in expansion contexts (incl
The commands \ffx'{\val,\ifval,\ifvalTF, \keyval,\ifkeyval,\ifkeyvalTF}, like the command and environment keys, are available in \ang{defn}, \ang{begdefn} and \ang{enddefn}. These commands (\ie, \ffx'{\val,\ifval,\ifvalTF, \keyval,\ifkeyval,\ifkeyvalTF}) are pushed on entry into \ang{defn} or \ang{begdefn}, and they are popped on exit of \ang{defn} or \ang{enddefn}. Unless they're defined elsewhere outside the \pkg'{ltxkeys}, they're undefined outside \ang{defn}, \ang{begdefn}, \ang{enddefn}, and the environment body\footnote{The commands \ftffx'{\pathkeysval,\ifpathkeysval,\ifpathkeysvalTF, \pathkeyskeyval,\ifpathkeyskeyval,\ifpathkeyskeyvalTF} are always available, but they can be used only in the context of \quoted{pathkeys} (\sref{sec:pathkeys}).}.
-%\rvtflag{\rvtpauseedit}
\docsubsection(sec:eoe){Final tokens of every environment}
@@ -1812,9 +1820,61 @@ The following example shows that in place of the functions \ffx'{\val,\ifval,\if
\finish{example}
+\docsection(sec:declarevariables)<declarevariables>{Declaring variables}
+
+Sometimes keys are used simply to save values for later use. This can be achieved easily by using the command \fx{\ltxkeys@declarevariables}.
+
+\start{newmacro}[\ltxkeys@declarevariables,\setvarvalues,\getvarvalue]
+\ltxkeys@declarevariables[|A(namespace)]{%
+ |A(key-1) = |A(dft-1) = |A(cbk-1), ..., |A(key-n) = |A(dft-n) = |A(cbk-n)
+}
+\setvarvalues[|A(namespace)]{|keyval pairs}
+\getvarvalue[|A(namespace)]{|A(key)}
+\finish{newmacro}
+\fxim*{\ltxkeys@declarevariables,\setvarvalues,\getvarvalue}
+
+Here, \ang{key-i}, \ang{dft-i} and \ang{cbk-i} are key name, key default value, and key callback, respectively, for key \quotedfx{i}. The optional \ang{namespace} is the private namespace for the declared variables and is used to avoid clashes of control sequences.
+
+The key default value \ang{dft} and callback \ang{cbk} are optional and may be missing in the mandatory argument of \fx{\ltxkeys@declarevariables}.
+
+\start{example}[\ltxkeys@declarevariables]
+\ltxkeys@declarevariables[mynamespace]{%
+ var1 = {default value1} = \def\userinput{#1}\def\cmd##1{##1},
+ |com(No callback:)
+ var2 = default value2,
+ |com(No default value and no callback:)
+ var3
+}
+\setvarvalues[mynamespace]{var1=new value1, var2=new value2}
+\edef\x{\getvarvalue[mynamespace]{var1}}
+
+\begin{document}
+\getvarvalue[mynamespace]{var1}
+\end{document}
+\finish{example}
+
+The private namespace is optional but clashes of control sequences might occur:
+
+\start{example}[\ltxkeys@declarevariables]
+\ltxkeys@declarevariables{%
+ var1 = {default value1} = \def\userinput{#1}\def\cmd##1{##1},
+ |com(No callback:)
+ var2 = default value2,
+ |com(No default value and no callback:)
+ var3
+}
+\setvarvalues{var1=new value1, var2=new value2}
+\edef\x{\getvarvalue{var1}}
+
+\begin{document}
+\getvarvalue{var1}
+\end{document}
+\finish{example}
+
+
\docsection(sec:pathkeys)<pathkeys>{Pathkeys}
-Let us start this section with a welcome message: you don't have to repeatedly type in long key paths and commands when using pathkeys. There is help ahead on how to reduce estate when using pathkeys.
+Let us start this section with a welcome message: you don't have to repeatedly type in long key paths and commands when using pathkeys. There is plenty of help ahead on how to reduce estate when using pathkeys.
The \pkg'{pathkeys} can be loaded on its own (via \hx{\RequirePackage} or \hx{\usepackage}) or as an option to the \pkg'{ltxkeys} (see \sref{tab:pkgoptions}). All the options listed in \sref{tab:pkgoptions} are accepted by the \pkg'{pathkeys}. They are all passed on to \pkg'{ltxkeys}, except \fx{pathkeys} that is simply ignored by \pkg'{pathkeys}.
@@ -1822,22 +1882,28 @@ Pathkeys are keys with a tree or directory structure\footnote{This might sound l
The command for defining and setting pathkeys is \fx{\pathkeys}, which has the following syntax. The same command is used for several other tasks related to pathkeys. The \quoted{flag} entry in the argument of \fx{\pathkeys} determines the action that the command is expected to take.
+\start+{newmacro}[\pathkeys]
+\pathkeys{|A(paths)/|A(flag)|R(:) |A(attrib)}
+\finish{newmacro}
+\fxim*{\pathkeys}
+
+In the argument of command \fx{\pathkeys}, \ang{paths} has the syntax
\start+{newmacro}[\pathkeys]
-\pathkeys{|A(main)/|A(sub)/|A(subsub)/.../|A(flag)|R(:) |A(attrib)}
+|A(main1)/|A(sub1)/|A(subsub1)/...|R(,)|A(main2)/|A(sub2)/|A(subsub2)/...|R(,)etc.
\finish{newmacro}
\fxim*{\pathkeys}
-In the argument of command \fx{\pathkeys}, the \quoted{path} is made up of \quoted{\texttt{\ang{main}/\ang{sub}/\ang{subsub}/.../}}. The quantity \ang{main} is the main path and \ang{sub} is the sub path, \eetc. Note that there is no forward slash ~(\fx{/}) before \ang{main}. If the path is empty, the default path \quotedfx{dft@main/dft@sub/}, or the user-supplied current path, is used. There is more about the default and current paths later in this guide.
+in which individual paths are separated by \qcomma. The quantity \ang{main} is the main path and \ang{sub} is the sub path, \eetc. Note that there is no forward slash ~(\fx{/}) before \ang{paths} or \ang{main}. If the path is empty, the default path \quotedfx{dft@main/dft@sub/}, or the user-supplied current path (see later), is used. There is more about the default and current paths later in this guide.
-The \ang{attrib} is determined by the key called \ang{flag}. The \ang{flag} must be a member of the set described in \sref{tab:flags}. See the table notes for the \ang{attrib}'s of the flags. The attributes describe the arguments associated with the flags, \ie, the quantities expected after the \qcolon in the argument of \fx{\pathkeys}. The \ang{na} is the list of keys that are ignored. If it is present in the attribute \ang{attrib} part of \fx{\pathkeys}, it must always be given in square brackets \quotedfx{[]} (see \sref{nte:pathkeys-flags}).
+The \ang{attrib} is determined by the key called \ang{flag}. The \ang{flag} determines the action the command \fx{\pathkeys} takes, and must be a member of the set described in \sref{tab:flags}. The action specified by \ang{flag} is, if applicable on all the given paths, taken on all the given paths\footnote{However, in most of this manual only one path is used in the sample syntaxes and in the examples.}. See the table notes for the \ang{attrib}'s of the flags. The attributes describe the arguments associated with the flags, \ie, the quantities expected after the \qcolon in the argument of \fx{\pathkeys}. The \ang{na} is the list of keys that are ignored by the \ang{flag}'s action. If it is present in the attribute \ang{attrib} part of \fx{\pathkeys}, it must always be given in square brackets \quotedfx{[]} (see \sref{nte:pathkeys-flags}).
-For flags with \stsign the user should make sure there is no space between the flag and its star.
+For flags with \redstar and \redplus signs the user should make sure there is no space between the flag and its star or plus sign: such a space will not be zapped internally, since syntactic matching is required.
-\defltablenote{pathkeys-flags-1}{%
- The flag \fx{declareoptions}\Redstar simply signifies the user's aim to define definable options; it has nothing to do with the \stform of the command \fx{\ltxkeys@declareoption} of \sref{sec:declareoption}. Attribute: same as for \fx{define} flag.
+\newltablenote{pathkeys-flags-1}{%
+ The flag \fx{declareoptions}\Redstar simply signifies the user's aim to define definable options; it has nothing to do with the \stform of the command \fx{\ltxkeys@declareoption} of \sref{sec:declareoption}. The attribute is the same as for \fx{define} flag.
}
-\defltablenote{pathkeys-flags-2}{%
+\newltablenote{pathkeys-flags-2}{%
The arguments of the unknown key or option handler are the main path, subpaths (separated by forward slash), key name, and the current key value (see \sref{sec:unknownkeyhandler}). The key or option handler can have up to a maximum of~4 arguments.
}
@@ -1847,7 +1913,7 @@ For flags with \stsign the user should make sure there is no space between the f
\small
\begin{tabularx}{\linewidth}{|C|>{\raggedright}p{2.5cm}|X|}
\caption{Flags and attributes for pathkeys\label{tab:flags}}\\\hline
-\ltablenotehead{These notes describe the attributes of handlers, \ie, what are required to be specified in \fx{\pathkeys} command after the \qcolon sign. \ang{na} keys must appear in square brackets, \eg, \fx{[keya]}.}
+\ltablenotehead{These notes describe the attributes of handlers, \ie, what are required to be specified in the command \fx{\pathkeys} after the \qcolon sign. \ang{na} keys are the keys to be ignored; they must appear in square brackets, \eg, \fx{[keya]}.}
\rowcolor{pink}
\bfseries No. &\bfseries Flag & \bfseries Meaning\\\hline
\endfirsthead
@@ -1859,25 +1925,35 @@ For flags with \stsign the user should make sure there is no space between the f
\endfoot
\hline
\endlastfoot
-1 & \fx{define} & Define the keys whether or not they already exist.\ltablenote*{See attribute in \sref{nte:pathkeys-flags}.}\\\hline
-2 & \fx{define}\Redstar & Define the keys only if they don't already exist.\ltablenote*{Same as for \fx{define} flag.} \\\hline
-3 & \fx{declareoptions} & Declare the given options whether or not they already exist.\ltablenote*{Same as for \fx{define} flag.} \\\hline
-4 & \fx{declareoptions}\Redstar & Declare the options if they don't already exist. \useltablenote*{pathkeys-flags-1} \\\hline
-5 & \fx{set} & Set the listed keys. \ltablenote*{\ang{na} keys and \keyval pairs (see \sref{sec:settingkeys}).} \\\hline
-6 & \fx{executeoptions} & Execute the listed options. \ltablenote*{\ang{na} keys and \keyval pairs (see \sref{sec:executeoption}).} \\\hline
-7 & \fx{processoptions} & Process the listed options in the order in which they were declared, and don't copy \hx{\documentclass} options. \ltablenote*{\ang{na} keys (see \sref{sec:processoption}).} \\\hline
-8 & \fx{processoptions}\Redstar & Process the listed options in the order in which they appear in the command \hx{\usepackage}, and copy \hx{\documentclass} options. \ltablenote*{\ang{na} keys (see \sref{sec:processoption}).} \\\hline
-9 & \fx{launch} & Launch the listed keys (see \sref{sec:launchingkeys}). \ltablenote*{\keyval pairs.} \\\hline
-10 & \fx{store value} & Store the value of \ang{key} in the given \ang{macro}. \ltablenote*{\ang{key} and \ang{macro}.} \\\hline
-11 & \fx{print value} & Print the current value of \ang{key}. \ltablenote*{\ang{key}.}\\\hline
-12 & \fx{add value} & Add the specified value to the current value of key. \ltablenote*{\ang{key} and \ang{value}.} \\\hline
-13 & \fx{ifbool} & Test the state of a boolean key. This returns \ang{true} or \ang{false}. \ltablenote*{\ang{key}.}\\\hline
-14 & \fx{ifdef} & Test if key is currently defined on the given single path. This returns \ang{true} or \ang{false}. \ltablenote*{\ang{key}.}\\\hline
-15 & \fx{ifkeyonpath} & Test if key is currently defined on any of the given comma-separated multiple paths. This returns \ang{true} or \ang{false}. \ltablenote*{\ang{key}.}\\\hline
-16 & \fx{disable} & Immediately disable the given keys. \ltablenote*{The attribute is a comma-separated key list.} \\\hline
-17 & \fx{disable}\Redstar & Disable the given keys at the hook \hx{\AtBeginDocument} and not immediately. \ltablenote*{Comma-separated key list.}\\\hline
-18 & \fx{key handler} or \fx{handler} & Unknown key handler.\useltablenote*{pathkeys-flags-2}\\\hline
-19 & \fx{option handler} & Unknown option handler (see \sref{sec:unknownkeyhandler}). Options are keys with a special default family. There might be a reason to handle unknown options separately from unknown keys.
+\rownr & \fx{define} & Define the keys whether or not they already exist.\ltablenote{See attribute in \sref{nte:pathkeys-flags}.}\\\hline
+\rownr & \fx{define}\Redstar & Define the keys only if they don't already exist.\ltablenote{Same as for \fx{define} flag.} \\\hline
+\rownr & \fx{declareoptions} & Declare the given options whether or not they already exist.\ltablenote{Same as for \fx{define} flag.} \\\hline
+\rownr & \fx{declareoptions}\Redstar & Declare the options if they don't already exist. \useltablenote{pathkeys-flags-1} \\\hline
+\rownr & \fx{preset} & Preset the listed keys on the given path. This actually means preparing the list of preset keys. \ltablenote{\keyval pairs (see \sref{sec:presettingkeys}).} \\\hline
+\rownr & \fx{preset}\Redclam & Preset the listed keys, saving the list globally. \ltablenote{\keyval pairs (see \sref{sec:presettingkeys}).} \\\hline
+\rownr & \fx{postset} & Post-set the listed keys. \ltablenote{\keyval pairs (see \sref{sec:presettingkeys}).} \\\hline
+\rownr & \fx{postset}\Redclam & Post-set the listed keys, saving the list globally. \ltablenote{\keyval pairs (see \sref{sec:presettingkeys}).} \\\hline
+\rownr & \fx{set} & Set the listed keys. \ltablenote{\ang{na} keys and \keyval pairs (see \sref{sec:settingkeys}).} \\\hline
+\rownr & \fx{set}\Redstar & Set the listed keys and save undefined keys in the list of \quoted{remaining keys} without raising errors. \ltablenote{\ang{na} keys and \keyval pairs (see \sref{sec:settingkeys}).} \\\hline
+\rownr & \fx{set}\Redstar\Redplus & Set the listed keys in all the given key prefixes and families; save undefined keys in the list of \quoted{remaining keys} without raising errors. \ltablenote{\ang{na} keys and \keyval pairs (see \sref{sec:settingkeys}).} \\\hline
+\rownr & \fx{setrm} & Set the \quoted{remaining keys}. \ltablenote{\ang{na} keys (see \sref{sec:rmkeys}).} \\\hline
+\rownr & \fx{setrm}\Redstar & Set the \quoted{remaining keys} and again save undefined keys in the revised list of \quoted{remaining keys} without raising errors. \ltablenote{\ang{na} keys (see \sref{sec:rmkeys}).} \\\hline
+\rownr & \fx{setrm}\Redstar\Redplus & Set the \quoted{remaining keys} in all the given key prefixes and families; save undefined keys in the revised list of \quoted{remaining keys} without raising errors. \ltablenote{\ang{na} keys (see \sref{sec:rmkeys}).} \\\hline
+
+\rownr & \fx{executeoptions} & Execute the listed options. \ltablenote{\ang{na} keys and \keyval pairs (see \sref{sec:executeoption}).} \\\hline
+\rownr & \fx{processoptions} & Process the listed options in the order in which they were declared, and don't copy \hx{\documentclass} options. \ltablenote{\ang{na} keys (see \sref{sec:processoption}).} \\\hline
+\rownr & \fx{processoptions}\Redstar & Process the listed options in the order in which they appear in the command \hx{\usepackage}, and copy \hx{\documentclass} options. \ltablenote{\ang{na} keys (see \sref{sec:processoption}).} \\\hline
+\rownr & \fx{launch} & Launch the listed keys (see \sref{sec:launchingkeys}). \ltablenote{\keyval pairs.} \\\hline
+\rownr & \fx{store value} & Store the value of \ang{key} in the given \ang{macro}. \ltablenote{\ang{key} and \ang{macro}, \eg, \fx{keya \cmda}.} \\\hline
+\rownr & \fx{print value} & Print the current value of \ang{key}. \ltablenote{\ang{key}, \eg, \fx{keya}.}\\\hline
+\rownr & \fx{add value} & Add the specified value to the current value of key. \ltablenote{\ang{key} and \ang{value}.} \\\hline
+\rownr & \fx{ifbool} & Test the state of a boolean key. This returns \ang{true} or \ang{false}. \ltablenote{\ang{key}.}\\\hline
+\rownr & \fx{ifdef} & Test if key is currently defined on any of the given comma-separated multiple paths. This returns \ang{true} or \ang{false}. \ltablenote{\ang{key}.}\\\hline
+\rownr & \fx{ifkeyonpath} & Test if key is currently defined on any of the given comma-separated multiple paths. This returns \ang{true} or \ang{false}. \ltablenote{\ang{key}.}\\\hline
+\rownr & \fx{disable} & Immediately disable the given keys. \ltablenote{The attribute is a comma-separated key list.} \\\hline
+\rownr & \fx{disable}\Redstar & Disable the given keys at the hook \hx{\AtBeginDocument} and not immediately. \ltablenote{Comma-separated key list.}\\\hline
+\rownr & \fx{key handler} or \fx{handler} & Unknown key handler.\useltablenote{pathkeys-flags-2}\\\hline
+\rownr & \fx{option handler} & Unknown option handler (see \sref{sec:unknownkeyhandler}). Options are keys with a special default family. There might be a reason to handle unknown options separately from unknown keys.
\end{tabularx}
\endgroup
@@ -1896,10 +1972,16 @@ The syntax for specifying keys to be defined by \fx{\pathkeys} is (see \sref{sec
The default value \ang{dft} and the callback \ang{cbk} can be absent in all cases. \ang{keytype} may be any member of the set \fnz{ord,cmd,sty,sty*,bool,choice}. The star (\redstar) in \quoted{sty\Redstar} has the same meaning as in \fx{\ltxkeys@stylekey} (\sref{sec:stylekeys}), namely, undefined dependants will be defined on the fly when the parent is set/executed. \aidx*{style keys (sty*)}
\start{example}[Syntax for defining pathkeys]
+|com(Define keys on only one path:)
\pathkeys{fam/subfam/subsubfam/|R(define):
cmd/keya/defaultval/\def\cmda#1{#1};
bool/keyb/true;
}
+|com(Define keys on multiple paths:)
+\pathkeys{fam1/subfam1/subsubfam1,fam2/subfam2/subsubfam2,.../|R(define):
+ cmd/keya/defaultval/\def\cmda#1{#1};
+ bool/keyb/true;
+}
\finish{example}
Choice keys must have their names associated with their nominations (\ie, admissible values) in the format \keydotchoice{keyname}{nominations}, as below (see also \sref{sec:declarekeys}):
@@ -1934,7 +2016,7 @@ The \ang{na} keys, if they are present in the attribute of \fx{\pathkeys}, must
\pathkeys{fam/subfam/subsubfam/|R(set): [keyb] keya=zz,keyb=true}
\finish{example}
-See \sref{sec:options-pathkeys} for further examples of the use of ignored keys. Here we can see that a value is provided for \quoted{keyb} and yet we're ignoring the key. However, in practical applications it is often impossible to predict the set of keys (among a set of them) that may be executed at any time by the user of the keys. Therefore, \ang{na} keys are much more useful than the above example demonstrates.
+See \sref{sec:options-pathkeys} for further examples of the use of ignored keys. Here we can see that a value is provided for \quoted{keyb} and yet we're ignoring the key. However, in practical applications it is often impossible to predict the set of keys (among a set of them) that may be executed at any time by the user of the keys. Therefore, \ang{na} keys are much more useful than the above example demonstrates\@gobble{.}
\end{noteenv}
Some of the commands associated with pathkeys are listed below. The abbreviation \ang{pk} means the full key path and key name, all separated by forward slash.
@@ -1988,7 +2070,6 @@ The following provide our first examples of pathkeys and a demonstration of some
\finish{example}
\fxim*{unknown key handler in pathkeys}
-
\start+{example}[Pathkeys]
\pathkeys{KV/frame/framebox/|R(define*):
cmd/width/\textwidth/\def\x##1{#1xx##1};
@@ -2043,7 +2124,6 @@ The following provide our first examples of pathkeys and a demonstration of some
\end{document}
\finish{example}
-
\begin{noteenv}
When using pathkeys (and in general the commands \ffx'{\ltxkeys@definekeys,\ltxkeys@declarekeys}), there is a potential problem in deploying forward slashes in key defaults and macros without enclosing those slashes in curly braces. They will confuse the parser. Several solutions exist, including tweaking the relevant internal parser, but I haven't decided on the optimal solution to this possibility. For example, the following will fail:
@@ -2099,7 +2179,7 @@ Instead of defining your own commands like the above \fx{\mypath}, you can use t
\finish{newmacro}
\fxim*{\newpath,\defpath,\changepath,\undefpath,\usepath}
-These commands have their own separate namespace. Here, \ang{pathname} is used, after definition, as an abbreviation for the full path \ang{path}. The command \fx{\newpath} creates \ang{pathname} if it didn't already exist; \fx{\defpath} creates \ang{pathname} whether or not it exists; \fx{\changepath} is equivalent to \fx{\defpath}; \fx{\undefpath} undefines \ang{pathname}; and \fx{\usepath} expands \ang{pathname} to its full meaning. The macro \fx{\usepath} does accept, as argument, a comma-separated list of pathnames, but it is unlikely that such a list will, for now anyway, be needed outside when using the flag \fx{ifkeyonpath} (see the following example).
+These commands have their own separate namespace. Here, \ang{pathname} is used, after definition, as an abbreviation for the full path \ang{path}. The command \fx{\newpath} creates \ang{pathname} if it didn't already exist; \fx{\defpath} creates \ang{pathname} whether or not it exists; \fx{\changepath} is equivalent to \fx{\defpath}; \fx{\undefpath} undefines \ang{pathname}; and \fx{\usepath} expands \ang{pathname} to its full meaning. The macro \fx{\usepath} does accept, as argument, a comma-separated list of pathnames. When using the flag \fx{ifdef} or \fx{ifkeyonpath}, if \ang{path} or \ang{pathname} is a comma-separated list, all the given paths are searched in determining if the key is defined (see the following example).
\start+{example}[\newpath, \usepath]
\newpath{path1}{fam/subfam/subsubfam1}
@@ -2113,6 +2193,23 @@ These commands have their own separate namespace. Here, \ang{pathname} is used,
\edef\x{\ifpathkeysvalTF{\usepath{path1}/keya}{T}{F}}
\finish{example}
+\start+{example}[\defpath, \usepath, set, setrm]
+\defpath{path1}{fam/subfam/subsubfam1}
+\defpath{path2}{fam/subfam/subsubfam2}
+|com(Define `key1' on two paths:)
+\pathkeys{\usepath{path1,path2}/define*:
+ cmd/key1/12cm/\def\y##1{#1yy##1}
+}
+|com(Set keys on paths 1 and 2 and put undefined keys in the `rm list')
+|com(instead of raising errors:)
+\pathkeys{\usepath{path1,path2}/|R(set*+):
+ key1=10cm,key2=true,key3=xx
+}
+|com(Set `rm keys` and again put undefined keys in the `rm list')
+|com(instead of raising errors:)
+\pathkeys{\usepath{path1,path2}/|R(setrm*+):}
+\finish{example}
+
The following shortened counterparts of the pathkeys commands are provided (see \sref{tab:pathkeys-cmdabbrv}). The abbreviated commands are available only after the user has invoked \fx{\pathkeys@useshortcmds}, which expects no argument. The command \fx{\pathkeys@useshortcmds} has only local effect, \ie, the abbreviations may be localized to a group. The abbreviations are defined only if they're definable (\ie, didn't exist before calling the command \fx{\pathkeys@useshortcmds}).
\begingroup\small
@@ -2165,7 +2262,7 @@ where \ang{short-i} and \ang{long-i} are the short (new) and long (existing) ali
If the key path is empty, then the current path will be used; and if there is no current path, the default path will be used. The default path is \fx{dft@main/dft@sub}. This can be changed by the commands \ffx'{\pathkeys@addtodefaultpath, \pathkeys@changedefaultpath}. The current path can be declared by providing an argument to the command \fx{\pathkeys@currentpath}. The default path can be made the current path by invoking the command \fx{\pathkeys@usedefaultpath}, which is parameterless.
-It isn't mandatory, but it is useful, to first push the prevailing path before changing it. This can be done by calling the parameterless command \fx{\pathkeys@pushcurrentpath}. When you're done with the current path, you can revert to the path before the current path by calling the command \fx{\pathkeys@popcurrentpath}. You can get the entire history of path changes from the container \fx{\pathkeys@pathhistory}, which is useful in complex situations.
+It isn't mandatory, but it is useful, to first push the prevailing path before changing it. This can be done by calling the parameterless command \fx{\pathkeys@pushcurrentpath}. When you're done with the current path, you can revert to the path before the current path by calling the command \fx{\pathkeys@popcurrentpath}. You can get the entire history of path changes from the container \fx{\pathkeys@pathhistory}, which is useful in complex situations. However, it should be noted that \fx{\pathkeys@pathhistory} doesn't contain a chronological order of path changes: if a path is already contained in it, it wouldn't be added again.
Before the current path is resorted to, the path for the commands \ffx{\pathkeys, \pathkeysval, \ifpathkeysval}, \eetc must be empty (\ie, no main and no subs). Therefore, in any given setting, the path that is dominant can be made current so that it isn't given in \ffx{\pathkeys, \pathkeysval, \ifpathkeysval}, \eetc. The non-dominant paths could then be listed in full. Of course, there can't be more than one current path.
@@ -2295,7 +2392,7 @@ The command \fx{\ltxkeys@trimspacesincs} trims the leading and trailing spaces a
\fxim*{\ltxkeys@checkchoice,\ltxkeys@checkinput,\CheckUserInput,
\ltxkeys@commacheckchoice}
-The command \fx{\ltxkeys@checkchoice} is a re-implementation of \pkg'{xkeyval}'s command \fx{\XKV@checkchoice} so as to accept arbitrary list parser \ang{parser} and more robustness. It checks the user input \ang{input} against the list of nominations \ang{nomin}. If the input is valid, the user input is returned in \ang{val} and the numerical order (starting from zero) of the input in the nominations is returned in \ang{order}\footnote{The functions \ang{val} and \ang{order} are user-supplied macros.}. If the input isn't valid, the user input is still returned in \ang{val}, but $-1$ is returned in \ang{order}. \ang{parser} is the list parser. The \stform of \fx{\ltxkeys@checkchoice} will convert \ang{input} into lowercase before checking it against the nominations. The \plform of \fx{\ltxkeys@checkchoice} expects two branches (\ang{true} and \ang{false}) of callback at the end of the test. The \unplform expects only one branch (\ang{true}) and will return error if the input is invalid\footnote{There is also \ftfx{\ltxkeys@commacheckchoice}, whose parser is implicitly \qcomma and does not need to be given by the user.}.
+The command \fx{\ltxkeys@checkchoice} is a re-implementation of \pkg'{xkeyval}'s command \fx{\XKV@checkchoice} so as to accept arbitrary list parser \ang{parser} and for more robustness. It checks the user input \ang{input} against the list of nominations \ang{nomin}. If the input is valid, the user input is returned in \ang{val} and the numerical order (starting from zero) of the input in the nominations is returned in \ang{order}\footnote{The functions \ang{val} and \ang{order} are user-supplied macros.}. If the input isn't valid, the user input is still returned in \ang{val}, but $-1$ is returned in \ang{order}. \ang{parser} is the list parser. The \stform of \fx{\ltxkeys@checkchoice} will convert \ang{input} into lowercase before checking it against the nominations. The \plform of \fx{\ltxkeys@checkchoice} expects two branches (\ang{true} and \ang{false}) of callback at the end of the test. The \unplform expects only one branch (\ang{true}) and will return error if the input is invalid\footnote{There is also \ftfx{\ltxkeys@commacheckchoice}, whose parser is implicitly \qcomma and does not need to be given by the user.}.
The commands \ffx'{\ltxkeys@checkinput,\CheckUserInput} apply to comma-separated lists of nominations \ang{nomin} and they always convert \ang{input} to lowercase before checking it against the nominations \ang{nomin}. The macro \fx{\ltxkeys@checkinput} expects two branches of callback, while \fx{\CheckUserInput} expects no callback. Instead, \fx{\CheckUserInput} will toggle the internal boolean \fx{\ifinputvalid} to \hx{true} if the input is valid, and to \hx{false} otherwise. The internal boolean \fx{\ifinputvalid} could then be called by the user after the test.
@@ -2309,7 +2406,7 @@ The commands \ffx'{\ltxkeys@checkinput,\CheckUserInput} apply to comma-separated
\finish{newmacro}
\fxim*{\ltxkeys@in,\ltxkeys@iffound}
-The \unstform of the command \fx{\ltxkeys@in} is identical with \usecsn{latex2e} kernel's (2011/06/27) \hx{\in@}. The command \hx{\in@} tests for the presence of \ang{teststr} in \ang{str}. The \stform of \fx{\ltxkeys@in} returns two \latex branches \ang{true} and \ang{false}. On the other hand, the command \fx{\ltxkeys@iffound} requires the first argument to be delimited by \fx{\in} and the second argument by \fx{\then}.
+The \unstform of the command \fx{\ltxkeys@in} is identical with \usecsn{latex2e} kernel's (2011/06/27) \hx{\in@}. The command \hx{\in@} tests for the presence of \ang{teststr} in \ang{str} and returns the boolean \hx{\ifin@} as \hx{\iftrue} or \hx{\iffalse}. The \stform of \fx{\ltxkeys@in} returns two \latex branches \ang{true} and \ang{false}. On the other hand, the command \fx{\ltxkeys@iffound} requires the first argument to be delimited by \fx{\in} and the second argument by \fx{\then}.
\start{example}[\ltxkeys@iffound]
\ltxkeys@iffound xx\in aax\then \def\x{T}\else \def\x{F}\fi
@@ -2462,7 +2559,7 @@ Here are some points to note about the list processor \fx{\ltxkeys@parse}:
\finish{newmacro}
\fxim*{\ltxkeys@declarelistparser}
-Given a parser (or list separator) \ang{parser}, the command \fx{\ltxkeys@declarelistparser} can be used to define an expandable list iterator \ang{iterator}. The item processor \ang{processor} should be a one-parameter macro, which will receive and process each element of \ang{list}. The optional \clsign determines whether or not the processor is actually expanded and executed in the current expansion context. If \redclam is given, the processor is expanded and executed, otherwise it is merely given the elements as argument without expansion. In general, \ang{list} isn't normalized, but is expanded once, before commencing the loop. The list can be normalized by the command \fx{\csv@@normalize} (see \pkg'{catoptions}) before looping. The following example demonstrates the concept. The user can insert \fx{\listbreak} as an item in the list to break out of the iteration prematurely.
+Given a parser (or list separator) \ang{parser}, the command \fx{\ltxkeys@declarelistparser} can be used to define an expandable list iterator \ang{iterator}. The item processor \ang{processor} should be a one-parameter macro, which will receive and process each element of \ang{list}. The optional \clsign determines whether or not the processor is actually expanded and executed in the current expansion context. If \redclam is given, the processor is expanded and executed, otherwise it is merely given the elements as argument without expansion. In general, \ang{list} isn't normalized, but is expanded once, before commencing the loop. The list can be normalized by the command \fx{\csv@@normalize} of the \pkg'{catoptions} before looping\footnote{The \pkg'{ltxtools-base} provides the command \ftfx{\ltsdeclarelistparser}, which works similar to the macro \ftfx{\ltxkeys@declarelistparser} but has a dynamic, expandable list normalizer for arbitrary list parsers/separators.}. The following example demonstrates the concept. The user can insert \fx{\listbreak} as an item in the list to break out of the iteration prematurely.
\start+{example}[\ltxkeys@declarelistparser]
\ltxkeys@declarelistparser\iterator{;}
@@ -2475,8 +2572,16 @@ Given a parser (or list separator) \ang{parser}, the command \fx{\ltxkeys@declar
|com(The following example will add `a,b,c' to macro \y:)
\ltxkeys@declarelistparser\doloop{,}
\doloop{a,b,c}{\cptaddtolist\y}
-|com(The following example will add `d,e' to macro \y:)
+|com(The following example will add `d,e' to macro \y and ignore `f':)
\doloop|!{d,e,\listbreak,f}{\cptaddtolist\y}
+
+|com(Nesting of the |A(iterator) is possible:)
+\ltxkeys@declarelistparser\alistparser{,}
+\ltxkeys@declarelistparser\blistparser{;}
+\def\@do#1{#1}
+\def\do#1{=#1=\blistparser!{x;y;z}\@do}
+\edef\x{\alistparser!{a,b,c}\do}
+|com(This gives: \x=macro:->=a=xyz=b=xyz=c=xyz)
\finish{example}
@@ -2527,26 +2632,26 @@ where \ang{old-i} is the element to be replaced and \ang{new-i} is its replaceme
\docsubsection(sec:stripbraces){Stripping outer braces}
-The list and key parsers of the \pkg'{ltxkeys} preserve outer braces. But sometimes it is needed to rid a token of one or more of its outer braces. This can be achieved by the following commands:
+The list and key parsers of the \pkg'{ltxkeys} preserve outer braces, but sometimes it is needed to rid a token of one or more of its outer braces. This can be achieved by the following commands:
-\start+{newmacro}[\ltxkeys@stripouterbraces,\ltxstripouterbraces]
-\ltxkeys@stripouterbraces|A(nr){|A(token)}
-\ltxstripouterbraces|A(nr){|A(token)}|A(cmd)
+\start+{newmacro}[\ltxkeys@stripNouterbraces, \ltxkeys@stripallouterbraces, etc.]
+\ltxkeys@stripNouterbraces|A(nr){|A(token)}
+\ltxkeys@stripallouterbraces{|A(token)}
+\ltxkeys@stripallouterbracesincs{|A(cmd)}
\finish{newmacro}
-\fxim*{\ltxkeys@stripouterbraces,\ltxstripouterbraces}
+\fxim*{\ltxkeys@stripNouterbraces,
+ \ltxkeys@stripallouterbraces,\ltxkeys@stripallouterbracesincs}
-The command \fx{\ltxkeys@stripouterbraces} strips \ang{nr} number of outer braces from \ang{token}. The command \fx{\ltxstripouterbraces} strips \ang{nr} number of outer braces from \ang{token} and returns the result in the macro \ang{cmd}. The command \fx{\ltxkeys@stripouterbraces} is expandable, but \fx{\ltxstripouterbraces} isn't expandable. Normally, \ang{token} shouldn't be expanded by these commands after the outer braces have been stripped off.
+The command \fx{\ltxkeys@stripNouterbraces} strips \ang{nr} number of outer braces from \ang{token}. The command \fx{\ltxkeys@stripallouterbraces} strips all outer braces from \ang{token}. The command \fx{\ltxkeys@stripallouterbracesincs} strips all the outer braces in the top content of the command \ang{cmd}. All these commands are expandable. Normally, \ang{token} wouldn't be expanded by these commands in the process of stripping off outer braces.
-\start+{example}[\ltxkeys@stripouterbraces,\ltxstripouterbraces]
+\start+{example}[\ltxkeys@stripNouterbraces,\ltxkeys@stripallouterbraces, etc.]
\toks@\expandafter\expandafter\expandafter
- {\ltxkeys@stripouterbraces{2}{{{\y}}}}
+ {\ltxkeys@stripNouterbraces{2}{{{\y}}}}
\edef\x{\unexpanded\expandafter\expandafter\expandafter
- {\ltxkeys@stripouterbraces{\@m}{{{\y}}}}}%
-\ltxstripouterbraces{2}{{{{\y}}}}\x
+ {\ltxkeys@stripNouterbraces\@m{{{\y}}}}}
+\edef\x{\ltxkeys@stripallouterbraces{{{{\y}}}}}
\finish{example}
-If it is required to strip all the outer braces off \ang{token}, then \ang{nr} can be made large, \eg, \hx{\@m}.
-
\docsection(sec:todo){To-do list}
@@ -2581,8 +2686,11 @@ Introduce toggle keys and switch keys, but in practice who needs them? I would r
The following change history highlights significant changes that affect user utilities and interfaces; changes of technical nature are not documented in this section. 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.3}{2011/12/17}
+ \item More flags (\ffx{preset, postset, setrm}, \eetc) have been introduced for pathkeys \vsecref{sec:pathkeys}
+ \end{version}
\begin{version}{0.0.2}{2011/09/01}
- \item \quoted{Pathkeys} introduced\vsecref{sec:pathkeys}
+ \item Pathkeys introduced\vsecref{sec:pathkeys}
\item User guide completed.\vsecref*
\end{version}
\begin{version}{0.0.1}{2011/07/30}