summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2010-11-05 01:41:19 +0100
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2010-11-11 15:50:31 +0100
commitdd0868e84017939ea3e326c942315cf81a2b95ef (patch)
tree149a1d54842a098d7714be3193cd2dff82f974ec
parent34d730f8e5f2ca209e2734a3cf31773789a368a2 (diff)
downloadluatexbase-dd0868e84017939ea3e326c942315cf81a2b95ef.tar.gz
document & review public functions for management
-rw-r--r--luatexbase-mcb.dtx87
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}