You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
44 lines
2.3 KiB
44 lines
2.3 KiB
# `a`
|
|
|
|
A Swiss army knife for everyday hacks. `a` embeds a Lua interpreter and wraps it in a rich standard library and real IO access, so a small script can reach the network, a database, the filesystem, and the terminal without any setup.
|
|
|
|
```sh
|
|
a file.lua
|
|
```
|
|
|
|
That's the whole interface. The script is the program.
|
|
|
|
## What it is
|
|
|
|
`a` is not a Lua implementation; it embeds [Lua 5.5](https://www.lua.org/) (via [`mlua`](https://github.com/mlua-rs/mlua)) and adds the parts stock Lua leaves out. Plain Lua is small and pleasant but ships almost no standard library and no way to talk to the outside world without C modules and a build toolchain. `a` fills that in with a standard library built partly in Rust and partly in Lua, plus the IO access that makes scripts actually useful.
|
|
|
|
The result is a single binary you point at a `.lua` file. No package manager, no build step, no project scaffolding, just a script and the tools it needs to do real work.
|
|
|
|
## The standard library
|
|
|
|
This is the point of `a`. Planned surface:
|
|
|
|
- **Networking** — HTTP client, WebSocket, and MQTT (3.1.1 and 5), with high-level APIs.
|
|
- **SQLite** — a real embedded database one call away.
|
|
- **Filesystem** — ergonomic read/write/glob/walk, without the ceremony of stock Lua's `io`.
|
|
- **Terminal UI** — interactive line and full-screen TUI in the spirit of `ncurses`, but without the awkwardness.
|
|
|
|
Each should feel native: the common case is one obvious call, not a setup ritual.
|
|
|
|
## How it works
|
|
|
|
- Embeds Lua 5.5 via `mlua`, on an async core ([`tokio`](https://tokio.rs/)) so IO-heavy scripts don't block.
|
|
- A single self-contained binary. No LuaRocks, no make, no virtualenv.
|
|
- Scripts run in a **sandboxed** environment modeled on [Luau's safe environment](https://luau.org/sandbox): `io`, `package`, and `debug` are not loaded; `os` is trimmed to its time functions; the bytecode/chunk-loading escape hatches (`load`, `loadfile`, `dofile`, `string.dump`) are removed. The library `a` provides is the sanctioned way to reach the outside world.
|
|
- A leading `#!` shebang line is skipped, so scripts can be made executable directly.
|
|
|
|
## Building
|
|
|
|
```sh
|
|
cargo build --release
|
|
# binary at target/release/a
|
|
|
|
cargo run -- lua/test.lua # run a script during development
|
|
```
|
|
|
|
Requires a Rust toolchain (2024 edition). Lua is vendored and built from source, so no system Lua is needed.
|
|
|