trunk/Master/texmf-dist/source/latex/expl3

git-svn-id: svn://tug.org/texlive/trunk@270 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 212 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/expl3/l3quark.dtx b/Master/texmf-dist/source/latex/expl3/l3quark.dtx
new file mode 100644
index 00000000000..1f95aa6fe71
--- /dev/null
+++ b/Master/texmf-dist/source/latex/expl3/l3quark.dtx
@@ -0,0 +1,212 @@
+% \iffalse
+%% File: l3quark.dtx Copyright (C) 1990-1998 LaTeX3 project
+%
+%<*dtx>
+          \ProvidesFile{l3quark.dtx}
+%</dtx>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{l3quark}
+%<driver> \ProvidesFile{l3quark.drv}
+% \fi
+%         \ProvidesFile{l3quark.dtx}
+          [1998/05/20 v1.0e L3 Experimental Quark Commands]
+%
+% \iffalse
+%<*driver>
+\documentclass{l3doc}
+
+\begin{document}
+\DocInput{l3quark.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+%
+% \GetFileInfo{l3quark.dtx}
+% \title{The \textsf{l3quark} package\thanks{This file
+%         has version number \fileversion, last
+%         revised \filedate.}\\
+% ``Quarks''}
+% \author{\Team}
+% \date{\filedate}
+% \maketitle
+%
+%
+% \section{Quarks}
+%^^A \label{sec:quarks}
+% 
+%    
+% A special type of constants in \LaTeX3 are `quarks'. These are control
+% sequences that expand to themselves and should therefore NEVER be
+% executed directly in the code. This would result in an endless loop!
+% 
+% They are meant to be used as delimiter is weird functions (for example
+% as the stop token (i.e., "\q_stop"). They also permit the following
+% ingenious trick: when you pick up a token in a temporary, and you want
+% to know whether you have picked up a particular quark, all you have to
+% do is compare the temporary to the quark using "\if_meaning:NN". A
+% set of special quark testing functions is set up below.
+% 
+% By convention all constants of type quark start out with "\q_".
+% 
+% \subsection{Functions}
+% 
+% \begin{function}{%
+%                  \quark_new:N |
+% }
+% \begin{syntax}
+%    "\quark_new:N"   <quark>
+% \end{syntax}
+% Defines <quark> to be a new constant of type "quark".
+% \end{function}
+% 
+% \begin{function}{%
+%                  \quark_if_no_value:nTF |
+%                  \quark_if_no_value:nF  |
+%                  \quark_if_no_value:nT  |
+%                  \quark_if_no_value:NTF |
+%                  \quark_if_no_value:NF  |
+% }
+% \begin{syntax}
+%    "\quark_if_no_value:nTF" "{" <token list> "}"
+%                          "   {"<true code>"}{"<false code>"}"
+%    "\quark_if_no_value:NTF" <tlp>
+%                          "   {"<true code>"}{"<false code>"}"
+% \end{syntax}
+% This tests whether or not <token list> contains only the quark
+% "\q_no_value".
+% 
+% If <token list> to be tested is stored in a token list pointer use
+% "\quark_if_no_value:NTF", or "\quark_if_no_value:NF" or check the
+% value directly with "\if_meaning:NN". All those cases are faster then
+% "\quark_if_no_value:nTF" so should be preferred.
+% 
+% \begin{texnote}
+% But  be aware of the fact that "\if_meaning:NN" can result in an
+% overflow of \TeX{}'s parameter stack since it leaves the corresponding
+% "\fi:" on the input until the whole replacement text is processed. It
+% is therefore better in recursions to use "\quark_if_no_value:NTF" as
+% it will remove the conditional prior to processing the "T" or "F" case
+% and so allows tail-recursion.
+% \end{texnote}
+% \end{function}
+% 
+% \subsection{Constants}
+% 
+% \begin{variable}{\q_no_value} The canonical `missing value quark'
+% that is returned by certain functions to denote that a requested value
+% is not found in the data structure.
+% \end{variable}
+% 
+% \begin{variable}{\q_stop}
+% This constant is used as a a marker in parameter text. This allows a
+% scanning function to find the end of some input string.
+% \end{variable}
+% 
+% \begin{variable}{\q_nil}
+% This constant represent the nil pointer in pointer structures.
+% \end{variable}
+% 
+% \section{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>\RequirePackage{l3expan}\par
+%<*package>
+%    \end{macrocode}
+%    
+% \begin{macro}{\quark_new:N}
+%    Allocate a new quark.
+%    \begin{macrocode}
+\def_new:Npn \quark_new:N #1{\tlp_new:Nn #1{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\q_stop}
+% \begin{macro}{\q_no_value}
+% \begin{macro}{\q_nil}
+%    |\q_stop| is often used as a marker in parameter text,
+%    |\q_no_value| is the canonical missing value, and |\q_nil|
+%    represents a nil pointer in some data structures.
+%    \begin{macrocode}
+\quark_new:N \q_stop
+\quark_new:N \q_no_value
+\quark_new:N \q_nil
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\q_error}
+% \begin{macro}{\q_mark}
+%    We need two additional quarks.  |\q_error| delimits the end of
+%    the computation for purposes of error recovery.  |\q_mark| is
+%    used in parameter text when we need a scanning boundary that is
+%    distinct from |\q_stop|.
+%    \begin{macrocode}
+\quark_new:N\q_error
+\quark_new:N\q_mark
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\quark_if_no_value:NTF}
+% \begin{macro}{\quark_if_no_value:NF}
+% \begin{macro}{\quark_if_no_value:nTF}
+% \begin{macro}{\quark_if_no_value:nT}
+% \begin{macro}{\quark_if_no_value:nF}
+%    Here we test if we found a special quark as the first argument.
+%    The argument might contain an arbitrary list of tokens, therefore
+%    we have to wrap it up in a token list pointer.
+%    \begin{macrocode}
+\def_new:Npn \quark_if_no_value:NTF #1{
+%    \end{macrocode}
+%    We better start with |\q_no_value| as the first argument since
+%    the whole thing may otherwise loop if |#1| is wrongly given
+%    a string like |aabc| instead of a single token.\footnote{It may
+%    still loop in special circumstances however!}
+%    \begin{macrocode}
+     \if_meaning:NN\q_no_value#1
+          \exp_after:NN\use_choice_i:nn
+     \else: \exp_after:NN\use_choice_ii:nn \fi:}
+%    \end{macrocode}
+%    It would be possible to speed up the following commands by
+%    providing individual implementations similar to the one above.
+%    Should perhaps be done if they are used often!
+%    \begin{macrocode}
+\def_new:Npn \quark_if_no_value:NF #1{\quark_if_no_value:NTF {#1}\use_noop:}
+\def_new:Npn \quark_if_no_value:nTF #1{\tlp_gset:Nn \g_testa_tlp {#1}
+    \quark_if_no_value:NTF\g_testa_tlp}
+\def_new:Npn \quark_if_no_value:nF #1{\quark_if_no_value:nTF {#1}\use_noop:}
+\def_new:Npn \quark_if_no_value:nT #1#2{\quark_if_no_value:nTF {#1}
+        {#2}\use_noop:}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\quark_if_nil:NTF}
+%    A function to check for the presence of |\q_nil|.
+%    \begin{macrocode}
+\def_new:Npn\quark_if_nil:NTF#1{
+  \if_meaning:NN#1\q_nil
+    \exp_after:NN\use_choice_i:nn
+  \else:
+    \exp_after:NN\use_choice_ii:nn\fi:}
+%    \end{macrocode}
+% \end{macro}
+%
+%    Show token usage:
+%    \begin{macrocode}
+%</package>
+%<*showmemory>
+\showMemUsage
+%</showmemory>
+%    \end{macrocode}
+%
+%