Callbacks

From LuaTeXWiki

Callbacks allow the user to interact with TeX's internal operations; those can be enhanced by additional ones, but also replaced altogether. All callbacks are written in Lua.

Since functions registered in callbacks occur in a sequence of actions that makes up TeX's processing, many of them will receive arguments (and thus should be defined to handle them) and, most importantly, many are supposed to return values. What arguments are passed, if any, and what should be return, vary from callback to callback.

Registering a callback

To install a function in a callback one must use the callback.register() function, whose syntax is:

callback.register(callback_name, function)

where callback_name is a string representing a predefined callback name (see below), and function is either a function variable or an anonymous function. The former is just the name of a function previously defined, for instance:

local my_function = function (an_arg)
  do_this_or_that(an_arg)
end
callback.register("some_callback", my_function)

An anonymous function is a function definition that is not assigned to a variable, e.g.:

callback.register("some_callback", function (an_arg) do_this_or_that(an_arg) end)

Even in the case of a function variable, what LuaTeX registers is the function itself, and any further assignment to the variable has no effect on the callback.

If registering is successful, callback.register() returns a number, which is the internal representation of the callback; if registering fails (for instance because a callback doesn't exist, or what is registered isn't a function), the function returns nil and a string representing an error message.

Besides functions, callback.register() can take nil or false. The first value clears the callback, and returns to the default behavior (i.e. either nothing or TeX's default processing); the second value prevents anything from happening at this point, even TeX's default operations, and should be used with great care (the benefits are minor speed gain).

Several functions in a callback

Each call to callback.register() erases any function previously registered. I.e. after

callback.register("some_callback", function_one)
callback.register("some_callback", function_two)

only function_two is registered in some_callback. Hence, if one wants several successive functions to occur in a callback, callback.register() is clearly insufficient. Instead, one must register a metafunction which calls the functions one after the other. This is taken care of in ConTeXt, and there exists luatexbase-mcb for plain TeX and LaTeX, but here's how to do it oneself. We'll take the process_input_buffer callback has an example; it is called whenever TeX reads an input line, it receives a string (the line) and should return one. A rough approach would be:

local function_table = { }

local function metafunction (str)
  for _, fct in ipairs(function_table) do
    str = fct(str)
  end
  return str
end

function add_function (fct)
  table.insert(function_table, fct)
end

callback.register("process_input_buffer", metafunction)

Then one can call add_function(my_function) to add my_function to the list of functions registered in process_input_buffer, and metafunction will pass the callback's argument (an input line) to the first function, set that argument to what the function returns, then repeat the process for all functions and finally return the resulting string.

If one also wants to be able to remove functions (and not the entire metafunction), a subtler approach is required, where names are associated with functions and can be used as handles.

Information about callbacks

LuaTeX has two functions to get some information about callbacks. The first is callback.list(), called without arguments and returning a table with the callback names as keys and booleans as values: if the value is true, it means that something is registered in the callback, or that it is set to false (see above). The other function is callback.find(), called with a callback name. If a function is registered, it is returned; if the callback is set to false, a boolean with that value is returned; finally, if nothing is registered, nil is returned (note that if ret is the returned value, then if ret is false if ret is either false or nil; you must use if ret == nil to distinguish between the two).

List of callbacks

For suggestions on how to document callbacks, see the discussion page.

File discovery callbacks

These are called whenever an input file is needed. Each receives the asked_name, a string representing what file name was called by the user (for instance, my_file.tex in \input my_file.tex) and should return the name of a file to be read (or written to). The id_number in the first two callbacks is the stream's number plus one, because 0 denotes log and \input files.

Name Argument(s) Return value(s) Short description
find_read_file id_number, asked_name actual_name File called with \read or \input
find_write_file id_number, asked_name actual_name log file or file called with \write
find_font_file asked_name actual_name
find_output_file asked_name actual_name
find_format_file asked_name actual_name
find_vf_file asked_name actual_name
find_map_file asked_name actual_name
find_enc_file asked_name actual_name
find_sfd_file asked_name actual_name
find_pk_file asked_name actual_name
find_data_file asked_name actual_name
find_opentype_file asked_name actual_name
find_truetype_file asked_name actual_name
find_type_file asked_name actual_name
find_image_file asked_name actual_name

File reading callbacks

The previous callbacks were called when a file was asked for; the following are triggered when the file is read. In all, filename is the string returned by the file discovery callbacks. The first callback reads \input or \read files; it must return a table, whose first cell is a function that will be called whenever a line from the input file is readed; the second cell is an optional function executed when the input file terminates.

The other callbacks are used for binary files: success is a boolean, data is a string and data_size is a number (the length of data in bytes).

Name Argument(s) Return value(s) Short description
open_read_file filename {reader, close}
read_font_file filename success, data, data_size
read_vf_file filename success, data, data_size
read_map_file filename success, data, data_size
read_enc_file filename success, data, data_size
read_sfd_file filename success, data, data_size
read_pk_file filename success, data, data_size
read_data_file filename success, data, data_size
read_truetype_file filename success, data, data_size
read_type1_file filename success, data, data_size
read_opentype_file filename success, data, data_size

Data processing callbacks

Name Argument(s) Return value(s) Short description
process_input_buffer line modified_line Called for each input line (after reader in open_read_file if TeX is not reading the main file).
process_output_buffer line modified_line Called for each line TeX writes to an external file; this excludes the log file, the terminal and \write18 calls.
process_jobname string modified_string Processes the jobname when queried with \jobname or tex.jobname. The internal job name (used for the output and log files) remains untouched. (This callback appeared in v.0.71.)
token_filter token Called when TeX needs token; no argument is passed to the callback, the next token must be fetched with token.get_next(); what is returned is immediately processed by TeX.

Node list processing callbacks

These callbacks deal with node manipulations and occur at various stages of TeX's typesetting processes.

Name Argument(s) Return value(s) Short description
buildpage_filter information Called when TeX moves material to the main vertical list. (This callback is an endangered species.)
hyphenate head, tail Inserts discretionary nodes in the node list; called in restricted and unrestricted horizontal mode (i.e. \hbox'es and paragraph building). A function doing what TeX does here by default is lang.hyphenate().
ligaturing head, tail Same as hyphenate, but applying ligatures (and adding some discretionaries too). An associated function is node.ligaturing().
kerning head, tail Same as above, with font kerns. The associated function is node.kerning().
pre_linebreak_filter head, context boolean or newhead Called in unrestricted horizontal mode, after kerning, and before calling the paragraph builder; it receives the list of nodes that is the contents of the paragraph (plus the \parfillskip glue) and must return something similar.
linebreak_filter head, is_display newhead The paragraph builder. It receives what the previous callback has returned and is in charge of making a paragraph out of it; it must return what it has built. An associated function is tex.linebreak().
post_linebreak_filter head, groupcode, boolean or newhead Receives what has been returned by linebreak_filter and must return something similar.
hpack_filter head, context, size, packtype[, dir] boolean or newhead Called when TeX is going to build an \hbox.
vpack_filter head, context, size, packtype, maxdepth[, dir] boolean or newhead Called when TeX is going to build a \vbox.
pre_output_filter head, context, size, packtype, maxdepth[, dir] boolean or newhead Same as vpack_filter, but when TeX packs box 255 (or any other value of \outputbox) and goes to the output routine.
mlist_to_hlist head, display_type, need_penalties newhead Called when TeX turns a math list into a horizontal list (as described in Appendix G of the TeXbook).

Information reporting callbacks

These callbacks are called in various places when TeX has something to say. None of them takes an argument nor returns anything.


Name Short description
pre_dump Called before dumping a format.
start_run LuaTeX's banner (`This is LuaTeX...'); must be changed in the initialization script, otherwise the banner has already been printed.
stop_run TeX's final words (statistics and `Output written to...').
start_page_number The opening bracket and the page number printed when a page is shipped out.
stop_page_number The closing bracket printed after the previous callback.
show_error_hook Called at the beginning of each error message.

Miscellaneous

Name Argument(s) Return value(s) Short description
finish_pdffile Called when all pages have been written to the PDF file.
define_font name, size, id font_table Called when the \font command is executed; name is the filename asked for, size is the at size, id is the number that will be assigned as an internal representation to the font thus loaded. The callback should return a table representing a font.