summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-07-12 22:54:42 +0000
committerKarl Berry <karl@freefriends.org>2013-07-12 22:54:42 +0000
commit60ede63177ff54dd8d1934012fbecce179a633ee (patch)
tree9dbd9e4608c9a0caa9864fedf49f0a2aea36fedf /Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
parentc2d4fa6f59f3c566ccd85e3b250f0a27485bbaea (diff)
l3 (12jul13)
git-svn-id: svn://tug.org/texlive/trunk@31181 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3seq.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3seq.dtx114
1 files changed, 111 insertions, 3 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
index e917aeda4ea..82c08c35f60 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3seq.dtx 4434 2013-01-12 09:33:40Z bruno $
+\GetIdInfo$Id: l3seq.dtx 4500 2013-05-26 11:18:19Z bruno $
{L3 Sequences and stacks}
%</driver|package>
%<*driver>
@@ -253,7 +253,7 @@
% \end{syntax}
% Pops the right-most item from a \meta{sequence} into the
% \meta{token list variable}, \emph{i.e.}~removes the item from the
-% sequence and stores it in in the \meta{token list variable}.
+% sequence and stores it in the \meta{token list variable}.
% Both of the variables are assigned locally. If \meta{sequence} is
% empty the \meta{token list variable} will
% contain the special marker \cs{q_no_value}.
@@ -536,6 +536,64 @@
% \emph{i.e.}~every item in a \meta{sequence} is unique.
% \end{function}
%
+% \section{Using the content of sequences directly}
+%
+% \begin{function}[EXP, added = 2013-05-26]{\seq_use:Nnnn, \seq_use:cnnn}
+% \begin{syntax}
+% \cs{seq_use:Nnnn} \meta{seq~var} \Arg{separator~between~two} \Arg{separator~between~more~than~two} \Arg{separator~between~final~two}
+% \end{syntax}
+% Places the contents of the \meta{seq~var} in the input stream, with
+% the appropriate \meta{separator} between the items. Namely, if the
+% sequence has more than two items, the \meta{separator between more
+% than two} is placed between each pair of items except the last,
+% for which the \meta{separator between final two} is used. If the
+% sequence has exactly two items, then they are placed in the input stream
+% separated by the \meta{separator between two}. If the sequence has
+% a single item, it is placed in the input stream, and an empty sequence
+% produces no output. An error will be raised if the variable does
+% not exist or if it is invalid.
+%
+% For example,
+% \begin{verbatim}
+% \seq_set_split:Nnn \l_tmpa_seq { | } { a | b | c | {de} | f }
+% \seq_use:Nnnn \l_tmpa_seq { ~and~ } { ,~ } { ,~and~ }
+% \end{verbatim}
+% will insert \enquote{\texttt{a, b, c, de, and f}} in the input
+% stream. The first separator argument is not used in this case
+% because the sequence has more than $2$ items.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the \meta{items}
+% will not expand further when appearing in an \texttt{x}-type
+% argument expansion.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[EXP, added = 2013-05-26]{\seq_use:Nn, \seq_use:cn}
+% \begin{syntax}
+% \cs{seq_use:Nn} \meta{seq~var} \Arg{separator}
+% \end{syntax}
+% Places the contents of the \meta{seq~var} in the input stream, with
+% the \meta{separator} between the items. If the sequence has
+% a single item, it is placed in the input stream with no \meta{separator},
+% and an empty sequence produces no output. An error will be raised if
+% the variable does not exist or if it is invalid.
+%
+% For example,
+% \begin{verbatim}
+% \seq_set_split:Nnn \l_tmpa_seq { | } { a | b | c | {de} | f }
+% \seq_use:Nn \l_tmpa_seq { ~and~ }
+% \end{verbatim}
+% will insert \enquote{\texttt{a and b and c and de and f}} in the input
+% stream.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the \meta{items}
+% will not expand further when appearing in an \texttt{x}-type
+% argument expansion.
+% \end{texnote}
+% \end{function}
+%
% \section{Sequences as stacks}
%
% Sequences can be used as stacks, where data is pushed to and popped
@@ -1464,6 +1522,56 @@
% \end{macro}
% \end{macro}
%
+% \subsection{Using sequences}
+%
+% \begin{macro}[EXP]{\seq_use:Nnnn, \seq_use:cnnn}
+% \begin{macro}[EXP, aux]
+% {\@@_use:NnNnn, \@@_use:nwwwwnwn, \@@_use:nwwn}
+% \begin{macro}[EXP]{\seq_use:Nn, \seq_use:cn}
+% See \cs{clist_use:Nnnn} for a general explanation. The main
+% difference is that we use \cs{@@_item:n} as a delimiter rather than
+% commas. We also need to add \cs{@@_item:n} at various places.
+% \begin{macrocode}
+\cs_new:Npn \seq_use:Nnnn #1#2#3#4
+ {
+ \seq_if_exist:NTF #1
+ {
+ \int_case:nnn { \seq_count:N #1 }
+ {
+ { 0 } { }
+ { 1 } { \exp_after:wN \@@_use:NnNnn #1 \@@_item:n { } { } }
+ { 2 } { \exp_after:wN \@@_use:NnNnn #1 {#2} }
+ }
+ {
+ \exp_after:wN \@@_use:nwwwwnwn
+ \exp_after:wN { \exp_after:wN } #1 \@@_item:n
+ \q_mark { \@@_use:nwwwwnwn {#3} }
+ \q_mark { \@@_use:nwwn {#4} }
+ \q_stop { }
+ }
+ }
+ { \__msg_kernel_expandable_error:nnn { kernel } { bad-variable } {#1} }
+ }
+\cs_generate_variant:Nn \seq_use:Nnnn { c }
+\cs_new:Npn \@@_use:NnNnn \@@_item:n #1 \@@_item:n #2#3
+ { \exp_not:n { #1 #3 #2 } }
+\cs_new:Npn \@@_use:nwwwwnwn
+ #1 \@@_item:n #2 \@@_item:n #3 \@@_item:n #4#5
+ \q_mark #6#7 \q_stop #8
+ {
+ #6 \@@_item:n {#3} \@@_item:n {#4} #5
+ \q_mark {#6} #7 \q_stop { #8 #1 #2 }
+ }
+\cs_new:Npn \@@_use:nwwn #1 \@@_item:n #2 #3 \q_stop #4
+ { \exp_not:n { #4 #1 #2 } }
+\cs_new:Npn \seq_use:Nn #1#2
+ { \seq_use:Nnnn #1 {#2} {#2} {#2} }
+\cs_generate_variant:Nn \seq_use:Nn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \subsection{Sequence stacks}
%
% The same functions as for sequences, but with the correct naming.
@@ -1610,7 +1718,7 @@
% A simple short cut for a mapping.
% \begin{macrocode}
%<*deprecated>
-\cs_new:Npn \seq_use:N #1 { \seq_map_function:NN #1 \use:n }
+\cs_new:Npn \seq_use:N #1 { \seq_use:Nn #1 { } }
\cs_generate_variant:Nn \seq_use:N { c }
%</deprecated>
% \end{macrocode}