Qu’est-ce qu’un callback ?#
Les callbacks, ou fonctions de rappel en bon français, sont des fonctions accessibles par l’utilisateur qui implémentent les opérations internes de TeX ; celles-ci peuvent être améliorées en les combinant avec d’autres fonctions ad hoc, mais on peut aussi les remplacer complètement. Ces callbacks ne sont accessibles qu’avec le moteur LuaTeX qui est un moteur TeX incluant un interpréteur Lua. Tous les callbacks sont écrits en Lua.
Les fonctions enregistrées comme des callbacks interviennent donc dans une séquence d’actions qui constitue le traitement par le moteur TeX lors de la composition d’un document.
Les callbacks sont donc des portes d’entrées à différentes étapes de la production d’un document. La plupart des fonctions des callbacks recevront des arguments (et doivent donc être définies pour les gérer) et, surtout, beaucoup sont censées renvoyer des valeurs.
La liste des callbacks accessibles est impressionnante. Ils permettent d’avoir accès aux mécanismes :
de recherche de fichiers ;
de lecture de fichiers ;
de traitement de fichiers ;
de traitement des nœuds (notamment pour fabriquer les paragraphes, mais aussi pour la fabrication des pages) ;
de traitement des rapports de TeX ;
de gestion des fonctionnalités PDF ;
etc.
Pour lister l’ensemble des callbacks disponibles à partir d’un document LuaTeX, on pourra compiler le document suivant :
\documentclass{article}
\usepackage[width=8cm]{geometry}
\pagestyle{empty}
\begin{document}
\directlua{
info = callback.list()
for k, v in pairs(info) do
print(k)
end
}%
\end{document}
Ce code produit la liste suivante :
pre_dumpshow_lua_error_hookshow_warning_messagestart_page_numberopen_read_filehpack_qualityread_type1_filefind_read_fileprocess_input_bufferprocess_rulevpack_filterstop_runfinish_pdffileread_enc_filefind_font_filestart_runfind_cidmap_filefinish_pdfpageread_truetype_filepre_linebreak_filterfind_truetype_filestart_filekerningread_opentype_filefont_descriptor_objnum_providerread_data_fileread_map_fileinput_level_stringfind_image_fileglyph_not_foundwrapup_runmake_extensibleprocess_jobnamefind_vf_filefind_type1_filedefine_fontfind_output_fileglyph_infoprocess_output_bufferfinish_synctexpage_order_indexappend_to_vlist_filterprovide_charproc_datafind_pk_fileread_pk_fileprocess_pdf_image_contentread_cidmap_filebuildpage_filternew_grafhpack_filterglyph_stream_providerfind_write_filefind_format_filebuild_page_insertcall_editcontribute_filterinsert_local_parlinebreak_filterfind_opentype_filestop_page_numberstop_filefind_map_fileread_vf_filevpack_qualityfind_enc_filehyphenateshow_error_messagemlist_to_hlistshow_error_hookpre_output_filterread_font_filefind_data_fileligaturingpost_linebreak_filter
1. Enregistrer un callback#
Il y a deux types de callbacks : ceux qui étendent la fonctionnalité existante avec une nouvelle, et ceux qui (quand cela est possible) remplacent la fonctionnalité existante. Évidemment, lorsqu’on remplace la fonctionnalité existante, il est attendu que notre nouvelle définition fonctionne de façon similaire. Pour enregistrer un des callbacks listés ci-dessus, on utilisera la syntaxe (Lua) suivante :
id, error = callback.register(<string> callback_name, <function> func)
Si l’on souhaite rétablir le comportement par défaut, il suffira d’exécuter le code suivant :
id, error = callback.register(<string> callback_name, nil)
2. Avec LuaLaTeX#
Les fonctions ci-dessus sont celles du moteur LuaTeX. L’utilisation du format LaTeX peut poser quelques problèmes. David Carlisle et Joseph Wright ont développé le package ltluatex (présent dans le noyau LaTeX) qui fournit des commandes TeX et des fonctions Lua adaptées au format. En particulier, on utilisera les fonctions, aux noms plus explicites :
luatexbase.add_to_callback(<string> callback_name, <function> func, <string> description)
et
luatexbase.remove_from_callback(<string> callback, <string> description)