Skip to content

global callback

This library has functions that register, find and list callbacks. Callbacks are Lua functions that are called in well defined places. There are two kind of callbacks: those that mix with existing functionality, and those that (when enabled) replace functionality. In mosty cases the second category is expected to behave similar to the built in functionality because in a next step specific data is expected. For instance, you can replace the hyphenation routine. The function gets a list that can be hyphenated (or not). The final list should be valid and is (normally) used for constructing a paragraph. Another function can replace the ligature builder and/or kerner. Doing something else is possible but in the end might not give the user the expected outcome.

Reference:

😱 Types incomplete or incorrect? 🙏 Please contribute!

methods

callback.register

function callback.register(
  callback_name: CallbackName,
  func: (function|false)?
)
 -> id integer?
 -> error string

@return id - The function returns the internal id of the callback or nil, if the callback could not be registered.

@return error - In the latter case, error contains an error message, otherwise it is nil. The function returns No such callback exists. if a wrong callback name was specified.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Register a callback. Passing nil removes an existing callback. Returns nil, error on failure.

The first thing you need to do is registering a callback:

Here the callback_name is a predefined callback name, see below.

LuaTeX internalizes the callback function in such a way that it does not matter if you redefine a function accidentally.

Callback assignments are always global. You can use the special value nil instead of a function for clearing the callback.

For some minor speed gain, you can assign the boolean false to the non-file related callbacks, doing so will prevent LuaTeX from executing whatever it would execute by default (when no callback function is registered at all). Be warned: this may cause all sorts of grief unless you know exactly what you are doing!

Reference:

callback.list

function callback.list() -> info table<string,boolean>

Produce a list of all known callback names.

The keys in the table are the known callback names, the value is a boolean where true means that the callback is currently set (active).

Reference:

callback.find

function callback.find(callback_name: CallbackName) -> f (function)?

If the callback is not set, find returns nil.

Reference: