diff options
| -rw-r--r-- | luatexbase-mcb.dtx | 87 |
1 files changed, 47 insertions, 40 deletions
diff --git a/luatexbase-mcb.dtx b/luatexbase-mcb.dtx index f920ddb..3a86b00 100644 --- a/luatexbase-mcb.dtx +++ b/luatexbase-mcb.dtx @@ -186,8 +186,21 @@ See source file '\inFileName' for details. % 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. +% description used when adding the function to this callback. You can also +% remove all functions from a callback at once using +% \begin{verbatim} +% luatexbase.reset_callback(name) +% \end{verbatim} % +% When new functions are added at the beginning of the list, other functions +% are shifted down the list. To get the current rank of a function in a +% callback's list, use: +% \begin{verbatim} +% priority = luatexbase.priority_in_callback(name, description) +% \end{verbatim} +% Again, the description is the string used when adding the function. If the +% function identified by this string is not in this callback's list, the +% priority returned is the boolean value |false|. % % \subsection{Creating new callbacks} % @@ -195,22 +208,17 @@ See source file '\inFileName' for details. % addition to the default Lua\TeX\ callbacks. % See comments in the implementation section for details. % -% \subsubsection*{Limitations} +% \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. +% For callbacks of type |first|, our new management system isn't actually +% better than good old |callback.register|. For some of them, is may be +% possible to split them into many callbacks, so that these callbacks can +% accept multiple functions. However, its seems risky and limited in use and +% is therefore nor implemented. % -% 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}. +% At some point, \pf{luatextra} used to split |open_read_file| that way, but +% support for this was removed. It may be added back (as well as support for +% other splitted callbacks) if it appears there is an actual need for it. % % \section{Implementation} % @@ -654,7 +662,7 @@ function remove_from_callback (name, description) % % 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. +% callback handler unless the callback is user-defined. % % \begin{macrocode} local index = false @@ -680,7 +688,8 @@ function remove_from_callback (name, description) end % \end{macrocode} % -% This function removes all the functions registered in a callback. +% Remove all the functions registered in a callback. Unregisters the +% callback handler unless the callback is user-defined. % % \begin{macrocode} function reset_callback (name) @@ -702,6 +711,27 @@ function reset_callback (name) end % \end{macrocode} % +% Get a function's priority in a callback list, or false if the function is +% not in the list. +% +% \begin{macrocode} +function priority_in_callback (name, description) + if not name or name == "" + or not callbacktypes[name] + or not description then + return false + end + local l = callbacklist[name] + if not l then return false end + for p, f in pairs(l) do + if f.description == description then + return p + end + end + return false +end +% \end{macrocode} +% % 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 @@ -774,29 +804,6 @@ function call_callback(name, ...) end % \end{macrocode} % -% 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 priority_in_callback (name, description) - if not name or name == "" - or not callbacktypes[name] - or not description then - return false - end - local l = callbacklist[name] - if not l then return false end - for p, f in pairs(l) do - if f.description == description then - return p - end - end - return false -end -% \end{macrocode} -% % Finally, overwrite |callback.register| so that bails out in error. % % \begin{macrocode} |