summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3keys.dtx129
1 files changed, 72 insertions, 57 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
index a825c0cad3b..f49bd433df4 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3keys.dtx Copyright (C) 2006-2013 The LaTeX3 Project
+%% File: l3keys.dtx Copyright (C) 2006-2014 The LaTeX3 Project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -33,13 +33,14 @@
%%
%% -----------------------------------------------------------------------
%
+%<*driver>
+\documentclass[full]{l3doc}
+%</driver>
%<*driver|package>
-\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3keys.dtx 4614 2013-12-08 17:07:31Z joseph $
- {L3 Experimental key-value interfaces}
+\GetIdInfo$Id: l3keys.dtx 4728 2014-05-04 13:25:37Z joseph $
+ {L3 Key-value interfaces}
%</driver|package>
%<*driver>
-\documentclass[full]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -281,7 +282,7 @@
% (which must a floating point expression). If the variable does not exist,
% it will be created globally at the point that the key is set up.
% \end{function}
-%
+%
% \begin{function}[added = 2013-07-14]
% {.groups:n}
% \begin{syntax}
@@ -321,7 +322,7 @@
% is used, then the value will be passed through to the subsidiary
% \meta{keys} for processing (as |#1|).
% \end{function}
-%
+%
% \begin{function}[added = 2013-07-10]{.meta:nn}
% \begin{syntax}
% \meta{key} .meta:nn = \Arg{path} \Arg{keyval list}
@@ -330,7 +331,7 @@
% one go using the \meta{path} in place of the current one.
% If \meta{key} is given with a value at the time the key
% is used, then the value will be passed through to the subsidiary
-% \meta{keys} for processing (as |#1|).
+% \meta{keys} for processing (as |#1|).
% \end{function}
%
% \begin{function}[added = 2011-08-21]{.multichoice:}
@@ -488,7 +489,7 @@
% These variables do not have defined behaviour when used outside of
% code created using \texttt{.choices:nn}
% (\emph{i.e.}~anything might happen).
-%
+%
% It is possible to allow choice keys to take values which have not previously
% been defined by adding code for the special \texttt{unknown} choice. The
% general behavior of the \texttt{unknown} key is described in
@@ -501,16 +502,16 @@
% key / choice-a .code:n = code-a,
% key / choice-b .code:n = code-b,
% key / choice-c .code:n = code-c,
-% key / unknown .code:n =
+% key / unknown .code:n =
% \msg_error:nnxxx { mymodule } { unknown-choice }
% { key } % Name of choice key
% { choice-a , choice-b , choice-c } % Valid choices
% { \exp_not:n {#1} } % Invalid choice given
% %
-% %
+% %
% }
% \end{verbatim}
-%
+%
% Multiple choices are created in a very similar manner to mutually-exclusive
% choices, using the properties \texttt{.multichoice:} and
% \texttt{.multichoices:nn}. As with mutually exclusive choices, multiple
@@ -538,8 +539,8 @@
% key / choice-c .code:n = code-c,
% }
% \end{verbatim}
-% are valid.
-%
+% are valid.
+%
% When a multiple choice key is set
% \begin{verbatim}
% \keys_set:nn { mymodule }
@@ -557,9 +558,9 @@
% key = c ,
% }
% \end{verbatim}
-% Thus each separate choice will have passed to it the
+% Thus each separate choice will have passed to it the
% \cs{l_keys_choice_tl} and \cs{l_keys_choice_int} in exactly
-% the same way as described for \texttt{.choices:nn}.
+% the same way as described for \texttt{.choices:nn}.
%
% \section{Setting keys}
%
@@ -573,17 +574,17 @@
% by defining a special \texttt{unknown} key: this will be illustrated
% later.
% \end{function}
-%
+%
% \begin{variable}{\l_keys_key_tl, \l_keys_path_tl, \l_keys_value_tl}
% For each key processed, information of the full \emph{path} of the
% key, the \emph{name} of the key and the \emph{value} of the key is
% available within three token list variables. These may be used within
% the code of the key.
-%
+%
% The \emph{value} is everything after the \texttt{=}, which may be
% empty if no value was given. This is stored in \cs{l_keys_value_tl}, and
% is not processed in any way by \cs{keys_set:nn}.
-%
+%
% The \emph{path} of the key is a \enquote{full} description of the key,
% and is unique for each key. It consists of the module and full key name,
% thus for example
@@ -596,7 +597,7 @@
% \end{verbatim}
% has path \texttt{mymodule/subset/key-a}. This information is stored in
% \cs{l_keys_path_tl}, and will have been processed by \cs{tl_to_str:n}.
-%
+%
% The \emph{name} of the key is the part of the path after the last
% \texttt{/}, and thus is not unique. In the preceding examples, both keys
% have name \texttt{key-a} despite having different paths. This information
@@ -619,7 +620,7 @@
% }
% \end{verbatim}
%
-% \begin{function}[added = 2011-08-23]
+% \begin{function}[added = 2011-08-23, updated = 2014-04-27]
% {
% \keys_set_known:nnN, \keys_set_known:nVN,
% \keys_set_known:nvN, \keys_set_known:noN,
@@ -636,13 +637,16 @@
% are not processed further by the parser.
% The key--value pairs for each \emph{unknown} key name will be
% stored in the \meta{tl} in a comma-separated form (\emph{i.e.}~an edited
-% version of the \meta{keyval list}). The \cs{keys_set_known:nn} version skips
-% this stage.
+% version of the \meta{keyval list}). The \cs{keys_set_known:nn} version
+% skips this stage.
+%
+% Use of \cs{keys_set_known:nnN} can be nested, with the correct residual
+% \meta{keyval list} returned at each stage.
% \end{function}
-%
+%
% \section{Selective key setting}
% \label{sec:l3keys:selective}
-%
+%
% In some cases it may be useful to be able to select only some keys for
% setting, even though these keys have the same path. For example, with
% a set of keys defined using
@@ -675,12 +679,12 @@
% will assign \texttt{key-one} and \texttt{key-two} to group \texttt{first},
% \texttt{key-three} to group \texttt{second}, while \texttt{key-four} is
% not assigned to a group.
-%
+%
% Selective key setting may be achieved either by selecting one or more
% groups to be made \enquote{active}, or by marking one or more groups to
% be ignored in key setting.
-%
-% \begin{function}[added = 2013-07-14]
+%
+% \begin{function}[added = 2013-07-14, updated = 2014-04-27]
% {
% \keys_set_filter:nnnN, \keys_set_filter:nnVN,
% \keys_set_filter:nnvN, \keys_set_filter:nnoN,
@@ -697,8 +701,11 @@
% key which is filtered out will be stored in the \meta{tl} in a
% comma-separated form (\emph{i.e.}~an edited version of the \meta{keyval
% list}). The \cs{keys_set_filter:nnn} version skips this stage.
+%
+% Use of \cs{keys_set_filter:nnnN} can be nested, with the correct residual
+% \meta{keyval list} returned at each stage.
% \end{function}
-%
+%
% \begin{function}[added = 2013-07-14]
% {
% \keys_set_groups:nnn, \keys_set_groups:nnV,
@@ -826,14 +833,6 @@
%<*initex|package>
% \end{macrocode}
%
-% \begin{macrocode}
-%<*package>
-\ProvidesExplPackage
- {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
-\__expl_package_check:
-%</package>
-% \end{macrocode}
-%
% \subsection{Low-level interface}
%
% \begin{macrocode}
@@ -1077,7 +1076,7 @@
\tl_new:N \l_keys_choice_tl
% \end{macrocode}
% \end{variable}
-%
+%
% \begin{variable}{\l_@@_groups_clist}
% Used for storing and recovering the list of groups which apply to a key:
% set as a comma list but at one point we have to use this for a token
@@ -1108,7 +1107,7 @@
\bool_new:N \l_@@_no_value_bool
% \end{macrocode}
% \end{variable}
-%
+%
% \begin{variable}{\l_@@_only_known_bool}
% Used to track if only \enquote{known} keys are being set.
% \begin{macrocode}
@@ -1131,7 +1130,7 @@
\tl_new:N \l_@@_property_tl
% \end{macrocode}
% \end{variable}
-%
+%
% \begin{variable}{\l_@@_selective_bool, \l_@@_filtered_bool}
% Two flags for using key groups: one to indicate that \enquote{selective}
% setting is active, a second to specify which type (\enquote{opt-in}
@@ -1141,7 +1140,7 @@
\bool_new:N \l_@@_filtered_bool
% \end{macrocode}
% \end{variable}
-%
+%
% \begin{variable}{\l_@@_selective_seq}
% The list of key groups being filtered in or out during selective setting.
% \begin{macrocode}
@@ -1162,7 +1161,7 @@
\tl_new:N \l_keys_value_tl
% \end{macrocode}
% \end{variable}
-%
+%
% \begin{variable}{\l_@@_tmp_bool}
% Scratch space.
% \begin{macrocode}
@@ -1399,7 +1398,7 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}[int]{\@@_groups_set:n}
% Assigning a key to one or more groups uses comma lists. So that the comma
% list is \enquote{well-behaved} later, the storage is done via a stored
@@ -1521,7 +1520,7 @@
%
% The key property functions are all wrappers for internal functions,
% meaning that things stay readable and can also be altered later on.
-%
+%
% Importantly, while key properties have \enquote{normal} argument specs, the
% underlying code always supplies one braced argument to these. As such, argument
% expansion is handled by hand rather than using the standard tools. This shows
@@ -1655,7 +1654,7 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-%
+%
% \begin{macro}{.groups:n}
% A single property to create groups of keys.
% \begin{macrocode}
@@ -1701,7 +1700,7 @@
{ \@@_meta_make:n {#1} }
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}{.meta:nn}
% Meta with path: potentially lots of variants, but for the moment
% no so many defined.
@@ -1816,21 +1815,29 @@
% \keys_set_known:nnN, \keys_set_known:nVN,
% \keys_set_known:nvN, \keys_set_known:noN
% }
+% \begin{macro}[aux]{\@@_set_known:nnnN, \@@_set_known:onnN}
% \begin{macro}
% {
% \keys_set_known:nn, \keys_set_known:nV,
% \keys_set_known:nv, \keys_set_known:no
% }
% Setting known keys simply means setting the appropriate flag, then
-% running the standard code.
+% running the standard code. To allow for nested setting, any existing
+% value of \cs{l_@@_unused_clist} is saved on the stack and reset
+% afterwards.Note that for speed/simplicity reasons we use a \texttt{tl}
+% operation to set the \texttt{clist} here!
% \begin{macrocode}
-\cs_new_protected:Npn \keys_set_known:nnN #1#2#3
+\cs_new_protected_nopar:Npn \keys_set_known:nnN
+ { \@@_set_known:onnN \l_@@_unused_clist }
+\cs_generate_variant:Nn \keys_set_known:nnN { nV , nv , no }
+\cs_new_protected:Npn \@@_set_known:nnnN #1#2#3#4
{
\clist_clear:N \l_@@_unused_clist
- \keys_set_known:nn {#1} {#2}
- \tl_set:Nx #3 { \exp_not:o { \l_@@_unused_clist } }
+ \keys_set_known:nn {#2} {#3}
+ \tl_set:Nx #4 { \exp_not:o { \l_@@_unused_clist } }
+ \tl_set:Nn \l_@@_unused_clist {#1}
}
-\cs_generate_variant:Nn \keys_set_known:nnN { nV , nv , no }
+\cs_generate_variant:Nn \@@_set_known:nnnN { o }
\cs_new_protected:Npn \keys_set_known:nn #1#2
{
\bool_set_true:N \l_@@_only_known_bool
@@ -1841,12 +1848,14 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}
% {
% \keys_set_filter:nnnN, \keys_set_filter:nnVN, \keys_set_filter:nnvN
% \keys_set_filter:nnoN
% }
+% \begin{macro}[aux]{\@@_set_filter:nnnnN, \@@_set_filter:onnnN}
% \begin{macro}
% {
% \keys_set_filter:nnn, \keys_set_filter:nnV, \keys_set_filter:nnv
@@ -1858,15 +1867,20 @@
% \keys_set_groups:nno
% }
% The idea of setting keys in a selective manner again uses flags
-% wrapped around the basic code.
+% wrapped around the basic code. The comments on \cs{keys_set_known:nnN}
+% also apply here.
% \begin{macrocode}
-\cs_new_protected:Npn \keys_set_filter:nnnN #1#2#3#4
+\cs_new_protected_nopar:Npn \keys_set_filter:nnnN
+ { \@@_set_filter:onnnN \l_@@_unused_clist }
+\cs_generate_variant:Nn \keys_set_filter:nnnN { nnV , nnv , nno }
+\cs_new_protected:Npn \@@_set_filter:nnnnN #1#2#3#4#5
{
\clist_clear:N \l_@@_unused_clist
- \keys_set_filter:nnn {#1} {#2} {#3}
- \tl_set:Nx #4 { \exp_not:o { \l_@@_unused_clist } }
+ \keys_set_filter:nnn {#2} {#3} {#4}
+ \tl_set:Nx #5 { \exp_not:o { \l_@@_unused_clist } }
+ \tl_set:Nn \l_@@_unused_clist {#1}
}
-\cs_generate_variant:Nn \keys_set_filter:nnnN { nnV , nnv , nno }
+\cs_generate_variant:Nn \@@_set_filter:nnnnN { o }
\cs_new_protected:Npn \keys_set_filter:nnn #1#2#3
{
\bool_set_true:N \l_@@_selective_bool
@@ -1889,6 +1903,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}[int]{\@@_set_elt:n, \@@_set_elt:nn}
% \begin{macro}[aux]{\@@_set_elt_aux:nn}
@@ -2155,7 +2170,7 @@
{
\c_msg_coding_error_text_tl
Inside~\keys_define:nn each~key~name~
- needs~a~property: \\ \\
+ needs~a~property: \\ \\
\iow_indent:n { #1 .<property> } \\ \\
LaTeX~did~not~find~a~'.'~to~indicate~the~start~of~a~property.
}