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