path: root/Master/texmf-dist/source/latex/l3kernel/l3bootstrap.dtx

% \iffalse meta-comment
%
%% File: l3bootstrap.dtx Copyright (C) 2011 The LaTeX3 project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the "expl3 bundle" (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %%
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX3 Project.
%%
%% -----------------------------------------------------------------------
%
%<*package>
\def\GetIdInfo$%
  Id: #1 #2 #3-#4-#5 #6 #7 $#8%
  {%
    \def\ExplFileDate{#3/#4/#5}%
    \def\ExplFileVersion{#2}%
  }
\GetIdInfo$Id: l3bootstrap.dtx 2478 2011-06-19 21:34:23Z joseph $
  {L3 experimental bootstrap code}
%</package>
%<*driver>
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3bootstrap} package\\ Bootstrap code^^A
%   \thanks{This file describes v\ExplFileVersion,
%     last revised \ExplFileDate.}^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released \ExplFileDate}
%
% \maketitle
%
% \begin{documentation}
%
% \section{Using the \LaTeX3 modules}
%
% The modules documented in \file{source3} are designed to be used on top of
% \LaTeXe{} and are loaded all as one with the usual |\usepackage{expl3}| or
% |\RequirePackage{expl3}| instructions. These modules will also form the
% basis of the \LaTeX3 format, but work in this area is incomplete and not
% included in this documentation at present.
%
% As the modules use a coding syntax different from standard
% \LaTeXe{} it provides a few functions for setting it up.
%
% \begin{function}{\ExplSyntaxOn, \ExplSyntaxOff}
%   \begin{syntax}
%     \cs{ExplSyntaxOn} \meta{code}  \cs{ExplSyntaxOff}
%   \end{syntax}
%   The \cs{ExplSyntaxOn} function switches to a category code
%   regim{\'e} in which spaces are ignored and in which the colon (|:|)
%   and underscore (|_|) are treated as \enquote{letters}, thus allowing
%   access to the names of code functions and variables. Within this
%   environment, |~| is used to input a space. The \cs{ExplSyntaxOff}
%   reverts to the document category code regim{\'e}.
% \end{function}
%
% \begin{function}{\ExplSyntaxNamesOn, \ExplSyntaxNamesOff}
%   \begin{syntax}
%     \cs{ExplSyntaxNamesOn} \meta{code}  \cs{ExplSyntaxNamesOff}
%   \end{syntax}
%   The \cs{ExplSyntaxOn} function switches to a category code
%   regim{\'e} in which the colon (|:|) and underscore (|_|) are treated as
%   \enquote{letters}, thus allowing access to the names of code functions
%   and variables. In contrast to \cs{ExplSyntaxOn}, using
%   \cs{ExplSyntaxNamesOn} does not cause spaces to be ignored.
%   The \cs{ExplSyntaxNamesOff} reverts to the document category code
%   regim{\'e}.
% \end{function}
%
% \begin{function}{\ProvidesExplPackage, \ProvidesExplClass, \ProvidesExplFile}
%   \begin{syntax}
%     |\RequirePackage{expl3}| \\
%     \cs{ProvidesExplPackage} \Arg{package} \Arg{date} \Arg{version}
%     ~~\Arg{description}
%   \end{syntax}
%   These functions act broadly in the same way as the \LaTeXe{} kernel
%   functions \cs{ProvidesPackage}, \cs{ProvidesClass} and
%   \cs{ProvidesFile}. However, they also implicitly switch
%   \cs{ExplSyntaxOn} for the remainder of the code with the file. At the
%   end of the file, \cs{ExplSyntaxOff} will be called to reverse this.
%   (This is the same concept as \LaTeXe{} provides in turning on
%   \cs{makeatletter} within package and class code.)
% \end{function}
%
% \begin{function}{\GetIdInfo}
%   \begin{syntax}
%     |\RequirePackage{l3names}|
%     \cs{GetIdInfo} |$Id:| \meta{SVN info field} |$| \Arg{description}
%   \end{syntax}
%   Extracts all information from a SVN field. Spaces are not
%   ignored in these fields. The information pieces are stored in
%   separate control sequences with \cs{ExplFileName} for the part of the
%   file name leading up to the period, \cs{ExplFileDate} for date,
%   \cs{ExplFileVersion} for version and \cs{ExplFileDescription} for the
%   description.
% \end{function}
%
% To summarize: Every single package using this syntax should identify
% itself using one of the above methods. Special care is taken so that
% every package or class file loaded with \cs{RequirePackage} or alike
% are loaded with usual \LaTeXe{} category codes and the \LaTeX3 category code
% scheme is reloaded when needed afterwards. See implementation for
% details. If you use the \cs{GetIdInfo} command you can use the
% information when loading a package with
% \begin{verbatim}
%   \ProvidesExplPackage{\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
% \end{verbatim}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{Bootstrap code}
%
%    \begin{macrocode}
%<*initex|package>
%    \end{macrocode}
%
% \subsection{Format-specific code}
%
% The very first thing to do is to bootstrap the \IniTeX{} system so
% that everything else will actually work. \TeX{} does not start with
% some pretty basic character codes set up.
%    \begin{macrocode}
%<*initex>
\catcode `\{ = 1 \relax
\catcode `\} = 2 \relax
\catcode `\# = 6 \relax
\catcode `\^ = 7 \relax
%</initex>
%    \end{macrocode}
%
% Tab characters should not show up in the code, but to be on the
% safe side.
%    \begin{macrocode}
%<*initex>
\catcode `\^^I = 10 \relax
%</initex>
%    \end{macrocode}
%
% For \LuaTeX{} the extra primitives need to be enabled before
% they can be use. No \cs{ifdefined} yet, so do it the old-fashioned
% way. The primitive \cs{strcmp} is simulated using some \Lua{}
% code, which currently has to be applied to every job as the \Lua{}
% code is not part of the format. Thanks to Taco Hoekwater for this
% code. The odd \cs{csname} business is needed so that the later
% deletion code will work.
%    \begin{macrocode}
%<*initex>
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname directlua\endcsname\relax
\else
  \directlua
    {
      tex.enableprimitives('',tex.extraprimitives ())
      lua.bytecode[1] = function ()
        function strcmp (A, B)
          if A == B then
            tex.write("0")
          elseif A < B then
            tex.write("-1")
          else
            tex.write("1")
          end
        end
      end
      lua.bytecode[1]()
    }
  \everyjob\expandafter
    {\csname\detokenize{luatex_directlua:D}\endcsname{lua.bytecode[1]()}}
  \long\edef\pdfstrcmp#1#2%
     {%
       \expandafter\noexpand\csname\detokenize{luatex_directlua:D}\endcsname
         {%
           strcmp%
             (%
               "\noexpand\luaescapestring{#1}",%
               "\noexpand\luaescapestring{#2}"%
             )%
         }%
     }
\fi
%</initex>
%    \end{macrocode}
%
% \subsection{Package-specific code}
%
% The package starts by identifying itself: the information itself is
% taken from the SVN |Id| string at the start of the source file.
%    \begin{macrocode}
%<*package>
\ProvidesPackage{l3bootstrap}
  [%
    \ExplFileDate\space v\ExplFileVersion\space
    L3 Experimental bootstrap code%
  ]
%</package>
%    \end{macrocode}
%
% For \LuaTeX{} the functionality of the \cs{pdfstrcmp} primitive
% needs to be provided: the \pkg{pdftexmcds} package is used to
% do this if necessary. At present, there is also a need to deal
% with some low-level allocation stuff that could usefully be added
% to \texttt{lualatex.ini}. As it is currently not, load Heiko
% Oberdiek's \pkg{luatex} package instead.
%    \begin{macrocode}
%<*package>
\def\@tempa%
  {%
    \def\@tempa{}%
    \RequirePackage{luatex}%
    \RequirePackage{pdftexcmds}%
    \let\pdfstrcmp\pdf@strcmp
  }
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname directlua\endcsname\relax
\else
  \expandafter\@tempa
\fi
%</package>
%    \end{macrocode}
%
% \begin{macro}{\ExplSyntaxOff, \ExplSyntaxOn}
%   Experimental syntax switching is set up here for the package-loading
%   process.  These are redefined in \pkg{expl3} for the package and in
%   \pkg{l3final} for the format.
%    \begin{macrocode}
%<*package>
\protected\edef\ExplSyntaxOff
  {%
    \catcode   9 = \the\catcode   9\relax
    \catcode  32 = \the\catcode  32\relax
    \catcode  34 = \the\catcode  34\relax
    \catcode  38 = \the\catcode  38\relax
    \catcode  58 = \the\catcode  58\relax
    \catcode  94 = \the\catcode  94\relax
    \catcode  95 = \the\catcode  95\relax
    \catcode 124 = \the\catcode 124\relax
    \catcode 126 = \the\catcode 126\relax
    \endlinechar = \the\endlinechar\relax
    \chardef\csname\detokenize{l_expl_status_bool}\endcsname = 0 \relax
  }
\protected\edef\ExplSyntaxOn
  {
    \catcode 9   = 9  \relax
    \catcode 32  = 9  \relax
    \catcode 34  = 12 \relax
    \catcode 58  = 11 \relax
    \catcode 94  = 7  \relax
    \catcode 95  = 11 \relax
    \catcode 124 = 12 \relax
    \catcode 126 = 10 \relax
    \endlinechar = 32 \relax
    \chardef\csname\detokenize{l_expl_status_bool}\endcsname = 1 \relax
  }
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_expl_status_bool}
%   The status for experimental code syntax: this is off at present. This
%   code is used by both the package and the format.
%    \begin{macrocode}
\expandafter\chardef\csname\detokenize{l_expl_status_bool}\endcsname = 0 \relax
%    \end{macrocode}
%\end{macro}
%
% \subsection{Dealing with package-mode meta-data}
%
% \begin{macro}{\GetIdInfo}
% \begin{macro}[aux]
%   {
%     \GetIdInfoFull, \GetIdInfoAuxI, \GetIdInfoAuxII, \GetIdInfoAuxIII,
%     \GetIdInfoAuxCVS, \GetIdInfoAuxSVN
%   }
%   Functions for collecting up meta-data from the SVN information
%   used by the \LaTeX3 Project.
%    \begin{macrocode}
%<*package>
\protected\def\GetIdInfo
  {
    \begingroup
    \catcode 32 = 10 \relax
    \GetIdInfoAuxI
  }
\protected\def\GetIdInfoAuxI$#1$#2%
  {
    \def\tempa{#1}%
    \def\tempb{Id}%
    \ifx\tempa\tempb
      \def\tempa
        {%
          \endgroup
          \def\ExplFileDate{0000/00/00}%
          \def\ExplFileDescription{#2}%
          \def\ExplFileName{[unknown~name]}%
          \def\ExplFileVersion{000}%
        }%
    \else
      \def\tempa
        {%
          \endgroup
          \GetIdInfoAuxII$#1${#2}%
        }%
    \fi
    \tempa
  }
\protected\def\GetIdInfoAuxII$#1 #2.#3 #4 #5 #6 #7 #8$#9%
  {%
    \def\ExplFileName{#2}%
    \def\ExplFileVersion{#4}%
    \def\ExplFileDescription{#9}%
    \GetIdInfoAuxIII#5\relax#3\relax#5\relax#6\relax
  }
\protected\def\GetIdInfoAuxIII#1#2#3#4#5#6\relax
  {%
    \ifx#5/%
      \expandafter\GetIdInfoAuxCVS
    \else
      \expandafter\GetIdInfoAuxSVN
    \fi
  }
\protected\def\GetIdInfoAuxCVS#1,v\relax#2\relax#3\relax
  {\def\ExplFileDate{#2}}
\protected\def\GetIdInfoAuxSVN#1\relax#2-#3-#4\relax#5Z\relax
  {\def\ExplFileDate{#2/#3/#4}}
%</package>
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ProvidesExplPackage, \ProvidesExplClass, \ProvidesExplFile}
%   For other packages and classes building on this one it is convenient
%   not to need \cs{ExplSyntaxOn} each time.
%    \begin{macrocode}
%<*package>
\protected\def\ProvidesExplPackage#1#2#3#4%
  {%
    \ProvidesPackage{#1}[#2 v#3 #4]%
    \ExplSyntaxOn
  }
\protected\def\ProvidesExplClass#1#2#3#4%
  {%
    \ProvidesClass{#1}[#2 v#3 #4]%
    \ExplSyntaxOn
  }
\protected\def\ProvidesExplFile#1#2#3#4%
  {%
    \ProvidesFile{#1}[#2 v#3 #4]%
    \ExplSyntaxOn
  }
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@pushfilename, \@popfilename}
%   The idea here is to use \LaTeXe{}'s \cs{@pushfilename} and
%   \cs{@popfilename} to track the current syntax status. This can be
%   achieved by saving the current status flag at each push to a stack,
%   then recovering it at the pop stage and checking if the code
%   environment should still be active.
%    \begin{macrocode}
%<*package>
\edef\@pushfilename
  {%
    \edef\expandafter\noexpand
      \csname\detokenize{l_expl_status_stack_tl}\endcsname
      {%
        \noexpand\ifodd\expandafter\noexpand
          \csname\detokenize{l_expl_status_bool}\endcsname
          1%
        \noexpand\else
          0%
        \noexpand\fi
        \expandafter\noexpand
          \csname\detokenize{l_expl_status_stack_tl}\endcsname
      }%
    \ExplSyntaxOff
    \unexpanded\expandafter{\@pushfilename}%
  }
\edef\@popfilename
  {%
    \unexpanded\expandafter{\@popfilename}%
    \noexpand\if a\expandafter\noexpand\csname
      \detokenize{l_expl_status_stack_tl}\endcsname a%
      \ExplSyntaxOff
    \noexpand\else
      \noexpand\expandafter
        \expandafter\noexpand\csname
          \detokenize{expl_status_pop:w}\endcsname
          \expandafter\noexpand\csname
            \detokenize{l_expl_status_stack_tl}\endcsname
          \noexpand\@nil
   \noexpand\fi
  }
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_expl_status_stack_tl}
%   As \pkg{expl3} itself cannot be loaded with the code environment
%   already active, at the end of the package \cs{ExplSyntaxOff} can
%   safely be called.
%    \begin{macrocode}
%<*package>
\@namedef{\detokenize{l_expl_status_stack_tl}}{0}
%</package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[aux]{\expl_status_pop:w}
%   The pop auxiliary function removes the first item from the stack,
%   saves the rest of the stack and then does the test. As
%   \cs{ExplSyntaxOff} is already defined as a protected macro, there
%   is no need for \cs{noexpand} here.
%    \begin{macrocode}
%<*package>
\expandafter\edef\csname\detokenize{expl_status_pop:w}\endcsname#1#2\@nil
  {%
    \def\expandafter\noexpand
      \csname\detokenize{l_expl_status_stack_tl}\endcsname{#2}%
    \noexpand\ifodd#1\space
      \noexpand\expandafter\noexpand\ExplSyntaxOn
    \noexpand\else
      \noexpand\expandafter\ExplSyntaxOff
    \noexpand\fi
  }
%</package>
%    \end{macrocode}
% \end{macro}
%
% We want the \pkg{expl3} bundle to be loaded \enquote{as one};
% this command is
% used to ensure that one of the |l3| packages isn't loaded on its own.
%    \begin{macrocode}
%<*package>
\expandafter\protected\expandafter\def
  \csname\detokenize{package_check_loaded_expl:}\endcsname
  {%
    \@ifpackageloaded{expl3}
      {}
      {%
        \PackageError{expl3}
          {Cannot load the expl3 modules separately}
          {%
            The expl3 modules cannot be loaded separately;\MessageBreak
            please \string\usepackage\string{expl3\string} instead.
          }%
      }%
  }
%</package>
%    \end{macrocode}
%
% \subsection{The \cs{pdfstrcmp} primitive in \XeTeX{}}
%
% Only \pdfTeX{} has a primitive called \cs{pdfstrcmp}. The \XeTeX{}
% version is just \cs{strcmp}, so there is some shuffling to do.
%    \begin{macrocode}
\begingroup\expandafter\expandafter\expandafter\endgroup
  \expandafter\ifx\csname pdfstrcmp\endcsname\relax
  \let\pdfstrcmp\strcmp
\fi
%    \end{macrocode}
%
% \subsection{Engine requirements}
%
% The code currently requires functionality equivalent to \cs{pdfstrcmp}
% in addition to \eTeX{}. The former is therefore used as a test for
% a suitable engine.
%    \begin{macrocode}
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname pdfstrcmp\endcsname\relax
%<*package>
  \PackageError{l3names}{Required primitive not found: \protect\pdfstrcmp}
    {%
      LaTeX3 requires the e-TeX primitives and
        \string\pdfstrcmp.\MessageBreak
      These are available in engine versions: \MessageBreak
      - pdfTeX 1.30 \MessageBreak
      - XeTeX 0.9994 \MessageBreak
      - LuaTeX 0.60 \MessageBreak
      or later. \MessageBreak
      \MessageBreak
      Loading of expl3 will abort!
    }
%</package>
%<*initex>
  \newlinechar`\^^J\relax
  \errhelp{%
      LaTeX3 requires the e-TeX primitives and
        \string\pdfstrcmp. ^^J
      These are available in engine versions:  ^^J
      - pdfTeX 1.30  ^^J
      - XeTeX 0.9994 ^^J
      - LuaTeX 0.60  ^^J
      or later. ^^J
      For pdfTeX and XeTeX the '-etex' command-line switch is also
      needed.^^J
       ^^J
      Format building will abort!
  }
%</initex>
  \expandafter\endinput
\fi
%    \end{macrocode}
%
% \subsection{The \LaTeX3 code environment}
%
% \begin{macro}{\ExplSyntaxNamesOn, \ExplSyntaxNamesOff}
%   These can be set up early, as they are not used anywhere in the
%   package or format itself. Using an \cs{edef} here makes the
%   definitions that bit clearer later.
%    \begin{macrocode}
\protected\edef\ExplSyntaxNamesOn
  {%
    \expandafter\noexpand
      \csname\detokenize{char_set_catcode_letter:n}\endcsname{58}%
    \expandafter\noexpand
      \csname\detokenize{char_set_catcode_letter:n}\endcsname{95}%
  }
\protected\edef\ExplSyntaxNamesOff
  {%
    \expandafter\noexpand
      \csname\detokenize{char_set_catcode_math_subscript:n}\endcsname{58}%
    \expandafter\noexpand
      \csname\detokenize{char_set_catcode_other:n}\endcsname{95}%
  }
%    \end{macrocode}
% \end{macro}
%
% The code environment is now set up for the format: the package deals
% with this using \cs{ProvidesExplPackage}.
%    \begin{macrocode}
%<*initex>
\catcode 9   = 9  \relax
\catcode 32  = 9  \relax
\catcode 34  = 12 \relax
\catcode 58  = 11 \relax
\catcode 94  = 7  \relax
\catcode 95  = 11 \relax
\catcode 124 = 12 \relax
\catcode 126 = 10 \relax
\endlinechar = 32 \relax
%</initex>
%    \end{macrocode}
%    
% \begin{macro}{\ExplSyntaxOn, \ExplSyntaxOff}
%  The idea here is that multiple \cs{ExplSyntaxOn} calls are not
%  going to mess up category codes, and that multiple calls to
%  \cs{ExplSyntaxOff} are also not wasting time.
%    \begin{macrocode}
%<*initex>
\protected \def \ExplSyntaxOn
  {
    \bool_if:NF \l_expl_status_bool
      {
        \cs_set_protected_nopar:Npx \ExplSyntaxOff
          {
            \char_set_catcode:nn { 9 }   { \char_value_catcode:n { 9 } }
            \char_set_catcode:nn { 32 }  { \char_value_catcode:n { 32 } }
            \char_set_catcode:nn { 34 }  { \char_value_catcode:n { 34 } }
            \char_set_catcode:nn { 38 }  { \char_value_catcode:n { 38 } }
            \char_set_catcode:nn { 58 }  { \char_value_catcode:n { 58 } }
            \char_set_catcode:nn { 94 }  { \char_value_catcode:n { 94 } }
            \char_set_catcode:nn { 95 }  { \char_value_catcode:n { 95 } }
            \char_set_catcode:nn { 124 } { \char_value_catcode:n { 124 } }
            \char_set_catcode:nn { 126 } { \char_value_catcode:n { 126 } }
            \tex_endlinechar:D = 
              \tex_the:D \tex_endlinechar:D \scan_stop:
            \bool_set_false:N \l_expl_status_bool
            \cs_set_protected_nopar:Npn \ExplSyntaxOff { }
          }
      }
    \char_set_catcode_ignore:n           { 9 }   % tab
    \char_set_catcode_ignore:n           { 32 }  % space
    \char_set_catcode_other:n            { 34 }  % double quote
    \char_set_catcode_alignment:n        { 38 }  % ampersand
    \char_set_catcode_letter:n           { 58 }  % colon
    \char_set_catcode_math_superscript:n { 94 }  % circumflex
    \char_set_catcode_letter:n           { 95 }  % underscore
    \char_set_catcode_other:n            { 124 } % pipe
    \char_set_catcode_space:n            { 126 } % tilde  
    \tex_endlinechar:D = 32 \scan_stop:
    \bool_set_true:N \l_expl_status_bool
  }
\protected \def \ExplSyntaxOff { }
%</initex>
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}{\l_expl_status_bool}
%   A flag to show the current syntax status. 
%    \begin{macrocode}
%<*initex>
\chardef \l_expl_status_bool = 0 ~
%</initex>
%    \end{macrocode}
% \end{variable}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex