diff options
| -rw-r--r-- | Changes | 23 | ||||
| -rw-r--r-- | TODO | 6 | ||||
| -rw-r--r-- | luatexbase-mcb.dtx | 93 |
3 files changed, 67 insertions, 55 deletions
@@ -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. @@ -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 |