| 1 |
# LuaTeX Lua API |
| 2 |
|
| 3 |
Type definitions for the Lua API of `LuaTeX` and related projects. |
| 4 |
|
| 5 |
 |
| 6 |
|
| 7 |
[LuaTeX](http://luatex.org) has a very large [Lua](https://www.lua.org) |
| 8 |
API. This project tries to make this API accessible in the text editor |
| 9 |
of your choice. This is made possible by the |
| 10 |
[lua-language-server](https://github.com/LuaLS/lua-language-server) - a |
| 11 |
server that implements the [Language Server Protocol |
| 12 |
(LSP)](https://en.wikipedia.org/wiki/Language_Server_Protocol) for the |
| 13 |
`Lua` language. Features such as code completion, syntax highlighting |
| 14 |
and marking of warnings and errors, should therefore not only be |
| 15 |
possible in [Visual Studio Code](https://code.visualstudio.com), but in |
| 16 |
a [large number of |
| 17 |
editors](https://langserver.org/#implementations-client) that support |
| 18 |
the `LSP`. |
| 19 |
|
| 20 |
## Subprojects |
| 21 |
|
| 22 |
* [lualatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualatex) |
| 23 |
* [lualibs](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualibs) |
| 24 |
* [luametatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luametatex) |
| 25 |
* [luaotfload](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luaotfload) |
| 26 |
* [luatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luatex) |
| 27 |
|
| 28 |
## Distribution ... |
| 29 |
|
| 30 |
## via CTAN |
| 31 |
|
| 32 |
 |
| 33 |
|
| 34 |
The type definitions are published on |
| 35 |
[CTAN](https://www.ctan.org/pkg/luatex-type-definitions) as a single |
| 36 |
file to avoid cluttering the CTAN directory with many individual Lua |
| 37 |
files. Since this one file is just under 1.5 MB in size, a configuration |
| 38 |
must be made so that the language server can load the file. The |
| 39 |
following configuration example sets the preload file size to a maximum |
| 40 |
of 5000 kB. |
| 41 |
|
| 42 |
```json |
| 43 |
{ |
| 44 |
"Lua.workspace.preloadFileSize": 5000, |
| 45 |
} |
| 46 |
``` |
| 47 |
|
| 48 |
There are several ways to include type definitions in a project. |
| 49 |
The easiest way is to copy the file into the project folder. |
| 50 |
Or you can use the configuration `Lua.workspace.library`: |
| 51 |
|
| 52 |
```json |
| 53 |
{ |
| 54 |
"Lua.workspace.library": ["/path/to/luatex-type-definitions.lua"] |
| 55 |
} |
| 56 |
``` |
| 57 |
|
| 58 |
### via Visual Studio Code Extension |
| 59 |
|
| 60 |
 |
| 61 |
|
| 62 |
* [Visual Studio Code LuaTeX Extension](https://github.com/Josef-Friedrich/vscode_LuaTeX_Lua-API) |
| 63 |
← [library](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library) |
| 64 |
|
| 65 |
### via LuaCATS git respositories |
| 66 |
|
| 67 |
 |
| 68 |
|
| 69 |
[LuaCATS](https://github.com/LuaCATS) is a [Github](https://github.com) |
| 70 |
organisation and stands for *“Lua Comment And Type System”*. This |
| 71 |
organization provides a place for community projects to live. These |
| 72 |
projects are [addons](https://luals.github.io/wiki/addons) for popular |
| 73 |
libraries/frameworks. |
| 74 |
The repositories in this organization are used by |
| 75 |
[LLS-Addons](https://github.com/LuaLS/LLS-Addons), a repository that is used by the [addon |
| 76 |
manager](https://luals.github.io/wiki/addons/#addon-manager) of the [VS |
| 77 |
Code |
| 78 |
extension](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) |
| 79 |
for the [Lua Language Server]([lls](https://github.com/LuaLS/lua-language-server)). |
| 80 |
|
| 81 |
#### All related LuaCATS repositories |
| 82 |
|
| 83 |
This repositories in LuaCATS are related to this project: |
| 84 |
|
| 85 |
* [lmathx](https://github.com/LuaCATS/lmathx) |
| 86 |
* [lpeg](https://github.com/LuaCATS/lpeg) |
| 87 |
* [luafilesystem](https://github.com/LuaCATS/luafilesystem) |
| 88 |
* [luaharfbuzz](https://github.com/LuaCATS/luaharfbuzz) |
| 89 |
* [luasocket](https://github.com/LuaCATS/luasocket) |
| 90 |
* [luazip](https://github.com/LuaCATS/luazip) |
| 91 |
* [lzlib](https://github.com/LuaCATS/lzlib) |
| 92 |
* [md5](https://github.com/LuaCATS/md5) |
| 93 |
* [slnunicode](https://github.com/LuaCATS/slnunicode) |
| 94 |
* [tex-lualatex](https://github.com/LuaCATS/tex-lualatex) |
| 95 |
* [tex-lualibs](https://github.com/LuaCATS/tex-lualibs) |
| 96 |
* [tex-luametatex](https://github.com/LuaCATS/tex-luametatex) |
| 97 |
* [tex-luatex](https://github.com/LuaCATS/tex-luatex) |
| 98 |
|
| 99 |
#### Upstream LuaCATS repositories |
| 100 |
|
| 101 |
The following repositories are *upstream* projects. This means: The type |
| 102 |
definitions are developed in a LuaCATS repository and *pulled* in by |
| 103 |
this project. |
| 104 |
|
| 105 |
* [LuaCATS: lmathx](https://github.com/LuaCATS/lmathx) |
| 106 |
→ [library/luametatex/lmathx.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luametatex/lmathx.lua) |
| 107 |
* [LuaCATS: lpeg](https://github.com/LuaCATS/lpeg) |
| 108 |
→ [library/luatex/lpeg.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/lpeg.lua) |
| 109 |
* [LuaCATS: luaharfbuzz](https://github.com/LuaCATS/luaharfbuzz) |
| 110 |
→ [library/luatex/luaharfbuzz.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/luaharfbuzz.lua) |
| 111 |
* [LuaCATS: luasocket](https://github.com/LuaCATS/luasocket) |
| 112 |
→ [library/luatex/socket.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/socket.lua) |
| 113 |
→ [library/luatex/mime.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/mime.lua) |
| 114 |
* [LuaCATS: luazip](https://github.com/LuaCATS/luazip) |
| 115 |
→ [library/luatex/zip.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zip.lua) |
| 116 |
* [LuaCATS: lzlib](https://github.com/LuaCATS/lzlib) |
| 117 |
→ [library/luatex/zlib.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zlib.lua) |
| 118 |
* [LuaCATS: md5](https://github.com/LuaCATS/md5) |
| 119 |
→ [library/luatex/md5.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/md5.lua) |
| 120 |
* [LuaCATS: slnunicode](https://github.com/LuaCATS/slnunicode) |
| 121 |
→ [library/luatex/unicode.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/unicode.lua) |
| 122 |
|
| 123 |
#### Subprojects (push) detached from this repository |
| 124 |
|
| 125 |
The following repositories are *downstream* projects. This means: The |
| 126 |
type definitions are developed in this project. They are then *pushed* |
| 127 |
into a LuaCATS repository. |
| 128 |
|
| 129 |
* [LuaCATS: tex-lualatex](https://github.com/LuaCATS/tex-lualatex) |
| 130 |
← [library/lualatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualatex) |
| 131 |
* [LuaCATS: tex-luatex](https://github.com/LuaCATS/tex-luatex) |
| 132 |
← [library/luatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luatex) |
| 133 |
* [LuaCATS: tex-lualibs](https://github.com/LuaCATS/tex-lualibs) |
| 134 |
← [library/lualibs](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualibs) |
| 135 |
* [LuaCATS: tex-luametatex](https://github.com/LuaCATS/tex-luametatex) |
| 136 |
← [library/luametatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luametatex) |
| 137 |
|
| 138 |
## Directory structure of the repository |
| 139 |
|
| 140 |
In the subfolder `library` are files named after the global libraries |
| 141 |
they document. For example, the `library/tex.lua` file contains the |
| 142 |
documentation for the `tex` library. These *Lua* files don’t contain |
| 143 |
real *Lua* code. They consist only of function bodies and empty |
| 144 |
tables. The main focus is in the docstrings. |
| 145 |
|
| 146 |
The API documentation is written in a [well documented annotation |
| 147 |
format](https://luals.github.io/wiki/annotations). |
| 148 |
This format is based on the [EmmyLua](https://emmylua.github.io) |
| 149 |
format. Unfortunately, the *Lua* community has not yet been able to |
| 150 |
agree on a standarized annotation format. Many *Lua* project are |
| 151 |
documented in the [LDoc](https://github.com/lunarmodules/LDoc) format. |
| 152 |
However, the differences between these formats are marginal. |
| 153 |
|
| 154 |
### Directory `library` |
| 155 |
|
| 156 |
The actual definitions are located in the directory `library`. This |
| 157 |
directory is divided into further subdirectories. In the folder `luatex` |
| 158 |
you will find the definitions that the engine *LuaTeX* provides. The |
| 159 |
folder `lualibs` documents the extension library of the same name. If |
| 160 |
you use `lualatex`, you may be interested in the folder of the same |
| 161 |
name. |
| 162 |
|
| 163 |
### Directory `resources` |
| 164 |
|
| 165 |
The folder `resources` contains *TeX* manuals and *HTML* online |
| 166 |
documentation converted into *Lua* docstrings. |
| 167 |
|
| 168 |
### Directory `examples` |
| 169 |
|
| 170 |
The `example` folder contains *TeX* and *Lua* files for demonstrating |
| 171 |
and testing the documented Lua API. |
| 172 |
|
| 173 |
## Current version |
| 174 |
|
| 175 |
2025/07/24 v0.2.0 |
| 176 |
|
| 177 |
## License |
| 178 |
|
| 179 |
Copyright (C) 2022-2025 by Josef Friedrich <[email protected]> |
| 180 |
------------------------------------------------------------------------ |
| 181 |
|
| 182 |
This program is free software: you can redistribute it and/or modify it |
| 183 |
under the terms of the GNU General Public License as published by the |
| 184 |
Free Software Foundation, either version 2 of the License, or (at your |
| 185 |
option) any later version. |
| 186 |
|
| 187 |
This program is distributed in the hope that it will be useful, but |
| 188 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
| 189 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General |
| 190 |
Public License for more details. |
| 191 |
|
| 192 |
You should have received a copy of the GNU General Public License along |
| 193 |
with this program. If not, see <https://www.gnu.org/licenses/>. |
| 194 |
|
| 195 |
## Installation / Setup for Visual Studio Code |
| 196 |
|
| 197 |
Install [Visual Studio Code](https://code.visualstudio.com/) and the |
| 198 |
[lua-language-server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua). |
| 199 |
|
| 200 |
|
| 201 |
``` |
| 202 |
git clone https://github.com/Josef-Friedrich/LuaTeX_Lua-API.git |
| 203 |
``` |
| 204 |
|
| 205 |
`.vscode/settings.json`: |
| 206 |
|
| 207 |
```json |
| 208 |
{ |
| 209 |
"Lua.workspace.library": [ |
| 210 |
"<repo>/library" |
| 211 |
] |
| 212 |
} |
| 213 |
``` |
| 214 |
|
| 215 |
## How to contribute |
| 216 |
|
| 217 |
The preferred method of contributing to the project is via Github pull |
| 218 |
requests. You can also email patches to [email protected]. |
| 219 |
It is ok if you only document the data types of the input parameters. |
| 220 |
|
| 221 |
Use imperative mood for the first line: https://peps.python.org/pep-0257/ |
| 222 |
|
| 223 |
`Please contribute!` messages |
| 224 |
|
| 225 |
Default message: |
| 226 |
|
| 227 |
```lua |
| 228 |
---😱 [Types](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/pdf.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/pulls) |
| 229 |
``` |
| 230 |
|
| 231 |
No documentation at all: |
| 232 |
|
| 233 |
```lua |
| 234 |
--- |
| 235 |
---Warning! Undocumented code!<p> |
| 236 |
---TODO: Please contribute |
| 237 |
---https://github.com/Josef-Friedrich/LuaTeX_Lua-API#how-to-contribute |
| 238 |
``` |
| 239 |
|
| 240 |
### Minimal example of `tex.sp()` |
| 241 |
|
| 242 |
```lua |
| 243 |
--- |
| 244 |
---@param s string |
| 245 |
function tex.sp(s) end |
| 246 |
``` |
| 247 |
|
| 248 |
### Less minimal example of `tex.sp()` |
| 249 |
|
| 250 |
```lua |
| 251 |
--- |
| 252 |
---@param s string |
| 253 |
--- |
| 254 |
---@return integer |
| 255 |
function tex.sp(s) end |
| 256 |
``` |
| 257 |
|
| 258 |
Or if you have more time you can also expand the documentation to this |
| 259 |
level: |
| 260 |
|
| 261 |
### Prime example of `tex.sp()` |
| 262 |
|
| 263 |
```lua |
| 264 |
---@meta |
| 265 |
|
| 266 |
tex = {} |
| 267 |
|
| 268 |
--- |
| 269 |
---Convert a string `s` that represents an explicit |
| 270 |
---dimension into an integer number of scaled points. |
| 271 |
--- |
| 272 |
---For parsing the string, the same scanning and conversion rules are used that |
| 273 |
---*LuaTeX* would use if it was scanning a dimension specifier in its *TeX*-like |
| 274 |
---input language (this includes generating errors for bad values), expect for the |
| 275 |
---following: |
| 276 |
--- |
| 277 |
---* only explicit values are allowed, control sequences are not handled |
| 278 |
---* infinite dimension units (`fil...`) are forbidden |
| 279 |
---* `mu` units do not generate an error (but may not be useful either) |
| 280 |
--- |
| 281 |
---__Example:__ |
| 282 |
--- |
| 283 |
---```lua |
| 284 |
---local scaled_points = tex.sp('1cm') |
| 285 |
---print(scaled_points) -- 1864679 |
| 286 |
---``` |
| 287 |
--- |
| 288 |
---__Reference:__ |
| 289 |
--- |
| 290 |
---* `LuaTeX` manual: 10.3.15.5 `sp` page 204 |
| 291 |
---* Source file of the `LuaTeX` manual: [luatex-tex.tex#L1386-L1413](https://gitlab.lisn.upsaclay.fr/texlive/luatex/-/blob/f52b099f3e01d53dc03b315e1909245c3d5418d3/manual/luatex-tex.tex#L1386-L1413) |
| 292 |
--- |
| 293 |
---@param s string # A string to convert into scaled points. |
| 294 |
--- |
| 295 |
---@return integer # The dimension in the scaled points format. |
| 296 |
function tex.sp(s) end |
| 297 |
``` |
| 298 |
|
| 299 |
The docstring above is rendered as follows in Visual Studio Code: |
| 300 |
|
| 301 |
 |
| 302 |
|
| 303 |
The description text can be or was taken from the official [LuaTeX |
| 304 |
reference manual](https://github.com/TeX-Live/luatex/tree/trunk/manual). |
| 305 |
In the project folder |
| 306 |
[resources/manuals/luatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/resources/manuals/luatex) |
| 307 |
you will find slightly edited `Lua` versions of the `LuaTeX` manual |
| 308 |
sources. |
| 309 |
|
| 310 |
1. [Preamble](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/01_preamble.tex.lua) |
| 311 |
2. [Basic TEX enhancements](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/02_enhancements.tex.lua) |
| 312 |
3. [Modifications](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/03_modifications.tex.lua) |
| 313 |
4. [Using LUATEX](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/04_lua.tex.lua) |
| 314 |
5. [Languages, characters, fonts and glyphs](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/05_languages.tex.lua) |
| 315 |
6. [Font structure](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/06_fonts.tex.lua) |
| 316 |
7. [Math](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/07_math.tex.lua) |
| 317 |
8. [Nodes](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/08_nodes.tex.lua) |
| 318 |
9. [LUA callbacks](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/09_callbacks.tex.lua) |
| 319 |
10. [The TEX related libraries](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/10_tex.tex.lua) |
| 320 |
11. [The graphic libraries](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/11_graphics.tex.lua) |
| 321 |
12. [The fontloader](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/12_fontloader.tex.lua) |
| 322 |
13. [The HarfBuzz libraries](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/13_harfbuzz.tex.lua) |
| 323 |
14. [The backend libraries](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/luatex/14_backend.tex.lua) |
| 324 |
|
| 325 |
This quick hacked and very ugly Python script |
| 326 |
[resources/manuals/convert-tex-to-lua-docstrings.py](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/manuals/convert-tex-to-lua-docstrings.py) |
| 327 |
was used to convert the source files. |
| 328 |
|
| 329 |
### Navigation table `_N` |
| 330 |
|
| 331 |
Some Lua files contain a table named `_N`. `_N` stands for `navigation`. |
| 332 |
With the help of this table and the outline view of the editor, it is |
| 333 |
easier to navigate through the documentation. The name is inspired by |
| 334 |
the global Lua table `_G`. Many parts of the documentation, such as the |
| 335 |
definition of the various `Node` classes, are not shown in the outline. |
| 336 |
If the API documentation is published, the `_N` table can be commented |
| 337 |
out. |
| 338 |
|
| 339 |
### Documentation of function overloading |
| 340 |
|
| 341 |
`LuaTeX` makes extensive use of function overloading. The following |
| 342 |
example is taken from the `LuaTeX` manual: |
| 343 |
|
| 344 |
``` |
| 345 |
<number> w, <number> h, <number> d = |
| 346 |
node.dimensions(<node> n) |
| 347 |
<number> w, <number> h, <number> d = |
| 348 |
node.dimensions(<node> n, <string> dir) |
| 349 |
<number> w, <number> h, <number> d = |
| 350 |
node.dimensions(<node> n, <node> t) |
| 351 |
<number> w, <number> h, <number> d = |
| 352 |
node.dimensions(<node> n, <node> t, <string> dir) |
| 353 |
<number> w, <number> h, <number> d = |
| 354 |
node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, <node> n) |
| 355 |
<number> w, <number> h, <number> d = |
| 356 |
node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, <node> n, <string> dir) |
| 357 |
<number> w, <number> h, <number> d = |
| 358 |
node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, <node> n, <node> t) |
| 359 |
<number> w, <number> h, <number> d = |
| 360 |
node.dimensions(<number> glue_set, <number> glue_sign, <number> glue_order, <node> n, <node> t, <string> dir) |
| 361 |
``` |
| 362 |
|
| 363 |
This can easily be done by documenting the function with the same name |
| 364 |
but different signatures multiple times. |
| 365 |
|
| 366 |
[Issue for further improvement of the function loading](https://github.com/sumneko/lua-language-server/issues/1456) |
| 367 |
|
| 368 |
Function overloading in `tex.sp()` |
| 369 |
|
| 370 |
 |
| 371 |
|
| 372 |
### Documentation of nodes |
| 373 |
|
| 374 |
A node (object) can be described by the `@class` annotation and provided |
| 375 |
with some documentation about its attributes using `@field`. There is a base class `Node` for all node type classes. |
| 376 |
|
| 377 |
```lua |
| 378 |
--- |
| 379 |
---A node that comprise actual typesetting commands. A few fields are |
| 380 |
---present in all nodes regardless of their type, these are: |
| 381 |
--- |
| 382 |
---@class Node |
| 383 |
---@field next Node|nil # the next node in a list, or nil |
| 384 |
---@field prev Node|nil # That prev field is always present, but only initialized on explicit request ... |
| 385 |
``` |
| 386 |
|
| 387 |
The `KernNode` class for example inherits from `Node` and represents |
| 388 |
a kern node. |
| 389 |
|
| 390 |
```lua |
| 391 |
--- |
| 392 |
---The `kern` command creates such nodes but for instance the font and math |
| 393 |
---machinery can also add them. |
| 394 |
--- |
| 395 |
---@class KernNode: Node |
| 396 |
---@field subtype KernNodeSubtype |
| 397 |
---@field kern integer # Fixed horizontal or vertical advance (in scaled points) |
| 398 |
``` |
| 399 |
|
| 400 |
```lua |
| 401 |
---@alias KernNodeSubtype |
| 402 |
---|0 # fontkern |
| 403 |
---|1 # userkern |
| 404 |
---|2 # accentkern |
| 405 |
---|3 # italiccorrection |
| 406 |
``` |
| 407 |
|
| 408 |
The `@cast` annotation forces a unspecific node to a distinct node type. |
| 409 |
|
| 410 |
```lua |
| 411 |
while n do |
| 412 |
if n.id == node.id('kern') then |
| 413 |
---@cast n KernNode |
| 414 |
print(n.kern) |
| 415 |
end |
| 416 |
n = n.next |
| 417 |
end |
| 418 |
``` |
| 419 |
|
| 420 |
Use `--[[@as <node type>]]` to force a node type onto an expression. |
| 421 |
|
| 422 |
```lua |
| 423 |
local kern = node.new('kern') --[[@as KernNode]] |
| 424 |
``` |
| 425 |
|
| 426 |
 |
| 427 |
|
| 428 |
|
| 429 |
### Documentation of callback functions |
| 430 |
|
| 431 |
How a callback function is documented is shown using the |
| 432 |
`pre_linebreak_filter` as an example. |
| 433 |
|
| 434 |
#### @alias `PreLinebreakFilterGroupCode` |
| 435 |
|
| 436 |
```lua |
| 437 |
--- |
| 438 |
---The string called `groupcode` identifies the nodelist's context within |
| 439 |
---*TeX*'s processing. The range of possibilities is given in the table below, but |
| 440 |
---not all of those can actually appear in `pre_linebreak_filter`, some are |
| 441 |
---for the `hpack_filter` and `vpack_filter` callbacks that will be |
| 442 |
---explained in the next two paragraphs. |
| 443 |
---@alias PreLinebreakFilterGroupCode |
| 444 |
---|'' # main vertical list |
| 445 |
---|'hbox' # hbox` in horizontal mode |
| 446 |
---|'adjusted_hbox' #hbox` in vertical mode |
| 447 |
---|'vbox' # vbox` |
| 448 |
---|'vtop' # vtop' # |
| 449 |
---|'align' # halign` or `valign` |
| 450 |
---|'disc' # discretionaries |
| 451 |
---|'insert' # packaging an insert |
| 452 |
---|'vcenter' # vcenter` |
| 453 |
---|'local_box' # localleftbox` or `localrightbox` |
| 454 |
---|'split_off' # top of a `vsplit` |
| 455 |
---|'split_keep' # remainder of a `vsplit` |
| 456 |
---|'align_set' # alignment cell |
| 457 |
---|'fin_row' # alignment row |
| 458 |
``` |
| 459 |
|
| 460 |
#### @alias `NodeCallbackReturn` |
| 461 |
|
| 462 |
|
| 463 |
```lua |
| 464 |
--- |
| 465 |
---As for all the callbacks that deal with nodes, the return value can be one of |
| 466 |
---three things: |
| 467 |
--- |
| 468 |
---* boolean `true` signals successful processing |
| 469 |
---* `<node>` signals that the “head” node should be replaced by the |
| 470 |
--- returned node |
| 471 |
---* boolean `false` signals that the “head” node list should be |
| 472 |
--- ignored and flushed from memory |
| 473 |
---@alias NodeCallbackReturn true|false|Node |
| 474 |
``` |
| 475 |
|
| 476 |
#### @alias `PreLinebreakFilter` |
| 477 |
|
| 478 |
```lua |
| 479 |
--- |
| 480 |
---# `pre_linebreak_filter` callback |
| 481 |
--- |
| 482 |
---This callback is called just before *LuaTeX* starts converting a list of nodes |
| 483 |
---into a stack of `hbox`es, after the addition of `parfillskip`. |
| 484 |
--- |
| 485 |
---```lua |
| 486 |
------@type PreLinebreakFilter |
| 487 |
---function(head, groupcode) |
| 488 |
--- --- true|false|node |
| 489 |
--- return true |
| 490 |
---end |
| 491 |
---``` |
| 492 |
--- |
| 493 |
---This callback does not replace any internal code. |
| 494 |
---@alias PreLinebreakFilter fun(head: Node, groupcode: PreLinebreakFilterGroupCode): NodeCallbackReturn |
| 495 |
``` |
| 496 |
|
| 497 |
Annotation your custom callback function with `@type`. |
| 498 |
|
| 499 |
```lua |
| 500 |
---@type PreLinebreakFilter |
| 501 |
local function visit_nodes(head, group) |
| 502 |
return true |
| 503 |
end |
| 504 |
|
| 505 |
luatexbase.add_to_callback('pre_linebreak_filter', visit_nodes, 'visit nodes') |
| 506 |
``` |
| 507 |
|
| 508 |
 |
| 509 |
|
| 510 |
Quick info `node.id(type)` |
| 511 |
|
| 512 |
 |
| 513 |
|
| 514 |
Type error in `node.id(type)` |
| 515 |
|
| 516 |
 |
| 517 |
|
| 518 |
`node.id(type)` type definition |
| 519 |
|
| 520 |
 |
| 521 |
|
| 522 |
Quick info `node.write(n)` |
| 523 |
|
| 524 |
 |
| 525 |
|
| 526 |
Documentation for the field `data` of the `pdf_colorstack` node: |
| 527 |
|
| 528 |
 |
| 529 |
|
| 530 |
## Documentation |
| 531 |
|
| 532 |
* [LuaTeX Repo](https://gitlab.lisn.upsaclay.fr/texlive/luatex/) [LuaTeX Mirror](https://github.com/TeX-Live/luatex) |
| 533 |
* [pdfTeX Mirror](https://github.com/tex-mirror/pdftex) |
| 534 |
|
| 535 |
## Howtos |
| 536 |
|
| 537 |
* [Custom libraries](https://github.com/sumneko/lua-language-server/wiki/Libraries#custom) |
| 538 |
* [@meta annotation](https://github.com/sumneko/lua-language-server/wiki/Annotations#meta) |
| 539 |
|
| 540 |
## Other type definition / stub repos: |
| 541 |
|
| 542 |
* [Template of the Lua interface itself](https://github.com/sumneko/lua-language-server/tree/master/meta/template) |
| 543 |
* [In the lua-language-server included 3rd party libraries](https://github.com/sumneko/lua-language-server/tree/master/meta/3rd) |
| 544 |
* [FiveM Lua Stubs](https://github.com/jamie-34254/fivem_lua_stubs) |
| 545 |
|
| 546 |
|
| 547 |
## References |
| 548 |
|
| 549 |
```lua |
| 550 |
--- |
| 551 |
---__Reference:__ |
| 552 |
--- |
| 553 |
---* Corresponding C source code: [ltexlib.c#L1430-L1436](https://gitlab.lisn.upsaclay.fr/texlive/luatex/-/blob/f52b099f3e01d53dc03b315e1909245c3d5418d3/source/texk/web2c/luatexdir/lua/ltexlib.c#L1430-L1436) |
| 554 |
---* Source file of the `LuaTeX` manual: [luatex-nodes.tex#L1199-L1211](https://gitlab.lisn.upsaclay.fr/texlive/luatex/-/blob/f52b099f3e01d53dc03b315e1909245c3d5418d3/manual/luatex-nodes.tex#L1199-L1211) |
| 555 |
---* Corresponding plain TeX control sequence: [\sfcode](https://www.tug.org/utilities/plain/cseq.html#sfcode-rp) |
| 556 |
---* Victor Eijkhout. “TeX by Topic” (1991, 2007) [page 185](http://mirrors.ctan.org/info/texbytopic/TeXbyTopic.pdf) |
| 557 |
---* Donald Ervin Knuth. “The TexBook” (1984): page 76. Also: 76, 271, 285, 363, 433. [TeX-Source](https://ctan.org/tex-archive/systems/knuth/dist/tex/texbook.tex) [PDF](https://visualmatheditor.equatheque.net/doc/texbook.pdf) |
| 558 |
---David Bausum. “TeX Reference Manual” (2002) [](https://www.tug.org/utilities/plain/cseq.html) |
| 559 |
``` |
| 560 |
|
| 561 |
```lua |
| 562 |
--- |
| 563 |
---__Reference:__ |
| 564 |
--- |
| 565 |
---* Source file of the `LuaTeX` manual: []() |
| 566 |
--- |
| 567 |
``` |
| 568 |
|
| 569 |
## Global namespaces |
| 570 |
|
| 571 |
The Makefile provides targets for printing the global namespace |
| 572 |
available on the specific engines. The Makefile uses some Lua functions |
| 573 |
to output all functions and tables of the global namespace that can be |
| 574 |
found in |
| 575 |
[utils.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/utils.lua). |
| 576 |
|
| 577 |
To print the [LuaTeX global |
| 578 |
namespace](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/namespaces/luatex.md): |
| 579 |
|
| 580 |
``` |
| 581 |
make namespace_luatex |
| 582 |
``` |
| 583 |
|
| 584 |
To print the [LuaMetaTeX global namespace](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/namespaces/luametatex_luaonly.md): |
| 585 |
|
| 586 |
``` |
| 587 |
make namespace_luametatex |
| 588 |
``` |