diff options
author | Karl Berry <karl@freefriends.org> | 2011-09-16 22:35:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-09-16 22:35:41 +0000 |
commit | 6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch) | |
tree | 1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | |
parent | b7f762397f5df2d732326713423e31e1bf91b903 (diff) |
l3kernel 2828 (15sep11)
git-svn-id: svn://tug.org/texlive/trunk@23983 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | 202 |
1 files changed, 104 insertions, 98 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx index 631faf966d9..c2069873a77 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) 2009-2011 The LaTeX3 Project +%% File: l3keys.dtx Copyright (C) 2006-2011 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 @@ -9,7 +9,7 @@ %% %% http://www.latex-project.org/lppl.txt %% -%% This file is part of the "expl3 bundle" (The Work in LPPL) +%% This file is part of the "l3kernel bundle" (The Work in LPPL) %% and all files in that bundle must be distributed together. %% %% The released version of this bundle is available from CTAN. @@ -35,7 +35,7 @@ % %<*driver|package> \RequirePackage{l3names} -\GetIdInfo$Id: l3keys.dtx 2722 2011-09-05 08:49:40Z joseph $ +\GetIdInfo$Id: l3keys.dtx 2800 2011-09-10 16:54:36Z will $ {L3 Experimental key-value interfaces} %</driver|package> %<*driver> @@ -189,8 +189,8 @@ % does not exist, it will be created at the point that the key is % set up. The \meta{boolean} will be assigned globally. % \end{function} -% -% \begin{function}{.bool_set_inverse:N} +% +% \begin{function}[added = 2011-08-28]{.bool_set_inverse:N} % \begin{syntax} % \meta{key} .bool_set_inverse:N = \meta{boolean} % \end{syntax} @@ -199,7 +199,7 @@ % \texttt{false}). % If the \meta{boolean} does not exist, it will be created at the point % that the key is set up. The \meta{boolean} will be assigned locally. -% +% % \textbf{This property is experimental.} % \end{function} % @@ -212,7 +212,7 @@ % \texttt{false}). % If the \meta{boolean} does not exist, it will be created at the point % that the key is set up. The \meta{boolean} will be assigned globally. -% +% % \textbf{This property is experimental.} % \end{function} % @@ -224,8 +224,8 @@ % for \meta{key} must then be created, as discussed in % section~\ref{sec:choice}. % \end{function} -% -% \begin{function}{.choices:nn} +% +% \begin{function}[added = 2011-08-21]{.choices:nn} % \begin{syntax} % \meta{key} .choices:nn \meta{choices} \meta{code} % \end{syntax} @@ -235,7 +235,7 @@ % \cs{l_keys_choice_int} will be the position of the choice in the list % of \meta{choices} (indexed from $0$). % Choices are discussed in detail in section~\ref{sec:choice}. -% +% % \textbf{This property is experimental.} % \end{function} % @@ -251,6 +251,26 @@ % detail in section~\ref{sec:choice}. % \end{function} % +% \begin{function}[added=2011/09/11]{.clist_set:N, .clist_set:c} +% \begin{syntax} +% \meta{key} .clist_set:N = \meta{comma list variable} +% \end{syntax} +% Defines \meta{key} to locally set \meta{comma list variable} to \meta{value}. +% Spaces around commas and empty items will be stripped. +% If the variable does not exist, it +% will be created at the point that the key is set up. +% \end{function} +% +% \begin{function}[added=2011/09/11]{.clist_gset:N, .clist_gset:c} +% \begin{syntax} +% \meta{key} .clist_gset:N = \meta{comma list variable} +% \end{syntax} +% Defines \meta{key} to globally set \meta{comma list variable} to \meta{value}. +% Spaces around commas and empty items will be stripped. +% If the variable does not exist, it +% will be created at the point that the key is set up. +% \end{function} +% % \begin{function}{.code:n, .code:x} % \begin{syntax} % \meta{key} .code:n = \meta{code} @@ -365,19 +385,19 @@ % is used, then the value will be passed through to the subsidiary % \meta{keys} for processing (as |#1|). % \end{function} -% -% \begin{function}{.multichoice:} +% +% \begin{function}[added = 2011-08-21]{.multichoice:} % \begin{syntax} % \meta{key} .multichoice: % \end{syntax} % Sets \meta{key} to act as a multiple choice key. Each valid choice % for \meta{key} must then be created, as discussed in % section~\ref{sec:choice}. -% +% % \textbf{This property is experimental.} % \end{function} -% -% \begin{function}{.multichoice:nn} +% +% \begin{function}[added = 2011-08-21]{.multichoice:nn} % \begin{syntax} % \meta{key} .multichoice:nn \meta{choices} \meta{code} % \end{syntax} @@ -388,7 +408,7 @@ % \cs{l_keys_choice_int} will be the position of the choice in the list % of \meta{choices} (indexed from $0$). % Choices are discussed in detail in section~\ref{sec:choice}. -% +% % \textbf{This property is experimental.} % \end{function} % @@ -535,7 +555,7 @@ % indexed from $0$ (as an offset), so that the value of % \cs{l_keys_choice_int} for the first choice in a list will be % zero. -% +% % The same approach is also implemented by the \emph{experimental} % property \texttt{.choices:nn}. This combines the functionality of % \texttt{.choice_code:n} and \texttt{.generate_choices:n} into one @@ -550,7 +570,7 @@ % which~is~in~position~ % \int_use:N \l_keys_choice_int \c_space_tl % in~the~list. -% } +% } % } % \end{verbatim} % Note that the \texttt{.choices:nn} property should \emph{not} be mixed with @@ -584,7 +604,7 @@ % These variables do not have defined behaviour when used outside of % code created using \texttt{.generate_choices:n} % (\emph{i.e.}~anything might happen). -% +% % 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 @@ -599,7 +619,7 @@ % which~is~in~position~ % \int_use:N \l_keys_choice_int \c_space_tl % in~the~list. -% } +% } % } % \end{verbatim} % and @@ -615,28 +635,29 @@ % are valid. The \texttt{.multichoices:nn} property causes % \cs{l_keys_choice_tl} and \cs{l_keys_choice_int} to be set in exactly % the same way as described for \texttt{.choices:nn}. -% +% % When multiple choice keys are set, the value is treated as a comma-separated % list: % \begin{verbatim} % \keys_set:nn { module } % { % key = { a , b , c } % 'key' defined as a multiple choice -% } +% } %\end{verbatim} % Each choice will be applied in turn, with the usual handling of unknown % values. % % \section{Setting keys} % -% \begin{function}{\keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:no} +% \begin{function} +% {\keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:no} % \begin{syntax} % \cs{keys_set:nn} \Arg{module} \Arg{keyval list} % \end{syntax} % Parses the \meta{keyval list}, and sets those keys which are defined % for \meta{module}. The behaviour on finding an unknown key can be set % by defining a special \texttt{unknown} key: this will be illustrated -% later. +% later. % \end{function} % % If a key is not known, \cs{keys_set:nn} will look for a special @@ -661,19 +682,19 @@ % as \cs{l_keys_path_tl}. Note that this will have been processed % using \cs{tl_to_str:n}. % \end{variable} -% +% % \begin{variable}{\l_keys_value_tl} % When processing an unknown key, the value of the key is available as % \cs{l_keys_value_tl}. Note that this will be empty if no value was given % for the key. % \end{variable} -% +% % \section{Setting known keys only} -% +% % The functionality described in this section is experimental and may be % altered or removed, depending on feedback. % -% \begin{function} +% \begin{function}[added = 2011-08-23] % { % \keys_set_known:nnN, \keys_set_known:nVN, % \keys_set_known:nvN, \keys_set_known:noN @@ -692,19 +713,17 @@ % % \begin{function}[EXP,pTF]{\keys_if_exist:nn} % \begin{syntax} -% \cs{keys_if_exist_p:nn} \meta{module} \meta{key} -% \cs{keys_if_exist:nnTF} \meta{module} \meta{key} -% ~~\Arg{true code} \Arg{false code} +% \cs{keys_if_exist_p:nn} \meta{module} \meta{key} \\ +% \cs{keys_if_exist:nnTF} \meta{module} \meta{key} \Arg{true code} \Arg{false code} % \end{syntax} % Tests if the \meta{key} exists for \meta{module}, \emph{i.e.}~if any code % has been defined for \meta{key}. % \end{function} -% -% \begin{function}[EXP,pTF]{\keys_if_choice_exist:nn} +% +% \begin{function}[added = 2011-08-21,EXP,pTF]{\keys_if_choice_exist:nn} % \begin{syntax} -% \cs{keys_if_exist_p:nnn} \meta{module} \meta{key} \meta{choice} -% \cs{keys_if_exist:nnnTF} \meta{module} \meta{key} \meta{choice} -% ~~\Arg{true code} \Arg{false code} +% \cs{keys_if_exist_p:nnn} \meta{module} \meta{key} \meta{choice} \\ +% \cs{keys_if_exist:nnnTF} \meta{module} \meta{key} \meta{choice} \Arg{true code} \Arg{false code} % \end{syntax} % Tests if the \meta{choice} is defined for the \meta{key} within the % \meta{module},, \emph{i.e.}~if any code has been defined for @@ -761,10 +780,9 @@ % \end{verbatim} % are treated identically. % -% \begin{function}{\keyval_parse:NNn} +% \begin{function}[updated = 2011-09-08]{\keyval_parse:NNn} % \begin{syntax} -% \cs{keyval_parse:NNn} \meta{function1} \meta{function2} -% ~~\Arg{key--value list} +% \cs{keyval_parse:NNn} \meta{function1} \meta{function2} \Arg{key--value list} % \end{syntax} % Parses the \meta{key--value list} into a series of \meta{keys} and % associated \meta{values}, or keys alone (if no \meta{value} was @@ -788,10 +806,11 @@ % \end{verbatim} % Note that there is a difference between an empty value (an equals % sign followed by nothing) and a missing value (no equals sign at -% all). +% all). Spaces are trimmed from the ends of the \meta{key} and \meta{value}, +% and any \emph{outer} set of braces are removed from the \meta{value} as +% part of the processing. % \end{function} % -% % \end{documentation} % % \begin{implementation} @@ -928,42 +947,16 @@ % \end{macro} % % \begin{macro}{\keyval_split_key:w} -% \begin{macro}{\keyval_remove_spaces:w} -% \begin{macro}[aux]{\keyval_split_key_aux:w} -% \begin{macro}[aux]{\keyval_remove_spaces_aux:w} % The aim here is to remove spaces and also exactly one set of braces. -% The spaces are trimmed off from each end using a \enquote{funny} -% |Q|, which will never turn up in normal use. The idea is that -% the \texttt{f}-type expansion will stop if it finds an unexpandable -% token or a space, and will gobble the space. To avoid expanding -% anything else, the \cs{exp_not:N} works by ensuring that the first -% non-space token in the setting will stop the \texttt{f}-type -% expansion. The \cs{use_none:n} is needed to remove the leading -% quark, while the second setting of \cs{l_keyval_key_tl} -% removes exactly one set of braces. +% There is also a quark to remove, hence the \cs{use_none:n} appearing before +% application of \cs{tl_trim_spaces:n}. % \begin{macrocode} -\group_begin: - \char_set_catcode_math_toggle:n { `\Q } - \cs_new_protected:Npn \keyval_split_key:w #1 \q_stop - { - \exp_args:NNf \tl_set:Nn \l_keyval_key_tl - { - \exp_after:wN \keyval_remove_spaces:w \exp_after:wN - \exp_not:N \use_none:n #1 Q ~ Q - } - \tl_set:Nx \l_keyval_key_tl - { \exp_after:wN \keyval_split_key_aux:w \l_keyval_key_tl \q_stop } - } - \cs_gset:Npn \keyval_split_key_aux:w #1 \q_stop { \exp_not:n {#1} } - \cs_gset:Npn \keyval_remove_spaces:w #1 ~ Q - { \keyval_remove_spaces_aux:w #1 Q } - \cs_gset:Npn \keyval_remove_spaces_aux:w #1 Q #2 {#1} -\group_end: +\cs_new_protected:Npn \keyval_split_key:w #1 \q_stop + { + \tl_set:Nx \l_keyval_key_tl + { \exp_after:wN \tl_trim_spaces:n \exp_after:wN { \use_none:n #1 } } + } % \end{macrocode} -% Fixme: use \cs{tl_trim_spaces} instead of the aux function above? -% \end{macro} -% \end{macro} -% \end{macro} % \end{macro} % % \begin{macro}{\keyval_split_value:w} @@ -1002,16 +995,12 @@ % A similar idea to the key code: remove the spaces from each end and % deal with one set of braces. % \begin{macrocode} -\group_begin: - \char_set_catcode_math_toggle:n { `\Q } - \cs_new_protected:Npn \keyval_split_value_aux:w \q_nil #1 \q_stop - { - \exp_args:NNf \tl_set:Nn \l_keyval_value_tl - { \keyval_remove_spaces:w \exp_not:N #1 Q ~ Q } - \tl_put_right:Nx \l_keyval_parse_tl - { { \exp_not:o \l_keyval_value_tl } } - } -\group_end: +\cs_new_protected:Npn \keyval_split_value_aux:w \q_nil #1 \q_stop + { + \tl_set:Nx \l_keyval_value_tl { \tl_trim_spaces:n {#1} } + \tl_put_right:Nx \l_keyval_parse_tl + { { \exp_not:o \l_keyval_value_tl } } + } % \end{macrocode} % \end{macro} % @@ -1042,7 +1031,6 @@ } % \end{macrocode} % -% % \subsection{Constants and variables} % % \begin{variable}{\c_keys_code_root_tl, \c_keys_vars_root_tl} @@ -1114,7 +1102,7 @@ \tl_new:N \l_keys_property_tl % \end{macrocode} % \end{variable} -% +% % \begin{variable}{\l_keys_unknown_clist} % Used when setting only known keys to store those left over. % \begin{macrocode} @@ -1135,7 +1123,8 @@ % \begin{macro}[aux]{\keys_define_aux:nnn, \keys_define_aux:onn} % The public function for definitions is just a wrapper for the lower % level mechanism, more or less. The outer function is designed to -% keep a track of the current module, to allow safe nesting. +% keep a track of the current module, to allow safe nesting. The module is set +% removing any leading |/| (which is not needed here). % \begin{macrocode} \cs_new_protected:Npn \keys_define:nn { \keys_define_aux:onn \l_keys_module_tl } @@ -1262,7 +1251,7 @@ } % \end{macrocode} % \end{macro} -% +% % \begin{macro}[int]{\keys_bool_set_inverse:NN} % Inverse boolean setting is much the same. % \begin{macrocode} @@ -1300,7 +1289,7 @@ } % \end{macrocode} % \end{macro} -% +% % \begin{macro}[int]{\keys_choices_make:nn} % Auto-generating choices means setting up the root key as a choice, then % defining each choice in turn. @@ -1425,7 +1414,7 @@ } % \end{macrocode} % \end{macro} -% +% % \begin{macro}[int]{\keys_multichoice_find:n} % \begin{macro}[int]{\keys_multichoice_make:} % \begin{macro}[int]{\keys_multichoices_make:nn} @@ -1517,7 +1506,7 @@ % \end{macrocode} % \end{macro} % \end{macro} -% +% % \begin{macro}{.bool_set_inverse:N} % \begin{macro}{.bool_gset_inverse:N} % One function for this. @@ -1538,7 +1527,7 @@ { \keys_choice_make: } % \end{macrocode} % \end{macro} -% +% % \begin{macro}{.choices:nn} % For auto-generation of a series of mutually-exclusive choices. % Here, |#1| will consist of two separate @@ -1571,6 +1560,21 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{.clist_set:N, .clist_set:c} +% \begin{macro}{.clist_gset:N, .clist_gset:c} +% \begin{macrocode} +\cs_new_protected_nopar:cpn { \c_keys_props_root_tl .clist_set:N } #1 + { \keys_variable_set:NnN #1 { clist } n } +\cs_new_protected_nopar:cpn { \c_keys_props_root_tl .clist_set:c } #1 + { \keys_variable_set:cnN {#1} { clist } n } +\cs_new_protected_nopar:cpn { \c_keys_props_root_tl .clist_gset:N } #1 + { \keys_variable_set:NnNN #1 { clist } g n } +\cs_new_protected_nopar:cpn { \c_keys_props_root_tl .clist_gset:c } #1 + { \keys_variable_set:cnNN {#1} { clist } g n } +% \end{macrocode} +% \end{macro} +% \end{macro} +% % \begin{macro}{.default:n, .default:V} % Expansion is left to the internal functions. % \begin{macrocode} @@ -1646,7 +1650,7 @@ { \keys_meta_make:x {#1} } % \end{macrocode} % \end{macro} -% +% % \begin{macro}{.multichoice:} % \begin{macro}{.multichoices:nn} % The same idea as \texttt{.choice:} and \texttt{.choices:nn}, but @@ -1727,7 +1731,7 @@ { \keys_set_aux:onn { \l_keys_module_tl } } \cs_new_protected:Npn \keys_set_aux:nnn #1#2#3 { - \tl_set:Nn \l_keys_module_tl {#2} + \tl_set:Nx \l_keys_module_tl { \tl_to_str:n {#2} } \keyval_parse:NNn \keys_set_elt:n \keys_set_elt:nn {#3} \tl_set:Nn \l_keys_module_tl {#1} } @@ -1736,7 +1740,7 @@ % \end{macrocode} % \end{macro} % \end{macro} -% +% % \begin{macro} % { % \keys_set_known:nnN, \keys_set_known:nVN, @@ -1748,7 +1752,7 @@ { \keys_set_known_aux:onnN { \l_keys_module_tl } } \cs_new_protected:Npn \keys_set_known_aux:nnnN #1#2#3#4 { - \tl_set:Nn \l_keys_module_tl {#2} + \tl_set:Nx \l_keys_module_tl { \tl_to_str:n {#2} } \clist_clear:N \l_keys_unknown_clist \cs_set_eq:NN \keys_execute_unknown: \keys_execute_unknown_alt: \keyval_parse:NNn \keys_set_elt:n \keys_set_elt:nn {#3} @@ -1918,7 +1922,7 @@ } % \end{macrocode} % \end{macro} -% +% % \begin{macro}[EXP,pTF]{\keys_if_choice_exist:nnn} % Just an alternative view on \cs{keys_if_exist:nn(TF)}. % \begin{macrocode} @@ -2017,9 +2021,11 @@ % \begin{macro}{\KV_process_no_space_removal_no_sanitize:NNn} % There is just one function for this now. % \begin{macrocode} +%<*deprecated> \cs_new_eq:NN \KV_process_space_removal_sanitize:NNn \keyval_parse:NNn \cs_new_eq:NN \KV_process_space_removal_no_sanitize:NNn \keyval_parse:NNn \cs_new_eq:NN \KV_process_no_space_removal_no_sanitize:NNn \keyval_parse:NNn +%</deprecated> % \end{macrocode} % \end{macro} % \end{macro} @@ -2031,4 +2037,4 @@ % %\end{implementation} % -%\PrintIndex
\ No newline at end of file +%\PrintIndex |