summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3prop.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3prop.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3prop.dtx174
1 files changed, 95 insertions, 79 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3prop.dtx b/Master/texmf-dist/source/latex/l3kernel/l3prop.dtx
index 744cea629fc..0923121015d 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3prop.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3prop.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3prop.dtx 2478 2011-06-19 21:34:23Z joseph $
+\GetIdInfo$Id: l3prop.dtx 2665 2011-08-25 22:15:27Z joseph $
{L3 Experimental property lists}
%</driver|package>
%<*driver>
@@ -228,7 +228,8 @@
% variable}. If the \meta{key} is not found in the
% \meta{property list} then the \meta{token list variable} will
% contain the special marker \cs{q_no_value}. The \meta{token list
-% variable} is set within the current \TeX{} group.
+% variable} is set within the current \TeX{} group. See also
+% \cs{prop_get:NnNTF}.
% \end{function}
%
% \begin{function}{\prop_pop:NnN, \prop_pop:NoN, \prop_pop:cnN, \prop_pop:coN}
@@ -258,7 +259,7 @@
% The \meta{property list} is modified globally, while the assignment of
% the \meta{token list variable} is local.
% \end{function}
-%
+%%
% \section{Modifying property lists}
%
% \begin{function}{\prop_del:Nn, \prop_del:NV, \prop_del:cn, \prop_del:cV}
@@ -292,32 +293,62 @@
% \cs{prop_if_empty:NTF} \meta{property list}
% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{property list} is empty (containing no entries). The
-% branching versions then leave either \meta{true code} or
-% \meta{false code} in the input stream, as appropriate to the truth of
-% the test and the variant of the function chosen. The logical truth of
-% the test is left in the input stream by the predicate version.
+% Tests if the \meta{property list} is empty (containing no entries).
% \end{function}
%
-% \begin{function}[EXP,pTF]{
-% \prop_if_in:Nn, \prop_if_in:NV, \prop_if_in:No,
-% \prop_if_in:cn, \prop_if_in:cV, \prop_if_in:co
-% }
+% \begin{function}[EXP,pTF]
+% {
+% \prop_if_in:Nn, \prop_if_in:NV, \prop_if_in:No,
+% \prop_if_in:cn, \prop_if_in:cV, \prop_if_in:co
+% }
% \begin{syntax}
% \cs{prop_if_in:NnTF} \meta{property list} \Arg{key}
% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
% Tests if the \meta{key} is present in the \meta{property list},
% making the comparison using the method described by \cs{str_if_eq:nnTF}.
-% Either the \meta{true code} or \meta{false code} in the input stream, as
-% appropriate to the truth of the test and the variant of the function
-% chosen.
% \begin{texnote}
% This function iterates through every key--value pair in the
% \meta{property list} and is therefore slower than using the
% non-expandable \cs{prop_get:NnNTF}.
% \end{texnote}
% \end{function}
+%
+% \section{Recovering values from property lists with branching}
+%
+% The functions in this section combine tests for the presence of a key
+% in a property list with recovery of the associated valued. This makes them
+% useful for cases where different cases follow dependent on the presence
+% or absence of a key in a property list. They offer increased readability
+% and performance over separate testing and recovery phases.
+%
+% \begin{function}[TF]{\prop_get:NnN, \prop_get:cnN}
+% \begin{syntax}
+% \cs{prop_get:NnNTF} \meta{property list} \Arg{key}
+% ~~\meta{token list variable} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% If the \meta{key} is not present in the \meta{property list}, leaves
+% the \meta{false code} in the input stream and leaves the
+% \meta{token list variable} unchanged. If the \meta{key} is present in
+% the \meta{property list}, stores the corresponding \meta{value}
+% in the \meta{token list variable} without removing it from the
+% \meta{property list}. The \meta{token list variable} is assigned locally.
+% \end{function}
+%
+% \begin{function}[TF]{\prop_pop:NnN, \prop_pop:cnN}
+% \begin{syntax}
+% \cs{prop_pop:NnNTF} \meta{property list} \Arg{key}
+% ~~\meta{token list variable} \Arg{true code} \Arg{false code}
+% \end{syntax}
+% If the \meta{key} is not present in the \meta{property list}, leaves
+% the \meta{false code} in the input stream and leaves the
+% \meta{token list variable} unchanged. If the \meta{key} is present in
+% the \meta{property list}, pops the corresponding \meta{value}
+% in the \meta{token list variable}, \emph{i.e.}~removes the item from
+% the \meta{property list}.
+% Both the \meta{property list} and the \meta{token list variable}
+% are assigned locally.
+% \end{function}
%
% \section{Mapping to property lists}
%
@@ -401,36 +432,7 @@
% This section contains functions which may or may not be retained, depending
% on how useful they are found to be.
%
-% \begin{function}[TF]{\prop_get:NnN}
-% \begin{syntax}
-% \cs{prop_get:NnNTF} \meta{property list} \Arg{key}
-% ~~\meta{token list variable} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% If the \meta{key} is not present in the \meta{property list}, leaves
-% the \meta{false code} in the input stream and leaves the
-% \meta{token list variable} unchanged. If the \meta{key} is present in
-% the \meta{property list}, stores the corresponding \meta{value}
-% in the \meta{token list variable} without removing it from the
-% \meta{property list}. The \meta{true code} is then left in the input
-% stream. The \meta{token list variable} is assigned locally.
-% \end{function}
-%
-% \begin{function}[TF]{\prop_pop:NnN}
-% \begin{syntax}
-% \cs{prop_pop:NnNTF} \meta{property list} \Arg{key}
-% ~~\meta{token list variable} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% If the \meta{key} is not present in the \meta{property list}, leaves
-% the \meta{false code} in the input stream and leaves the
-% \meta{token list variable} unchanged. If the \meta{key} is present in
-% the \meta{property list}, pops the corresponding \meta{value}
-% in the \meta{token list variable}, \emph{i.e.}~removes the item from
-% the \meta{property list}. The \meta{true code} is then left in the input
-% stream. Both the \meta{property list} and the \meta{token list variable}
-% are assigned locally.
-% \end{function}
-%
-% \begin{function}[TF]{\prop_gpop:NnN}
+% \begin{function}[TF]{\prop_gpop:NnN, \prop_gpop:cnN}
% \begin{syntax}
% \cs{prop_gpop:NnNTF} \meta{property list} \Arg{key}
% ~~\meta{token list variable} \Arg{true code} \Arg{false code}
@@ -440,12 +442,12 @@
% \meta{token list variable} unchanged. If the \meta{key} is present in
% the \meta{property list}, pops the corresponding \meta{value}
% in the \meta{token list variable}, \emph{i.e.}~removes the item from
-% the \meta{property list}. The \meta{true code} is then left in the input
-% stream. The \meta{property list} is modified globally, while the
+% the \meta{property list}.
+% The \meta{property list} is modified globally, while the
% \meta{token list variable} is assigned locally.
% \end{function}
%
-% \begin{function}[EXP]{\prop_map_tokens:Nn}
+% \begin{function}[EXP]{\prop_map_tokens:Nn, \prop_map_tokens:cn}
% \begin{syntax}
% \cs{prop_map_tokens:Nn} \meta{property list} \Arg{code}
% \end{syntax}
@@ -454,7 +456,7 @@
% property list while keeping track of a given key.
% \end{function}
%
-% \begin{function}[EXP]{\prop_get:Nn}
+% \begin{function}[EXP]{\prop_get:Nn, \prop_get:cn}
% \begin{syntax}
% \cs{prop_get:Nn} \meta{property list} \Arg{key}
% \end{syntax}
@@ -920,6 +922,32 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
+%
+% \subsection{Recovering values from property lists with branching}
+%
+% \begin{macro}[TF]{\prop_get:NnN, \prop_get:cnN}
+% \begin{macro}[aux]{\prop_get_aux_true:Nnnn}
+% Getting the value corresponding to a key, keeping track of whether
+% the key was present or not, is implemented as a conditional (with
+% side effects). If the key was absent, the token list is not altered.
+% \begin{macrocode}
+\prg_new_protected_conditional:Npnn \prop_get:NnN #1#2#3 { T , F , TF }
+ {
+ \prop_split:NnTF #1 {#2}
+ { \prop_get_aux_true:Nnnn #3 }
+ { \prg_return_false: }
+ }
+\cs_new_protected:Npn \prop_get_aux_true:Nnnn #1#2#3#4
+ {
+ \tl_set:Nn #1 {#3}
+ \prg_return_true:
+ }
+\cs_generate_variant:Nn \prop_get:NnNT { c }
+\cs_generate_variant:Nn \prop_get:NnNF { c }
+\cs_generate_variant:Nn \prop_get:NnNTF { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
%
% \subsection{Mapping to property lists}
%
@@ -1043,28 +1071,8 @@
%
% \subsection{Experimental functions}
%
-% \begin{macro}[TF]{\prop_get:NnN}
-% \begin{macro}[aux]{\prop_get_aux_true:Nnnn}
-% Getting the value corresponding to a key, keeping track of whether
-% the key was present or not, is implemented as a conditional (with
-% side effects). If the key was absent, the token list is not altered.
-% \begin{macrocode}
-\prg_new_protected_conditional:Npnn \prop_get:NnN #1#2#3 { T , F , TF }
- {
- \prop_split:NnTF #1 {#2}
- { \prop_get_aux_true:Nnnn #3 }
- { \prg_return_false: }
- }
-\cs_new_protected:Npn \prop_get_aux_true:Nnnn #1#2#3#4
- {
- \tl_set:Nn #1 {#3}
- \prg_return_true:
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[TF]{\prop_pop:NnN,\prop_gpop:NnN}
+% \begin{macro}[TF]
+% {\prop_pop:NnN, \prop_pop:cnN, \prop_gpop:cnN, \prop_gpop:cnN}
% \begin{macro}[aux]{\prop_pop_aux_true:NNNnnn}
% Popping an item from a property list, keeping track of whether
% the key was present or not, is implemented as a conditional.
@@ -1072,13 +1080,13 @@
% list are altered. Otherwise, \cs{prg_return_true:} is used after
% the assignments.
% \begin{macrocode}
-\prg_new_protected_conditional:Npnn \prop_pop:NnN #1#2#3 {T,F,TF}
+\prg_new_protected_conditional:Npnn \prop_pop:NnN #1#2#3 { T , F , TF }
{
\prop_split:NnTF #1 {#2}
{ \prop_pop_aux_true:NNNnnn \tl_set:Nn #1 #3 }
{ \prg_return_false: }
}
-\prg_new_protected_conditional:Npnn \prop_gpop:NnN #1#2#3 {T,F,TF}
+\prg_new_protected_conditional:Npnn \prop_gpop:NnN #1#2#3 { T , F , TF }
{
\prop_split:NnTF #1 {#2}
{ \prop_pop_aux_true:NNNnnn \tl_gset:Nn #1 #3 }
@@ -1090,11 +1098,17 @@
#1 #2 { #4 #6 }
\prg_return_true:
}
+\cs_generate_variant:Nn \prop_pop:NnNT { c }
+\cs_generate_variant:Nn \prop_pop:NnNF { c }
+\cs_generate_variant:Nn \prop_pop:NnNTF { c }
+\cs_generate_variant:Nn \prop_gpop:NnNT { c }
+\cs_generate_variant:Nn \prop_gpop:NnNF { c }
+\cs_generate_variant:Nn \prop_gpop:NnNTF { c }
% \end{macrocode}
% \end{macro}
% \end{macro}
%
-% \begin{macro}[EXP]{\prop_map_tokens:Nn}
+% \begin{macro}[EXP]{\prop_map_tokens:Nn, \prop_map_tokens:cn}
% \begin{macro}[aux]{\prop_map_tokens_aux:nwn}
% The mapping grabs one key--value pair at a time, and stops when
% reaching the marker key |A|, with catcode \enquote{letter}, which
@@ -1114,24 +1128,26 @@
\use:n {#1} {#2} {#3}
\prop_map_tokens_aux:nwn {#1}
}
+\cs_generate_variant:Nn \prop_map_tokens:Nn { c }
% \end{macrocode}
% \end{macro}
% \end{macro}
%
-% \begin{macro}[EXP]{\prop_get:Nn}
+% \begin{macro}[EXP]{\prop_get:Nn, \prop_get:Nn}
% \begin{macro}[aux]{\prop_get_aux:nnn}
-% Getting expandably the value corresponding to a key in a property list
-% is a simple instance of mapping some tokens.
+% Getting the value corresponding to a key in a property list in an
+% expandable fashion is a simple instance of mapping some tokens.
% Map the function \cs{prop_get_aux:nnn} which takes as its three
% arguments the \meta{key} that we are looking for, the current
% \meta{key} and the current \meta{value}. If the \meta{keys} match,
% the \meta{value} is returned. If none of the keys match, this expands
% to nothing.
% \begin{macrocode}
-\cs_new:Npn \prop_get:Nn #1 #2
+\cs_new:Npn \prop_get:Nn #1#2
{ \prop_map_tokens:Nn #1 { \prop_get_aux:nnn {#2} } }
-\cs_new:Npn \prop_get_aux:nnn #1 #2 #3
+\cs_new:Npn \prop_get_aux:nnn #1#2#3
{ \str_if_eq:nnT {#1} {#2} { \prop_map_break:n {#3} } }
+\cs_generate_variant:Nn \prop_get:Nn { c }
% \end{macrocode}
% \end{macro}
% \end{macro}