luatexbase.dtx

% \iffalse meta-comment
%
% Copyright 2009-2013 by Élie Roux <elie.roux@telecom-bretagne.eu>
% Copyright 2010, 2011 by Manuel Pégourié-Gonnard <mpg@elzevir.fr>
%
% This work is under the CC0 license.
%
% This work consists of the main source file luatexbase.dtx
% and the derived files
%    luatexbase.sty
%
% Unpacking:
%    tex luatexbase.dtx
% Documentation:
%    pdflatex luatexbase.dtx
%
%<*ignore>
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex

\keepsilent
\askforoverwritefalse

\preamble

See the aforementioned source file(s) for copyright and licensing information.

\endpreamble

\generate{%
  \usedir{tex/luatex/luatexbase}%
  \file{luatexbase.sty}{\from{luatexbase.dtx}{texpackage}}%
}

\generate{%
  \usedir{doc/luatex/luatexbase}%
  \file{test-base-plain.tex}{\from{luatexbase.dtx}{testplain}}%
  \file{test-base-latex.tex}{\from{luatexbase.dtx}{testlatex}}%
}

\obeyspaces
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* files into a directory searched by TeX:}
\Msg{*}
\Msg{*     luatexbase.sty}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\documentclass{ltxdoc}
\input{lltxb-dtxstyle}
\luatexbasetrue
\newcommand\subpk[1]{%
  \item[\href{luatexbase-#1.pdf}{luatexbase-#1}\normalfont:]}
\begin{document}
  \DocInput{luatexbase.dtx}%
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \pkdate{luatexbase}{v0.6 2013-05-11}
%
% \maketitle
%
% \begin{abstract}
% This package provides resource management for the LuaTeX macro programmer.
% It is divided in sub-packages which can be used independantly if desired.
% \end{abstract}
%
% \tableofcontents
%
% \section{Documentation}
%
% The \pk{luatexbase} package consists of the following sub-packages:
% \begin{description}
%   \subpk{compat} compatibility helpers for \verb+\directlua+, primitive
%   names and version information from Lua.
%   \subpk{loader} extension of \luatex's Lua module loader (since version
%   0.60.0, this is more of a compatibility layer for older versions than a
%   real extension).
%   \subpk{regs} extented allocation scheme for registers and the like,
%   \emph{\`a la} \pk{etex}.
%   \subpk{cctb} catcode table allocation.
%   \subpk{attr} attribute and whatsit node allocation.
%   \subpk{mcb} callbacks extensions allowing to register many functions in a
%   single callback, and declare new callbacks for packages.
%   \subpk{modutils} Lua module declaration, including version checks.
% \end{description}
%
% This package collection is considered stable: no backward-incompatible
% change should happen in the future, except the removal of the deprecated
% commands (currently only \cs{setcatcoderange}). It works with the Plain and
% \latex formats adapted for \luatex as provided by \texlive and MiK\tex.
% Currently the oldest version supported is 0.40.6 with formats from 
% \texlive 2009 and greater.
%
% \subsection{History}
%
% The first package for managing \luatex's new resources was the \pk{luatex}
% package by Heiko Oberdiek. Later, \'Elie Roux wrote \pk{luatextra} which
% reprised many features of \pk{luatex} with little extensions to some of them
% and added independant low-level features (currently found in the
% \pk{modutils} and \pk{mcb} subpackages), as well as user-level things.
% Later, \pk{luatexbase} was created by Manuel P\'egouri\'e-Gonnard by isolating
% the general low-level features of \pk{luatextra}, and later expanding on
% them.
%
% For some time there was two conflicting packages controling access to
% \luatex's resources: \pk{luatex} and \pk{luatexbase}, neither of which was a
% subset of the other, and with small differences in their overlapping parts
% (mainly macro names).
%
% Then \pk{luatexbase} was expanded by absorbing the features of \pk{luatex}
% that were previously missing (essentially the advanced scheme for catcode
% table management). It currently provides the \pk{luatex} package as a
% wrapper around the relevant subpackages, so that the two are no longer in
% conflict.
%
% \medskip
%
% For a detailled history of changes in \pk{luatexbase} since its split from
% \pk{luatextra}, see the \file{Changes} file in the distribution. For even
% more details, see the git history.
%
%    \section{Implementation}
%
%    \begin{macrocode}
%<*texpackage>
%    \end{macrocode}
%
%    \subsection{Preliminaries}
%
%    Catcode defenses and reload protection.
%
%    \begin{macrocode}
\begingroup\catcode61\catcode48\catcode32=10\relax% = and space
  \catcode123 1 % {
  \catcode125 2 % }
  \catcode 35 6 % #
  \toks0\expandafter{\expandafter\endlinechar\the\endlinechar}%
  \edef\x{\endlinechar13}%
  \def\y#1 #2 {%
    \toks0\expandafter{\the\toks0 \catcode#1 \the\catcode#1}%
    \edef\x{\x \catcode#1 #2}}%
  \y  13  5 % carriage return
  \y  61 12 % =
  \y  32 10 % space
  \y 123  1 % {
  \y 125  2 % }
  \y  35  6 % #
  \y  64 11 % @ (letter)
  \y  10 12 % new line ^^J
  \y  39 12 % '
  \y  40 12 % (
  \y  41 12 % )
  \y  45 12 % -
  \y  46 12 % .
  \y  47 12 % /
  \y  58 12 % :
  \y  91 12 % [
  \y  93 12 % ]
  \y  94  7 % ^
  \y  96 12 % `
  \toks0\expandafter{\the\toks0 \relax\noexpand\endinput}%
  \edef\y#1{\noexpand\expandafter\endgroup%
    \noexpand\ifx#1\relax \edef#1{\the\toks0}\x\relax%
    \noexpand\else \noexpand\expandafter\noexpand\endinput%
    \noexpand\fi}%
\expandafter\y\csname luatexbase@sty@endinput\endcsname%
%    \end{macrocode}
%
%    Package declaration.
%
%    \begin{macrocode}
\begingroup
  \expandafter\ifx\csname ProvidesPackage\endcsname\relax
    \def\x#1[#2]{\immediate\write16{Package: #1 #2}}
  \else
    \let\x\ProvidesPackage
  \fi
\expandafter\endgroup
\x{luatexbase}[2013/05/11 v0.6 Resource management for the LuaTeX macro programmer]
%    \end{macrocode}
%
%    Make sure \luatex is used.
%
%    \begin{macrocode}
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname RequirePackage\endcsname\relax
  \input ifluatex.sty
\else
  \RequirePackage{ifluatex}
\fi
\ifluatex\else
  \begingroup
    \expandafter\ifx\csname PackageError\endcsname\relax
      \def\x#1#2#3{\begingroup \newlinechar10
        \errhelp{#3}\errmessage{Package #1 error: #2}\endgroup}
    \else
      \let\x\PackageError
    \fi
  \expandafter\endgroup
  \x{luatexbase}{LuaTeX is required for this package. Aborting.}{%
    This package can only be used with the LuaTeX engine^^J%
    (command `lualatex' or `luatex').^^J%
    Package loading has been stopped to prevent additional errors.}
  \expandafter\luatexbase@sty@endinput%
\fi
%    \end{macrocode}
%
%    %\subsection{luatex.sty compatibility}
%
%    Currently, |luatex.sty| has to be loaded before luatexbase, otherwise it
%    raises an error, as the same names are used between luatexbase and luatex.
%
%    This is a quite strange situation, but we hope to clarify it.
%
%    \begin{macrocode}
\expandafter\ifx\csname RequirePackage\endcsname\relax
  \input luatex.sty
\else
  \RequirePackage{luatex}
\fi
%    \end{macrocode}
%
%    \subsection{Packages loading}
%
%    \begin{macrocode}
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname RequirePackage\endcsname\relax
  \input luatexbase-compat.sty
  \input luatexbase-modutils.sty
  \input luatexbase-loader.sty
  \input luatexbase-regs.sty
  \input luatexbase-attr.sty
  \input luatexbase-cctb.sty
  \input luatexbase-mcb.sty
\else
  \RequirePackage{luatexbase-compat}
  \RequirePackage{luatexbase-modutils}
  \RequirePackage{luatexbase-loader}
  \RequirePackage{luatexbase-regs}
  \RequirePackage{luatexbase-attr}
  \RequirePackage{luatexbase-cctb}
  \RequirePackage{luatexbase-mcb}
\fi
%    \end{macrocode}
%
%    This is the end, my friend\dots the end.
%
%    \begin{macrocode}
\luatexbase@sty@endinput%
%</texpackage>
%    \end{macrocode}
%
%    \section{Test file}
%
%    Very minimal, just check that the package correctly loads.
%
%    \begin{macrocode}
%<testplain>\input luatexbase.sty
%<testlatex>\RequirePackage{luatexbase}
%<testplain>\bye
%<testlatex>\stop
%    \end{macrocode}
%
%
% \Finale
\endinput