Directory support/expltools
Expltools: Development tools for expl3 programmers
This repository contains the code and documentation of an expl3 static analysis tool explcheck
outlined in the following devlog posts:
On September 6, 2024, the tool has been accepted for funding by the TeX Development Fund. The full text of the project proposal, which summarizes devlog posts 1–4 is available here.
These devlog posts chronicle the latest updates and progress in the ongoing development of the tool:
- Frank Mittelbach in Brno, the first public release of explcheck, and expl3 usage statistics from December 5, 2024
- A flurry of releases, CSTUG talk, and what's next from December 19, 2024
In the future, this repository may also contain the code of other useful development tools for expl3 programmers, such as a command-line utility similar to grep
that will ignore whitespaces and newlines as well as other tools.
Usage
You can use the tool from the command line as follows:
$ explcheck [options] [.tex, .cls, and .sty files]
You can also use the tool from your own Lua code by importing the corresponding files explcheck-*.lua
. For example, here is Lua code that applies the preprocessing step to the code from a file named code.tex
:
local new_issues = require("explcheck-issues") local preprocessing = require("explcheck-preprocessing") -- LuaTeX users must initialize Kpathsea Lua module searchers first. local using_luatex, kpse = pcall(require, "kpse") if using_luatex then kpse.set_program_name("texlua", "explcheck") end -- Apply the preprocessing step to a file "code.tex". local filename = "code.tex" local issues = new_issues() local file = assert(io.open(filename, "r")) local content = assert(file:read("*a")) assert(file:close()) local line_starting_byte_numbers = preprocessing(issues, content) print( "There were " .. #issues.warnings .. " warnings " .. "and " .. #issues.errors .. " errors " .. "in the file " .. filename .. "." )
You can also use the tool from continuous integration workflows using the Docker image ghcr.io/witiko/expltools/explcheck
. For example, here is a GitHub Actions workflow file that applies the tool to all .tex file in a Git repository:
name: Check expl3 code on: push: jobs: typeset: runs-on: ubuntu-latest container: image: ghcr.io/witiko/expltools/explcheck steps: - uses: actions/checkout@v4 - run: explcheck *.tex
Notes to distributors
You can prepare the expltools bundle for distribution with the following two commands:
l3build tag
: Add the current version numbers to the fileexplcheck-lua.cli
.l3build ctan
: Run tests, build the documentation, and create a CTAN archiveexpltools-ctan.zip
.
The file explcheck.lua
should be installed in the TDS directory scripts/expltools/explcheck
. Furthermore, it should be made executable and either symlinked to system directories as explcheck
on Unix or have a wrapper explcheck.exe
installed on Windows.
Authors
- Vít Starý Novotný (<witiko@mail.muni.cz>)
License
This material is dual-licensed under GNU GPL 2.0 or later and LPPL 1.3c or later.
Download the contents of this package in one zip archive (2.7M).
expltools – Development tools for expl3 programmers
This bundle introduces explcheck, a static analysis tool for developers working with expl3 code. Currently in its initial release, explcheck aims to help developers identify potential issues and improve code quality. In the future, this bundle may expand to include additional development tools for expl3.
Package | expltools |
Support | https://github.com/witiko/expltools/discussions |
Bug tracker | https://github.com/witiko/expltools/issues |
Announcements | https://github.com/witiko/expltools/releases |
Repository | https://github.com/witiko/expltools |
Version | 2024-12-23 |
Licenses | GNU General Public License, version 2 or newer The LaTeX Project Public License 1.3c |
Copyright | 2024 Vít Starý Novotný |
Maintainer | Vít Starý Novotný |
Contained in | TeX Live as expltools MiKTeX as expltools |
Topics | Debug supp |