summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx')
-rw-r--r--Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx314
1 files changed, 255 insertions, 59 deletions
diff --git a/Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx b/Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx
index b3172c06e24..f869c5bfa3d 100644
--- a/Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx
+++ b/Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx
@@ -1,8 +1,7 @@
% \iffalse meta-comment
%
-% Written in 2009, 2010 by Manuel Pégourié-Gonnard and Élie Roux.
-% <mpg@elzevir.fr>
-% <elie.roux@telecom-bretagne.eu>
+% Copyright 2009, 2010 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.
%
@@ -35,10 +34,7 @@
\preamble
-Written in 2009, 2010 by Manuel Pegourie-Gonnard and Elie Roux.
-
-This work is under the CC0 license.
-See source file '\inFileName' for details.
+See the aforementioned source file(s) for copyright and licensing information.
\endpreamble
@@ -113,27 +109,30 @@ See source file '\inFileName' for details.
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
-% \pkdate{luatexbase-cctb}{v0.3 2010-05-27}
+% \pkdate{luatexbase-cctb}{v0.4 2011-05-24}
%
% \maketitle
%
% \begin{abstract}
% In addition to the registers existing in \tex and \etex, \luatex introduces
% a new concept: catcode tables. This package takes care of catcode table
-% allocation just like Plain TeX and LaTeX do for other registers.
+% allocation just like Plain TeX and LaTeX do for other registers. It also
+% provides a few handy macros from common use cases.
% \end{abstract}
%
% \tableofcontents
%
% \section{Documentation}
%
+% \subsection{Allocation and setting}
+%
% The main macro defined here is |\newluatexcatcodetable|. It behaves the same
-% as |\newbox|. Additonally, the newly allocated catcode table is initialised
+% as |\newbox|. Additionally, the newly allocated catcode table is initialised
% to the catcodes of Ini\tex. In order to help you define the catcode tables
% (once they are allocated), two helper macros are available.
%
% \begin{quote}
-% \cs{setcatcoderange}\marg{from}\marg{to}\marg{value}
+% \cs{SetCatcodeRange}\marg{from}\marg{to}\marg{value}
% \end{quote}
% Set all characters code in the range \meta{from}--\meta{to} to the given
% catcode \meta{value}.
@@ -144,9 +143,10 @@ See source file '\inFileName' for details.
% Set a previously allocated \meta{table} to the catcodes given by executing
% \meta{catcode statements}. Note that \meta{table} must not be the current
% active catcode table. You may, however, load another catcode table in your
-% \meta{catcode statements}.
+% \meta{catcode statements} (if you don't, then the current catcodes will be
+% used as a basis).
%
-% For your convenience, a few catcode tables are prefined:
+% For your convenience, a few catcode tables are predefined:
% \begin{itemize}
% \item |\CatcodeTableIniTeX|: Ini\tex catcodes.
% \item |\CatcodeTableString|: the catcode regime used by |\string| and
@@ -161,14 +161,28 @@ See source file '\inFileName' for details.
% |\endlinechar| is not adjusted (it should be 32).
% \end{itemize}
%
-% Various Lua function accept a catcode table number as argument. In order to
-% use them, the package writer needs to know the number of an allocated
-% catcode table. Since |\chardef| is used for the definition of the control
-% sequence, this is rather easy to do. However, for extra ease of use, the
-% numbers are also directly accessible from Lua as the value of the table
-% |luatexbase.catcodetables|, whose keys is the name of the control sequence
-% (without any leading backslash). Moreover, nickames are available for the
-% predefined catcode tables:
+% \subsection{Access from Lua}
+%
+% Various Lua functions, such as |tex.print| accept a catcode table number as
+% argument. In order to use in Lua the catcode tables allocated in \tex, the
+% package writer needs to know their number. Since |\chardef| is used for the
+% definition of the control sequence, this is rather easy to do. However, for
+% extra ease of use, the numbers are also directly accessible from Lua as the
+% value of the table |luatexbase.catcodetables|, whose keys is the name of the
+% control sequence (without any leading backslash). For example, after
+% \begin{quote}
+% |\newluatexcatcodetable\mycatcodes|
+% \end{quote}
+% the variable |luatexbase.catcodetables.mycatcodes| will hold the number of
+% the catcode table |\mycatcodes|. You will usually want to do
+% \begin{quote}
+% |local mycatcodes = luatexbase.catcodetables.mycatcodes|
+% \end{quote}
+% at the beginning of your Lua module (assuming it is loaded after the catcode
+% table has been allocated) and then use |tex.print(mycatcodes, ...)| in the
+% rest of your Lua code.
+%
+% Also, nicknames are available for the predefined catcode tables:
% \begin{itemize}
% \item |CatcodeTableIniTeX| = |ini|,
% \item |CatcodeTableString| = |string|,
@@ -178,6 +192,76 @@ See source file '\inFileName' for details.
% \item |CatcodeTableExpl| = |expl| = |expl3|,
% \end{itemize}
%
+% \subsection{High-level stack interface}
+%
+% In many situations, you want to ensure a proper set of catcodes for some
+% time, then go back to the previous catcodes without using a group. The
+% obvious use case is a package, which may be loaded while unexpected
+% catcodes are active. A pair of macros is provided to deal precisely with
+% this situation.
+% \begin{quote}
+% \cs{BeginCatcodeRegime}\marg{catcode table}\\
+% \meta{code}\\
+% \cs{EndCatcodeRegime}
+% \end{quote}
+% \cs{BeginCatcodeRegime} remembers the current catcode table, then
+% initializes a new one with a copy of the \meta{catcode table} given (so that
+% this table is not changed by anything in \meta{code}), and makes it the
+% active table. \cs{EndCatcodeRegime} restores the previous catcode table.
+%
+% For example, a \latex package might do:
+% \begin{quote}
+% |\BeginCatcodeRegime\CatcodeTableLaTeXAtLetter|\\
+% |% package code|\\
+% |\EndCatcodeRegime|
+% \end{quote}
+% Every catcode change made in the package code will be lost avec
+% \cs{EndCatcodeRegime}; if you want them to survive, please use
+% \cs{AtEndOfPackage} or \cs{AtBeginDocument}.
+%
+% By the way, you may add catcode statements in the argument of
+% \cs{BeginCatcodeRegime} after the name of a catcode table. So the first line
+% of the previous example is equivalent to
+% \begin{quote}
+% |\BeginCatcodeRegime{\CatcodeTableLaTeX \makeatletter}|
+% \end{quote}
+%
+% \subsection{Low-level stack interface}
+%
+% The previous macros use internally two stacks : the first on holds the
+% numbers of the active catcodes tables, so remembering the current table
+% means pushing its number on the stack, and restoring the previously active
+% table means popping it off the stack. This is done with:
+% \begin{quote}
+% \cs{PushCatcodeTableNumStack}\\
+% \cs{PopCatcodeTableNumStack}
+% \end{quote}
+% Note that \cs{PushCatcodeTableNumStack} doesn't change current catcodes
+% but \cs{PopCatcodeTableNumStack} does.
+%
+% The second stack consists of temporary tables, mainly used to hold copies of
+% existing tables. A temporary table are allocated with
+% \cs{IncCatcodeTableStack}, accessed with \cs{CatcodeTableStack} and the
+% freed with \cs{DecCatcodeTableStack}, none of which changes the current
+% table.
+%
+% As an illustration, \cs{BeginCatcodeRegime} does
+% \begin{quote}
+% |\PushCatcodeTableNumStack|\\
+% |\IncCatcodeTableStack|\\
+% |\setluatexcatcodetable\CatcodeTableStack{\luatexcatcodetable#1}%|\\
+% |\luatexcatcodetable\CatcodeTableStack|
+% \end{quote}
+% and \cs{EndCatcodeRegime} is defined as
+% \begin{quote}
+% |\DecCatcodeTableStack|\\
+% |\PopCatcodeTableNumStack|
+% \end{quote}
+%
+% If you choose to use this low-level interface, it is your responsibility to
+% ensure proper balancing of push-pop and inc-dec, as well as making sure that
+% a temporary table is never used after it has been freed.
+%
% \section{Implementation}
%
% \subsection{\tex package}
@@ -188,48 +272,47 @@ See source file '\inFileName' for details.
%
% \subsubsection{Preliminaries}
%
-% Reload protection, especially for \plaintex.
-%
-% \begin{macrocode}
- \csname lltxb@cctb@loaded\endcsname
-\expandafter\let\csname lltxb@cctb@loaded\endcsname\endinput
-% \end{macrocode}
-%
-% Catcode defenses.
+% Catcode defenses and reload protection.
%
% \begin{macrocode}
-\begingroup
+\begingroup\catcode61\catcode48\catcode32=10\relax% = and space
\catcode123 1 % {
\catcode125 2 % }
\catcode 35 6 % #
- \toks0{}%
- \def\x{}%
+ \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 123 1 % {
- \y 125 2 % }
- \y 35 6 % #
- \y 10 12 % ^^J
- \y 34 12 % "
- \y 36 3 % $ $
+ \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 42 12 % *
- \y 43 12 % +
\y 44 12 % ,
\y 45 12 % -
\y 46 12 % .
\y 47 12 % /
+ \y 58 12 % :
\y 60 12 % <
- \y 61 12 % =
- \y 64 11 % @ (letter)
\y 62 12 % >
- \y 95 12 % _ (other)
+ \y 91 12 % [
+ \y 93 12 % ]
+ \y 94 7 % ^
+ \y 95 8 % _
\y 96 12 % `
- \edef\y#1{\endgroup\edef#1{\the\toks0\relax}\x}%
-\expandafter\y\csname lltxb@cctb@AtEnd\endcsname
+ \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@cctb@sty@endinput\endcsname%
% \end{macrocode}
%
% Package declaration.
@@ -242,7 +325,7 @@ See source file '\inFileName' for details.
\let\x\ProvidesPackage
\fi
\expandafter\endgroup
-\x{luatexbase-cctb}[2010/10/10 v0.3 Catcodetable allocation for LuaTeX]
+\x{luatexbase-cctb}[2011/05/24 v0.4 Catcodetable allocation for LuaTeX]
% \end{macrocode}
%
% Make sure \luatex is used.
@@ -263,12 +346,11 @@ See source file '\inFileName' for details.
\let\x\PackageError
\fi
\expandafter\endgroup
- \x{luatexbase-attr}{LuaTeX is required for this package. Aborting.}{%
+ \x{luatexbase-cctb}{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.}
- \lltxb@cctb@AtEnd
- \expandafter\endinput
+ \expandafter\luatexbase@cctb@sty@endinput%
\fi
% \end{macrocode}
%
@@ -299,15 +381,21 @@ See source file '\inFileName' for details.
\luatexbase@ensure@primitive{savecatcodetable}
% \end{macrocode}
%
-% \subsubsection{User macros}
+% \subsubsection{Allocation and temporary tables}
%
-% The allocation macro. Allocate tables starting with 1, since table 0 is
-% the default table. Allocate only odd numbers to allow using even numbers
-% as a stack.
+% Counters for the allocated and temporary tables.
%
% \begin{macrocode}
\newcount\lltxb@catcodetable@alloc
\lltxb@catcodetable@alloc\m@ne
+\newcount\CatcodeTableStack
+\CatcodeTableStack\z@
+% \end{macrocode}
+%
+% The allocation macro. Allocate only odd numbers to allow using even
+% numbers for temporary tables.
+%
+% \begin{macrocode}
\def\newluatexcatcodetable#1{%
\ifnum\lltxb@catcodetable@alloc<65535\relax
\global\advance\lltxb@catcodetable@alloc\tw@
@@ -324,6 +412,30 @@ See source file '\inFileName' for details.
\fi}
% \end{macrocode}
%
+% Allocate a new temporary table, using even numbers.
+%
+% \begin{macrocode}
+\def\IncCatcodeTableStack{%
+ \ifnum\CatcodeTableStack<65534\relax
+ \global\advance\CatcodeTableStack\tw@
+ \else
+ \errmessage{CatcodeTableStack overflow}%
+ \fi}
+% \end{macrocode}
+%
+% Free a temporary table.
+%
+% \begin{macrocode}
+\def\DecCatcodeTableStack{%
+ \ifnum\CatcodeTableStack>\z@
+ \global\advance\CatcodeTableStack-2\relax
+ \else
+ \errmessage{CatcodeTableStack underflow}%
+ \fi}
+% \end{macrocode}
+%
+% \subsubsection{Setting catcode tables}
+%
% A small patch to get two new counters in Plain too.
%
% \begin{macrocode}
@@ -338,7 +450,7 @@ See source file '\inFileName' for details.
% Set the catcodes for a range of characters.
%
% \begin{macrocode}
-\def\setcatcoderange#1#2#3{%
+\def\SetCatcodeRange#1#2#3{%
\edef\luaSCR@temp{%
\noexpand\@tempcnta=\the\@tempcnta
\noexpand\@tempcntb=\the\@tempcntb
@@ -354,6 +466,29 @@ See source file '\inFileName' for details.
\luaSCR@temp}
% \end{macrocode}
%
+% Make \cs{SetCatcodeRange} available with its old name.
+%
+% \begin{macrocode}
+\def\lltxb@synonym#1#2{%
+ \def#1{%
+ \begingroup
+ \ifdefined\PackageWarning
+ \let\x\PackageWarning
+ \else
+ \def\x####1####2{%
+ \begingroup \endlinechar10
+ \message{Package ####1 warning: ####2}%
+ \endgroup}
+ \fi
+ \expandafter\endgroup
+ \x{luatex}{\string#1 is deprecated^^J%
+ and will be removed in the next version of the package.^^J%
+ Please use \string#2 instead.}
+ \let#1#2%
+ #1}}
+\lltxb@synonym \setcatcoderange \SetCatcodeRange
+% \end{macrocode}
+%
% Set a catcode table.
%
% \begin{macrocode}
@@ -381,8 +516,8 @@ See source file '\inFileName' for details.
\catcode0 12 % nul
\catcode13 12 % carriage return
\catcode37 12 % percent
- \setcatcoderange{65}{90}{12}% A-Z
- \setcatcoderange{97}{122}{12}% a-z
+ \SetCatcodeRange{65}{90}{12}% A-Z
+ \SetCatcodeRange{97}{122}{12}% a-z
\catcode92 12 % backslash
\catcode127 12 }
% \end{macrocode}
@@ -400,8 +535,9 @@ See source file '\inFileName' for details.
\newluatexcatcodetable\CatcodeTableLaTeX
\setluatexcatcodetable\CatcodeTableLaTeX{%
\luatexcatcodetable\CatcodeTableIniTeX
- \setcatcoderange{0}{31}{15}%
+ \SetCatcodeRange{0}{31}{15}%
\catcode9 10 % tab
+ \catcode10 12 % newline
\catcode12 13 % form feed
\catcode13 5 % carriage return
\catcode35 6 % hash
@@ -436,16 +572,76 @@ See source file '\inFileName' for details.
}
% \end{macrocode}
%
-% Finally do the shortcuts.
+% Now do the shortcuts.
%
% \begin{macrocode}
\luatexbase@directlua{luatexbase.catcodetable_do_shortcuts()}
% \end{macrocode}
%
+% \subsubsection{Catcode table number stack and regimes}
+%
+% The stack is implemented as a list of (brace-enclosed) \tex arguments.
+% Initially, in contains only $0$, the number of the active table when
+% \luatex starts.
+%
+% \begin{macrocode}
+\def\lltxb@cctb@numstack{0}
+% \end{macrocode}
+%
+% Pushing a number on the stack actually means adding it to the beginning
+% of the list (ie, unshifting it).
+%
+% \begin{macrocode}
+\def\PushCatcodeTableNumStack{%
+ \xdef\lltxb@cctb@numstack{{\the\luatexcatcodetable}\lltxb@cctb@numstack}}
+% \end{macrocode}
+%
+% Popping a number off the stack means shifting it.
+%
+% \begin{macrocode}
+\def\PopCatcodeTableNumStack{%
+ \expandafter\lltxb@cctb@numstack@pop\lltxb@cctb@numstack\@nil}
+\def\lltxb@cctb@numstack@pop#1#2\@nil{%
+ \ifx\empty#2\empty
+ \begingroup
+ \ifdefined\PackageWarning
+ \let\x\PackageWarning
+ \else
+ \def\x####1####2{%
+ \begingroup \endlinechar10
+ \message{Package ####1 warning: ####2}%
+ \endgroup}%
+ \fi
+ \expandafter\endgroup
+ \x{luatexbase-cctb}{Popping from an empty CatcodeTableNumStack}%
+ \luatexcatcodetable\z@
+ \else
+ \gdef\lltxb@cctb@numstack{#2}%
+ \luatexcatcodetable#1\relax
+ \fi}
+% \end{macrocode}
+%
+% Now the catcode regime pseudo-environment as presented in the
+% documentation.
+%
+% \begin{macrocode}
+\def\BeginCatcodeRegime#1{%
+ \PushCatcodeTableNumStack
+ \IncCatcodeTableStack
+ \setluatexcatcodetable\CatcodeTableStack{\luatexcatcodetable#1}%
+ \luatexcatcodetable\CatcodeTableStack}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\def\EndCatcodeRegime{%
+ \DecCatcodeTableStack
+ \PopCatcodeTableNumStack}
+% \end{macrocode}
+%
% That's all, folks!
%
% \begin{macrocode}
-\lltxb@cctb@AtEnd
+\luatexbase@cctb@sty@endinput%
%</texpackage>
% \end{macrocode}
%