diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | 129 |
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. } |