diff options
Diffstat (limited to 'Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx')
-rw-r--r-- | Master/texmf-dist/source/luatex/luatexbase/luatexbase-cctb.dtx | 314 |
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} % |