summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3toks.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3toks.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3toks.dtx548
1 files changed, 548 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3toks.dtx b/Master/texmf-dist/source/latex/l3kernel/l3toks.dtx
new file mode 100644
index 00000000000..62824848afc
--- /dev/null
+++ b/Master/texmf-dist/source/latex/l3kernel/l3toks.dtx
@@ -0,0 +1,548 @@
+% \iffalse meta-comment
+%
+%% File: l3toks.dtx Copyright (C) 1990-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
+%% license or (at your option) any later version. The latest version
+%% of this license is in the file
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% This file is part of the "expl3 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.
+%%
+%% -----------------------------------------------------------------------
+%%
+%% The development version of the bundle can be found at
+%%
+%% http://www.latex-project.org/svnroot/experimental/trunk/
+%%
+%% for those people who are interested.
+%%
+%%%%%%%%%%%
+%% NOTE: %%
+%%%%%%%%%%%
+%%
+%% Snapshots taken from the repository represent work in progress and may
+%% not work or may contain conflicting material! We therefore ask
+%% people _not_ to put them into distributions, archives, etc. without
+%% prior consultation with the LaTeX3 Project.
+%%
+%% -----------------------------------------------------------------------
+%
+%<*driver|package>
+\RequirePackage{l3names}
+\GetIdInfo$Id: l3toks.dtx 2478 2011-06-19 21:34:23Z joseph $
+ {L3 Experimental token registers}
+%</driver|package>
+%<*driver>
+\documentclass[full]{l3doc}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \pkg{l3toks} package\\ Token registers^^A
+% \thanks{This file describes v\ExplFileVersion,
+% last revised \ExplFileDate.}^^A
+% }
+%
+% \author{^^A
+% The \LaTeX3 Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released \ExplFileDate}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \textbf{THIS ENTIRE MODULE IS DEPRECIATED: DO NOT USE \cs{TOKS_\ldots}
+% FUNCTIONS}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3toks} implementation}
+%
+% We start by ensuring that the required packages are loaded.
+% \begin{macrocode}
+%<*package>
+\ProvidesExplPackage
+ {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
+\package_check_loaded_expl:
+%</package>
+%<*initex|package>
+% \end{macrocode}
+%
+% \subsection{Allocation and use}
+%
+% \begin{macro}{\toks_new:N,\toks_new:c}
+% Allocates a new token register.
+% \begin{macrocode}
+%<*initex>
+\alloc_new:nnnN {toks} \c_zero \c_max_register_int \tex_toksdef:D
+%</initex>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<*package>
+\cs_new_protected_nopar:Npn \toks_new:N #1 {
+ \chk_if_free_cs:N #1
+ \newtoks #1
+}
+%</package>
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_new:N {c}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\toks_use:N}
+% \begin{macro}{\toks_use:c}
+% This function returns the contents of a token register.
+% \begin{macrocode}
+\cs_new_eq:NN \toks_use:N \tex_the:D
+\cs_generate_variant:Nn \toks_use:N {c}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_set:Nn}
+% \begin{macro}{\toks_set:NV}
+% \begin{macro}{\toks_set:Nv}
+% \begin{macro}{\toks_set:No}
+% \begin{macro}{\toks_set:Nx}
+% \begin{macro}{\toks_set:Nf}
+% \begin{macro}{\toks_set:cn}
+% \begin{macro}{\toks_set:co}
+% \begin{macro}{\toks_set:cV}
+% \begin{macro}{\toks_set:cv}
+% \begin{macro}{\toks_set:cx}
+% \begin{macro}{\toks_set:cf}
+% |\toks_set:Nn|\m{toks}\m{stuff} stores \m{stuff} without expansion
+% in \m{toks}. |\toks_set:No| and |\toks_set:Nx| expand \m{stuff} once
+% and fully.
+% \begin{macrocode}
+%<*check>
+\cs_new_protected_nopar:Npn \toks_set:Nn #1 { \chk_local:N #1 #1 }
+\cs_generate_variant:Nn \toks_set:Nn {No,Nf}
+%</check>
+% \end{macrocode}
+% If we don't check if \m{toks} is a local register then the
+% |\toks_set:Nn| function has nothing to do.
+% We implement |\toks_set:No|/|d|/|f| by hand when not checking because this
+% is going to be used \emph{extensively} in keyval processing!
+% TODO: (Will) Can we get some numbers published on how necessary this is?
+% On the other hand I'm happy to believe Morten |:)|
+% \begin{macrocode}
+%<*!check>
+\cs_new_eq:NN \toks_set:Nn \prg_do_nothing:
+\cs_new_protected:Npn \toks_set:NV #1#2 {
+ #1 \exp_after:wN { \int_to_roman:w -`0 \exp_eval_register:N #2 }
+}
+\cs_new_protected:Npn \toks_set:Nv #1#2 {
+ #1 \exp_after:wN { \int_to_roman:w -`0 \exp_eval_register:c {#2} }
+}
+\cs_new_protected:Npn \toks_set:No #1#2 { #1 \exp_after:wN {#2} }
+\cs_new_protected:Npn \toks_set:Nf #1#2 {
+ #1 \exp_after:wN { \int_to_roman:w -`0#2 }
+}
+%</!check>
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_set:Nn {Nx,cn,cV,cv,co,cx,cf}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_gset:Nn}
+% \begin{macro}{\toks_gset:NV}
+% \begin{macro}{\toks_gset:No}
+% \begin{macro}{\toks_gset:Nx}
+% \begin{macro}{\toks_gset:cn}
+% \begin{macro}{\toks_gset:cV}
+% \begin{macro}{\toks_gset:co}
+% \begin{macro}{\toks_gset:cx}
+% These functions are the global variants of the above.
+% \begin{macrocode}
+%<check>\cs_new_protected_nopar:Npn \toks_gset:Nn #1 { \chk_global:N #1 \pref_global:D #1 }
+%<!check>\cs_new_eq:NN \toks_gset:Nn \pref_global:D
+\cs_generate_variant:Nn \toks_gset:Nn {NV,No,Nx,cn,cV,co,cx}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_set_eq:NN}
+% \begin{macro}{\toks_set_eq:Nc}
+% \begin{macro}{\toks_set_eq:cN}
+% \begin{macro}{\toks_set_eq:cc}
+% \begin{macro}{\toks_gset_eq:NN}
+% \begin{macro}{\toks_gset_eq:Nc}
+% \begin{macro}{\toks_gset_eq:cN}
+% \begin{macro}{\toks_gset_eq:cc}
+% |\toks_set_eq:NN|\m{toks1}\m{toks2} copies the contents of \m{toks2}
+% in \m{toks1}.
+% \begin{macrocode}
+%<*check>
+\cs_new_protected_nopar:Npn\toks_set_eq:NN #1#2 {
+ \chk_local:N #1
+ \chk_var_or_const:N #2
+ #1 #2
+}
+\cs_new_protected_nopar:Npn\toks_gset_eq:NN #1#2 {
+ \chk_global:N #1
+ \chk_var_or_const:N #2
+ \pref_global:D #1 #2
+}
+%</check>
+%<*!check>
+\cs_new_eq:NN \toks_set_eq:NN \prg_do_nothing:
+\cs_new_eq:NN \toks_gset_eq:NN \pref_global:D
+%</!check>
+\cs_generate_variant:Nn \toks_set_eq:NN {Nc,cN,cc}
+\cs_generate_variant:Nn \toks_gset_eq:NN {Nc,cN,cc}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_clear:N,\toks_gclear:N,\toks_clear:c,\toks_gclear:c}
+% These functions clear a token register, either locally or globally.
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_clear:N #1 {
+ #1\c_empty_toks
+%<check>\chk_local_or_pref_global:N #1
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_gclear:N {
+%<check> \pref_global_chk:
+%<!check> \pref_global:D
+ \toks_clear:N
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_clear:N {c}
+\cs_generate_variant:Nn \toks_gclear:N {c}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\toks_use_clear:N}
+% \begin{macro}{\toks_use_clear:c}
+% \begin{macro}{\toks_use_gclear:N}
+% \begin{macro}{\toks_use_gclear:c}
+% These functions clear a token register (locally or globally) after
+% returning the contents.
+%
+% They make sure that clearing the register does not
+% interfere with following tokens. In other words, the contents of
+% the register might operate on what follows in the input stream.
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_use_clear:N #1 {
+ \exp_last_unbraced:NNV \toks_clear:N #1 #1
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_use_gclear:N {
+%<check> \pref_global_chk:
+%<!check> \pref_global:D
+ \toks_use_clear:N
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_use_clear:N {c}
+\cs_generate_variant:Nn \toks_use_gclear:N {c}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_show:N}
+% \begin{macro}{\toks_show:c}
+% This function shows the contents of a token register on the terminal.
+% \begin{macrocode}
+\cs_new_eq:NN \toks_show:N \kernel_register_show:N
+\cs_generate_variant:Nn \toks_show:N {c}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Adding to token registers' contents}
+%
+% \begin{macro}{\toks_put_left:Nn}
+% \begin{macro}{\toks_put_left:NV}
+% \begin{macro}{\toks_put_left:No}
+% \begin{macro}{\toks_put_left:Nx}
+% \begin{macro}{\toks_put_left:cn}
+% \begin{macro}{\toks_put_left:cV}
+% \begin{macro}{\toks_put_left:co}
+% \begin{macro}{\toks_gput_left:Nn}
+% \begin{macro}{\toks_gput_left:NV}
+% \begin{macro}{\toks_gput_left:No}
+% \begin{macro}{\toks_gput_left:Nx}
+% \begin{macro}{\toks_gput_left:cn}
+% \begin{macro}{\toks_gput_left:cV}
+% \begin{macro}{\toks_gput_left:co}
+% \begin{macro}[aux]{\toks_put_left_aux:w}
+% |\toks_put_left:Nn |\meta{toks}\meta{stuff\/} adds the tokens of
+% \textsl{stuff} on the `left-side' of the token register
+% \m{toks}. |\toks_put_left:No| does the same, but expands the
+% tokens once. We need to look out for brace stripping so we add a
+% token, which is then later removed.
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_put_left:Nn #1 {
+ \exp_after:wN \toks_put_left_aux:w \exp_after:wN \q_nil
+ \toks_use:N #1 \q_stop #1
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_put_left:Nn {NV,No,Nx,cn,co,cV}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_gput_left:Nn {
+%<check> \pref_global_chk:
+%<!check> \pref_global:D
+ \toks_put_left:Nn
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_gput_left:Nn {NV,No,Nx,cn,cV,co}
+% \end{macrocode}
+% A helper function for |\toks_put_left:Nn|. Its arguments are
+% subsequently the tokens of \meta{stuff\/}, the token register
+% \meta{toks} and the current contents of \meta{toks}. We make sure to
+% remove the token we inserted earlier.
+% \begin{macrocode}
+\cs_new:Npn \toks_put_left_aux:w #1\q_stop #2#3 {
+ #2 \exp_after:wN { \use_i:nn {#3} #1 }
+%<check> \chk_local_or_pref_global:N #2
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_put_right:Nn}
+% \begin{macro}{\toks_put_right:NV}
+% \begin{macro}{\toks_put_right:No}
+% \begin{macro}{\toks_put_right:Nx}
+% \begin{macro}{\toks_put_right:cn}
+% \begin{macro}{\toks_put_right:cV}
+% \begin{macro}{\toks_put_right:co}
+% \begin{macro}{\toks_gput_right:Nn}
+% \begin{macro}{\toks_gput_right:NV}
+% \begin{macro}{\toks_gput_right:No}
+% \begin{macro}{\toks_gput_right:Nx}
+% \begin{macro}{\toks_gput_right:cn}
+% \begin{macro}{\toks_gput_right:cV}
+% \begin{macro}{\toks_gput_right:co}
+% These macros add a list of tokens to the right of a token register.
+% \begin{macrocode}
+\cs_new_protected:Npn \toks_put_right:Nn #1#2 {
+ #1 \exp_after:wN { \toks_use:N #1 #2 }
+%<check> \chk_local_or_pref_global:N #1
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected_nopar:Npn \toks_gput_right:Nn {
+%<check> \pref_global_chk:
+%<!check> \pref_global:D
+ \toks_put_right:Nn
+}
+% \end{macrocode}
+% A couple done by hand for speed.
+% \begin{macrocode}
+%<check>\cs_generate_variant:Nn \toks_put_right:Nn {No}
+%<*!check>
+\cs_new_protected:Npn \toks_put_right:NV #1#2 {
+ #1 \exp_after:wN \exp_after:wN \exp_after:wN {
+ \exp_after:wN \toks_use:N \exp_after:wN #1
+ \int_to_roman:w -`0 \exp_eval_register:N #2
+ }
+}
+\cs_new_protected:Npn \toks_put_right:No #1#2 {
+ #1 \exp_after:wN \exp_after:wN \exp_after:wN {
+ \exp_after:wN \toks_use:N \exp_after:wN #1 #2
+ }
+}
+%</!check>
+\cs_generate_variant:Nn \toks_put_right:Nn {Nx,cn,cV,co}
+\cs_generate_variant:Nn \toks_gput_right:Nn {NV,No,Nx,cn,cV,co}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_put_right:Nf}
+% We implement |\toks_put_right:Nf| by hand because I think I might
+% use it in the \textsf{l3keyval} module in which case it is going to
+% be used a lot.
+% \begin{macrocode}
+%<check>\cs_generate_variant:Nn \toks_put_right:Nn {Nf}
+%<*!check>
+\cs_new_protected:Npn \toks_put_right:Nf #1#2 {
+ #1 \exp_after:wN \exp_after:wN \exp_after:wN {
+ \exp_after:wN \toks_use:N \exp_after:wN #1 \int_to_roman:w -`0#2
+ }
+}
+%</!check>
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Predicates and conditionals}
+%
+% \begin{macro}{\toks_if_empty_p:N,\toks_if_empty_p:c}
+% \begin{macro}[TF]{\toks_if_empty:N,\toks_if_empty:c}
+% |\toks_if_empty:NTF|\m{toks}\m{true code}\m{false code} tests if a
+% token register is empty and executes either \m{true code} or
+% \m{false code}. This test had the advantage of being
+% expandable. Otherwise one has to do an |x| type expansion in order
+% to prevent problems with parameter tokens.
+% \begin{macrocode}
+\prg_new_conditional:Nnn \toks_if_empty:N {p,TF,T,F} {
+ \tl_if_empty:VTF #1 {\prg_return_true:} {\prg_return_false:}
+}
+% \end{macrocode}
+% \begin{macrocode}
+\cs_generate_variant:Nn \toks_if_empty_p:N {c}
+\cs_generate_variant:Nn \toks_if_empty:NTF {c}
+\cs_generate_variant:Nn \toks_if_empty:NT {c}
+\cs_generate_variant:Nn \toks_if_empty:NF {c}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\toks_if_eq_p:NN,\toks_if_eq_p:cN,\toks_if_eq_p:Nc,\toks_if_eq_p:cc}
+% \begin{macro}[TF]{\toks_if_eq:NN,\toks_if_eq:Nc,\toks_if_eq:cN,\toks_if_eq:cc}
+% This function test whether two token registers have the same contents.
+% \begin{macrocode}
+\prg_new_conditional:Nnn \toks_if_eq:NN {p,TF,T,F} {
+ \str_if_eq:xxTF {\toks_use:N #1} {\toks_use:N #2}
+ {\prg_return_true:} {\prg_return_false:}
+}
+\cs_generate_variant:Nn \toks_if_eq_p:NN {Nc,c,cc}
+\cs_generate_variant:Nn \toks_if_eq:NNTF {Nc,c,cc}
+\cs_generate_variant:Nn \toks_if_eq:NNT {Nc,c,cc}
+\cs_generate_variant:Nn \toks_if_eq:NNF {Nc,c,cc}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Variables and constants}
+%
+% \begin{macro}{\l_tmpa_toks}
+% \begin{macro}{\l_tmpb_toks}
+% \begin{macro}{\l_tmpc_toks}
+% \begin{macro}{\g_tmpa_toks}
+% \begin{macro}{\g_tmpb_toks}
+% \begin{macro}{\g_tmpc_toks}
+% Some scratch registers \ldots
+% \begin{macrocode}
+\tex_toksdef:D \l_tmpa_toks = 255\scan_stop:
+%<initex>\seq_put_right:Nn \g_toks_allocation_seq {255}
+\toks_new:N \l_tmpb_toks
+\toks_new:N \l_tmpc_toks
+\toks_new:N \g_tmpa_toks
+\toks_new:N \g_tmpb_toks
+\toks_new:N \g_tmpc_toks
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\c_empty_toks}
+% And here is a constant, which is a (permanently) empty token register.
+% \begin{macrocode}
+\toks_new:N \c_empty_toks
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\l_tl_replace_toks}
+% And here is one for tl vars. Can't define it there as the allocation
+% isn't set up at that point.
+% \begin{macrocode}
+\toks_new:N \l_tl_replace_toks
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</initex|package>
+% \end{macrocode}
+%
+%
+% \end{implementation}
+% \PrintIndex
+%
+% \endinput
+