diff options
| -rw-r--r-- | luatexbase-mcb.dtx | 176 |
1 files changed, 103 insertions, 73 deletions
diff --git a/luatexbase-mcb.dtx b/luatexbase-mcb.dtx index 224ad18..f920ddb 100644 --- a/luatexbase-mcb.dtx +++ b/luatexbase-mcb.dtx @@ -122,41 +122,74 @@ See source file '\inFileName' for details. % \maketitle % % \begin{abstract} -% This package manages the callback adding and removing, by providing new -% functions and overwriting \texttt{callback.register}. It also allows to -% create and call new callbacks.\par -% The user part of this documentation is currently very incomplete, and will -% be expanded later. Sorry for this and thanks for your patience.\par +% The primary feature of this package is to allow many functions to be +% registered in the same callback. Depending of the type of the callback, the +% functions will be combined in some way when the callback is called. Functions +% are provided for addition and removal of individual functions from a +% callback's list, with a priority system.\par +% Additionally, you can create new callbacks that will be handled the same way +% as predefined callbacks, except that they must be called explicitely. % \end{abstract} % % \tableofcontents % % \section{Documentation} % +% \subsection{Managing functions in callbacks} +% % 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 -% \verb+luatexbase.add_to_callback+ 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. There are -% also functions to remove one or all functions from a callback. -% See comments in the implementation section for details. -% -% 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. -% See comments in the implementation section for details. +% The problem with |callback.register| is that is registers only one function +% in a callback. This package solves the problem by disabling +% |callback.register| and providing a new interface allowing many functions to +% be registered in a single callback. +% +% The way the functions are combined together depends on +% the type of the callback. There are currently 4 types of callback, depending +% on the signature of the functions that can be registered in it: +% \begin{description} +% \item[list] functions taking a list of nodes and returning a boolean and +% possibly a new head: (TODO); +% \item[data] functions taking datas and returning it modified: the functions +% are called in order and passed the return value of the previous function as +% an argument, the return value is that of the last function; +% \item[simple] functions that don't return anything: they are called in +% order, all with the same argument; +% \item[first] functions with more complex signatures; functions in this type +% of callback are \emph{not} combined: only the first one (according to +% priorities) is executed. +% \end{itemize} +% +% To add a function to a callback, use: +% \begin{verbatim} +% luatexbase.add_to_callback(name, func, description, priority) +% \end{verbatim} +% The first argument is the name of the callback, the second is a function, +% the third one is a string used to identify the function later, and the +% optional priority is a postive integer, representing the rank of the +% function in the list of functions to be executing for this callback. So, +% |1| is the highest priority. If no priority is specified, the function is +% appended to the list, that is, its priority is the one of the last function +% plus one. +% +% The priority system is intended to help resolving conflicts between packages +% competing on the same callback, but it cannot solve every possible issue. If +% two packages request priority |1| on the same callback, then the last one +% loaded will win. +% +% To remove a function from a callback, use: +% \begin{verbatim} +% luatexbase.remove_from_callback(name, description) +% \end{verbatim} +% The first argument must be the name of the callback, and the second one the +% description used when adding the function to this callback. +% +% +% \subsection{Creating new callbacks} % % This package also privides a way to create and call new callbacks, in % addition to the default Lua\TeX\ callbacks. @@ -329,22 +362,10 @@ local callbacklist = callbacklist or { } local lua_callbacks_defaults = { } % \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} +% Numerical codes for callback types. % % \begin{macrocode} -local list = 1 -local data = 2 -local first = 3 -local simple = 4 +local list, data, first, simple = 1, 2, 3, 4 % \end{macrocode} % % \texttt{callbacktypes} is the list that contains the callbacks as keys @@ -529,30 +550,12 @@ end % % \subsubsection{Public functions} % -% The main function. The signature is \texttt{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{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 themselves. Most of the time, the priority is not needed. +% Add a function to a callback. First check arguments. % % \begin{macrocode} function add_to_callback (name,func,description,priority) if type(func) ~= "function" then - err("unable to add function:\nno proper function passed") - return + return err("unable to add function:\nno proper function passed") end if not name or name == "" then err("unable to add function:\nno proper callback name passed") @@ -567,9 +570,16 @@ function add_to_callback (name,func,description,priority) return end if priority_in_callback(name, description) then - warning("function '%s' already registered\nin callback '%s'", + err("function '%s' already registered\nin callback '%s'", description, name) + return end +% \end{macrocode} +% +% Then test if this callback is already in use. If not, initialise its list +% and register the proper handler. +% +% \begin{macrocode} local l = callbacklist[name] if not l then l = {} @@ -588,6 +598,11 @@ function add_to_callback (name,func,description,priority) end end end +% \end{macrocode} +% +% Actually register the function. +% +% \begin{macrocode} local f = { func = func, description = description, @@ -598,20 +613,22 @@ function add_to_callback (name,func,description,priority) elseif priority < 1 then priority = 1 end + table.insert(l,priority,f) +% \end{macrocode} +% +% Keep user informed. +% +% \begin{macrocode} if callbacktypes[name] == first and (priority ~= 1 or #l ~= 0) then warning("several callbacks registered in callback '%s',\n" .."only the first function will be active.", name) end - table.insert(l,priority,f) info("inserting function '%s'\nat position %s in callback list\nfor '%s'", description, priority, name) end % \end{macrocode} % -% The function that removes a function from a callback. The signature is -% \texttt{remove (name, description)} with \texttt{name} being -% the name of callbacks, and description the description passed to -% \texttt{add}. +% Remove a function from a callback. First check arguments. % % \begin{macrocode} function remove_from_callback (name, description) @@ -633,20 +650,33 @@ function remove_from_callback (name, description) err("no callback list for '%s'",name) return end +% \end{macrocode} +% +% Then loop over the callback's function list until we find a matching +% entry. Remove it and check if the list gets empty: if so, unregister the +% callback unless it is user-defined. +% +% \begin{macrocode} + local index = false for k,v in ipairs(l) do if v.description == description then - table.remove(l,k) - info("removing function '%s'\nfrom '%s'",description,name) - if not next(l) then - callbacklist[name] = nil - if not lua_callbacks_defaults[name] then - internalregister(name, nil) - end - end - return + index = k + break + end + end + if not index then + err("unable to remove function '%s'\nfrom '%s'", description, name) + return + end + table.remove(l, index) + info("removing function '%s'\nfrom '%s'", description, name) + if table.maxn(l) == 0 then + callbacklist[name] = nil + if not lua_callbacks_defaults[name] then + internalregister(name, nil) end end - warning("unable to remove function '%s'\nfrom '%s'",description,name) + return end % \end{macrocode} % |