# m2SQLITE — SQLite bindings for GNU Modula-2

Thin `DEFINITION MODULE FOR "C"` bindings of SQLite for `gm2`
(GCC 16 / GNU Modula-2), covering the core C API: open/close, exec,
prepare/step/finalize, bind, column access and error reporting.

Reference sources: `sqlite-master/` (SQLite 3.54.0, fossil checkout).
That folder is git-ignored (see `.gitignore`); the binding only needs
the SQLite shared library at link time.

## Status

Starter set, verified with gm2 16.0.1 + SQLite 3.46.1 (system
`libsqlite3.so.0`) on Linux:

| Module | C header | Contents |
|---|---|---|
| `SQLite` | `<sqlite3.h>` (`sqlite-master/src/sqlite.h.in`) | version, open/close, exec, errcode/errmsg, prepare/step/finalize/reset, bind_*, column_*, changes/rowid, busy_timeout, limits |
| `SQLiteUtils` (`lib/`) | — | `CStrToM2()` + `ErrMsg()`/`ErrStr()`/`LibVersionStr()`, `StaticDestr()`/`TransientDestr()`, `BindTextCopy()`/`BindBlobCopy()`, `ExecSimple()`/`ExecWithErr()` |

Custom SQL functions (`create_function`), blobs (`blob_open`),
backups and sessions come next.

## Layout

```text
m2SQLITE/
  src/            FOR "C" .def binding (SQLite)
  lib/            pure-M2 helpers (SQLiteUtils)
  tests/          gm2 smoke tests + run_tests.sh
  examples/       version, hello_db
  showcases/      showcase_all (exercises the whole binding)
  build/          generated binaries (git-ignored)
  sqlite-master/  upstream SQLite sources (git-ignored)
```

## Prerequisites

- `gm2` (tested: 16.0.1 experimental)
- SQLite runtime (`/usr/lib/x86_64-linux-gnu/libsqlite3.so.0`,
  tested: 3.46.1). The dev package (`pkg-config sqlite3`) is used
  when present but is not required.

## Build & test

```sh
make            # tests + examples + showcases -> build/
./tests/run_tests.sh
./build/examples/version
./build/examples/hello_db
./build/showcases/showcase_all
```

`make check` is `make tests` + the runner script.

Optional: build a local amalgamation from the reference tree
(takes a few minutes, needs `tclsh` + `cc`):

```sh
make local-sqlite   # -> build/sqlite/sqlite3.o
```

## Usage

```modula2
FROM SQLite IMPORT DbHandle, SQLiteOk,
   sqlite3_open, sqlite3_close;
FROM SQLiteUtils IMPORT ExecSimple, ErrMsg;
```

Compile your program with the binding search path and the C library:

```sh
gm2 -Isrc -Ilib myprog.mod lib/SQLiteUtils.mod -o myprog -lsqlite3
# without the dev package, link the runtime lib directly:
gm2 -Isrc -Ilib myprog.mod lib/SQLiteUtils.mod -o myprog \
  /usr/lib/x86_64-linux-gnu/libsqlite3.so.0
```

Notes:

- Opaque `sqlite3 *` / `sqlite3_stmt *` travel as `ADDRESS`
  (`DbHandle` / `StmtHandle`, `NIL` == `NULL`).
- `ARRAY OF CHAR` parameters map onto `char *`: string literals and
  `CHAR` arrays can be passed directly (see gm2 "Interface to C" node).
  Pass `-1` for `nByte`/`n` on NUL-terminated text.
- `VAR` handle parameters map onto `T **`: `sqlite3_open(":memory:", db)`,
  `sqlite3_prepare_v2(db, sql, -1, stmt, NIL)`.
- Optional `char **` OUT params (`errmsg`, `pzTail`) are plain
  `ADDRESS`: pass `ADR(msg)` or `NIL`.
- `bind_text`/`bind_blob` destructors: pass `VAL(ADDRESS, -1)` for
  `SQLITE_TRANSIENT` (copy) or use `BindTextCopy()`/`BindBlobCopy()`.
- `INTEGER <-> int`, `LONGINT <-> sqlite3_int64`, `REAL <-> double`
  (see gm2 "Elementary data types" node and `libc.atof`).
  Pass `INTEGER` constants through a variable before handing them
  to C varargs (`printf("%d")` garbles literal constants).

## Showcase

`showcases/showcase_all` calls every `SQLite` procedure and every
`SQLiteUtils` helper in seven sections (info, settings, errors,
prepare, binds, columns, close) and prints each result.

## Roadmap

1. `sqlite3_create_function` + value/result family (custom functions).
2. Incremental BLOB I/O (`blob_open/read/write`) + backup API.
3. Extended result codes as named constants + `sqlite3_get_table` wrapper.