[latex3-commits] [git/LaTeX3-latex3-latex2e] callback_rules: Add documentation (8fbed5ba)
Marcel Fabian Krüger
tex at 2krueger.de
Mon Oct 3 21:08:17 CEST 2022
Repository : https://github.com/latex3/latex2e
On branch : callback_rules
Link : https://github.com/latex3/latex2e/commit/8fbed5ba246f3464b53fb0e090442cca277769b1
>---------------------------------------------------------------
commit 8fbed5ba246f3464b53fb0e090442cca277769b1
Author: Marcel Fabian Krüger <tex at 2krueger.de>
Date: Sun Aug 14 21:54:21 2022 +0200
Add documentation
>---------------------------------------------------------------
8fbed5ba246f3464b53fb0e090442cca277769b1
base/changes.txt | 5 +++++
base/doc/ltnews36.tex | 30 +++++++++++++++++++++++++++++-
base/ltluatex.dtx | 38 ++++++++++++++++++++++++++++++++++++--
3 files changed, 70 insertions(+), 3 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index 87442619..102f31e4 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
are not part of the distribution.
================================================================================
+2022-10-03 Marcel Krüger <marcel.krueger at latex-project.org>
+
+ * ltluatex.dtx:
+ Add ordering rules for callback handlers
+
2022-09-20 Frank Mittelbach <Frank.Mittelbach at latex-project.org>
* ltfssdcl.dtx (section{Interface Commands}):
diff --git a/base/doc/ltnews36.tex b/base/doc/ltnews36.tex
index 55de9862..0ed38263 100644
--- a/base/doc/ltnews36.tex
+++ b/base/doc/ltnews36.tex
@@ -281,7 +281,6 @@ approach.
\githubissue{903}
-
\subsection{Improve font series handling with incorrect \texttt{.fd} files}
By convention, the font series value is supposed to contain no
@@ -304,6 +303,35 @@ substitutions. Regardless of this support such
\githubissue{918}
+\subsection{Rule based ordering for \LuaTeX\ callback handlers}
+
+In \hologo{LuaLaTeX} the callback handlers used to be called in the order
+they are registered in, but this was often rather fragile.
+It depends a lot on the load order and any attempts to enforce a
+different order required to unregister and reregister the handlers to
+be reordered. Additionally even if some ordering constraints where
+enforced that way another package loaded later could accidentally
+overwrite it.
+
+To improve this, we now order the callback handlers based on ordering
+rules similar to the hook rules.
+
+When registering a callback which should run before or after another
+callback, \verb+luatexbase.declare_callback_rule+ can now be used to
+record this ordering constraint.
+For example
+\begin{verbatim}
+ luatexbase.add_to_callback('pre_shaping_filter', my_handler, 'my_name')
+ luatexbase.declare_callback_rule('pre_shaping_filter', 'my_name', 'before', 'other_name')
+\end{verbatim}
+will ensure that \verb+my_handler+ will always be called before the
+handler registered as \verb+other_name+.
+
+This also means that the order in which callbacks are registered no
+longer implicitly defines an order.
+Code which relied on this implicit order should now define the order
+rules explicitly.
+
\section{Bug fixes}
diff --git a/base/ltluatex.dtx b/base/ltluatex.dtx
index c38b943d..8be179de 100644
--- a/base/ltluatex.dtx
+++ b/base/ltluatex.dtx
@@ -28,7 +28,7 @@
\ProvidesFile{ltluatex.dtx}
%</driver>
%<*tex>
-[2022/08/13 v1.1y
+[2022/10/03 v1.2a
%</tex>
%<plain> LuaTeX support for plain TeX (core)
%<*tex>
@@ -380,7 +380,7 @@
%
% \noindent
% \DescribeMacro{create_callback}
-% |luatexbase.create_callback(|\meta{name},meta{type},\meta{default}|)|
+% |luatexbase.create_callback(|\meta{name},\meta{type},\meta{default}|)|
% Defines a user defined callback. The last argument is a default
% function or |false|.
%
@@ -389,6 +389,34 @@
% |luatexbase.call_callback(|\meta{name},\ldots|)|
% Calls a user defined callback with the supplied arguments.
%
+% \noindent
+% \DescribeMacro{declare_callback_rule}
+% |luatexbase.declare_callback_rule(|\meta{name}, \meta{first}, \meta{relation}, \meta{second}|)|
+% Adds an ordering constraint between two callback functions for callback \meta{name}.
+%
+% The kind of constraint added depends on \meta{relation}:
+% \begin{description}
+% \item[before] The callback function with description \meta{first} will be
+% executed before the function with description \meta{second}.
+% \item[after] The callback function with description \meta{first} will be
+% executed after the function with description \meta{second}.
+% \item[incompatible-warning] When both a callback function with description \meta{first}
+% and with description \meta{second} is registered, then a warning is printed when
+% the callback is executed.
+% \item[incompatible-error] When both a callback function with description \meta{first}
+% and with description \meta{second} is registered, then an error is printed when
+% the callback is executed.
+% \item[unrelated] Any previously declared callback rule between \meta{first}
+% and \meta{second} gets disabled.
+% \end{description}
+% Every call to \texttt{declare_callback_rule} with a specific callback \meta{name}
+% and descriptions \meta{first} and \meta{second} overwrites all previous calls with
+% same callback and descriptions.
+%
+% The callback functions do not have to be registered yet when the functions is called.
+% Ony the constraints for which both callback descriptions refer to callbacks
+% registered at the time the callback is called will have an effect.
+%
% \endgroup
%
% \MaybeStop{}
@@ -1298,6 +1326,8 @@ luatexbase.new_luafunction = new_luafunction
% element tables with the descriptions of the constrained callback implementations.
% It can additionally contain a |type| entry indicating the kind of rule. A missing
% value indicates a normal ordering contraint.
+%
+% \changes{v1.2a}{2022/10/03}{Add rules for callback ordering}
% \begin{macrocode}
local realcallbacklist = {}
local callbackrules = {}
@@ -1808,6 +1838,7 @@ luatexbase.call_callback=call_callback
% \changes{v1.0a}{2015/09/24}{Function added}
% Add a function to a callback. First check arguments.
% \changes{v1.0k}{2015/12/02}{Give more specific error messages (PHG)}
+% \changes{v1.2a}{2022/10/03}{Add rules for callback ordering}
% \begin{macrocode}
local function add_to_callback(name, func, description)
if not name or name == "" then
@@ -1850,6 +1881,7 @@ local function add_to_callback(name, func, description)
end
end
% \end{macrocode}
+% \changes{v1.2a}{2022/10/03}{Add rules for callback ordering}
% Actually register the function and give an error if more than one
% |exclusive| one is registered.
% \begin{macrocode}
@@ -1878,6 +1910,7 @@ luatexbase.add_to_callback = add_to_callback
% \end{macro}
%
% \begin{macro}{declare_callback_rule}
+% \changes{v1.2a}{2022/10/03}{Add function}
% Add an ordering constraint between two callback implementations
% \begin{macrocode}
local function declare_callback_rule(name, desc1, relation, desc2)
@@ -1932,6 +1965,7 @@ luatexbase.declare_callback_rule = declare_callback_rule
% \changes{v1.0k}{2015/12/02}{Give more specific error messages (PHG)}
% \changes{v1.1m}{2020/03/07}{Do not call callback.register for user-defined callbacks}
% \changes{v1.1y}{2022/08/13}{Adapted code for shared\_callbacks}
+% \changes{v1.2a}{2022/10/03}{Add rules for callback ordering}
% Remove a function from a callback. First check arguments.
% \begin{macrocode}
local function remove_from_callback(name, description)
More information about the latex3-commits
mailing list.