summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2010-11-05 16:12:35 +0100
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2010-11-11 15:51:09 +0100
commit3e5253b3c2cc7d952d39f010eec61b14d0a54135 (patch)
treeff247018905a9ccd018d826fe225227dbc7621b4
parent0c343190fba0595582dd058cd9451046d308b36f (diff)
downloadluatexbase-3e5253b3c2cc7d952d39f010eec61b14d0a54135.tar.gz
fix listhandler logic and describe it
-rw-r--r--Changes23
-rw-r--r--TODO6
-rw-r--r--luatexbase-mcb.dtx93
3 files changed, 67 insertions, 55 deletions
diff --git a/Changes b/Changes
index 67ce85d..8f4faf9 100644
--- a/Changes
+++ b/Changes
@@ -1,20 +1,29 @@
Changes in the luatexbase package/bundle
+The [BI] tag signals backward-incompatible changes.
+After v0.3, the only possible source of such changes will be the upcoming
+merge with luatex.sty. Afterwards, no such changes are expected.
-(current changes)
+(current changes) v0.3
attr
- - Name changes: \*luatexattribute -> \*attribute.
+ - [BI] Name changes: \*luatexattribute -> \*attribute.
modutils
- - \luatexUseModule and \luatexRequireModule replaced by
+ - [BI] \luatexUseModule and \luatexRequireModule replaced by
\RequireLuaModule with a unified syntax.
- - luatexbase.use_module removed (use luatexbase.require_module with
+ - [BI] luatexbase.use_module removed (use luatexbase.require_module with
a single argument instead).
+ - [BI] rm module_log & module_term functions.
- change formatting of messages.
- - rm module_log & module_term functions.
- luatexbase.require_module now returns curstom err/war/inf functions.
+ mcb
+ - [BI] rationalise "list" type handling. The new calling convention
+ differs from the old one only in edge cases.
+ - add user documentation
+ - misc code tuning (more locals, etc)
2010/10/04
- various documentation updates/fixes uploaded to CTAN
+ - various documentation updates/fixes uploaded to CTAN
+ - luatexbase.sty used to be broken on CTAN (bad docstrip)
2010/05/27 v0.2a
attr
@@ -25,7 +34,7 @@
luatexbase
- new, loads: compat,loader,regs,attr,cctb.
-Summary of backwards-incompatible interface changes between 0.1 and 0.2:
+[BI] Summary of backwards-incompatible interface changes between 0.1 and 0.2:
- Lua objects are now in table luatexbase, not luatextra.
- Lua tables tex.attributenumber and tex.catcodetablenumber are not
created any more, use their couterparts in luatexbase.
diff --git a/TODO b/TODO
index c8fd9bf..c6d32cd 100644
--- a/TODO
+++ b/TODO
@@ -1,6 +1,7 @@
modutils
--------
+- use string for version, and check only date?
- review logic: should this module be mandatory?
if not, what should happen with mixed require(), require_module(),
declaration and no declaration?
@@ -10,4 +11,7 @@ declaration and no declaration?
mcb
---
-- remaining bit: understand and explain 'list' callback conventions
+- test: make each handler run at least once
+- doc: make an "example" section
+- doc: add a word about compatibility
+- code: verify that the return value of callback.register is checked
diff --git a/luatexbase-mcb.dtx b/luatexbase-mcb.dtx
index 0040269..64e5b6c 100644
--- a/luatexbase-mcb.dtx
+++ b/luatexbase-mcb.dtx
@@ -128,7 +128,7 @@ See source file '\inFileName' for details.
% 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.
+% as predefined callbacks, except that they must be called explicitly.
% \end{abstract}
%
% \tableofcontents
@@ -137,10 +137,10 @@ See source file '\inFileName' for details.
%
% \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
+% \luatex 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
+% The \luatex core offers a function called \texttt{callback.register} that
% enables to register a function in a callback.
%
% The problem with |callback.register| is that is registers only one function
@@ -150,18 +150,27 @@ See source file '\inFileName' for details.
%
% 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:
+% on the calling convention of the functions the callback can hold:
% \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.
+% \item[simple] is for functions that don't return anything: they are called
+% in order, all with the same argument;
+% \item[data] is for functions receiving a piece of data of nay type
+% except node list head (and possibly other arguments) and returning it
+% (possibly modified): the functions are called in order, and each is
+% passed the return value of the previous (and the other arguments
+% untouched, if any). The return value is that of the last function;
+% \item[list] is for functions taking the head of a node list as their first
+% argument (and possibly other arguments) and returning either a modified
+% node list or |true| or |false|. If a function returns a node
+% list, then this node list is passed as the first argument to the next
+% function, along with the original remaining arguments; if it returns
+% |true|, the original node list is passed to the next function; if it
+% returns false, then no the other functions are \emph{not} called, a
+% warning is issued and |false| is immediately returned. Otherwise, the
+% return value of the last function is returned.
+% \item[first] is for 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{description}
%
% To add a function to a callback, use:
@@ -170,7 +179,7 @@ See source file '\inFileName' for details.
% \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
+% optional priority is a positive 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
@@ -204,8 +213,8 @@ See source file '\inFileName' for details.
%
% \subsection{Creating new callbacks}
%
-% This package also privides a way to create and call new callbacks, in
-% addition to the default Lua\TeX\ callbacks.
+% This package also provides a way to create and call new callbacks, in
+% addition to the default \luatex callbacks.
% \begin{verbatim}
% luatexbase.create_callback(name, type, default)
% \end{verbatim}
@@ -225,7 +234,7 @@ See source file '\inFileName' for details.
% \begin{verbatim}
% luatexbase.call_callback(name, arguments...)
% \end{verbatim}
-% The functions registered for this callback (or teh default function) will be
+% The functions registered for this callback (or the default function) will be
% called with |arguments...| as arguments.
%
% \subsubsection{Limitations}
@@ -238,7 +247,7 @@ See source file '\inFileName' for details.
%
% At some point, \pk{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.
+% other split callbacks) if it appears there is an actual need for it.
%
% \section{Implementation}
%
@@ -488,37 +497,27 @@ end
% When the last function is removed from the callback's list, the handler
% is unregistered.
%
+% More precisely, the functions below are used to generate a specialized
+% function (closure) for a given callback, which is the actual handler.
+%
% Handler for |list| callbacks.
%
% \begin{macrocode}
--- local
-function listhandler (name)
+local function listhandler (name)
return function(head,...)
- local l = callbacklist[name]
- if l then
- local done = true
- for _, f in ipairs(l) do
- -- the returned value is 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
- err("function '%s' returned false\nin callback '%s'",
- f.description, name)
- end
+ local ret
+ for _, f in ipairs(callbacklist[name]) do
+ ret = f.func(head, ...)
+ if ret == false then
+ warn("function '%s' returned false\nin callback '%s'",
+ f.description, name)
+ break
+ end
+ if ret ~= true then
+ head = ret
end
- return head, done
- else
- return head, false
end
+ return ret
end
end
% \end{macrocode}
@@ -527,11 +526,11 @@ end
%
% \begin{macrocode}
local function datahandler (name)
- return function(data,...)
+ return function(data, ...)
local l = callbacklist[name]
if l then
for _, f in ipairs(l) do
- data = f.func(data,...)
+ data = f.func(data, ...)
end
end
return data