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

% \iffalse
%% File: l3toks.dtx Copyright (C) 1990-2010 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 LaTeX Project Team.
%%
%% -----------------------------------------------------------------------
%
%<*driver|package>
\RequirePackage{l3names}
%</driver|package>
%\fi
\GetIdInfo$Id: l3toks.dtx 1933 2010-05-25 00:26:38Z will $
          {L3 Experimental Token Registers}
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass[full]{l3doc}
\begin{document}
\DocInput{l3toks.dtx}
\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
%
% \begin{documentation}
%
% 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 variables we have an accessing function as one can see
% below.
%
% 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., denoted by |x|)
% \m{toks}'s expand always only up to one level, i.e., passing their
% contents without further expansion.
%
% 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   }
% \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_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:Nf |
%                   \toks_set:cn |
%                   \toks_set:co |
%                   \toks_set:cV |
%                   \toks_set:cv |
%                   \toks_set:cx |
%                   \toks_set:cf }
% \begin{syntax}
%   "\toks_set:Nn" <toks> \Arg{token list}
% \end{syntax}
% Defines <toks> to hold the token list <token list>.
% \begin{texnote}
% "\toks_set:Nn" could have been specified in plain \TeX{} by <toks> "="
% \Arg{token list} but all other functions have no counterpart in
% plain \TeX. 
% \end{texnote}
% \end{function}
%
% \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}
% 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_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_use_clear:N  |
%                   \toks_use_clear:c  |
%                   \toks_use_gclear:N |
%                   \toks_use_gclear:c }
% \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}
%
% \begin{function}{ \toks_show:N | \toks_show:c}
% \begin{syntax}
%   "\toks_show:N" <toks>
% \end{syntax}
% Displays the contents of <toks> in the terminal output and log file.
% "#" signs in the <toks> will be shown doubled.
% \begin{texnote}
% Something like "\showthe" <toks>.
% \end{texnote}
% \end{function}
%
% \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_put_left:Nn" <toks> \Arg{token list}
% \end{syntax}
% 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}
%
% \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_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_gput_right:Nn" <toks> \Arg{token list}
% \end{syntax}
% These functions will append <token list> to the right of
% <toks>. Assignment is done globally.
% \end{function}
%
%
% \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 |
%                   \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}
%
% \begin{variable}{ \l_tl_replace_toks }
% A placeholder for contents of functions replacing contents of strings.
% \end{variable}
%
% \end{documentation}
%
% \begin{implementation}
%
%    \section{\pkg{l3toks} implementation}
%
%    We start by ensuring that the required packages are loaded.
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage
  {\filename}{\filedate}{\fileversion}{\filedescription}
\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_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_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} {
  \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 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}
%
%    Show token usage:
%    \begin{macrocode}
%<*showmemory>
\showMemUsage
%</showmemory>
%    \end{macrocode}
%
% \end{implementation}
% \PrintIndex
%
% \endinput