[ANN] The Tiny Lua Compiler - A self-hosting, educational implementation of Lua 5.1

[daniel...@proton.me]

<div style="font-family: Arial, sans-serif; font-size: 14px;">Hi everyone,<br>
<br>
For the past year, I have been working on The Tiny Lua Compiler, an educational project that implements Lua 5.1 entirely in Lua. It features a fully functioning lexer, parser, code generator, and virtual machine, all contained in a single file of roughly 4000 lines of heavily commented code.<br>
<br>
<a href="https://github.com/bytexenon/The-Tiny-Lua-Compiler">https://github.com/bytexenon/The-Tiny-Lua-Compiler</a><br>
<br>
The motivation came from studying the official C implementation. While efficient, I found it difficult for a beginner to fully grasp. I wanted to build a "clean room" implementation that prioritizes readability over performance, essentially treating the code as executable documentation.<br>
<br>
To that end, the project has zero dependencies; I avoided LPeg to ensure it runs on a stock interpreter. It is also fully self-hosting: the compiler can compile its own source code and execute the result within its own VM.<br>
<br>
There are a few intentional omissions, most notably the&nbsp;<code>CLOSE</code>&nbsp;instruction (and by extension, full upvalue closing semantics on scope exit). I decided that the added complexity in the Code Generator outweighed the educational value for this specific project.<br>
<br>
I am specifically looking for feedback on simplification. My goal is to keep the project as small and approachable as possible. If you see areas where the implementation could be made cleaner without sacrificing readability, I would love to hear your thoughts.<br>
<br>
-Daniel</div>

[daniel...@proton.me]

Apologies for the raw HTML in the previous message.

Here is the readable version:

---

Hi everyone,

For the past year, I have been working on The Tiny Lua Compiler, an educational project that implements Lua 5.1 entirely in Lua. It features a fully functioning lexer, parser, code generator, and virtual machine, all contained in a single file of roughly 4000 lines of heavily commented code.

https://github.com/bytexenon/The-Tiny-Lua-Compiler

The motivation came from studying the official C implementation. While efficient, I found it difficult for a beginner to fully grasp. I wanted to build a "clean room" implementation that prioritizes readability over performance, essentially treating the code as executable documentation.

To that end, the project has zero dependencies; I avoided LPeg to ensure it runs on a stock interpreter. It is also fully self-hosting: the compiler can compile its own source code and execute the result within its own VM.

There are a few intentional omissions, most notably the `CLOSE` instruction (and by extension, full upvalue closing semantics on scope exit). I decided that the added complexity in the Code Generator outweighed the educational value for this specific project.

I am specifically looking for feedback on simplification. My goal is to keep the project as small and approachable as possible. If you see areas where the implementation could be made cleaner without sacrificing readability, I would love to hear your thoughts.

-Daniel

[Martin Eden]

I really like style of your project.

Doing parser, compiler and runner under 5k lines of readable code
with high-level comments is achievement I admire.

-- Martin

[Bas Groothedde]

> On 21 Nov 2025, at 16:11, danielgtdavis via lua-l <lu...@googlegroups.com> wrote:
>
> Apologies for the raw HTML in the previous message.

Really impressive work, I think this is a cool resource for people trying to learn about writing fully featured programming languages. Well done!

The code is really clean and recognisable.

~b

[David Sicilia]

How does it handle garbage collection?

--
You received this message because you are subscribed to the Google Groups "lua-l" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lua-l+un...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/lua-l/803E6473-0DB2-4DC9-8458-90245DE147BD%40xoru.net.

[Rett Berg]

> How does it handle garbage collection?

It's pure-lua. My guess is it uses the underlying lua compiler for all actual values.

Running tokei on it gave 5272 lines total, 3333 of which are code and 1183 of which are comments. Nice work.

You might be interested in https://lua.civboot.org - I am working towards writing a public domain educational tech stack, which will include a lua compiler and interpreter in mostly pure-lua. Among other things, I wrote an ultra-simple parsing "grammar" library https://lua.civboot.org#Package_pegl.

The projects share some goals, I'd love to join forces.

https://github.com/civboot/civlua

Best,

Rett