{"id":30751282,"url":"https://github.com/texluacats/meta","last_synced_at":"2025-09-04T07:39:22.796Z","repository":{"id":72532604,"uuid":"583927494","full_name":"TeXLuaCATS/meta","owner":"TeXLuaCATS","description":"Meta package for the TeX related Lua type definitions. Bundles all sub repos to build and distribute the definitions","archived":false,"fork":false,"pushed_at":"2025-08-28T14:13:30.000Z","size":27176,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-28T14:21:53.792Z","etag":null,"topics":["api","documentation","lsp","lua","luatex"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TeXLuaCATS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-12-31T13:53:56.000Z","updated_at":"2025-08-28T14:13:34.000Z","dependencies_parsed_at":"2025-08-14T12:30:26.718Z","dependency_job_id":"311f84c3-3aec-486c-9df3-3d1930513fda","html_url":"https://github.com/TeXLuaCATS/meta","commit_stats":null,"previous_names":["texluacats/meta"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/TeXLuaCATS/meta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXLuaCATS%2Fmeta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXLuaCATS%2Fmeta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXLuaCATS%2Fmeta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXLuaCATS%2Fmeta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TeXLuaCATS","download_url":"https://codeload.github.com/TeXLuaCATS/meta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TeXLuaCATS%2Fmeta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273574046,"owners_count":25129882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","documentation","lsp","lua","luatex"],"created_at":"2025-09-04T07:39:20.498Z","updated_at":"2025-09-04T07:39:22.778Z","avatar_url":"https://github.com/TeXLuaCATS.png","language":"Lua","readme":"# LuaTeX Lua API\n\nType definitions for the Lua API of `LuaTeX` and related projects.\n\n![](resources/screencasts/node.new.gif)\n\n[LuaTeX](http://luatex.org) has a very large [Lua](https://www.lua.org)\nAPI. This project tries to make this API accessible in the text editor\nof your choice. This is made possible by the\n[lua-language-server](https://github.com/LuaLS/lua-language-server) - a\nserver that implements the [Language Server Protocol\n(LSP)](https://en.wikipedia.org/wiki/Language_Server_Protocol) for the\n`Lua` language. Features such as code completion, syntax highlighting\nand marking of warnings and errors, should therefore not only be\npossible in [Visual Studio Code](https://code.visualstudio.com), but in\na [large number of\neditors](https://langserver.org/#implementations-client) that support\nthe `LSP`.\n\n## Subprojects\n\n* [lualatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualatex)\n* [lualibs](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualibs)\n* [luametatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luametatex)\n* [luaotfload](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luaotfload)\n* [luatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luatex)\n\n## Distribution ...\n\n## via CTAN\n\n![](resources/images/Screenshot_CTAN.png)\n\nThe type definitions are published on\n[CTAN](https://www.ctan.org/pkg/luatex-type-definitions) as a single\nfile to avoid cluttering the CTAN directory with many individual Lua\nfiles. Since this one file is just under 1.5 MB in size, a configuration\nmust be made so that the language server can load the file. The\nfollowing configuration example sets the preload file size to a maximum\nof 5000 kB.\n\n```json\n{\n    \"Lua.workspace.preloadFileSize\": 5000,\n}\n```\n\nThere are several ways to include type definitions in a project.\nThe easiest way is to copy the file into the project folder.\nOr you can use the configuration `Lua.workspace.library`:\n\n```json\n{\n    \"Lua.workspace.library\": [\"/path/to/luatex-type-definitions.lua\"]\n}\n```\n\n### via Visual Studio Code Extension\n\n![](resources/images/Screenshot_VSCode-extension.png)\n\n* [Visual Studio Code LuaTeX Extension](https://github.com/Josef-Friedrich/vscode_LuaTeX_Lua-API)\n  ← [library](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library)\n\n### via LuaCATS git respositories\n\n![](resources/images/Screenshot_LuaCATS.png)\n\n[LuaCATS](https://github.com/LuaCATS) is a [Github](https://github.com)\norganisation and stands for *“Lua Comment And Type System”*. This\norganization provides a place for community projects to live. These\nprojects are [addons](https://luals.github.io/wiki/addons) for popular\nlibraries/frameworks.\nThe repositories in this organization are used by\n[LLS-Addons](https://github.com/LuaLS/LLS-Addons), a repository that is used by the [addon\nmanager](https://luals.github.io/wiki/addons/#addon-manager) of the [VS\nCode\nextension](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)\nfor the [Lua Language Server]([lls](https://github.com/LuaLS/lua-language-server)).\n\n#### All related LuaCATS repositories\n\nThis repositories in LuaCATS are related to this project:\n\n* [lmathx](https://github.com/LuaCATS/lmathx)\n* [lpeg](https://github.com/LuaCATS/lpeg)\n* [luafilesystem](https://github.com/LuaCATS/luafilesystem)\n* [luaharfbuzz](https://github.com/LuaCATS/luaharfbuzz)\n* [luasocket](https://github.com/LuaCATS/luasocket)\n* [luazip](https://github.com/LuaCATS/luazip)\n* [lzlib](https://github.com/LuaCATS/lzlib)\n* [md5](https://github.com/LuaCATS/md5)\n* [slnunicode](https://github.com/LuaCATS/slnunicode)\n* [tex-lualatex](https://github.com/LuaCATS/tex-lualatex)\n* [tex-lualibs](https://github.com/LuaCATS/tex-lualibs)\n* [tex-luametatex](https://github.com/LuaCATS/tex-luametatex)\n* [tex-luatex](https://github.com/LuaCATS/tex-luatex)\n\n#### Upstream LuaCATS repositories\n\nThe following repositories are *upstream* projects. This means: The type\ndefinitions are developed in a LuaCATS repository and *pulled* in by\nthis project.\n\n* [LuaCATS: lmathx](https://github.com/LuaCATS/lmathx)\n  → [library/luametatex/lmathx.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luametatex/xmath.lua)\n* [LuaCATS: lpeg](https://github.com/LuaCATS/lpeg)\n  → [library/luatex/lpeg.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/lpeg.lua)\n* [LuaCATS: luaharfbuzz](https://github.com/LuaCATS/luaharfbuzz)\n  → [library/luatex/luaharfbuzz.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/luaharfbuzz.lua)\n* [LuaCATS: luasocket](https://github.com/LuaCATS/luasocket)\n  → [library/luatex/socket.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/socket.lua)\n  → [library/luatex/mime.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/mime.lua)\n* [LuaCATS: luazip](https://github.com/LuaCATS/luazip)\n  → [library/luatex/zip.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zip.lua)\n* [LuaCATS: lzlib](https://github.com/LuaCATS/lzlib)\n  → [library/luatex/zlib.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zlib.lua)\n* [LuaCATS: md5](https://github.com/LuaCATS/md5)\n  → [library/luatex/md5.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/md5.lua)\n* [LuaCATS: slnunicode](https://github.com/LuaCATS/slnunicode)\n  → [library/luatex/unicode.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/unicode.lua)\n\n#### Downstream LuaCATS repositories\n\nThe following repositories are *downstream* projects. This means: The\ntype definitions are developed in this project. They are then *pushed*\ninto a LuaCATS repository.\n\n* [LuaCATS: tex-lualatex](https://github.com/LuaCATS/tex-lualatex)\n  ← [library/lualatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualatex)\n* [LuaCATS: tex-luatex](https://github.com/LuaCATS/tex-luatex)\n  ← [library/luatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luatex)\n* [LuaCATS: tex-lualibs](https://github.com/LuaCATS/tex-lualibs)\n  ← [library/lualibs](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualibs)\n* [LuaCATS: tex-luametatex](https://github.com/LuaCATS/tex-luametatex)\n  ← [library/luametatex](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luametatex)\n\n## Directory structure of the repository\n\nIn the subfolder `library` are files named after the global libraries\nthey document. For example, the `library/tex.lua` file contains the\ndocumentation for the `tex` library. These *Lua* files don’t contain\nreal *Lua* code. They consist only of function bodies and empty\ntables. The main focus is in the docstrings.\n\nThe API documentation is written in a [well documented annotation\nformat](https://luals.github.io/wiki/annotations).\nThis format is based on the [EmmyLua](https://emmylua.github.io)\nformat. Unfortunately, the *Lua* community has not yet been able to\nagree on a standarized annotation format. Many *Lua* project are\ndocumented in the [LDoc](https://github.com/lunarmodules/LDoc) format.\nHowever, the differences between these formats are marginal.\n\n### Directory `library`\n\nThe actual definitions are located in the directory `library`. This\ndirectory is divided into further subdirectories. In the folder `luatex`\nyou will find the definitions that the engine *LuaTeX* provides. The\nfolder `lualibs` documents the extension library of the same name. If\nyou use `lualatex`, you may be interested in the folder of the same\nname.\n\n### Directory `resources`\n\nThe folder `resources` contains *TeX* manuals and *HTML* online\ndocumentation  converted into *Lua* docstrings.\n\n### Directory `examples`\n\nThe `example` folder contains *TeX* and *Lua* files for demonstrating\nand testing the documented Lua API.\n\n## Current version\n\n2025/07/24 v0.2.0\n\n## License\n\nCopyright (C) 2022-2025 by Josef Friedrich \u003cjosef@friedrich.rocks\u003e\n------------------------------------------------------------------------\n\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 2 of the License, or (at your\noption) any later version.\n\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License for more details.\n\nYou should have received a copy of the GNU General Public License along\nwith this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n### About the license selection\n\nThe same license was used for the type definitions as for LuaTeX (GPLv2).\nThe MIT license is used for the external upstream projects.\n\n### GPLv2 copyright notice for every file\n\nOnly two hyphens are used here, rather than three, so that the copyright notice\ndoes not end up in the rendered documentation.\n\n```lua\n-- -----------------------------------------------------------------------------\n-- Copyright (C) 2022-2025 by Josef Friedrich \u003cjosef@friedrich.rocks\u003e\n-- -----------------------------------------------------------------------------\n--\n-- This program is free software: you can redistribute it and/or modify it\n-- under the terms of the GNU General Public License as published by the\n-- Free Software Foundation, either version 2 of the License, or (at your\n-- option) any later version.\n--\n-- This program is distributed in the hope that it will be useful, but\n-- WITHOUT ANY WARRANTY; without even the implied warranty of\n-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\n-- Public License for more details.\n--\n-- You should have received a copy of the GNU General Public License along\n-- with this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n--\n-- -----------------------------------------------------------------------------\n\n```\n\n### MIT copyright notice for every file\n\n```lua\n-- -----------------------------------------------------------------------------\n-- Copyright (c) 2023-2025 by Josef Friedrich \u003cjosef@friedrich.rocks\u003e\n-- -----------------------------------------------------------------------------\n--\n-- MIT License\n--\n-- Permission is hereby granted, free of charge, to any person obtaining a copy\n-- of this software and associated documentation files (the \"Software\"), to deal\n-- in the Software without restriction, including without limitation the rights\n-- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n-- copies of the Software, and to permit persons to whom the Software is\n-- furnished to do so, subject to the following conditions:\n--\n-- The above copyright notice and this permission notice shall be included in\n-- all copies or substantial portions of the Software.\n--\n-- THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n-- SOFTWARE.\n--\n-- -----------------------------------------------------------------------------\n\n```\n\n## Installation / Setup for Visual Studio Code\n\nInstall [Visual Studio Code](https://code.visualstudio.com/) and the\n[lua-language-server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua).\n\n\n```\ngit clone https://github.com/Josef-Friedrich/LuaTeX_Lua-API.git\n```\n\n`.vscode/settings.json`:\n\n```json\n{\n\"Lua.workspace.library\": [\n    \"\u003crepo\u003e/library\"\n  ]\n}\n```\n\n## How to contribute\n\nThe preferred method of contributing to the project is via Github pull\nrequests. You can also email patches to josef@friedrich.rocks.\nIt is ok if you only document the data types of the input parameters.\n\nUse imperative mood for the first line: https://peps.python.org/pep-0257/\n\n`Please contribute!` messages\n\nDefault message:\n\n```lua\n---😱 [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)\n```\n\nNo documentation at all:\n\n```lua\n---\n---Warning! Undocumented code!\u003cp\u003e\n---TODO: Please contribute\n---https://github.com/Josef-Friedrich/LuaTeX_Lua-API#how-to-contribute\n```\n\n### Minimal example of `tex.sp()`\n\n```lua\n---\n---@param s string\nfunction tex.sp(s) end\n```\n\n### Less minimal example of `tex.sp()`\n\n```lua\n---\n---@param s string\n---\n---@return integer\nfunction tex.sp(s) end\n```\n\nOr if you have more time you can also expand the documentation to this\nlevel:\n\n### Prime example of `tex.sp()`\n\n```lua\n---@meta\n\ntex = {}\n\n---\n---Convert a string `s` that represents an explicit\n---dimension into an integer number of scaled points.\n---\n---For parsing the string, the same scanning and conversion rules are used that\n---*LuaTeX* would use if it was scanning a dimension specifier in its *TeX*-like\n---input language (this includes generating errors for bad values), expect for the\n---following:\n---\n---* only explicit values are allowed, control sequences are not handled\n---* infinite dimension units (`fil...`) are forbidden\n---* `mu` units do not generate an error (but may not be useful either)\n---\n---__Example:__\n---\n---```lua\n---local scaled_points = tex.sp('1cm')\n---print(scaled_points) -- 1864679\n---```\n---\n---__Reference:__\n---\n---* `LuaTeX` manual: 10.3.15.5 `sp` page 204\n---* 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)\n---\n---@param s string # A string to convert into scaled points.\n---\n---@return integer # The dimension in the scaled points format.\nfunction tex.sp(s) end\n```\n\nThe docstring above is rendered as follows in Visual Studio Code:\n\n![](resources/images/tex.sp.png)\n\nThis quick hacked and very ugly Python script\n[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)\nwas used to convert the source files.\n\n### Navigation table `_N`\n\nSome Lua files contain a table named `_N`. `_N` stands for *navigation*.\nWith the help of this table and the outline view of the editor, it is\neasier to navigate through the documentation. The name is inspired by\nthe global Lua table `_G`. Many parts of the documentation, such as the\ndefinition of the various `Node` classes, are not shown in the outline.\nIn the released version, this navigation table is removed using the\n`manage.py` management script.\n\n```lua\n-- The `_N` table makes it easier to navigate through the type definitions with\n-- the help of the outline:\n-- https://github.com/TeXLuaCATS/meta?tab=readme-ov-file#navigation-table-_n\n_N = {}\n```\n\nThe different node types are defined as classes. Since this class\ndefinition takes place entirely in the comments, it is not displayed in\nthe outline.\n\n```lua\n_N.hlist = 0\n\n---@class HlistNode: ListNode\n\n_N.vlist = 1\n\n---@class VlistNode: ListNode\n```\n\nThe following example refers to section “8.7.2 is_node” on page 149 in\nthe LuaTeX documentation.\n\n```lua\n_N._8_7_2_is_node = \"page 149\"\n```\n\n### Documentation of function overloading\n\n`LuaTeX` makes extensive use of function overloading. The following\nexample is taken from the `LuaTeX` manual:\n\n```\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnode\u003e n)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnode\u003e n, \u003cstring\u003e dir)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnode\u003e n, \u003cnode\u003e t)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnode\u003e n, \u003cnode\u003e t, \u003cstring\u003e dir)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnumber\u003e glue_set, \u003cnumber\u003e glue_sign, \u003cnumber\u003e glue_order, \u003cnode\u003e n)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnumber\u003e glue_set, \u003cnumber\u003e glue_sign, \u003cnumber\u003e glue_order, \u003cnode\u003e n, \u003cstring\u003e dir)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnumber\u003e glue_set, \u003cnumber\u003e glue_sign, \u003cnumber\u003e glue_order, \u003cnode\u003e n, \u003cnode\u003e t)\n\u003cnumber\u003e w, \u003cnumber\u003e h, \u003cnumber\u003e d =\n  node.dimensions(\u003cnumber\u003e glue_set, \u003cnumber\u003e glue_sign, \u003cnumber\u003e glue_order, \u003cnode\u003e n, \u003cnode\u003e t, \u003cstring\u003e dir)\n```\n\nThis can easily be done by documenting the function with the same name\nbut different signatures multiple times.\n\n[Issue for further improvement of the function loading](https://github.com/sumneko/lua-language-server/issues/1456)\n\nFunction overloading in `tex.sp()`\n\n![](resources/images/tex.sp_overload.png)\n\n### Overview of the existing Lua language server\n\n#### lua-language-server\n\nThe most popular language server, simply named\n[lua-language-server](https://github.com/LuaLS/lua-language-server), was\ncreated by a Chinese with the nickname\n[*sumneko*](https://github.com/sumneko). In addition to the nickname,\n*sumnekos* Github profile also shows 最萌小汐 in Chinese characters,\nwhich means “The cutest Xiaoxi”[^google-translate] or “Xiao Shi, the\nmost adorable child in the world”[^deepl]. The [first\ncommit](https://github.com/LuaLS/lua-language-server/commit/3546129c29fbfd7211099a3fbee03a763915ab58)\nin the Git repository was made on 7 September 2018. The\n*lua-language-server* is written in Lua. In August 2025, the repository\non Gibhub has around 3,800 stars.\n\n[^google-translate]: https://translate.google.de/?sl=zh-CN\u0026tl=en\u0026text=%E6%9C%80%E8%90%8C%E5%B0%8F%E6%B1%90%20\u0026op=translate\n[^deepl]: https://www.deepl.com/en/translator#zh/en-gb/%E6%9C%80%E8%90%8C%E5%B0%8F%E6%B1%90\n\n### EmmyLua Analyzer Rust\n\nA promising language server that is not written in Lua but in Rust is\nthe [EmmyLua Analyzer\nRust](https://github.com/EmmyLuaLs/emmylua-analyzer-rust). This server\nwas written by [CppCXY](https://github.com/CppCXY), the developer with\nthe most commits after sumneko. The new server is advertised in\n[several](https://github.com/LuaLS/lua-language-server/issues/2910)\n[issues](https://github.com/LuaLS/lua-language-server/issues/3017) in\nthe sumnekos *lua-language-server* Github repository.\n\n### Documentation of nodes\n\nA node (object) can be described by the `@class` annotation and provided\nwith some documentation about its attributes using `@field`. There is a base class `Node` for all node type classes.\n\n```lua\n---\n---A node that comprise actual typesetting commands. A few fields are\n---present in all nodes regardless of their type, these are:\n---\n---@class Node\n---@field next Node|nil # the next node in a list, or nil\n---@field prev Node|nil # That prev field is always present, but only initialized on explicit request ...\n```\n\nThe `KernNode` class for example inherits from `Node` and represents\na kern node.\n\n```lua\n---\n---The `kern` command creates such nodes but for instance the font and math\n---machinery can also add them.\n---\n---@class KernNode: Node\n---@field subtype KernNodeSubtype\n---@field kern integer # Fixed horizontal or vertical advance (in scaled points)\n```\n\n```lua\n---@alias KernNodeSubtype\n---|0 # fontkern\n---|1 # userkern\n---|2 # accentkern\n---|3 # italiccorrection\n```\n\nThe `@cast` annotation forces a unspecific node to a distinct node type.\n\n```lua\nwhile n do\n  if n.id == node.id('kern') then\n    ---@cast n KernNode\n    print(n.kern)\n  end\n  n = n.next\nend\n```\n\nUse `--[[@as \u003cnode type\u003e]]` to force a node type onto an expression.\n\n```lua\nlocal kern = node.new('kern') --[[@as KernNode]]\n```\n\n![](resources/images/cast.png)\n\n\n### Documentation of callback functions\n\nHow a callback function is documented is shown using the\n`pre_linebreak_filter` as an example.\n\n#### @alias `PreLinebreakFilterGroupCode`\n\n```lua\n---\n---The string called `groupcode` identifies the nodelist's context within\n---*TeX*'s processing. The range of possibilities is given in the table below, but\n---not all of those can actually appear in `pre_linebreak_filter`, some are\n---for the `hpack_filter` and `vpack_filter` callbacks that will be\n---explained in the next two paragraphs.\n---@alias PreLinebreakFilterGroupCode\n---|'' # main vertical list\n---|'hbox' # hbox` in horizontal mode\n---|'adjusted_hbox' #hbox` in vertical mode\n---|'vbox' # vbox`\n---|'vtop' # vtop' #\n---|'align' # halign` or `valign`\n---|'disc' # discretionaries\n---|'insert' # packaging an insert\n---|'vcenter' # vcenter`\n---|'local_box' # localleftbox` or `localrightbox`\n---|'split_off' # top of a `vsplit`\n---|'split_keep' # remainder of a `vsplit`\n---|'align_set' # alignment cell\n---|'fin_row' # alignment row\n```\n\n#### @alias `NodeCallbackReturn`\n\n\n```lua\n---\n---As for all the callbacks that deal with nodes, the return value can be one of\n---three things:\n---\n---* boolean `true` signals successful processing\n---* `\u003cnode\u003e` signals that the “head” node should be replaced by the\n---  returned node\n---* boolean `false` signals that the “head” node list should be\n---  ignored and flushed from memory\n---@alias NodeCallbackReturn true|false|Node\n```\n\n#### @alias `PreLinebreakFilter`\n\n```lua\n---\n---# `pre_linebreak_filter` callback\n---\n---This callback is called just before *LuaTeX* starts converting a list of nodes\n---into a stack of `hbox`es, after the addition of `parfillskip`.\n---\n---```lua\n------@type PreLinebreakFilter\n---function(head, groupcode)\n---  --- true|false|node\n---  return true\n---end\n---```\n---\n---This callback does not replace any internal code.\n---@alias PreLinebreakFilter fun(head: Node, groupcode: PreLinebreakFilterGroupCode): NodeCallbackReturn\n```\n\nAnnotation your custom callback function with `@type`.\n\n```lua\n---@type PreLinebreakFilter\nlocal function visit_nodes(head, group)\n  return true\nend\n\nluatexbase.add_to_callback('pre_linebreak_filter', visit_nodes, 'visit nodes')\n```\n\n![](resources/images/PreLinebreakFilter.png)\n\nQuick info `node.id(type)`\n\n![](resources/images/node.id.png)\n\nType error in `node.id(type)`\n\n![](https://raw.githubusercontent.com/Josef-Friedrich/LuaTeX_Lua-API/main/resources/images/node.id_wrong-type.png)\n\n`node.id(type)` type definition\n\n![](https://raw.githubusercontent.com/Josef-Friedrich/LuaTeX_Lua-API/main/resources/images/node.id_definition.png)\n\nQuick info `node.write(n)`\n\n![](https://raw.githubusercontent.com/Josef-Friedrich/LuaTeX_Lua-API/main/resources/images/node.write.png)\n\nDocumentation for the field `data` of the `pdf_colorstack` node:\n\n![](https://raw.githubusercontent.com/Josef-Friedrich/LuaTeX_Lua-API/main/resources/images/PdfColorstockWhatsitNode.data.png)\n\n## Documentation\n\n* [LuaTeX Repo](https://gitlab.lisn.upsaclay.fr/texlive/luatex/) [LuaTeX Mirror](https://github.com/TeX-Live/luatex)\n* [pdfTeX Mirror](https://github.com/tex-mirror/pdftex)\n\n## Howtos\n\n* [Custom libraries](https://github.com/sumneko/lua-language-server/wiki/Libraries#custom)\n* [@meta annotation](https://github.com/sumneko/lua-language-server/wiki/Annotations#meta)\n\n## Other type definition / stub repos:\n\n* [Template of the Lua interface itself](https://github.com/sumneko/lua-language-server/tree/master/meta/template)\n* [In the lua-language-server included 3rd party libraries](https://github.com/sumneko/lua-language-server/tree/master/meta/3rd)\n* [FiveM Lua Stubs](https://github.com/jamie-34254/fivem_lua_stubs)\n\n## Annotation\n\n### @meta\n\nDo not put the `@meta` tag in the docstrings for a global table, because\nEmmaLua Rust will not render the docstrings for this global table.\n\nMarks a file as \"meta\", meaning it is used for definitions and not for\nits functional Lua code. It is used internally by the language server\nfor defining the [built-in Lua\nlibraries](https://github.com/LuaLS/lua-language-server/tree/master/meta/template).\nIf you are writing your own [definition files](/wiki/definition-files),\nyou will probably want to include this annotation in them. If you\nspecify a name, it will only be able to be required by the given name.\nGiving the name `_` will make it unable to be required. Files with the\n`@meta` tag in them behave a little different:\n\n- Completion will not display context in a meta file\n- Hovering a `require` of a meta file will show `[meta]` instead of its absolute path\n- `Find Reference` ignores meta files\n\n**Syntax**\n\n`---@meta [name]`\n\n**Examples**\n\n\nMark Meta File\n\n```Lua\n---@meta [name]\n```\n[^luals-meta]\n\n[^luals-meta]: https://github.com/LuaLS/LuaLS.github.io/blob/f87938ff71a9322ac2bdcbac2164ad2da7e394f0/src/content/wiki/annotations.mdx?plain=1#L731-L752\n\n## HTML doc generator\n\nThe [EmmyLua Analyzer\nRust](https://github.com/EmmyLuaLs/emmylua-analyzer-rust) provides a\n[documentation generation tool](https://github.com/EmmyLuaLs/emmylua-analyzer-rust/tree/main/crates/emmylua_doc_cli).\nThis tool generates Markdown files which can be parsed by [mkdocs](https://www.mkdocs.org).\n\n```yml\nsite_name: LuaTeX Lua API type definitions\n\ntheme:\n  name: material\n  font:\n    text: Roboto\n    code: Roboto Mono\n  search: true\n  features:\n    - quick-links\n    - navigation\n    - search\n    - toc\n    - fullscreen\n    - bookmarks\n    - tabs\n    - code\n    - edit-on-github\n    - language-selector\n    - code\n    - cover\n    - footer\n    - social-share\n    - theme-switcher\n\nmarkdown_extensions:\n  - pymdownx.highlight:\n      anchor_linenums: true\n      line_spans: __span\n      pygments_lang_class: true\n  - pymdownx.inlinehilite\n  - pymdownx.snippets\n  - pymdownx.superfences\n```\n\n## References\n\n\n\n```lua\n---\n---__Reference:__\n---\n---* Source file of the `LuaTeX` manual: []()\n---\n```\n\n## Global namespaces\n\nThe Makefile provides targets for printing the global namespace\navailable on the specific engines. The Makefile uses some Lua functions\nto output all functions and tables of the global namespace that can be\nfound in\n[utils.lua](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/utils.lua).\n\nTo print the [LuaTeX global\nnamespace](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/namespaces/luatex.md):\n\n```\nmake namespace_luatex\n```\n\nTo print the [LuaMetaTeX global namespace](https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/resources/namespaces/luametatex_luaonly.md):\n\n```\nmake namespace_luametatex\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexluacats%2Fmeta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftexluacats%2Fmeta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexluacats%2Fmeta/lists"}