Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 51 additions & 10 deletions .agents/plans/A12-readme-changelog.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
---
id: A12
title: Update README and CHANGELOG for 0.5.0
title: Update README and CHANGELOG for 1.0.0-rc.1
issue: 173
pr: null
pr: 201
branch: docs/0-5-0
base: main
status: ready
status: review
direction: A
blocked_on: [A14, A15, A16]
---

## Goal

Refresh user-facing docs to reflect the new VM. The current README still
references Luerl as the backend, which is no longer true.
Refresh user-facing docs to reflect the new VM and bump the version to
`1.0.0-rc.1`. The VM rewrite (Luerl → Elixir-native) is significant
enough to warrant the major version bump; cutting an `rc` first leaves
room to catch regressions before locking in 1.0 final.

## Out of scope

Expand All @@ -24,15 +26,19 @@ references Luerl as the backend, which is no longer true.

## Success criteria

- [ ] `README.md` accurately describes the new VM (no Luerl references).
- [ ] `CHANGELOG.md` has a `0.5.0` section summarizing:
- [ ] `README.md` accurately describes the new VM (no Luerl references
except a historical note in Credits).
- [ ] `CHANGELOG.md` has a `1.0.0-rc.1` section summarizing:
- VM rewrite (Luerl → Elixir-native)
- Performance improvements (PRs #143, #153–#156)
- Lua 5.3 suite pass rate
- Behavioral differences from 0.4 (sandbox model, encoding, error format)
- Behavioral differences from 0.4 (encoded value tags, error format,
integer wrapping, MFA encoding removed)
- Bug fixes referenced by PR/issue.
- [ ] `mix.exs` `@version` bumped to `1.0.0-rc.1`.
- [ ] Doctests in `lib/lua.ex` still pass (running on the new VM).
- [ ] `mix docs` builds cleanly without warnings.
- [ ] `mix docs` does not introduce new warnings (pre-existing warnings
about hidden modules are out of scope).

## Implementation notes

Expand Down Expand Up @@ -73,4 +79,39 @@ mix docs

## Discoveries

(populated during implementation)
- **Version**: framing this as `0.5.0` undersells the magnitude of the VM
rewrite. After discussion the version was bumped to `1.0.0-rc.1` —
pre-release leaves room to catch regressions before locking 1.0 final
while still signaling that this is a major release.
- `mix docs` emits 6 pre-existing warnings on `main` (references to hidden
modules `Lua.CompilerException`, `Lua.Compiler.Scope.State`). These are
about code visibility, not docs content, so they're out of scope for a
README/CHANGELOG plan. This PR does not introduce new warnings.
- ROADMAP said 4/24 suite files passing; the actual count is 5/29
(`simple_test.lua`, `api.lua`, `bitwise.lua`, `code.lua`, `vararg.lua`
— `bitwise.lua` was added as ready in #198/#199). ROADMAP updated.
- The `{module(), atom(), list()}` MFA encoding form is no longer accepted
by `Lua.encode!/2` in the new VM. Documented in the CHANGELOG's Removed
section.

## What changed

Files touched:
- `README.md` — rewrote tagline, Features list, encoding/decoding table
rows, and Credits section. No more Luerl claims in user-facing copy
(only a historical reference in Credits).
- `CHANGELOG.md` — new `[v1.0.0-rc.1]` entry covering Added / Changed /
Removed / Performance / Fixed; updated link refs.
- `mix.exs` — `@version` bumped from `0.4.0` to `1.0.0-rc.1`.
- `ROADMAP.md` — milestone names updated (`0.5.0` → `1.0.0`,
`0.5.x` → `1.0.x`); stale 4/24 suite count corrected to 5/29; current
unit test count updated.
- `.agents/plans/A13-release-rc1.md` — retitled and rebranched to
`1.0.0-rc.1`; success criteria updated to reflect that A12 already
bumped `mix.exs` and seeded the CHANGELOG entry.

Suite delta: none — pure docs/release-prep PR.

Tests: 1420 passing, 0 failing, 31 skipped (unchanged).

PR: #201.
37 changes: 22 additions & 15 deletions .agents/plans/A13-release-rc1.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,39 @@
---
id: A13
title: Cut 0.5.0-rc.1
title: Cut 1.0.0-rc.1
issue: 174
pr: null
branch: release/0-5-0-rc-1
branch: release/1-0-0-rc-1
base: main
status: blocked
direction: A
---

## Goal

Publish `0.5.0-rc.1` to Hex.pm. This is the final plan in Direction A and
gates on the rest of the milestone closing.
Publish `1.0.0-rc.1` to Hex.pm. This is the final plan in Direction A and
gates on the rest of the milestone closing. The major version bump
reflects the magnitude of the VM rewrite (Luerl → Elixir-native) and a
commitment to public API stability.

## Out of scope

- New features (must be in by now or wait for 0.5.0 final).
- Documentation rewrites beyond what A12 ships.
- New features (must be in by now or wait for 1.0.0 final).
- Documentation rewrites beyond what A12 ships (note: A12 already bumps
`mix.exs` and writes the CHANGELOG entry — this plan only needs to
date the entry, tag, and publish).

## Success criteria

- [ ] `mix.exs` `@version` bumped to `0.5.0-rc.1`.
- [ ] `CHANGELOG.md` has a `0.5.0-rc.1` section dated and entry-listed.
- [ ] All `0.5.0` milestone issues closed or moved to `0.5.x`.
- [ ] `mix test` passes (≥ 1273)
- [ ] `mix test --only lua53` passes ≥ 12/24 files (target)
- [ ] `mix docs` builds cleanly.
- [ ] Tag created: `git tag v0.5.0-rc.1`
- [ ] Pushed: `git push origin v0.5.0-rc.1`
- [x] `mix.exs` `@version` bumped to `1.0.0-rc.1` (done in A12 / PR #201).
- [x] `CHANGELOG.md` has a `1.0.0-rc.1` section (done in A12 / PR #201).
- [ ] CHANGELOG entry's date is the actual publish date.
- [ ] All `1.0.0` milestone issues closed or moved to `1.0.x`.
- [ ] `mix test` passes (≥ 1420).
- [ ] `mix test --only lua53` passes (target: improve on 5/29).
- [ ] `mix docs` does not introduce new warnings.
- [ ] Tag created: `git tag v1.0.0-rc.1`
- [ ] Pushed: `git push origin v1.0.0-rc.1`
- [ ] Published: `mix hex.publish` (manual; pre-release flag).

## Blocked on
Expand Down Expand Up @@ -59,9 +64,11 @@ mix hex.build

## Risks

- Pre-release semver (`0.5.0-rc.1`) may not be visible by default in Hex
- Pre-release semver (`1.0.0-rc.1`) may not be visible by default in Hex
resolvers; the user should know.
- Anything broken in the doctest set will break `mix hex.publish`.
- Going to 1.0 commits to API stability. Any breaking change after this
requires a 2.0.

## Discoveries

Expand Down
83 changes: 82 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased


## [v1.0.0-rc.1] - 2026-05-06

This is the first release candidate for `1.0.0`. The library has been
rewritten on a new Elixir-native Lua 5.3 virtual machine, and the public
API is intended to be stable. Please report any regressions before final.

### Added
- New Elixir-native Lua 5.3 virtual machine: lexer, parser, compiler, and
register-based executor, with no Erlang or C dependencies.
- Standard library: `string` (including `string.format` width/precision and
the full pattern engine for `find`/`match`/`gmatch`/`gsub`), `table`,
`math`, `debug`, `io` stubs, `os` (sandboxed), `package`/`require`.
- `_G` global table and Lua 5.3 `_ENV` semantics for global access.
- Full metamethod dispatch: `__index`, `__newindex`, `__call`, plus the
arithmetic, comparison, length, concat, and `tostring` metamethods.
- Varargs (`...`), multiple returns, generic `for`, `goto`/`label`, `break`,
protected calls (`pcall`, `xpcall`).
- `userdata` support for passing arbitrary Elixir terms across the boundary.
- Beautiful Lua-style stack traces and error messages with source line
tracking.
- Lua 5.3 official test suite integration (5/29 files passing on this
release: `simple_test.lua`, `api.lua`, `bitwise.lua`, `code.lua`,
`vararg.lua`).
- Benchmark harness comparing against Luerl and PUC-Lua.

### Changed
- **VM backend**: Luerl is no longer a runtime dependency. The library now
runs on its own Elixir-native VM. Luerl is kept only as a `:benchmark`-env
dependency for performance comparison.
- Encoded value tags now use the new VM's internal representation:
`{:tref, integer()}` for tables (replacing `:luerl.tref()`), `{:udref,
integer()}` for userdata (replacing `:luerl.usdref()`), `{:native_func,
fun}` for Elixir-defined Lua callables (replacing `:luerl.erl_func()`),
and `{:lua_closure, _, _}` for compiled Lua functions.
- Parser error messages have a new format. The old Luerl-style
`"Line 1: syntax error before: ';'"` is now produced by the new parser
(e.g. `"Expected expression"`); user-visible string contents differ.
- Chunks no longer require a separate "load" step — `Lua.Chunk` now holds a
compiled prototype and is reusable across `Lua.eval!/2` calls.
- 64-bit integer arithmetic and bitwise ops wrap on overflow per Lua 5.3
§3.4.1, instead of widening to bignums (Luerl's behaviour).

### Removed
- The `{module(), atom(), list()}` MFA encoding form is no longer accepted
by `Lua.encode!/2`. Use a function literal or a `deflua` callback
instead.

### Performance
- Right-size register tuple allocations (#153).
- O(N²) → O(N) upvalue collection in the closure handler (#154).
- O(1) upvalue access by storing upvalues as a tuple (#155).
- Fully tail-recursive CPS executor with line tracking moved off the heap
(#156).

### Fixed
- 64-bit integer overflow wrapping for arithmetic and bitwise ops (#177).
- Empty/missing-key table reads now return `nil` per Lua 5.3 §3.4.11
(#179, #200).
- Long-string `[[ ... ]]` lexer handles embedded `]` and bracket levels
like `[==[ ... ]==]`, including `main.lua`-style headers (#180).
- Comment tokens no longer leak past the lexer in expression lists (#182).
- Stdlib modules are pre-populated in `package.loaded` so `require"io"`
resolves (#184); module sentinel is set before executing required
modules (#191).
- For-loop variable now binds per statement, fixing register reuse (#195).
- Closure-handler crash on missing upvalue cells in `get_open_upvalue` and
`set_open_upvalue` (#196).
- `_ENV` semantics for global variable access (#197).
- Hex literal and string coercion in bitwise ops (#198); `math.fmod`
implemented for `bitwise.lua` verification (#199).
- Function declaration assigned to in-scope local rather than shadowing
it (#185).
- Multi-return expansion no longer overflows the register tuple (#189).
- Pattern engine threads VM state through `gsub` callbacks and preserves
capture order (#188, #190).
- Atom values encode to strings (#158).
- Files containing only comments load successfully.
- Unicode characters supported in Lua scripts.

## [v0.4.0] - 2025-12-06

### Changed
Expand Down Expand Up @@ -62,7 +141,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Upgrade to Luerl 1.4.1
- Tables must now be explicitly decoded when receiving as arguments `deflua` and other Elixir callbacks

[unreleased]: https://github.com/tv-labs/lua/compare/v0.3.0...HEAD
[unreleased]: https://github.com/tv-labs/lua/compare/v1.0.0-rc.1...HEAD
[1.0.0-rc.1]: https://github.com/tv-labs/lua/compare/v0.4.0...v1.0.0-rc.1
[0.4.0]: https://github.com/tv-labs/lua/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/tv-labs/lua/compare/v0.2.1...v0.3.0
[0.2.1]: https://github.com/tv-labs/lua/compare/v0.2.0...v0.2.1
[0.2.0]: https://github.com/tv-labs/lua/compare/v0.1.1...v0.2.0
Expand Down
60 changes: 36 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,27 @@

<!-- MDOC !-->

`Lua` is an ergonomic interface to [Luerl](https://github.com/rvirding/luerl), aiming to be the best way to use Luerl from Elixir.
`Lua` is an Elixir-native Lua 5.3 virtual machine. It runs Lua code on the BEAM
with no Erlang or C dependencies, and exposes an ergonomic Elixir API for
embedding Lua scripting in your application.

## Features

* `~LUA` sigil for validating Lua code at compile-time
* Pure-Elixir implementation of Lua 5.3 — lexer, parser, register-based VM,
and standard library — running directly on the BEAM
* `~LUA` sigil for validating (and optionally pre-compiling) Lua code at
compile time
* `deflua` macro for exposing Elixir functions to Lua
* Improved error messages and sandboxing
* Deep setting/getting variables and state
* Excellent documentation and guides for working with Luerl
* Beautiful error messages and stack traces
* Sandboxing of stdlib paths
* Deep setting/getting of variables and state from Elixir
* Pattern-matching, metatables, varargs, multiple returns, `_G`/`_ENV`,
`string`/`table`/`math`/`debug` libraries, and the `string.find`/`match`/
`gmatch`/`gsub` pattern engine

> #### Lua the Elixir library vs Lua the language {: .info}
> When referring to this library, `Lua` will be stylized as a link.
>
>
> References to Lua the language will be in plaintext and not linked.

## Executing Lua
Expand Down Expand Up @@ -162,23 +170,22 @@ This allows you to have simple, expressive APIs that access context that is unav

## Encoding and Decoding data

When working with `Lua`, you may want inject data of various types into the runtime. Some values, such as integers, have the same representation inside of the runtime as they do in Elixir, they do not require encoding. Other values, such as maps, are represented inside of `Lua` as tables, and must be encoded first. Values not listed are not valid and cannot be encoded by `Lua` and Luerl, however, they can be passed using a `{:userdata, any()}` tuple and encoding them.

Values may be encoded with `Lua.encode!/2`

Elixir type | Luerl type | Requires encoding?
:-------------------------- | :------------------------ | :---------------------
`nil` | `nil` | no
`boolean()` | `boolean()` | no
`number()` | `number()` | no
`binary()` | `binary()` | no
`atom()` | `binary()` | yes
`map()` | `:luerl.tref()` | yes
`{:userdata, any()}` | `:luerl.usdref()` | yes
`(any()) -> any()` | `:luerl.erl_func()` | yes
`(any(), Lua.t()) -> any()` | `:luerl.erl_func()` | yes
`{module(), atom(), list()` | `:luerl.erl_mfa()` | yes
`list(any())` | `list(luerl type)` | maybe (if any of its values require encoding)
When working with `Lua`, you may want to inject data of various types into the runtime. Some values, such as integers, have the same representation inside the VM as they do in Elixir and do not require encoding. Other values, such as maps, are represented inside the VM as tables and must be encoded first. Arbitrary Elixir terms can be passed across the boundary using a `{:userdata, any()}` tuple.

Values may be encoded with `Lua.encode!/2`.

Elixir type | Internal VM type | Requires encoding?
:-------------------------- | :-------------------------- | :---------------------
`nil` | `nil` | no
`boolean()` | `boolean()` | no
`number()` | `number()` | no
`binary()` | `binary()` | no
`atom()` | `binary()` | yes
`map()` | `{:tref, integer()}` | yes
`{:userdata, any()}` | `{:udref, integer()}` | yes
`(any()) -> any()` | `{:native_func, fun}` | yes
`(any(), Lua.t()) -> any()` | `{:native_func, fun}` | yes
`list(any())` | `list(VM type)` | maybe (if any of its values require encoding)


## Userdata
Expand All @@ -202,4 +209,9 @@ Trying to deference userdata inside a Lua program will result in an exception.

## Credits

`Lua` piggy-backs off of Robert Virding's [Luerl](https://github.com/rvirding/luerl) project, which implements a Lua lexer, parser, and full-blown Lua virtual machine that runs inside the BEAM.
`Lua` started as an ergonomic Elixir wrapper around Robert Virding's
[Luerl](https://github.com/rvirding/luerl) project. As of `1.0.0` this library
is a full Elixir-native reimplementation of the Lua 5.3 lexer, parser, and
virtual machine, with a public API designed to feel idiomatic from Elixir.
Luerl deserves credit as the prior art that made this possible — its design
informed many of the decisions in the new VM, and we benchmark against it.
26 changes: 16 additions & 10 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@ This is the strategic overview. For per-PR detail, see [`.agents/plans/`](.agent

## Status: 2026-05-06

- **Unit tests**: 1,369 passing, 0 failing, 36 skipped.
- **Lua 5.3 official suite**: 4/24 files passing (`simple_test.lua`, `api.lua`, `code.lua`, `vararg.lua`).
- **Current focus**: [Direction A — Suite Triage](#in-flight-direction-a--suite-triage-milestone-050).
- **Unit tests**: 1,420 passing, 0 failing, 31 skipped.
- **Lua 5.3 official suite**: 5/29 files passing (`simple_test.lua`,
`api.lua`, `bitwise.lua`, `code.lua`, `vararg.lua`).
- **Current focus**: [Direction A — Suite Triage](#in-flight-direction-a--suite-triage-milestone-100).

## Done

Expand All @@ -30,10 +31,15 @@ The new Elixir-native VM (replacing Luerl) is built up through:
- O(1) upvalue access by storing upvalues as a tuple (PR #155).
- Fully tail-recursive CPS executor with line tracking off heap (PR #156).

## In flight: Direction A — Suite Triage (milestone `0.5.0`)
## In flight: Direction A — Suite Triage (milestone `1.0.0`)

**Goal**: push the official Lua 5.3 test suite from 4/24 to ≥ 12/24 passing files,
without regressing unit tests, then cut `0.5.0-rc.1`.
**Goal**: push the official Lua 5.3 test suite from 5/29 to a healthier
pass rate, without regressing unit tests, then cut `1.0.0-rc.1`.

The version jump from `0.4` to `1.0` reflects the magnitude of the VM
rewrite (Luerl is no longer a runtime dependency) and a commitment to
public API stability. Cutting an `rc` first leaves room to catch
regressions before locking 1.0 final.

Per-PR plans live in [`.agents/plans/A*.md`](.agents/plans). Issues track them
under the [`0.5.0` milestone](https://github.com/tv-labs/lua/milestone/1).
Expand Down Expand Up @@ -63,10 +69,10 @@ under the [`0.5.0` milestone](https://github.com/tv-labs/lua/milestone/1).

- ~~**A11**: Clear in-source TODOs (`compiler.ex:34`, `compiler_exception.ex:27`,
`stdlib.ex:412`).~~ Shipped in PR #194.
- **A12**: README and CHANGELOG for 0.5.0.
- **A13**: Cut `0.5.0-rc.1` (blocked on the rest).
- **A12**: README and CHANGELOG for 1.0.0-rc.1.
- **A13**: Cut `1.0.0-rc.1` (blocked on the rest).

## Next: Direction B — Performance (milestone `0.5.x`)
## Next: Direction B — Performance (milestone `1.0.x`)

Several B-direction wins shipped already (PRs #153–#156). What remains:

Expand All @@ -78,7 +84,7 @@ Several B-direction wins shipped already (PRs #153–#156). What remains:
Per-PR plans land in [`.agents/plans/B*.md`](.agents/plans) when Direction A
wraps.

## Deferred (intentional, not in 0.5)
## Deferred (intentional, not in 1.0)

- **Coroutines** (`coroutine.lua`) — full continuation/process model, weeks of work.
- **Garbage collection / weak tables** (`gc.lua`).
Expand Down
Loading
Loading