summaryrefslogtreecommitdiff
path: root/luamcallbacks.dtx
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2010-01-07 12:33:44 +0100
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2010-01-07 13:02:28 +0100
commitc8d64bf4bfd2d87d11b49a1a4091fad9aa00dcf9 (patch)
treef857a638e4c85428d6d6aacadebc45d53e32ed0c /luamcallbacks.dtx
downloadluatexbase-c8d64bf4bfd2d87d11b49a1a4091fad9aa00dcf9.tar.gz
Initial import of luamcallbacks.
Adapted README with intended package organisation.
Diffstat (limited to 'luamcallbacks.dtx')
-rw-r--r--luamcallbacks.dtx857
1 files changed, 857 insertions, 0 deletions
diff --git a/luamcallbacks.dtx b/luamcallbacks.dtx
new file mode 100644
index 0000000..c23a198
--- /dev/null
+++ b/luamcallbacks.dtx
@@ -0,0 +1,857 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2009 by Elie Roux <elie.roux@telecom-bretagne.eu>
+%
+% This work is under the CC0 license.
+%
+% This work consists of the main source file luamcallbacks.dtx
+% and the derived files
+% luamcallbacks.sty, luamcallbacks.tex, luamcallbacks.lua
+% luamcallbacks-test.tex, luamcallbacks.pdf.
+%
+% Unpacking:
+% tex luamcallbacks.dtx
+% Documentation:
+% pdflatex luamcallbacks.dtx
+%
+% The class ltxdoc loads the configuration file ltxdoc.cfg
+% if available. Here you can specify further options, e.g.
+% use A4 as paper format:
+% \PassOptionsToClass{a4paper}{article}
+%
+%<*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
+\Msg{************************************************************************}
+\Msg{* Installation}
+\Msg{* Package: luamcallbacks 2009/09/18 v0.93 LuaTeX multiple callbacks.}
+\Msg{************************************************************************}
+
+\keepsilent
+\askforoverwritefalse
+
+\let\MetaPrefix\relax
+
+\preamble
+This is a generated file.
+
+Copyright (C) 2009 by Elie Roux <elie.roux@telecom-bretagne.eu>
+
+This work is under the CC0 license.
+
+This work consists of the main source file luamcallbacks.dtx
+and the derived files
+ luamcallbacks.lua, luamcallbacks-test.tex, luamcallbacks.pdf.
+
+\endpreamble
+
+\let\MetaPrefix\DoubleperCent
+
+\generate{%
+ \usedir{doc/luatex/luatextra}%
+ \file{luamcallbacks-test.tex}{\from{luamcallbacks.dtx}{test}}%
+}
+
+% The following hacks are to generate a lua file with lua comments starting by
+% -- instead of %%
+
+\def\MetaPrefix{-- }
+
+\def\luapostamble{%
+ \MetaPrefix^^J%
+ \MetaPrefix\space End of File `\outFileName'.%
+}
+
+\def\currentpostamble{\luapostamble}%
+
+\generate{%
+ \usedir{tex/luatex/luatextra}%
+ \file{luamcallbacks.lua}{\from{luamcallbacks.dtx}{lua}}%
+}
+
+\obeyspaces
+\Msg{************************************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the following}
+\Msg{* files into a directory searched by TeX:}
+\Msg{*}
+\Msg{* luamcallbacks.lua}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{*}
+\Msg{************************************************************************}
+
+\endbatchfile
+%</install>
+%<*ignore>
+\fi
+%</ignore>
+%<*driver>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesFile{luamcallbacks.drv}
+ [2009/09/18 v0.93 LuaTeX multiple callbacks package]
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\begin{document}
+ \DocInput{luamcallbacks.dtx}%
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{5}
+%
+% \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 \~}
+%
+% \GetFileInfo{luamcallbacks.drv}
+%
+% \title{The \textsf{luamcallbacks} package}
+% \date{2009/09/18 v0.93}
+% \author{Elie Roux \\ \texttt{elie.roux@telecom-bretagne.eu}}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This package manages the callback adding and removing, by adding
+% \texttt{callback.add} and \texttt{callback.remove}, and overwriting
+% \texttt{callback.register}. It also allows to create and call new callbacks.
+% For an introduction on this package (among others), please refer to the
+% document \texttt{luatextra-reference.pdf}.
+% \end{abstract}
+%
+% \section{Documentation}
+%
+% Lua\TeX\ provides an extremely interesting feature, named callbacks. It
+% allows to call some lua functions at some points of the \TeX\ algorithm (a
+% \emph{callback}), like when \TeX\ breaks likes, puts vertical spaces, etc.
+% The Lua\TeX\ core offers a function called \texttt{callback.register} that
+% enables to register a function in a callback.
+%
+% The problem with \texttt{callback.register} is that is registers only one
+% function in a callback. For a lot of callbacks it can be common to have
+% several packages registering their function in a callback, and thus it is
+% impossible with them to be compatible with each other.
+%
+% This package solves this problem by adding mainly one new function
+% \texttt{callback.\\add} that adds a function in a callback. With this
+% function it is possible for packages to register their function in a
+% callback without overwriting the functions of the other packages.
+%
+% The functions are called in a certain order, and when a package registers a
+% callback it can assign a priority to its function. Conflicts can still
+% remain even with the priority mechanism, for example in the case where two
+% packages want to have the highest priority. In these cases the packages have
+% to solve the conflicts themselves.
+%
+% This package also privides a way to create and call new callbacks, in
+% addition to the default Lua\TeX\ callbacks.
+%
+% This package contains only a \texttt{.lua} file, that can be called by
+% another lua script. For example, this script is called in
+% \textsf{luatextra}.
+%
+%\subsubsection*{Limitations}
+%
+% This package only works for callbacks where it's safe to add multiple
+% functions without changing the functions' signatures. There are callbacks,
+% though, where registering several functions is not possible without changing
+% the function's signatures, like for example the readers callbacks. These
+% callbacks take a filename and give the datas in it. One solution would be to
+% change the functions' signature to open it when the function is the first,
+% and to take the datas and modify them eventually if they are called after
+% the first. But it seems rather fragile and useless, so it's not implemented.
+% With these callbacks, in this package we simply execute the first function
+% in the list.
+%
+% Other callbacks in this case are \texttt{define\_font} and
+% \texttt{open\_read\_file}. There is though a solution for several packages
+% to use these callbacks, see the implementation of \texttt{luatextra}.
+%
+% \StopEventually{
+% }
+%
+% \section{Package code}
+%
+% \iffalse
+%<*lua>
+% \fi
+%
+% The package contains \texttt{luamcallbacks.lua} with the new functions,
+% and an example of the use of luamcallbacks.
+%
+% First the \texttt{luamcallbacks} module is registered as a Lua\TeX\
+% module, with some informations.
+%
+% \begin{macrocode}
+
+luamcallbacks = { }
+
+luamcallbacks.module = {
+ name = "luamcallbacks",
+ version = 0.93,
+ date = "2009/09/18",
+ description = "Module to register several functions in a callback.",
+ author = "Hans Hagen & Elie Roux",
+ copyright = "Hans Hagen & Elie Roux",
+ license = "CC0",
+}
+
+luatextra.provides_module(luamcallbacks.module)
+
+% \end{macrocode}
+%
+% \texttt{callbacklist} is the main list, that contains the callbacks as
+% keys and a table of the registered functions a values.
+%
+% \begin{macrocode}
+
+luamcallbacks.callbacklist = luamcallbacks.callbacklist or { }
+
+% \end{macrocode}
+%
+% A table with the default functions of the created callbacks. See
+% \texttt{luamcallbacks.create} for further informations.
+%
+% \begin{macrocode}
+
+luamcallbacks.lua_callbacks_defaults = { }
+
+local format = string.format
+
+% \end{macrocode}
+%
+% There are 4 types of callback:
+% \begin{itemize}
+% \item the ones taking a list of nodes and returning a boolean and
+% eventually a new head (\texttt{list})
+% \item the ones taking datas and returning the modified ones
+% (\texttt{data})
+% \item the ones that can't have multiple functions registered in them
+% (\texttt{first})
+% \item the ones for functions that don't return anything (\texttt{simple})
+% \end{itemize}
+%
+% \begin{macrocode}
+
+local list = 1
+local data = 2
+local first = 3
+local simple = 4
+
+% \end{macrocode}
+%
+% \texttt{callbacktypes} is the list that contains the callbacks as keys
+% and the type (list or data) as values.
+%
+% \begin{macrocode}
+
+luamcallbacks.callbacktypes = luamcallbacks.callbacktypes or {
+buildpage_filter = simple,
+token_filter = first,
+pre_output_filter = list,
+hpack_filter = list,
+process_input_buffer = data,
+mlist_to_hlist = list,
+vpack_filter = list,
+define_font = first,
+open_read_file = first,
+linebreak_filter = list,
+post_linebreak_filter = list,
+pre_linebreak_filter = list,
+start_page_number = simple,
+stop_page_number = simple,
+start_run = simple,
+show_error_hook = simple,
+stop_run = simple,
+hyphenate = simple,
+ligaturing = simple,
+kerning = data,
+find_write_file = first,
+find_read_file = first,
+find_vf_file = data,
+find_map_file = data,
+find_format_file = data,
+find_opentype_file = data,
+find_output_file = data,
+find_truetype_file = data,
+find_type1_file = data,
+find_data_file = data,
+find_pk_file = data,
+find_font_file = data,
+find_image_file = data,
+find_ocp_file = data,
+find_sfd_file = data,
+find_enc_file = data,
+read_sfd_file = first,
+read_map_file = first,
+read_pk_file = first,
+read_enc_file = first,
+read_vf_file = first,
+read_ocp_file = first,
+read_opentype_file = first,
+read_truetype_file = first,
+read_font_file = first,
+read_type1_file = first,
+read_data_file = first,
+}
+
+% \end{macrocode}
+%
+% In Lua\TeX\ version 0.43, a new callback called |process_output_buffer|
+% appeared, so we enable it.
+%
+% \begin{macrocode}
+
+if tex.luatexversion > 42 then
+ luamcallbacks.callbacktypes["process_output_buffer"] = data
+end
+
+% \end{macrocode}
+%
+% As we overwrite \texttt{callback.register}, we save it as
+% \texttt{luamcallbacks.internalregister}. After that we declare some
+% functions to write the errors or the logs.
+%
+% \begin{macrocode}
+
+luamcallbacks.internalregister = luamcallbacks.internalregister or callback.register
+
+local callbacktypes = luamcallbacks.callbacktypes
+
+luamcallbacks.log = luamcallbacks.log or function(...)
+ luatextra.module_log('luamcallbacks', format(...))
+end
+
+luamcallbacks.info = luamcallbacks.info or function(...)
+ luatextra.module_info('luamcallbacks', format(...))
+end
+
+luamcallbacks.warning = luamcallbacks.warning or function(...)
+ luatextra.module_warning('luamcallbacks', format(...))
+end
+
+luamcallbacks.error = luamcallbacks.error or function(...)
+ luatextra.module_error('luamcallbacks', format(...))
+end
+
+% \end{macrocode}
+%
+% A simple function we'll use later to understand the arguments of the
+% \texttt{create} function. It takes a string and returns the type
+% corresponding to the string or nil.
+%
+% \begin{macrocode}
+
+function luamcallbacks.str_to_type(str)
+ if str == 'list' then
+ return list
+ elseif str == 'data' then
+ return data
+ elseif str == 'first' then
+ return first
+ elseif str == 'simple' then
+ return simple
+ else
+ return nil
+ end
+end
+
+% \end{macrocode}
+%
+% \begin{macro}{luamcallbacks.create}
+%
+% This first function creates a new callback. The signature is
+% \texttt{create(name, ctype, default)} where \texttt{name} is the name of
+% the new callback to create, \texttt{ctype} is the type of callback, and
+% \texttt{default} is the default function to call if no function is
+% registered in this callback.
+%
+% The created callback will behave the same way Lua\TeX\ callbacks do, you
+% can add and remove functions in it. The difference is that the callback
+% is not automatically called, the package developer creating a new
+% callback must also call it, see next function.
+%
+% \begin{macrocode}
+
+function luamcallbacks.create(name, ctype, default)
+ if not name then
+ luamcallbacks.error(format("unable to call callback, no proper name passed", name))
+ return nil
+ end
+ if not ctype or not default then
+ luamcallbacks.error(format("unable to create callback '%s', callbacktype or default function not specified", name))
+ return nil
+ end
+ if callbacktypes[name] then
+ luamcallbacks.error(format("unable to create callback '%s', callback already exists", name))
+ return nil
+ end
+ local temp = luamcallbacks.str_to_type(ctype)
+ if not temp then
+ luamcallbacks.error(format("unable to create callback '%s', type '%s' undefined", name, ctype))
+ return nil
+ end
+ ctype = temp
+ luamcallbacks.lua_callbacks_defaults[name] = default
+ callbacktypes[name] = ctype
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% \begin{macro}{luamcallbacks.call}
+%
+% This function calls a callback. It can only call a callback created by
+% the \texttt{create} function.
+%
+% \begin{macrocode}
+
+function luamcallbacks.call(name, ...)
+ if not name then
+ luamcallbacks.error(format("unable to call callback, no proper name passed", name))
+ return nil
+ end
+ if not luamcallbacks.lua_callbacks_defaults[name] then
+ luamcallbacks.error(format("unable to call lua callback '%s', unknown callback", name))
+ return nil
+ end
+ local l = luamcallbacks.callbacklist[name]
+ local f
+ if not l then
+ f = luamcallbacks.lua_callbacks_defaults[name]
+ else
+ if callbacktypes[name] == list then
+ f = luamcallbacks.listhandler(name)
+ elseif callbacktypes[name] == data then
+ f = luamcallbacks.datahandler(name)
+ elseif callbacktypes[name] == simple then
+ f = luamcallbacks.simplehandler(name)
+ elseif callbacktypes[name] == first then
+ f = luamcallbacks.firsthandler(name)
+ else
+ luamcallbacks.error("unknown callback type")
+ end
+ end
+ return f(...)
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% \begin{macro}{luamcallbacks.add}
+%
+% The main function. The signature is \texttt{luamcallbacks.add (name,
+% func, description, priority)} with \texttt{name} being the name of the
+% callback in which the function is added; \texttt{func} is the added
+% function; \texttt{description} is a small character string describing the
+% function, and \texttt{priority} an optional argument describing the
+% priority the function will have.
+%
+% The functions for a callbacks are added in a list (in
+% \texttt{luamcallbacks.callbacklist\\.callbackname}). If they have no
+% priority or a high priority number, they will be added at the end of the
+% list, and will be called after the others. If they have a low priority
+% number, the will be added at the beginning of the list and will be called
+% before the others.
+%
+% Something that must be made clear, is that there is absolutely no
+% solution for packages conflicts: if two packages want the top priority on
+% a certain callback, they will have to decide the priority they will give
+% to their function themself. Most of the time, the priority is not needed.
+%
+% \begin{macrocode}
+
+function luamcallbacks.add (name,func,description,priority)
+ if type(func) ~= "function" then
+ luamcallbacks.error("unable to add function, no proper function passed")
+ return
+ end
+ if not name or name == "" then
+ luamcallbacks.error("unable to add function, no proper callback name passed")
+ return
+ elseif not callbacktypes[name] then
+ luamcallbacks.error(
+ format("unable to add function, '%s' is not a valid callback",
+ name))
+ return
+ end
+ if not description or description == "" then
+ luamcallbacks.error(
+ format("unable to add function to '%s', no proper description passed",
+ name))
+ return
+ end
+ if luamcallbacks.get_priority(name, description) ~= 0 then
+ luamcallbacks.warning(
+ format("function '%s' already registered in callback '%s'",
+ description, name))
+ end
+ local l = luamcallbacks.callbacklist[name]
+ if not l then
+ l = {}
+ luamcallbacks.callbacklist[name] = l
+ if not luamcallbacks.lua_callbacks_defaults[name] then
+ if callbacktypes[name] == list then
+ luamcallbacks.internalregister(name, luamcallbacks.listhandler(name))
+ elseif callbacktypes[name] == data then
+ luamcallbacks.internalregister(name, luamcallbacks.datahandler(name))
+ elseif callbacktypes[name] == simple then
+ luamcallbacks.internalregister(name, luamcallbacks.simplehandler(name))
+ elseif callbacktypes[name] == first then
+ luamcallbacks.internalregister(name, luamcallbacks.firsthandler(name))
+ else
+ luamcallbacks.error("unknown callback type")
+ end
+ end
+ end
+ local f = {
+ func = func,
+ description = description,
+ }
+ priority = tonumber(priority)
+ if not priority or priority > #l then
+ priority = #l+1
+ elseif priority < 1 then
+ priority = 1
+ end
+ if callbacktypes[name] == first and (priority ~= 1 or #l ~= 0) then
+ luamcallbacks.warning(format("several callbacks registered in callback '%s', only the first function will be active.", name))
+ end
+ table.insert(l,priority,f)
+ luamcallbacks.log(
+ format("inserting function '%s' at position %s in callback list for '%s'",
+ description,priority,name))
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% \begin{macro}{luamcallbacks.get priority}
+%
+% This function tells if a function has already been registered in a
+% callback, and gives its current priority. The arguments are the name of
+% the callback and the description of the function. If it has already been
+% registered, it gives its priority, and if not it returns false.
+%
+% \begin{macrocode}
+
+function luamcallbacks.get_priority (name, description)
+ if not name or name == "" or not callbacktypes[name] or not description then
+ return 0
+ end
+ local l = luamcallbacks.callbacklist[name]
+ if not l then return 0 end
+ for p, f in pairs(l) do
+ if f.description == description then
+ return p
+ end
+ end
+ return 0
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% \begin{macro}{luamcallbacks.remove}
+%
+% The function that removes a function from a callback. The signature is
+% \texttt{mcallbacks.remove (name, description)} with \texttt{name} being
+% the name of callbacks, and description the description passed to
+% \texttt{mcallbacks.add}.
+%
+% \begin{macrocode}
+
+function luamcallbacks.remove (name, description)
+ if not name or name == "" then
+ luamcallbacks.error("unable to remove function, no proper callback name passed")
+ return
+ elseif not callbacktypes[name] then
+ luamcallbacks.error(
+ format("unable to remove function, '%s' is not a valid callback",
+ name))
+ return
+ end
+ if not description or description == "" then
+ luamcallbacks.error(
+ format("unable to remove function from '%s', no proper description passed",
+ name))
+ return
+ end
+ local l = luamcallbacks.callbacklist[name]
+ if not l then
+ luamcallbacks.error(format("no callback list for '%s'",name))
+ return
+ end
+ for k,v in ipairs(l) do
+ if v.description == description then
+ table.remove(l,k)
+ luamcallbacks.log(
+ format("removing function '%s' from '%s'",description,name))
+ if not next(l) then
+ luamcallbacks.callbacklist[name] = nil
+ if not luamcallbacks.lua_callbacks_defaults[name] then
+ luamcallbacks.internalregister(name, nil)
+ end
+ end
+ return
+ end
+ end
+ luamcallbacks.warning(
+ format("unable to remove function '%s' from '%s'",description,name))
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% \begin{macro}{luamcallbacks.reset}
+%
+% This function removes all the functions registered in a callback.
+%
+% \begin{macrocode}
+
+function luamcallbacks.reset (name)
+ if not name or name == "" then
+ luamcallbacks.error("unable to reset, no proper callback name passed")
+ return
+ elseif not callbacktypes[name] then
+ luamcallbacks.error(
+ format("reset error, '%s' is not a valid callback",
+ name))
+ return
+ end
+ if not luamcallbacks.lua_callbacks_defaults[name] then
+ luamcallbacks.internalregister(name, nil)
+ end
+ local l = luamcallbacks.callbacklist[name]
+ if l then
+ luamcallbacks.log(format("resetting callback list '%s'",name))
+ luamcallbacks.callbacklist[name] = nil
+ end
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% This function and the following ones are only internal. This one is the
+% handler for the first type of callbacks: the ones that take a list head
+% and return true, false, or a new list head.
+%
+% \begin{macro}{luamcallbacks.listhandler}
+%
+% \begin{macrocode}
+
+function luamcallbacks.listhandler (name)
+ return function(head,...)
+ local l = luamcallbacks.callbacklist[name]
+ if l then
+ local done = true
+ for _, f in ipairs(l) do
+ -- the returned value can be either true or a new head plus true
+ rtv1, rtv2 = f.func(head,...)
+ if type(rtv1) == 'boolean' then
+ done = rtv1
+ elseif type (rtv1) == 'userdata' then
+ head = rtv1
+ end
+ if type(rtv2) == 'boolean' then
+ done = rtv2
+ elseif type(rtv2) == 'userdata' then
+ head = rtv2
+ end
+ if done == false then
+ luamcallbacks.error(format(
+ "function \"%s\" returned false in callback '%s'",
+ f.description, name))
+ end
+ end
+ return head, done
+ else
+ return head, false
+ end
+ end
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% The handler for callbacks taking datas and returning modified ones.
+%
+% \begin{macro}{luamcallbacks.datahandler}
+%
+% \begin{macrocode}
+
+function luamcallbacks.datahandler (name)
+ return function(data,...)
+ local l = luamcallbacks.callbacklist[name]
+ if l then
+ for _, f in ipairs(l) do
+ data = f.func(data,...)
+ end
+ end
+ return data
+ end
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% This function is for the handlers that don't support more than one
+% functions in them. In this case we only call the first function of the
+% list.
+%
+% \begin{macro}{luamcallbacks.firsthandler}
+%
+% \begin{macrocode}
+
+function luamcallbacks.firsthandler (name)
+ return function(...)
+ local l = luamcallbacks.callbacklist[name]
+ if l then
+ local f = l[1].func
+ return f(...)
+ else
+ return nil, false
+ end
+ end
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% Handler for simple functions that don't return anything.
+%
+% \begin{macro}{luamcallbacks.simplehandler}
+%
+% \begin{macrocode}
+
+function luamcallbacks.simplehandler (name)
+ return function(...)
+ local l = luamcallbacks.callbacklist[name]
+ if l then
+ for _, f in ipairs(l) do
+ f.func(...)
+ end
+ end
+ end
+end
+
+% \end{macrocode}
+%
+% \end{macro}
+%
+% Finally we add some functions to the \texttt{callback} module, and we
+% overwrite \texttt{callback.register} so that it outputs an error.
+%
+% \begin{macrocode}
+
+callback.add = luamcallbacks.add
+callback.remove = luamcallbacks.remove
+callback.reset = luamcallbacks.reset
+callback.create = luamcallbacks.create
+callback.call = luamcallbacks.call
+callback.get_priority = luamcallbacks.get_priority
+
+callback.register = function (...)
+luamcallbacks.error("function callback.register has been deleted by luamcallbacks, please use callback.add instead.")
+end
+
+% \end{macrocode}
+%
+% \iffalse
+%</lua>
+% \fi
+%
+% \iffalse
+%<*test>
+% \fi
+%
+% \section{Test file}
+%
+% The test file is made to run in plainTeX, but is trivial to adapt for
+% LaTeX. First we input the package, and we typeset a small sentence to
+% get a non-empty document.
+%
+% \begin{macrocode}
+\input luatextra.sty
+
+This is just a test file.
+% \end{macrocode}
+%
+% Then we declare three functions that we will use.
+%
+% \begin{macrocode}
+\luadirect{
+local function one(head,...)
+ texio.write_nl("I'm number 1")
+ return head, true
+end
+
+local function two(head,...)
+ texio.write_nl("I'm number 2")
+ return head, true
+end
+
+local function three(head,...)
+ texio.write_nl("I'm number 3")
+ return head, true
+end
+% \end{macrocode}
+%
+% Then we add the three functions to the hpack\_filter callback
+%
+% \begin{macrocode}
+callback.add("hpack_filter",one,"my example function one",1)
+callback.add("hpack_filter",two,"my example function two",2)
+callback.add("hpack_filter",three,"my example function three",1)
+% \end{macrocode}
+%
+% We remove the function three from the callback.
+%
+% \begin{macrocode}
+callback.remove("hpack_filter","my example function three")
+% \end{macrocode}
+%
+% And we remove a non-declared function to the callback, which will
+% generate an error.
+%
+% \begin{macrocode}
+}
+
+\bye
+% \end{macrocode}
+% \iffalse
+%</test>
+% \fi
+% \Finale
+\endinput