diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3toks.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/expl3/l3toks.dtx | 963 |
1 files changed, 527 insertions, 436 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3toks.dtx b/Master/texmf-dist/source/latex/expl3/l3toks.dtx index a5d78d7386c..e5575678f27 100644 --- a/Master/texmf-dist/source/latex/expl3/l3toks.dtx +++ b/Master/texmf-dist/source/latex/expl3/l3toks.dtx @@ -1,5 +1,5 @@ % \iffalse -%% File: l3toks.dtx Copyright (C) 1990-2006 LaTeX3 project +%% File: l3toks.dtx Copyright (C) 1990-2009 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 @@ -17,7 +17,7 @@ %% %% The development version of the bundle can be found at %% -%% http://www.latex-project.org/cgi-bin/cvsweb.cgi/ +%% http://www.latex-project.org/svnroot/experimental/trunk/ %% %% for those people who are interested. %% @@ -36,7 +36,7 @@ \RequirePackage{l3names} %</driver|package> %\fi -\GetIdInfo$Id: l3toks.dtx 728 2008-01-01 16:11:58Z morten $ +\GetIdInfo$Id: l3toks.dtx 1362 2009-05-28 20:19:21Z joseph $ {L3 Experimental Token Registers} %\iffalse %<*driver> @@ -44,9 +44,9 @@ \ProvidesFile{\filename.\filenameext} [\filedate\space v\fileversion\space\filedescription] %\iffalse -\documentclass{l3doc} +\documentclass[full]{l3doc} \begin{document} -\DocInput{\filename.\filenameext} +\DocInput{l3toks.dtx} \end{document} %</driver> % \fi @@ -60,70 +60,124 @@ % \date{\filedate} % \maketitle % -% \section {Token Registers} +% \begin{documentation} % -% There is a second form beside token list pointers in which \LaTeX3 +% There is a second form beside token list variables in which \LaTeX3 % stores token lists, namely the internal \TeX{} token registers. % Functions dealing with these registers got the prefix "\toks_". Unlike -% token list pointers we have an accessing function as one can see +% token list variables we have an accessing function as one can see % below. % -% The main difference between \m{toks} (token registers) and \m{tlp} (token -% list pointers) is their behavior regarding expansion. While \m{tlp}'s +% The main difference between \m{toks} (token registers) and \m{tl var.}~(token +% list variable) is their behavior regarding expansion. While \m{tl vars} % expand fully (i.e., until only unexpandable tokens are left) inside -% an argument that is subject to expansion (i.e., denote by |x|) +% an argument that is subject to expansion (i.e., denoted by |x|) % \m{toks}'s expand always only up to one level, i.e., passing their % contents without further expansion. % -% \subsection{Functions} -% -% \begin{function}{% -% \toks_new:N | -% \toks_new:c | -% \toks_new_l:N} +% There are fewer restrictions on the contents of a token register over +% a token list variable. So while \meta{token list} is used to describe +% the contents of both of these, bear in mind that slightly different lists +% of tokens are allowed in each case. The best (only?) example is that a +% \meta{toks} can contain the "#" character (i.e., characters of catcode 6), +% whereas a \meta{tl var.}~will require its input to be sanitised before that is +% possible. +% +% If you're not sure which to use between a \meta{tl var.}~or a \meta{toks}, +% consider what data you're trying to hold. If you're dealing with function +% parameters involving "#", or building some sort of data structure +% then you probably want a \meta{toks} (e.g., \file{l3prop} uses \meta{toks} +% to store its property lists). +% +% If you're storing ad-hoc data for later use (possibly from direct user +% input) then usually a \meta{tl var.}~will be what you want. +% +% \section{Allocation and use} +% +% \begin{function}{ \toks_new:N | +% \toks_new:c | +%^^A \toks_new_l:N | +% } % \begin{syntax} % "\toks_new:N" <toks> % \end{syntax} % Defines <toks> to be a new token list register. +%^^A "\toks_new_l:N" is only defined in the \LaTeX3 kernel. % \begin{texnote} % This is the \LaTeX3 allocation for what was called \tn{newtoks} in % plain \TeX. % \end{texnote} % \end{function} % -% \begin{function}{% -% \toks_set:Nn | -% \toks_set:No | -% \toks_set:Nd | -% \toks_set:Nf | -% \toks_set:Nx | -% \toks_set:cn | -% \toks_set:co | -% \toks_set:cf | -% \toks_set:cx | -% \toks_gset:Nn | -% \toks_gset:No | -% \toks_gset:Nx} +% \begin{function}{ \toks_use:N | \toks_use:c } +% \begin{syntax} +% "\toks_use:N" <toks> +% \end{syntax} +% Accesses the contents of <toks>. Contrary to token list variables +% <toks> can't be access simply by calling them directly. +% \begin{texnote} +% Something like "\the" <toks>. +% \end{texnote} +% \end{function} +% +% \begin{function}{ \toks_set:Nn | +% \toks_set:NV | +% \toks_set:Nv | +% \toks_set:No | +% \toks_set:Nx | +% \toks_set:Nd | +% \toks_set:Nf | +% \toks_set:cn | +% \toks_set:co | +% \toks_set:cV | +% \toks_set:cv | +% \toks_set:cx | +% \toks_set:cd | +% \toks_set:cf } % \begin{syntax} -% "\toks_set:Nn" <toks> "{"<token list>"}" +% "\toks_set:Nn" <toks> \Arg{token list} % \end{syntax} -% Defines <toks> to hold the token list <token list>. Global -% variants of this command assign the value globally the other variants -% expand the <token list> up to a certain level before the assignment -% or interpret the <token list> as a character list and form a control -% sequence out of it. +% Defines <toks> to hold the token list <token list>. % \begin{texnote} % "\toks_set:Nn" could have been specified in plain \TeX{} by <toks> "=" -% "{" <token list> "}" but all other functions have no counterpart in -% plain \TeX. Additionally the functions above will check for correct +% \Arg{token list} but all other functions have no counterpart in +% plain \TeX. Additionally the functions above the global variants described +% below will check for correct % local and global assignments, something that isn't available in plain % \TeX. % \end{texnote} % \end{function} % -% \begin{function}{% -% \toks_gset_eq:NN | -% } +% \begin{function}{ \toks_gset:Nn | +% \toks_gset:NV | +% \toks_gset:No | +% \toks_gset:Nx | +% \toks_gset:cn | +% \toks_gset:cV | +% \toks_gset:co | +% \toks_gset:cx } +% \begin{syntax} +% "\toks_gset:Nn" <toks> \Arg{token list} +% \end{syntax} +% Defines <toks> to globally hold the token list <token list>. +% \end{function} +% +% \begin{function}{ \toks_set_eq:NN | +% \toks_set_eq:cN | +% \toks_set_eq:Nc | +% \toks_set_eq:cc } +% \begin{syntax} +% "\toks_set_eq:NN" <toks1> <toks2> +% \end{syntax} +% Set <toks1> to the value of <toks2>. Don't try to use +% "\toks_set:Nn" for this purpose if the second argument is also a +% token register. +% \end{function} +% +% \begin{function}{ \toks_gset_eq:NN | +% \toks_gset_eq:cN | +% \toks_gset_eq:Nc | +% \toks_gset_eq:cc } % \begin{syntax} % "\toks_gset_eq:NN" <toks1> <toks2> % \end{syntax} @@ -132,325 +186,251 @@ % token register. % \end{function} % -% \begin{function}{% -% \toks_clear:N | -% \toks_gclear:N | -% } +% \begin{function}{ \toks_clear:N | +% \toks_clear:c | +% \toks_gclear:N | +% \toks_gclear:c } % \begin{syntax} % "\toks_clear:N" <toks> % \end{syntax} % The <toks> is locally or globally cleared. % \end{function} % -% \begin{function}{% -% \toks_put_left:Nn | -% \toks_gput_left:Nn | -% \toks_put_right:Nn | -% \toks_put_right:No | -% \toks_put_right:Nx | -% \toks_gput_right:Nn | -% \toks_gput_right:No | -% \toks_gput_right:Nx | -% } +% \begin{function}{ \toks_use_clear:N | +% \toks_use_clear:c | +% \toks_use_gclear:N | +% \toks_use_gclear:c } % \begin{syntax} -% "\toks_put_left:Nn" <toks> "{"<token list>"}" +% "\toks_use_clear:N" <toks> % \end{syntax} -% These functions will append <token list> to the left or right of -% <toks>. Assignment is done either locally or globally. If possible -% append to the right since this operation is faster. +% Accesses the contents of <toks> and clears (locally or globally) it +% afterwards. Actually the clearing operation is done in a way that does +% not prohibit the access of the following tokens in the input stream +% with functions stored in the token register. In other words this +% function is not exactly the same as calling "\toks_use:N" <toks> +% "\toks_clear:N" <toks> in sequence. % \end{function} % -% \begin{function}{\toks_use:N} +% \begin{function}{ \toks_show:N | \toks_show:c} % \begin{syntax} -% "\toks_use:N" <toks> +% "\toks_show:N" <toks> % \end{syntax} -% Accesses the contents of <toks>. Contrary to token list pointers -% <toks> can't be access simply by calling them directly. +% Displays the contents of <toks> in the terminal output and log file. +% "#" signs in the <toks> will be shown doubled. % \begin{texnote} -% Something like \tn{the} <toks>. +% Something like "\showthe" <toks>. % \end{texnote} % \end{function} % -% \begin{function}{\toks_use_clear:N | -% \toks_use_gclear:N} +% \section{Adding to the contents of token registers} +% +% \begin{function}{ \toks_put_left:Nn | +% \toks_put_left:NV | +% \toks_put_left:No | +% \toks_put_left:Nx | +% \toks_put_left:cn | +% \toks_put_left:cV | +% \toks_put_left:co } % \begin{syntax} -% "\toks_use_clear:N" <toks> +% "\toks_put_left:Nn" <toks> \Arg{token list} % \end{syntax} -% Accesses the contents of <toks> and clears (locally or globally) it -% afterwards. Actually the clearing operation is done in a way that does -% not prohibit the access of the following tokens in the input stream -% with functions stored in the token register. In other words this -% function is not exactly the same as calling "\toks_use:N" <toks> -% "\toks_clear:N" <toks> in sequence. +% These functions will append <token list> to the left of +% <toks>. Assignment is done locally. If possible +% append to the right since this operation is faster. % \end{function} % -% \subsection{Predicates and conditionals} +% \begin{function}{ \toks_gput_left:Nn | +% \toks_gput_left:NV | +% \toks_gput_left:No | +% \toks_gput_left:Nx | +% \toks_gput_left:cn | +% \toks_gput_left:cV | +% \toks_gput_left:co } +% \begin{syntax} +% "\toks_gput_left:Nn" <toks> \Arg{token list} +% \end{syntax} +% These functions will append <token list> to the left of +% <toks>. Assignment is done globally. If possible +% append to the right since this operation is faster. +% \end{function} % -% \begin{function}{ -% \toks_if_empty_p:N| -% \toks_if_empty:NTF| -% \toks_if_empty:NT | -% \toks_if_empty:NF| -% \toks_if_empty_p:c| -% \toks_if_empty:cTF | -% \toks_if_empty:cT | -% \toks_if_empty:cF -% } +% \begin{function}{ \toks_put_right:Nn | +% \toks_put_right:NV | +% \toks_put_right:No | +% \toks_put_right:Nx | +% \toks_put_right:cV | +% \toks_put_right:cn | +% \toks_put_right:co } +% \begin{syntax} +% "\toks_put_right:Nn" <toks> \Arg{token list} +% \end{syntax} +% These functions will append <token list> to the right of +% <toks>. Assignment is done locally. +% \end{function} +% +% \begin{function}{ \toks_put_right:Nf } +% \begin{syntax} +% "\toks_put_right:Nf" <toks> \Arg{token list} +% \end{syntax} +% Variant of the above. |:Nf| is used by |template.dtx| and will +% perhaps be moved to that package. +% \end{function} +% +% \begin{function}{ \toks_gput_right:Nn | +% \toks_gput_right:NV | +% \toks_gput_right:No | +% \toks_gput_right:Nx | +% \toks_gput_right:cn | +% \toks_gput_right:cV | +% \toks_gput_right:co } % \begin{syntax} -% "\toks_if_empty:NTF" <toks> "{"<true code>"}{"<false code>"}" +% "\toks_gput_right:Nn" <toks> \Arg{token list} % \end{syntax} -% Tests if <toks> is empty. +% These functions will append <token list> to the right of +% <toks>. Assignment is done globally. % \end{function} % -% \subsection{Variable and constants} +% +% \section{Predicates and conditionals} +% +% \begin{function}{ \toks_if_empty_p:N / (EXP) | +% \toks_if_empty:N / (EXP)(TF) | +% \toks_if_empty_p:c / (EXP) | +% \toks_if_empty:c / (EXP)(TF) } +% \begin{syntax} +% "\toks_if_empty:NTF" <toks> \Arg{true code} \Arg{false code} +% \end{syntax} +% Expandable test for whether <toks> is empty. +% \end{function} +% +% \begin{function}{ \toks_if_eq:NN / (TF)(EXP) | +% \toks_if_eq:Nc / (TF)(EXP) | +% \toks_if_eq:cN / (TF)(EXP) | +% \toks_if_eq:cc / (TF)(EXP) | +% \toks_if_eq_p:NN / (EXP) | +% \toks_if_eq_p:cN / (EXP) | +% \toks_if_eq_p:Nc / (EXP) | +% \toks_if_eq_p:cc / (EXP) } +% \begin{syntax} +% "\toks_if_eq:NNTF" <toks1> <toks2> \Arg{true code} \Arg{false code} +% \end{syntax} +% Expandably tests if <toks1> and <toks2> are equal. +% \end{function} +% +% \section{Variable and constants} % % \begin{variable}{\c_empty_toks} % Constant that is always empty. % \end{variable} % -% \begin{variable}{% -% \l_tmpa_toks | -% \l_tmpb_toks | -% \g_tmpa_toks | -% \g_tmpb_toks -% } +% \begin{variable}{ \l_tmpa_toks | +% \l_tmpb_toks | +% \l_tmpc_toks | +% \g_tmpa_toks | +% \g_tmpb_toks | +% \g_tmpc_toks } % Scratch register for immediate use. They are not used by conditionals % or predicate functions. % \end{variable} % -% \subsubsection{Internal functions} +% \begin{variable}{ \l_tl_replace_toks } +% A placeholder for contents of functions replacing contents of strings. +% \end{variable} % -% \begin{function}{\toks_put_left_aux:w} -% Used by "\toks_put_left:Nn" and its variants. -% \end{function} +% \end{documentation} % -% \begin{function}{\tex_toksdef:D} -% Primitive function for defining a <cs> to correspond to a token -% register should not be used by a programmer. -% \begin{texnote} -% This function was named \tn{toksdef}. -% \end{texnote} -% \end{function} -% -% \StopEventually{} +% \begin{implementation} % -% \subsection{The Implementation} +% \section{\pkg{l3toks} implementation} % % We start by ensuring that the required packages are loaded. -% We check for \texttt{l3expan} since this a basic package that is -% essential for use of any higher-level package. % \begin{macrocode} -%<package>\ProvidesExplPackage -%<package> {\filename}{\filedate}{\fileversion}{\filedescription} -%<package&check>\RequirePackage{l3chk}\par -%<package>\RequirePackage{l3expan}\par +%<*package> +\ProvidesExplPackage + {\filename}{\filedate}{\fileversion}{\filedescription} +\package_check_loaded_expl: +%</package> %<*initex|package> % \end{macrocode} % -% \begin{macro}{\toks_new:N} -% \begin{macro}{\toks_new_l:N} -% \begin{macro}{\toks_new:c} -% Allocates a new token register. This function is already defined above. +% \subsection{Allocation and use} +% +% \begin{macro}{\toks_new:N,\toks_new:c} +%^^A \begin{macro}{\toks_new_l:N} +% Allocates a new token register. % \begin{macrocode} %<*initex> \alloc_setup_type:nnn {toks} \c_zero \c_max_register_num -\def_new:Npn \toks_new:N #1{\alloc_reg:NnNN g {toks} \tex_toksdef:D #1} -\def_new:Npn \toks_new_l:N #1{\alloc_reg:NnNN l {toks} \tex_toksdef:D #1} +\cs_new_nopar:Npn \toks_new:N #1 { \alloc_reg:NnNN g {toks} \tex_toksdef:D #1 } +\cs_new_nopar:Npn \toks_new_l:N #1 { \alloc_reg:NnNN l {toks} \tex_toksdef:D #1 } %</initex> -%<package>\let:NN \toks_new:N \newtoks % nick from LaTeX for the moment -\def_new:Npn \toks_new:c {\exp_args:Nc\toks_new:N} +%<package>\cs_set_eq:NN \toks_new:N \newtoks % nick from LaTeX for the moment +\cs_generate_variant:Nn \toks_new:N {c} % \end{macrocode} % \end{macro} -% \end{macro} -% \end{macro} +%^^A \end{macro} % -% \begin{macro}{\toks_clear:N} -% \begin{macro}{\toks_gclear:N} -% These functions clear a token register, either locally or globally. -% \begin{macrocode} -\def_new:Npn \toks_clear:N #1{#1\c_empty_toks -%<*check> - \chk_local_or_pref_global:N #1 -%</check> -} -\def_new:Npn \toks_gclear:N { -%<*check> - \pref_global_chk: -%</check> -%<-check> \pref_global:D - \toks_clear:N} -% \end{macrocode} -% \end{macro} -% \end{macro} % % \begin{macro}{\toks_use:N} % \begin{macro}{\toks_use:c} -% This function just returns the contents of a token register. +% This function returns the contents of a token register. % \begin{macrocode} -\let_new:NN \toks_use:N \the_internal:D -\def_new:Npn \toks_use:c {\exp_args:Nc\toks_use:N} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\toks_use_clear:N} -% \begin{macro}{\toks_use_gclear:N} -% 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. -% A direct implementation will save one |\exp_after:NN| but for the -% sake of checking we do it this way now. -% \begin{macrocode} -\def_new:Npn \toks_use_clear:N#1{ - \exp_after:NN - \toks_clear:N - \exp_after:NN - #1 - \toks_use:N#1} -\def_new:Npn \toks_use_gclear:N{ -%<*check> - \pref_global_chk: -%</check> -%<-check> \pref_global:D - \toks_use_clear:N} +\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_put_left:Nn} -% \begin{macro}{\toks_put_left:No} -% \begin{macro}{\toks_gput_left:Nn} -% \begin{macro}{\toks_gput_left:Nx} -% \begin{macro}{\toks_put_left_aux:w} -% |\toks_put_left:Nn |\zz{toks}\zv{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} -\def_new:Npn \toks_put_left:Nn #1{ - \exp_after:NN\toks_put_left_aux:w\exp_after:NN\q_mark - \toks_use:N #1\q_stop #1} -\def_new:Npn \toks_put_left:No {\exp_args:NNo \toks_put_left:Nn} -\def_new:Npn \toks_gput_left:Nn { -%<*check> - \pref_global_chk: -%</check> -%<-check> \pref_global:D - \toks_put_left:Nn} -\def_new:Npn \toks_gput_left:Nx {\exp_args:NNx \toks_gput_left:Nn} -% \end{macrocode} -% A helper function for |\toks_put_left:Nn|. Its arguments are -% subsequently the tokens of \zv{stuff\/}, the token register -% \zz{toks} and the current contents of \zz{toks}. We make sure to -% remove the token we inserted earlier. -% \begin{macrocode} -\def_long_new:Npn \toks_put_left_aux:w #1\q_stop #2#3{ - #2\exp_after:NN{\use_arg_i:nn{#3}#1} -%<*check> - \chk_local_or_pref_global:N #2 -%</check> -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\toks_put_right:Nn} -% \begin{macro}{\toks_gput_right:Nn} -% \begin{macro}{\toks_put_right:No} -% \begin{macro}{\toks_put_right:Nd} -% \begin{macro}{\toks_put_right:Nf} -% \begin{macro}{\toks_put_right:Nx} -% \begin{macro}{\toks_gput_right:No} -% \begin{macro}{\toks_gput_right:Nx} -% These macros add a list of tokens to the right of a token register. -% \begin{macrocode} -\def_long_new:Npn \toks_put_right:Nn #1#2{#1\exp_after:NN{\toks_use:N #1#2} -%<*check> - \chk_local_or_pref_global:N #1 -%</check> -} -\def_new:Npn \toks_gput_right:Nn { -%<*check> - \pref_global_chk: -%</check> -%<-check> \pref_global:D - \toks_put_right:Nn} -% \end{macrocode} -% |\toks_gput_right:Nx| expands its (second) argument. -% \begin{macrocode} -%<check>\def_new:Npn \toks_put_right:No {\exp_args:NNo \toks_put_right:Nn } -%<-check>\def_long_new:Npn\toks_put_right:No#1#2{#1\exp_after:NN\exp_after:NN -%<-check>\exp_after:NN{\exp_after:NN\toks_use:N\exp_after:NN #1#2}} -%<check>\def_new:Npn \toks_put_right:Nd {\exp_args:NNd \toks_put_right:Nn } -%<-check>\def_long_new:Npn\toks_put_right:Nd#1#2{ -%<-check> \exp_after:NN\toks_put_right:No\exp_after:NN#1\exp_after:NN{#2}} -% \end{macrocode} -% 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>\def_new:Npn \toks_put_right:Nf {\exp_args:NNf \toks_put_right:Nn } -%<-check>\def_long_new:Npn \toks_put_right:Nf #1#2{ -%<-check> #1\exp_after:NN\exp_after:NN\exp_after:NN{ -%<-check> \exp_after:NN\toks_use:N\exp_after:NN #1\int_to_roman:w -`0#2}} -\def_new:Npn \toks_put_right:Nx {\exp_args:NNx \toks_put_right:Nn } -\def_new:Npn \toks_gput_right:No {\exp_args:NNo\toks_gput_right:Nn} -\def_new:Npn \toks_gput_right:Nx {\exp_args:NNx\toks_gput_right:Nn} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \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:Nd} % \begin{macro}{\toks_set:Nf} -% \begin{macro}{\toks_set:Nx} % \begin{macro}{\toks_set:cn} % \begin{macro}{\toks_set:co} -% \begin{macro}{\toks_set:cf} +% \begin{macro}{\toks_set:cV} +% \begin{macro}{\toks_set:cv} % \begin{macro}{\toks_set:cx} +% \begin{macro}{\toks_set:cd} +% \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> -\def_new:Npn \toks_set:Nn #1{\chk_local:N #1#1} +\cs_new_nopar:Npn \toks_set:Nn #1 { \chk_local:N #1 #1 } +\cs_generate_variant:Nn \toks_set:Nn {No,Nd,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> \let_new:NN \toks_set:Nn\use_noop: -%<-check> \def_long_new:Npn \toks_set:No#1#2{#1\exp_after:NN{#2}} -%<-check> \def_long_new:Npn \toks_set:Nd#1#2{ -%<-check> #1\exp_after:NN\exp_after:NN\exp_after:NN{#2}} -%<check> \def_new:Npn \toks_set:No {\exp_args:NNo \toks_set:Nn} -%<check> \def_new:Npn \toks_set:Nd {\exp_args:NNd \toks_set:Nn} -\def_new:Npn \toks_set:Nx {\exp_args:NNx \toks_set:Nn} +%<*!check> +\cs_new_eq:NN \toks_set:Nn \prg_do_nothing: +\cs_new:Npn \toks_set:NV #1#2 { + #1 \exp_after:wN { \int_to_roman:w -`0 \exp_eval_register:N #2 } +} +\cs_new:Npn \toks_set:Nv #1#2 { + #1 \exp_after:wN { \int_to_roman:w -`0 \exp_eval_register:c {#2} } +} +\cs_new:Npn \toks_set:No #1#2 { #1 \exp_after:wN {#2} } +\cs_new:Npn \toks_set:Nd #1#2 { + #1 \exp_after:wN \exp_after:wN \exp_after:wN {#2} +} +\cs_new:Npn \toks_set:Nf #1#2 { + #1 \exp_after:wN { \int_to_roman:w -`0#2 } +} +%</!check> % \end{macrocode} -% We implement |\toks_set:Nf| by hand when not checking because this -% is going to be used \emph{extensively} in keyval processing! +% % \begin{macrocode} -%<check>\def_new:Npn \toks_set:Nf {\exp_args:NNf \toks_set:Nn} -%<-check>\def_long_new:Npn\toks_set:Nf #1#2{ -%<-check> #1\exp_after:NN{\int_to_roman:w -`0#2}} -\def_new:Npn \toks_set:cf {\exp_args:Nc\toks_set:Nf} -\def_new:Npn \toks_set:cn {\exp_args:Nc\toks_set:Nn} -\def_new:Npn \toks_set:co {\exp_args:Nc\toks_set:No} -\def_new:Npn \toks_set:cx {\exp_args:Nc\toks_set:Nx} +\cs_generate_variant:Nn \toks_set:Nn {Nx,cn,cV,cv,co,cx,cd,cf} % \end{macrocode} % \end{macro} % \end{macro} @@ -461,24 +441,25 @@ % \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> -\def_new:Npn \toks_gset:Nn #1{\chk_global:N #1\pref_global:D#1} -%</check> -%<-check> \let_new:NN \toks_gset:Nn\pref_global:D -\def_new:Npn \toks_gset:No {\exp_args:NNo \toks_gset:Nn} -\def_new:Npn \toks_gset:Nx {\exp_args:NNx \toks_gset:Nn} -\def_new:Npn \toks_gset:cn {\exp_args:Nc \toks_gset:Nn} -\def_new:Npn \toks_gset:co {\exp_args:Nc \toks_gset:No} -\def_new:Npn \toks_gset:cx {\exp_args:Nc \toks_gset:Nx} +%<check>\cs_new_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} @@ -486,6 +467,8 @@ % \end{macro} % \end{macro} % \end{macro} +% \end{macro} +% \end{macro} % % \begin{macro}{\toks_set_eq:NN} % \begin{macro}{\toks_set_eq:Nc} @@ -499,23 +482,23 @@ % in \m{toks1}. % \begin{macrocode} %<*check> -\def_new:Npn\toks_set_eq:NN#1#2{ - \chk_local:N#1 - \chk_var_or_const:N#2 - #1#2} -\def_new:Npn\toks_gset_eq:NN#1#2{ - \chk_global:N#1 - \chk_var_or_const:N#2 - \pref_global:D#1#2} +\cs_new_nopar:Npn\toks_set_eq:NN #1#2 { + \chk_local:N #1 + \chk_var_or_const:N #2 + #1 #2 +} +\cs_new_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> \let_new:NN \toks_set_eq:NN \use_noop: -%<-check> \let_new:NN \toks_gset_eq:NN \pref_global:D -\def_new:Npn \toks_set_eq:Nc {\exp_args:NNc\toks_set_eq:NN} -\def_new:Npn \toks_set_eq:cN {\exp_args:Nc\toks_set_eq:NN} -\def_new:Npn \toks_set_eq:cc {\exp_args:Ncc\toks_set_eq:NN} -\def_new:Npn \toks_gset_eq:Nc {\exp_args:NNc\toks_gset_eq:NN} -\def_new:Npn \toks_gset_eq:cN {\exp_args:Nc\toks_gset_eq:NN} -\def_new:Npn \toks_gset_eq:cc {\exp_args:Ncc\toks_gset_eq:NN} +%<*!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} @@ -526,31 +509,126 @@ % \end{macro} % \end{macro} % -% \begin{macro}{\toks_if_empty_p:N} -% \begin{macro}{\toks_if_empty_p:c} -% \begin{macro}{\toks_if_empty:NTF} -% \begin{macro}{\toks_if_empty:cTF} -% \begin{macro}{\toks_if_empty:NT} -% \begin{macro}{\toks_if_empty:cT} -% \begin{macro}{\toks_if_empty:NF} -% \begin{macro}{\toks_if_empty:cF} -% |\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{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_nopar:Npn \toks_clear:N #1 { + #1\c_empty_toks +%<check>\chk_local_or_pref_global:N #1 +} +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_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_nopar:Npn \toks_use_clear:N #1 { + \exp_last_unbraced:NNV \toks_clear:N #1 #1 +} +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_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. +% TODO: this is not pretty when the argument is a control sequence that doesn't exist! +% \begin{macrocode} +\cs_new_eq:NN \toks_show:N \tex_showthe:D +\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_nopar:Npn \toks_put_left:Nn #1 { + \exp_after:wN \toks_put_left_aux:w \exp_after:wN \q_mark + \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_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} -\def_new:Npn\toks_if_empty_p:N#1{ - \if:w \tlist_if_empty_p:o{\toks_use:N #1} - \c_true - \else: - \c_false - \fi: +\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 } -\def_test_function_new:npn{toks_if_empty:N}#1{\if:w \toks_if_empty_p:N #1} -\def_new:Npn\toks_if_empty:cTF{\exp_args:Nc\toks_if_empty:NTF} -\def_new:Npn\toks_if_empty:cT{\exp_args:Nc\toks_if_empty:NT} -\def_new:Npn\toks_if_empty:cF{\exp_args:Nc\toks_if_empty:NF} % \end{macrocode} % \end{macro} % \end{macro} @@ -560,49 +638,61 @@ % \end{macro} % \end{macro} % \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} % -% \begin{macro}{\toks_if_eq:NNTF} -% \begin{macro}{\toks_if_eq:NNT} -% \begin{macro}{\toks_if_eq:NNF} -% \begin{macro}{\toks_if_eq:NcTF} -% \begin{macro}{\toks_if_eq:NcT} -% \begin{macro}{\toks_if_eq:NcF} -% \begin{macro}{\toks_if_eq:cNTF} -% \begin{macro}{\toks_if_eq:cNT} -% \begin{macro}{\toks_if_eq:cNF} -% \begin{macro}{\toks_if_eq:ccTF} -% \begin{macro}{\toks_if_eq:ccT} -% \begin{macro}{\toks_if_eq:ccF} -% \begin{macro}{\toks_if_eq_p:NN} -% \begin{macro}{\toks_if_eq_p:cN} -% \begin{macro}{\toks_if_eq_p:Nc} -% \begin{macro}{\toks_if_eq_p:cc} -% This function test whether two token registers contain the same. +% \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} -\def_new:NNn \toks_if_eq:NNTF 2 { - \tlist_if_eq:xxTF{\toks_use:N #1}{\toks_use:N #2} +\cs_new:Npn \toks_put_right:Nn #1#2 { + #1 \exp_after:wN { \toks_use:N #1 #2 } +%<check> \chk_local_or_pref_global:N #1 } -\def_new:NNn \toks_if_eq:NNT 2 { - \tlist_if_eq:xxT{\toks_use:N #1}{\toks_use:N #2} +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_nopar:Npn \toks_gput_right:Nn { +%<check> \pref_global_chk: +%<!check> \pref_global:D + \toks_put_right:Nn } -\def_new:NNn \toks_if_eq:NNF 2 { - \tlist_if_eq:xxF{\toks_use:N #1}{\toks_use:N #2} +% \end{macrocode} +% A couple done by hand for speed. +% \begin{macrocode} +%<check>\cs_generate_variant:Nn \toks_put_right:Nn {No} +%<*!check> +\cs_new: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 + } } -\def_new:Npn \toks_if_eq:NcTF {\exp_args:NNc \toks_if_eq:NNTF} -\def_new:Npn \toks_if_eq:NcT {\exp_args:NNc \toks_if_eq:NNT} -\def_new:Npn \toks_if_eq:NcF {\exp_args:NNc \toks_if_eq:NNF} -\def_new:Npn \toks_if_eq:cNTF {\exp_args:Nc \toks_if_eq:NNTF} -\def_new:Npn \toks_if_eq:cNT {\exp_args:Nc \toks_if_eq:NNT} -\def_new:Npn \toks_if_eq:cNF {\exp_args:Nc \toks_if_eq:NNF} -\def_new:Npn \toks_if_eq:ccTF {\exp_args:Ncc \toks_if_eq:NNTF} -\def_new:Npn \toks_if_eq:ccT {\exp_args:Ncc \toks_if_eq:NNT} -\def_new:Npn \toks_if_eq:ccF {\exp_args:Ncc \toks_if_eq:NNF} -\def_new:NNn \toks_if_eq_p:NN 2 { - \tlist_if_eq_p:xx {\toks_use:N #1} {\toks_use:N #2} +\cs_new: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 + } } -\def_new:Npn \toks_if_eq_p:cN {\exp_args:Nc \toks_if_eq_p:NN} -\def_new:Npn \toks_if_eq_p:Nc {\exp_args:NNc \toks_if_eq_p:NN} -\def_new:Npn \toks_if_eq_p:cc {\exp_args:Ncc \toks_if_eq_p:NN} +%</!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} @@ -618,18 +708,73 @@ % \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: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} { + \tl_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 register \ldots +% Some scratch registers \ldots % \begin{macrocode} -\tex_toksdef:D \l_tmpa_toks = 255 +\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 @@ -651,81 +796,27 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\toks_remove_extra_brace_group:N} -% \begin{macro}{\toks_remove_extra_brace_group_aux:NNw} -% Small function for removing an extra brace group if present. Hmm, -% not really needed anymore. +% \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} -\def_new:Npn \toks_remove_extra_brace_group:N #1{ - \exp_after:NN \toks_remove_extra_brace_group_aux:NNw - \exp_after:NN \toks_set:Nn \exp_after:NN #1 - \toks_use:N#1\q_nil -} -\def_long_new:Npn\toks_remove_extra_brace_group_aux:NNw #1#2#3\q_nil{#1#2{#3}} +\toks_new:N \l_tl_replace_toks % \end{macrocode} % \end{macro} -% \end{macro} % -% Show token usage: % \begin{macrocode} %</initex|package> +% \end{macrocode} +% +% Show token usage: +% \begin{macrocode} %<*showmemory> \showMemUsage %</showmemory> % \end{macrocode} % -% \endinput -% -% $Log$ -% Revision 1.25 2006/08/01 01:54:12 morten -% Prevent brace stripping in \toks_put_left:Nn and friends. -% -% Revision 1.24 2006/03/20 18:26:40 braams -% Updated the copyright notice (2006) and demoted all implementation -% sections to subsections and so on to clean up the toc for source3.tex -% -% Revision 1.23 2006/02/16 23:32:49 braams -% Imported \toks_put_left:No from l3messages -% -% Revision 1.22 2006/01/21 11:43:20 morten -% Tuned some of the \toks_set and \toks_put_right functions since they -% are going to be used intensively in the l3keyval module which is again -% going to be heavily used. -% -% Revision 1.21 2006/01/20 12:22:44 morten -% Minor changes plus added \toks_remove_extra_brace_group:N for l3keyval -% module -% -% Revision 1.20 2005/12/27 10:03:39 morten -% Changed RCS information retrieval -% -% Revision 1.19 2005/12/23 13:24:39 morten -% Added a few functions from template -% -% Revision 1.18 2005/12/21 20:44:04 morten -% Corrected typo. -% -% Revision 1.17 2005/12/02 15:56:48 morten -% Added some more functions and improved test for emptiness. -% -% Revision 1.16 2005/04/12 13:22:37 morten -% More functions added -% -% Revision 1.15 2005/04/07 08:18:17 morten -% Only put 255 in the toks stack when running initex -% -% Revision 1.14 2005/04/06 22:35:50 braams -% Now we have register allocation fitted -% -% Revision 1.13 2005/04/06 21:37:50 morten -% Added some more functions -% -% Revision 1.12 2005/03/15 23:39:21 braams -% Some fiddling to get it loaded by initex; needs a way to allocate -% token registers for it to work. -% -% Revision 1.11 2005/03/11 21:25:06 braams -% Changed copyright year, fixed use of RCS values; -% fixed a few typos in the documentation; -% \c_if_empty_toks had to be \c_empty_toks +% \end{implementation} +% \PrintIndex % +% \endinput + |