path: root/Master/texmf-dist/source/latex/expl3/l3toks.dtx

% \iffalse
%% File: l3toks.dtx Copyright (C) 1990-2006 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/cgi-bin/cvsweb.cgi/
%%
%% 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 LaTeX Project Team.
%%
%% -----------------------------------------------------------------------
%
%<*driver|package>
\RequirePackage{l3names}
%</driver|package>
%\fi
\GetIdInfo$Id: l3toks.dtx 728 2008-01-01 16:11:58Z morten $
          {L3 Experimental Token Registers}
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass{l3doc}
\begin{document}
\DocInput{\filename.\filenameext}
\end{document}
%</driver>
% \fi
%
%
% \title{The \textsf{l3toks} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}\\
% Token Registers}
% \author{\Team}
% \date{\filedate}
% \maketitle
%
% \section {Token Registers}
%
% There is a second form beside token list pointers 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
% below.
%
% The main difference between \m{toks} (token registers) and \m{tlp} (token
% list pointers) is their behavior regarding expansion. While \m{tlp}'s
% expand fully (i.e., until only unexpandable tokens are left) inside
% an argument that is subject to expansion (i.e., denote 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}
% \begin{syntax}
%    "\toks_new:N" <toks>
% \end{syntax}
% Defines <toks> to be a new token list register.
% \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{syntax}
%   "\toks_set:Nn" <toks> "{"<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.
% \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
% local and global assignments, something that isn't available in plain
% \TeX.
% \end{texnote}
% \end{function}
%
% \begin{function}{%
%                  \toks_gset_eq:NN |
% }
% \begin{syntax}
%   "\toks_gset_eq:NN" <toks1> <toks2>
% \end{syntax}
% The <toks1>  globally set to the value of <toks2>. Don't try to use
% "\toks_gset:Nn" for this purpose if the second argument is also a
% token register.
% \end{function}
%
% \begin{function}{%
%                  \toks_clear:N |
%                  \toks_gclear:N |
% }
% \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{syntax}
%   "\toks_put_left:Nn" <toks> "{"<token list>"}"
% \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.
% \end{function}
%
% \begin{function}{\toks_use:N}
% \begin{syntax}
%   "\toks_use:N" <toks>
% \end{syntax}
% Accesses the contents of <toks>. Contrary to token list pointers
% <toks> can't be access simply by calling them directly.
% \begin{texnote}
% Something like \tn{the} <toks>.
% \end{texnote}
% \end{function}
%
% \begin{function}{\toks_use_clear:N |
%                  \toks_use_gclear:N}
% \begin{syntax}
%   "\toks_use_clear:N" <toks>
% \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.
% \end{function}
%
% \subsection{Predicates and conditionals}
%
% \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{syntax}
%   "\toks_if_empty:NTF" <toks> "{"<true code>"}{"<false code>"}"
% \end{syntax}
% Tests if <toks> is empty.
% \end{function}
%
% \subsection{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
% }
% Scratch register for immediate use. They are not used by conditionals
% or predicate functions.
% \end{variable}
%
% \subsubsection{Internal functions}
%
% \begin{function}{\toks_put_left_aux:w}
% Used by "\toks_put_left:Nn" and its variants.
% \end{function}
%
% \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{}
%
%    \subsection{The 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
%<*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.
%    \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}
%</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}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \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.
%    \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}
%    \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:No}
% \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:cx}
%    |\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}
%</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.
%    \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}
%    \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}
%    \end{macrocode}
% \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:No}
% \begin{macro}{\toks_gset:Nx}
% \begin{macro}{\toks_gset:cn}
% \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}
%    \end{macrocode}
% \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>
\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}
%</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}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \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{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:
}
\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}
% \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{macrocode}
\def_new:NNn \toks_if_eq:NNTF 2 {
  \tlist_if_eq:xxTF{\toks_use:N #1}{\toks_use:N #2}
}
\def_new:NNn \toks_if_eq:NNT 2 {
  \tlist_if_eq:xxT{\toks_use:N #1}{\toks_use:N #2}
}
\def_new:NNn \toks_if_eq:NNF 2 {
  \tlist_if_eq:xxF{\toks_use:N #1}{\toks_use: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}
}
\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}
%    \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}
% \end{macro}
%
% \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
%    \begin{macrocode}
\tex_toksdef:D \l_tmpa_toks = 255
%<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}{\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{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}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%    Show token usage:
%    \begin{macrocode}
%</initex|package>
%<*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
%