LuaTeX Lua API

Type definitions for the Lua API of LuaTeX and related projects.

LuaTeX has a very large Lua API. This project tries to make this API accessible in the text editor of your choice. This is made possible by the lua-language-server - a server that implements the Language Server Protocol (LSP) for the Lua language. Features such as code completion, syntax highlighting and marking of warnings and errors, should therefore not only be possible in Visual Studio Code, but in a large number of editors that support the LSP.

Subprojects

• lualatex
• lualibs
• luametatex
• luaotfload
• luatex

Distribution ...

via CTAN

The type definitions are published on CTAN as a single file to avoid cluttering the CTAN directory with many individual Lua files. Since this one file is just under 1.5 MB in size, a configuration must be made so that the language server can load the file. The following configuration example sets the preload file size to a maximum of 5000 kB.

{
    "Lua.workspace.preloadFileSize": 5000,
}

There are several ways to include type definitions in a project. The easiest way is to copy the file into the project folder. Or you can use the configuration Lua.workspace.library:

{
    "Lua.workspace.library": ["/path/to/luatex-type-definitions.lua"]
}

via Visual Studio Code Extension

Visual Studio Code LuaTeX Extension

via LuaCATS git respositories

LuaCATS is a Github organisation and stands for “Lua Comment And Type System”. This organization provides a place for community projects to live. These projects are addons for popular libraries/frameworks. The repositories in this organization are used by LLS-Addons, a repository that is used by the addon manager of the VS Code extension for the Lua Language Server.

All related LuaCATS repositories

This repositories in LuaCATS are related to this project:

• lmathx
• lpeg
• luafilesystem
• luaharfbuzz
• luasocket
• luazip
• lzlib
• md5
• slnunicode
• tex-lualatex
• tex-lualibs
• tex-luametatex
• tex-luatex

Upstream LuaCATS repositories

The following repositories are upstream projects. This means: The type definitions are developed in a LuaCATS repository and pulled in by this project.

• LuaCATS: lmathx → library/luametatex/lmathx.lua
• LuaCATS: lpeg → TeXLuaCATS/LuaTeX/lpeg.lua
• LuaCATS: luaharfbuzz → TeXLuaCATS/LuaTeX/luaharfbuzz.lua
• LuaCATS: luasocket → TeXLuaCATS/LuaTeX/socket.lua → TeXLuaCATS/LuaTeX/mime.lua
• LuaCATS: luazip → TeXLuaCATS/LuaTeX/zip.lua
• LuaCATS: lzlib → TeXLuaCATS/LuaTeX/zlib.lua
• LuaCATS: md5 → TeXLuaCATS/LuaTeX/md5.lua
• LuaCATS: slnunicode → TeXLuaCATS/LuaTeX/unicode.lua

Downstream LuaCATS repositories

The following repositories are downstream projects. This means: The type definitions are developed in this project. They are then pushed into a LuaCATS repository.

• LuaCATS: tex-lualatex ← TeXLuaCATS/LuaLaTeX
• LuaCATS: tex-luatex ← TeXLuaCATS/LuaTeX
• LuaCATS: tex-lualibs ← TeXLuaCATS/Lualibs
• LuaCATS: tex-luametatex ← TeXLuaCATS/LuaMetaTeX

Directory structure of the repository

In the subfolder library are files named after the global libraries they document. For example, the library/tex.lua file contains the documentation for the tex library. These Lua files don’t contain real Lua code. They consist only of function bodies and empty tables. The main focus is in the docstrings.

The API documentation is written in a well documented annotation format. This format is based on the EmmyLua format. Unfortunately, the Lua community has not yet been able to agree on a standarized annotation format. Many Lua project are documented in the LDoc format. However, the differences between these formats are marginal.

Directory library

The actual definitions are located in the directory library. This directory is divided into further subdirectories. In the folder luatex you will find the definitions that the engine LuaTeX provides. The folder lualibs documents the extension library of the same name. If you use lualatex, you may be interested in the folder of the same name.

Directory resources

The folder resources contains TeX manuals and HTML online documentation converted into Lua docstrings.

Directory examples

The example folder contains TeX and Lua files for demonstrating and testing the documented Lua API.

Current version

2025/07/24 v0.2.0

License

Copyright (C) 2022-2025 by Josef Friedrich josef@friedrich.rocks

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

About the license selection

The same license was used for the type definitions as for LuaTeX (GPLv2). The MIT license is used for the external upstream projects.

GPLv2 copyright notice for every file

Only two hyphens are used here, rather than three, so that the copyright notice does not end up in the rendered documentation.

-- -----------------------------------------------------------------------------
-- Copyright (C) 2022-2025 by Josef Friedrich <josef@friedrich.rocks>
-- -----------------------------------------------------------------------------
--
-- This program is free software: you can redistribute it and/or modify it
-- under the terms of the GNU General Public License as published by the
-- Free Software Foundation, either version 2 of the License, or (at your
-- option) any later version.
--
-- This program is distributed in the hope that it will be useful, but
-- WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
-- Public License for more details.
--
-- You should have received a copy of the GNU General Public License along
-- with this program. If not, see <https://www.gnu.org/licenses/>.
--
-- -----------------------------------------------------------------------------

MIT copyright notice for every file

-- -----------------------------------------------------------------------------
-- Copyright (c) 2023-2025 by Josef Friedrich <josef@friedrich.rocks>
-- -----------------------------------------------------------------------------
--
-- MIT License
--
-- Permission is hereby granted, free of charge, to any person obtaining a copy
-- of this software and associated documentation fil