% \iffalse meta-comment
%
% Written in 2009, 2010 by Manuel Pégourié-Gonnard and Élie Roux.
% <mpg@elzevir.fr>
% <elie.roux@telecom-bretagne.eu>
%
% This work is under the CC0 license.
%
% This work consists of the main source file luatexbase-attr.dtx
% and the derived files
% luatexbase-attr.sty attr.lua
% test-regs-plain.tex test-regs-latex.tex
%
% Unpacking:
% tex luatexbase-attr.dtx
% Documentation:
% pdflatex luatexbase-attr.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
\let\MetaPrefix\relax
\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.
\endpreamble
\let\MetaPrefix\DoubleperCent
\generate{%
\usedir{tex/luatex/luatexbase}%
\file{luatexbase-attr.sty}{\from{luatexbase-attr.dtx}{texpackage}}%
}
\generate{%
\usedir{doc/luatex/luatexbase}%
\file{test-attr-plain.tex}{\from{luatexbase-attr.dtx}{testplain}}%
\file{test-attr-latex.tex}{\from{luatexbase-attr.dtx}{testlatex}}%
}
\def\MetaPrefix{-- }
\def\luapostamble{%
\MetaPrefix^^J%
\MetaPrefix\space End of File `\outFileName'.%
}
\def\currentpostamble{\luapostamble}%
\generate{%
\usedir{tex/luatex/luatexbase}%
\file{attr.lua}{\from{luatexbase-attr.dtx}{luamodule}}%
}
\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-attr.sty attr.lua}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}
\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\documentclass{ltxdoc}
\input lltxb-dtxstyle
\begin{document}
\DocInput{luatexbase-attr.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 \~}
%
% \title{The \pk{luatexbase-attr} package}
% \date{v0.2a 2010-05-27}
% \author{%
% Manuel P\'egouri\'e-Gonnard \\ \email{mpg@elzevir.fr} \and
% \'Elie Roux \\ \email{elie.roux@telecom-bretagne.eu}}
%
% \maketitle
%
% \begin{abstract}
% In addition to the registers existing in \tex and \etex, \luatex introduces
% a new concept: attributes. This package takes care of attribute allocation
% just like Plain TeX and LaTeX do for other registers, and also provides a
% Lua interface.
% \end{abstract}
%
% \tableofcontents
%
% \section{Documentation}
%
% The main macro defined here is |\newattribute|. It behaves in the same
% way as |\newcount|. There are also two helper macros: |\setattribute|
% sets an attribute's value (locally, but you can use |\global| in front of
% it). |\unsetattribute| unsets an atribute by giving it a special
% value, depending on \luatex's version; you should always use this macro
% in order to be sure the correct special value for your version of \luatex is
% used.
%
% Due to the intended use of attributes, it makes no sense to locally
% allocate an attribute the way you can locally allocate a counter using
% \file{etex.sty}'s |\loccount|, so no corresponding macro is defined.
%
% \subsection{Lua interface}
%
% The various Lua functions for manipulating attributes use a number to
% designate the attribute. Hence, package writers need a way to know the
% number of the attribute associated to |\fooattr| assuming it was defined
% using |\newattribute\fooattr|, something that \luatex currently
% doesn't support (you can get the current value of the associated attribute
% as |tex.atrribute.fooattr|, but not the attribute number).
%
% There are several ways to work around this. For example, it is possible to
% extract the number at any time from the |\meaning| of |\foobar|.
% Alternatively, one could look at |\the\allocationnumber| just after the
% definition of |\fooattr| and remember it in a Lua variable. For your
% convenience, this is automatically done by |\newattribute|: the number
% is remembered in a dedicated Lua table so that you can get it as
% |luatexbase.attributes.foobar| (mind the absence of backslash here) at any
% time.
%
% Also, two Lua functions are provided that are analogous to the above \tex
% macros (actually, the macros are wrappers around the functions):
% |luatexbase.new_attributes|\parg{name} allocates a new attribute, without
% defining a corresponding \tex control sequence (only an entry in
% |luatexbase.attributes| is created. It usually returns the number of the
% allocated attribute. If room is missing, it raises an error, unless the
% second argument (optional) is not false, in which case it returns -1.
%
% |luatexbase.unset_attribute|\parg{name} unsets an existing attribute.
%
% \section{Implementation}
%
% \subsection{\tex package}
%
% \begin{macrocode}
%<*texpackage>
% \end{macrocode}
%
% \subsubsection{Preliminaries}
%
% Reload protection, especially for \plaintex.
%
% \begin{macrocode}
\csname lltxb@attr@loaded\endcsname
\expandafter\let\csname lltxb@attr@loaded\endcsname\endinput
% \end{macrocode}
%
% Catcode defenses.
%
% \begin{macrocode}
\begingroup
\catcode123 1 % {
\catcode125 2 % }
\catcode 35 6 % #
\toks0{}%
\def\x{}%
\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 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 60 12 % <
\y 61 12 % =
\y 64 11 % @ (letter)
\y 62 12 % >
\y 95 12 % _ (other)
\y 96 12 % `
\edef\y#1{\endgroup\edef#1{\the\toks0\relax}\x}%
\expandafter\y\csname lltxb@attr@AtEnd\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-attr}[2010/05/27 v0.3-pre Attributes allocation for LuaTeX]
% \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 PackageWarningNoLine\endcsname\relax
\def\x#1#2{\begingroup\newlinechar10
\immediate\write16{Package #1 warning: #2}\endgroup}
\else
\let\x\PackageWarningNoLine
\fi
\expandafter\endgroup
\x{luatexbase-attr}{LuaTeX is required for this package. Aborting.}
\lltxb@attr@AtEnd
\expandafter\endinput
\fi
% \end{macrocode}
%
% \subsubsection{Primitives needed}
%
% Load \pk{luatexbase-compat}.
%
% \begin{macrocode}
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname RequirePackage\endcsname\relax
\input luatexbase-compat.sty
\else
\RequirePackage{luatexbase-compat}
\fi
% \end{macrocode}
%
% Make sure the primitives we need are available.
%
% \begin{macrocode}
\luatexbase@ensure@primitive{luaescapestring}
\luatexbase@ensure@primitive{attributedef}
\luatexbase@ensure@primitive{attribute}
% \end{macrocode}
%
% \subsubsection{Load supporting Lua module}
%
% First load \pk{luatexbase-loader} (hence \pk{luatexbase-compat}), then
% the supporting Lua module.
%
% \begin{macrocode}
\begingroup\expandafter\expandafter\expandafter\endgroup
\expandafter\ifx\csname RequirePackage\endcsname\relax
\input luatexbase-loader.sty
\else
\RequirePackage{luatexbase-loader}
\fi
\luatexbase@directlua{require('luatexbase.attr')}
% \end{macrocode}
%
% \subsection{User macros}
%
% The allocaton macro is merely a wrapper around the Lua function, but
% handles error and logging in \tex, for consistency with other allocation
% macros.
%
% \begin{macrocode}
\def\newattribute#1{%
\begingroup\escapechar\m@ne \expandafter\expandafter\expandafter
\endgroup \expandafter\expandafter\expandafter
\allocationnumber \luatexbase@directlua{tex.write(
luatexbase.new_attribute("\luatexluaescapestring{\string#1}", true))}%
\ifnum\allocationnumber>\m@ne
\global\luatexattributedef#1=\allocationnumber
\wlog{\string#1=\string\luatexattribute\the\allocationnumber}%
\else
\errmessage{No room for a new \string\luatexattribute}%
\fi}
% \end{macrocode}
%
% Helper macro |\unsetattribute|: wrapper around the Lua function.
%
% \begin{macrocode}
\def\unsetattribute#1{%
\begingroup\escapechar\m@ne
\luatexbase@directlua{%
luatexbase.unset_attribute("\luatexluaescapestring{\string#1}")}%
\endgroup}
% \end{macrocode}
%
% And now the trivial helper macro.
%
% \begin{macrocode}
\def\setattribute#1#2{%
#1=\numexpr#2\relax}
% \end{macrocode}
%
% That's all folks!
%
% \begin{macrocode}
\lltxb@attr@AtEnd
%</texpackage>
% \end{macrocode}
%
% \subsection{Lua module}
%
% \begin{macrocode}
%<*luamodule>
module('luatexbase', package.seeall)
% \end{macrocode}
%
% This table holds the values of the allocated attributes, indexed by name.
%
% \begin{macrocode}
attributes = {}
% \end{macrocode}
%
% The allocaton function. Unlike other registers, allocate starting from 1.
% Some code (eg, font handling coming from Con\tex{}t) behaves strangely
% with \verb+\attribute0+ and since there is plenty of room here, it
% doesn't seem bad to ``loose'' one item in order to avoid this problem.
%
% \begin{macrocode}
local last_alloc = 0
function new_attribute(name, silent)
if last_alloc >= 65535 then
if silent then
return -1
else
error("No room for a new \\attribute", 1)
end
end
last_alloc = last_alloc + 1
attributes[name] = last_alloc
unset_attribute(name)
if not silent then
texio.write_nl('log', string.format(
'luatexbase.attributes[%q] = %d', name, last_alloc))
end
return last_alloc
end
% \end{macrocode}
%
% Unset an attribute the correct way depending on \luatex's version.
%
% \begin{macrocode}
local unset_value = (luatexbase.luatexversion < 37) and -1 or -2147483647
function unset_attribute(name)
tex.setattribute(attributes[name], unset_value)
end
% \end{macrocode}
%
% \begin{macrocode}
%</luamodule>
% \end{macrocode}
%
% \section{Test files}
%
% The tests done are very basic: we just make sure that the package loads
% correctly and the macros don't generate any error, under both LaTeX en
% Plain TeX. We also check that the attribute's number is remembered well,
% independently of the current value of |\escapechar|.
%
% \begin{macrocode}
%<testplain>\input luatexbase-attr.sty
%<testlatex>\RequirePackage{luatexbase-attr}
%<*testplain,testlatex>
\newattribute\testattr
\setattribute\testattr{1}
\unsetattribute\testattr
\catcode64 11
\luatexbase@directlua{assert(luatexbase.attributes.testattr)}
\luatexbase@directlua{luatexbase.new_attribute('luatestattr')}
\luatexbase@directlua{assert(luatexbase.attributes.luatestattr)}
\begingroup
\escapechar64
\newattribute\anotherattr
\endgroup
\setattribute\anotherattr{1}
\luatexbase@directlua{assert(luatexbase.attributes.anotherattr)}
%</testplain,testlatex>
%<testplain>\bye
%<testlatex>\stop
% \end{macrocode}
%
%
% \Finale
\endinput