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