summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
committerKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
commit6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch)
tree1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
parentb7f762397f5df2d732326713423e31e1bf91b903 (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.dtx202
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