qrdl/regexped repository overview

⁠Using Regexped via Docker

The regexped Docker image contains the regexped compiler and the three external tools it shells out to: wasm-merge (from Binaryen), wasm-tools and wac (both from the Bytecode Alliance). It is intended to be used as a command-line tool against a project directory mounted as a volume.

⁠Official image

The official image is published on Docker Hub as qrdl/regexped⁠:

docker pull qrdl/regexped

⁠General usage

Mount your project directory to /work and pass regexped commands as arguments:

docker run --rm -v /path/to/your/project:/work -w /work regexped \
  <command> [flags]

All paths in regexped.yaml are resolved relative to the config file, which in turn resolves relative to /work inside the container. Keep all input and output files inside the mounted directory.

⁠File ownership

You do not need --user. Everything regexped writes into the mounted directory — compiled WASM, generated stubs, a component's sibling .wit, a merged binary, --diag-json output — is handed to the user who owns the directory it lands in, and so are any directories regexped had to create along the way (stub_file: src/generated/stubs.rs creates src/ and src/generated/ owned by you, not by root).

The container runs as root because it has to: your project directory belongs to you, the kernel enforces that ownership inside the container, and a non-root container cannot create a single file in it. Root can write, and regexped then corrects the ownership of what it produced.

Passing --user $(id -u):$(id -g) anyway is still supported and still works — regexped sees a non-root uid and leaves ownership alone, which is the correct answer, because files created by that uid already belong to you.

⁠Generating stubs

docker run --rm -v /path/to/your/project:/work -w /work regexped \
  generate --config=regexped.yaml

Reads regexped.yaml, writes the stub file to the path specified by stub_file in the config (e.g. src/stubs.rs, stubs.js, stubs.go, stubs.h). The stub type is inferred from the file extension or the stub_type config field.

To write the stub to stdout:

docker run --rm -v /path/to/your/project:/work -w /work regexped \
  generate --config=regexped.yaml --output=-

⁠Compiling patterns to WASM

docker run --rm -v /path/to/your/project:/work -w /work regexped \
  compile --config=regexped.yaml

Compiles all regexp patterns in the config to a single WASM file at the path specified by wasm_file in the config.

• If the config has no output field, the module is standalone (owns its memory; load directly in JS/TS without merging).
• If the config has an output field, the module is embedded (imports memory from "main"; must be merged with a host binary).
• Under wasm_format: component the output is a component, which always owns its memory: output only names what regexped merge writes. compile also writes a sibling .wit file — the interface a consumer binds against — next to wasm_file, and uses wasm-tools, which the image includes, to wrap the core module into the component.

⁠Merging WASM modules

docker run --rm -v /path/to/your/project:/work -w /work regexped \
  merge --config=regexped.yaml --main=target/wasm32-wasip1/release/app.wasm regexps.wasm

Links the host main WASM with one or more regexp WASM artifacts into a single binary. The output path is taken from the output field in the config, or overridden with --output. The command dispatches on wasm_format: a module config is merged with wasm-merge, a component config is composed with wac plug.

All three tools are available in $PATH inside the container — no extra configuration needed:

⁠Typical workflows

⁠Rust

# 1. Generate Rust stubs
docker run --rm -v $(pwd):/work -w /work regexped \
  generate --config=regexped.yaml

# 2. Build your Rust project to WASM (outside the container — needs cargo)
cargo build --target wasm32-wasip1 --release

# 3. Compile regexp patterns to WASM
docker run --rm -v $(pwd):/work -w /work regexped \
  compile --config=regexped.yaml

# 4. Merge into a single binary
docker run --rm -v $(pwd):/work -w /work regexped \
  merge --config=regexped.yaml --main=target/wasm32-wasip1/release/app.wasm regexps.wasm

⁠Go

# 1. Generate Go stubs
docker run --rm -v $(pwd):/work -w /work regexped \
  generate --config=regexped.yaml

# 2. Compile regexp patterns to WASM
docker run --rm -v $(pwd):/work -w /work regexped \
  compile --config=regexped.yaml

# 3. Build your Go project to WASM (outside the container — needs Go)
GOOS=wasip1 GOARCH=wasm go build -o app.wasm .

# 4. Merge into a single binary
docker run --rm -v $(pwd):/work -w /work regexped \
  merge --config=regexped.yaml --main=app.wasm regexps.wasm

⁠Rust, as a component

The config sets wasm_format: component (and a wit_package). The guest is a wasip2 component, and merge composes it with the regexp component using wac:

# 1. Generate the Rust component stub
docker run --rm -v $(pwd):/work -w /work regexped \
  generate --config=regexped.yaml

# 2. Build your Rust project as a component (outside the container — needs cargo
#    and the wasm32-wasip2 target; the stub needs the wit-bindgen crate)
cargo build --target wasm32-wasip2 --release

# 3. Compile regexp patterns to a component plus its sibling .wit
docker run --rm -v $(pwd):/work -w /work regexped \
  compile --config=regexped.yaml

# 4. Compose the two into one component (wac)
docker run --rm -v $(pwd):/work -w /work regexped \
  merge --config=regexped.yaml --main=target/wasm32-wasip2/release/app.wasm regexps.wasm

# 5. Run it (outside the container)
wasmtime run composed.wasm

⁠JavaScript / TypeScript (no merge needed)

# 1. Compile regexp patterns to WASM (standalone mode — no output field in config)
docker run --rm -v $(pwd):/work -w /work regexped \
  compile --config=regexped.yaml

# 2. Generate JS/TS stub
docker run --rm -v $(pwd):/work -w /work regexped \
  generate --config=regexped.yaml

Load the compiled WASM directly in your JS/TS code:

await init(await fetch('./regexps.wasm').then(r => r.arrayBuffer()));