Editing Callbacks

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 <tt>callback.register()</tt> function, whose syntax is:

<pre>
callback.register(callback_name, function)
</pre>

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

<pre>
local my_function = function (an_arg)
  do_this_or_that(an_arg)
end
callback.register("some_callback", my_function)
</pre>

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

<pre>
callback.register("some_callback", function (an_arg) do_this_or_that(an_arg) end)
</pre>

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, <tt>callback.register()</tt> 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 <tt>nil</tt> and a string representing an error message.

Besides functions, <tt>callback.register()</tt> can take <tt>nil</tt> or <tt>false</tt>. 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 <tt>callback.register()</tt> erases any function previously registered. I.e. after

<pre>
callback.register("some_callback", function_one)
callback.register("some_callback", function_two)
</pre>

only <tt>function_two</tt> is registered in <tt>some_callback</tt>. Hence, if one wants several successive functions to occur in a callback, <tt>callback.register()</tt> 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 <tt>luatexbase-mcb</tt> for plain TeX and LaTeX, but here's how to do it oneself. We'll take the <tt>process_input_buffer</tt> 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:

<pre>
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)
</pre>

Then one can call <tt>add_function(my_function)</tt> to add <tt>my_function</tt> to the list of functions registered in <tt>process_input_buffer</tt>, and <tt>metafunction</tt> 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 <tt>callback.list()</tt>, called without arguments and returning a table with the callback names as keys and booleans as values: if the value is <tt>true</tt>, it means that something is registered in the callback, or that it is set to <tt>false</tt> (see above). The other function is <tt>callback.find()</tt>, called with a callback name. If a function is registered, it is returned; if the callback is set to <tt>false</tt>, a boolean with that value is returned; finally, if nothing is registered, <tt>nil</tt> is returned (note that to distinguish between a boolean set to <tt>false</tt> and <tt>nil</tt>, you must use <tt>type()</tt>).

= List of callbacks =

For suggestions on how to document callbacks, see [[Talk:Callbacks|the discussion page]].

== File discovery callbacks ==

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

{| cellpadding="5"
!Name !! Argument(s) !! Return value(s) !! Short description
|-
|[[find_read_file]] ||id_number, asked_name ||actual_name ||File called with <tt>\read</tt> or <tt>\input</tt>
|-
|[[find_write_file]] ||id_number, asked_name ||actual_name ||<tt>log</tt> file or file called with <tt>\write</tt>
|-
|[[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, <tt>filename</tt> is the string returned by the file discovery callbacks. The first callback reads <tt>\input</tt> or <tt>\read</tt> 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: <tt>success</tt> is a boolean, <tt>data</tt> is a string and <tt>data_size</tt> is a number (the length of <tt>data</tt> in bytes).

{| cellpadding="5"
!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 ==

{| cellpadding="5"
!Name !! Argument(s) !! Return value(s) !! Short description
|-
|[[process_input_buffer]] ||line ||modified_line ||Called for each input line (after <tt>reader</tt> in <tt>open_read_file</tt> 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 <tt>log</tt> file, the terminal and <tt>\write18</tt> calls.
|-
|[[token_filter]] || ||token ||Called when TeX needs token; no argument is passed to the callback, the next token must be fetched with <tt>token.get_next()</tt>; 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.

{| cellpadding="5"
!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. <tt>\hbox</tt>'es and paragraph building). A function doing what TeX does here by default is <tt>lang.hyphenate()</tt>.
|-
|[[ligaturing]] ||head, tail || || Same as <tt>hyphenate</tt>, but applying ligatures (and adding some discretionaries too). An associated function is <tt>node.ligaturing()</tt>.
|-
|[[kerning]] ||head, tail || || Same as above, with font kerns. The associated function is <tt>node.kerning()</tt>.
|-
|[[pre_linebreak_filter]] ||head, context ||boolean or newhead ||Called in unrestricted horizontal mode, after <tt>kerning</tt>, and before calling the paragraph builder; it receives the list of nodes that is the contents of the paragraph (plus the <tt>\parfillskip</tt> 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 <tt>tex.linebreak()</tt>.
|-
|[[Show the hyphenation points|post_linebreak_filter]] ||head, groupcode, ||boolean or newhead ||Receives what has been returned by <tt>linebreak_filter</tt> and must return something similar.
|-
|[[hpack_filter]] ||head, context, size, packtype[, dir] ||boolean or newhead ||Called when TeX is going to build an <tt>\hbox</tt>.
|-
|[[vpack_filter]] ||head, context, size, packtype, maxdepth[, dir] ||boolean or newhead ||Called when TeX is going to build a <tt>\vbox</tt>.
|-
|[[pre_output_filter]] ||head, context, size, packtype, maxdepth[, dir] ||boolean or newhead ||Same as <tt>vpack_filter</tt>, but when TeX packs box 255 (or any other value of <tt>\outputbox</tt>) 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 <em>TeXbook</em>).
|}

== 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.


{| cellpadding="5"
!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 ==
{| cellpadding="5"
!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 <tt>\font</tt> command is executed; <tt>name</tt> is the filename asked for, <tt>size</tt> is the <tt>at</tt> size, <tt>id</tt> 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.
|}