summaryrefslogtreecommitdiff
path: root/src/kinds
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-06 15:58:05 -0300
committerGabriel Schneider <[email protected]>2026-11-06 17:53:43 -0300
commit31c77aa3f259e99a9723e188b77b651e5cd31621 (patch)
tree062567bcf58d4b66e26ea2ec8b048a0128793980 /src/kinds
parent0706014591cf4af3ee2ed08890675956fb771cc8 (diff)
downloadpardes-31c77aa3f259e99a9723e188b77b651e5cd31621.tar.gz
pardes-31c77aa3f259e99a9723e188b77b651e5cd31621.zip
kinds #34, ABI 3 (§17.8) and the Zig module's final surface (§17.6): tick takes a pa_tick and gives the next step and the tag's prefix, which leaves pa_paint; a kind's view(st, pa_view) is told each view by id, pa_window says which view paint is for and whether it shows glyph art, a key and a click the view they came from (in pa_key's and pa_mouse's padding, what §17 left out), pa_api loses view and gains cancel and found (search returns nothing), the head's flags say PA_PICTURES, PA_RASTER_MAX and PA_RECORD_MAX bound a picture and a record (no ask-again), 2.x is refused; addon.zig wraps every pa_ops function and pa_api call (heap as an Allocator, typed Mouse, Key and View, Color.rgb, an optional prefix(s, writer) after every tick, body_max) and refuses at compile time a word for a pane without ctl and a name over 15 bytes
Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'src/kinds')
-rw-r--r--src/kinds/addon.zig218
-rw-r--r--src/kinds/pardes_addon.h185
2 files changed, 273 insertions, 130 deletions
diff --git a/src/kinds/addon.zig b/src/kinds/addon.zig
index 41b431ea..804630ee 100644
--- a/src/kinds/addon.zig
+++ b/src/kinds/addon.zig
@@ -1,11 +1,24 @@
//! A kind of pane in Zig: what an addon imports beside the C ABI it is
//! built to (pardes_addon.h, translated: `c`), which stays the contract.
//! It imports nothing of the core. A kind is a struct whose `head` names
-//! it and whose functions are any of `open`, `paint` (required), `tick`,
-//! `key`, `body`, `ctlRead`, `jobRun`, `jobDone`, `dump` and `load`, each
-//! over a `*T` that `open` is handed zeroed (its defaults set) in the
-//! pane's arena; pa_ops's others (mouse, ctl, address, where, search,
-//! close) no kind here has needed yet:
+//! it and whose functions are any of pa_ops's, each over a `*T` that
+//! `open` is handed zeroed (its defaults set) in the pane's arena: `open`,
+//! `close`, `tick`, `prefix`, `paint` (required), `view`, `key`, `mouse`,
+//! `body`, `address`, `where`, `ctl`, `ctlRead`, `jobRun`, `jobDone`,
+//! `dump`, `load` and `search`, with these types:
+//!
+//! open(s, path: ?[]const u8, bytes: ?[]const u8) void
+//! tick(s, now: u64, flags: Flags) u64 the next step's time, 0 none
+//! prefix(s, w: *Writer) !void its tag's start, after every tick
+//! paint(s, Window, Paint) void view(s, View) void
+//! key(s, Key) bool mouse(s, Mouse) bool address(s, text) bool
+//! body, where, ctlRead(s, w: *Writer) !void ctl(s, line, reply: *Writer) bool
+//! jobRun(in, Allocator) ?[]u8 jobDone(s, token, out) void
+//! dump(s, buf) usize load(s, bytes, version) bool search(s, pat) void
+//!
+//! and pardes's side (pa_api) as the functions below: `arena` and `heap`
+//! as Allocators, `seed`, `say`, `job`, `cancel`, `look`, `text`, `exec`,
+//! `select` and `found`. A body is at most `body_max` bytes.
//!
//! export const pardes_addon = addon.ops(Snake);
//!
@@ -16,15 +29,16 @@ pub const c = @import("pardes_addon");
const Allocator = std.mem.Allocator;
/// The ABI this file speaks: a header of another needs it brought along.
-pub const abi = 0x20002;
+pub const abi = 0x30000;
comptime {
- if (c.PA_ABI != abi) @compileError("addon.zig speaks ABI 2.2 and the header another");
+ if (c.PA_ABI != abi) @compileError("addon.zig speaks ABI 3.0 and the header another");
}
/// A word the kind brings: `opens` a pane of it, else goes to the pane's
/// `ctl`; `leader` is the keys after Space that run it ("ng": SPC n g).
pub const Word = struct { name: [:0]const u8, leader: ?[:0]const u8 = null, arg: enum(u8) { none, optional, required } = .none, opens: bool = false, doc: [:0]const u8 = "" };
-pub const Head = struct { name: []const u8, version: u32, exts: [:0]const u8 = "", words: []const Word = &.{} };
+/// `pictures`: its panes place pictures, and their tag says how they show.
+pub const Head = struct { name: []const u8, version: u32, exts: [:0]const u8 = "", words: []const Word = &.{}, pictures: bool = false };
/// pardes's side, kept from init: about the pane of the current call.
pub var api: *const c.pa_api = undefined;
@@ -35,6 +49,17 @@ pub const arena: Allocator = .{ .ptr = undefined, .vtable = &.{ .alloc = arenaAl
fn arenaAlloc(_: *anyopaque, n: usize, a: std.mem.Alignment, _: usize) ?[*]u8 {
return if (a.toByteUnits() > 16) null else @ptrCast(api.alloc.?(n));
}
+/// pardes's heap: memory that outlives a call, from any thread.
+pub const heap: Allocator = .{ .ptr = undefined, .vtable = &.{ .alloc = heapAlloc, .resize = Allocator.noResize, .remap = heapRemap, .free = heapFree } };
+fn heapAlloc(_: *anyopaque, n: usize, a: std.mem.Alignment, _: usize) ?[*]u8 {
+ return if (a.toByteUnits() > 16) null else @ptrCast(api.heap.?(null, n));
+}
+fn heapRemap(_: *anyopaque, m: []u8, _: std.mem.Alignment, n: usize, _: usize) ?[*]u8 {
+ return @ptrCast(api.heap.?(m.ptr, n));
+}
+fn heapFree(_: *anyopaque, m: []u8, _: std.mem.Alignment, _: usize) void {
+ _ = api.heap.?(m.ptr, 0);
+}
/// A job's (`pa_out`): freed after its job_done, the last its answer.
fn jobAlloc(ctx: *anyopaque, n: usize, a: std.mem.Alignment, _: usize) ?[*]u8 {
const out: *c.pa_out = @ptrCast(@alignCast(ctx));
@@ -45,16 +70,38 @@ fn jobAlloc(ctx: *anyopaque, n: usize, a: std.mem.Alignment, _: usize) ?[*]u8 {
pub fn seed() u64 {
return api.seed.?();
}
-
/// A message on the pane; an error also refuses an `open`.
-pub fn say(text: []const u8, how: enum { note, err }) void {
- api.say.?(text.ptr, @intCast(text.len), @backingInt(how));
+pub fn say(text_: []const u8, how: enum { note, err }) void {
+ api.say.?(text_.ptr, @intCast(text_.len), @backingInt(how));
}
-
/// `jobRun` over a copy of `in` on a worker: its token, 0 when refused.
pub fn job(in: []const u8) u32 {
return api.job.?(in.ptr, @intCast(in.len));
}
+/// A job's answer not yet come dropped.
+pub fn cancel(token: u32) void {
+ api.cancel.?(token);
+}
+/// Looked at as a click would: a URL, `file:12`, a word.
+pub fn look(text_: []const u8) void {
+ api.look.?(text_.ptr, @intCast(text_.len));
+}
+/// Run as a middle click would.
+pub fn exec(text_: []const u8) void {
+ api.exec.?(text_.ptr, @intCast(text_.len));
+}
+/// What the pane has selected now; empty, none.
+pub fn select(text_: []const u8) void {
+ api.select.?(text_.ptr, @intCast(text_.len));
+}
+/// `place text` rows onto the pane's +Search, from `search` or later.
+pub fn found(rows: []const u8) void {
+ api.found.?(rows.ptr, @intCast(rows.len));
+}
+/// A new text pane `name` holding `bytes`: its serial, 0 if none.
+pub fn text(name: []const u8, bytes: []const u8) u32 {
+ return api.text.?(name.ptr, @intCast(name.len), bytes.ptr, @intCast(bytes.len));
+}
pub const Color = enum(u32) {
default = c.PA_DEFAULT,
@@ -63,22 +110,31 @@ pub const Color = enum(u32) {
pub fn index(n: u8) Color {
return @fromBackingInt(@intCast(0x02000000 | @as(u32, n)));
}
+ pub fn rgb(r: u8, g: u8, b: u8) Color {
+ return @fromBackingInt(@as(u32, r) << 16 | @as(u32, g) << 8 | b);
+ }
};
pub const Attrs = packed struct(u16) { bold: bool = false, dim: bool = false, italic: bool = false, _3: bool = false, reverse: bool = false, _5: u3 = 0, underline: bool = false, _9: u7 = 0 };
pub const Style = struct { fg: Color = .default, bg: Color = .default, attrs: Attrs = .{} };
-/// The pane's body as `paint` sees it, every cell unpainted.
+/// The pane's body in one view as `paint` sees it, every cell unpainted.
pub const Window = struct {
cells: [*]c.pa_cell,
stride: u32,
cols: u16,
rows: u16,
+ cell_w: u16,
+ cell_h: u16,
focused: bool,
+ /// The view painted (View.id), and whether it shows pictures as glyph art.
+ view: u8,
+ glyphs: bool,
- /// `text` (UTF-8) from column x of row y on, a character a cell, cut at the edge.
- pub fn put(w: Window, x: usize, y: usize, text: []const u8, style: Style) void {
+ /// `text` (UTF-8) from column x of row y on, a character a cell, cut at
+ /// the edge: column first, where the header's pa_put is row first.
+ pub fn put(w: Window, x: usize, y: usize, text_: []const u8, style: Style) void {
if (y >= w.rows) return;
- var it: std.unicode.Utf8Iterator = .{ .bytes = text, .i = 0 };
+ var it: std.unicode.Utf8Iterator = .{ .bytes = text_, .i = 0 };
var col = x;
while (it.nextCodepointSlice()) |ch| : (col += 1) {
if (col >= w.cols) return;
@@ -90,14 +146,10 @@ pub const Window = struct {
}
};
-/// What `paint` hands back beside the cells.
+/// What `paint` hands back beside the cells; `out`'s at, span and pointer
+/// as the header has them.
pub const Paint = struct {
out: *c.pa_paint,
- /// The start of the pane's tag; the kind's name when none.
- pub fn prefix(p: Paint, comptime fmt: []const u8, args: anytype) void {
- const t: []const u8 = std.fmt.bufPrint(&p.out.prefix, fmt, args) catch &p.out.prefix;
- p.out.prefix_len = @intCast(t.len);
- }
/// A picture over the cells (pa_placement), lowest first.
pub fn place(p: Paint, at: c.pa_placement) void {
if (p.out.n == p.out.cap) return;
@@ -106,12 +158,29 @@ pub const Paint = struct {
}
};
-/// A key: a codepoint (`char('h')`), or one of these.
+/// A view of the pane (pa_view): `id` 1 and up, `cols` 0 when it stops.
+pub const View = extern struct { cols: u16, rows: u16, cell_w: u16, cell_h: u16, fg: Color, bg: Color, sel: Color, link: Color, dpi: u16, max_px: u16, fill: bool, glyphs: bool, id: u8, _: u8 = 0 };
+/// A key: a codepoint (`char('h')`), or one of these; `view` it came from.
pub const Code = enum(u32) { tab = 0x09, enter = 0x0D, esc = 0x1B, backspace = 0x7F, up = 0xF0001, down, left, right, home, end, page_up, page_down, delete, _ };
-pub const Key = struct { code: Code, ctrl: bool = false, alt: bool = false, shift: bool = false };
+pub const Key = extern struct { code: Code, ctrl: bool = false, alt: bool = false, shift: bool = false, view: u8 = 0 };
pub fn char(comptime ch: u21) Code {
return @fromBackingInt(@intCast(ch));
}
+/// A pointer event at a cell of view `view`'s window (pa_mouse).
+pub const Mouse = extern struct {
+ button: enum(u8) { left, middle, right, wheel_up, wheel_down, wheel_left, wheel_right, _ },
+ action: enum(u8) { press, release, motion, drag, _ },
+ ctrl: bool,
+ shift: bool,
+ alt: bool,
+ view: u8,
+ col: u16,
+ row: u16,
+ amount: f32,
+};
+comptime {
+ if (@sizeOf(View) != @sizeOf(c.pa_view) or @sizeOf(Key) != @sizeOf(c.pa_key) or @sizeOf(Mouse) != @sizeOf(c.pa_mouse)) @compileError("addon.zig's records are not the header's");
+}
/// tick's flags.
pub const Flags = packed struct(u32) { focused: bool, framed: bool, _: u30 };
@@ -141,7 +210,8 @@ pub const Deadline = extern struct {
/// versions: `pub const dump = addon.dumpBytes;` and `load = addon.loadBytes`.
pub fn dumpBytes(s: anytype, buf: []u8) usize {
const b = std.mem.asBytes(s);
- if (b.len <= buf.len) @memcpy(buf[0..b.len], b);
+ if (b.len > buf.len) return 0;
+ @memcpy(buf[0..b.len], b);
return b.len;
}
pub fn loadBytes(s: anytype, bytes: []const u8, version: u32) bool {
@@ -151,6 +221,14 @@ pub fn loadBytes(s: anytype, bytes: []const u8, version: u32) bool {
return true;
}
+/// The most a body holds: past it, it is cut (said once in Debug).
+pub const body_max = 4096;
+var body_cut = false;
+
+fn span(p: [*c]const u8, n: u64) []const u8 {
+ return if (p == null) "" else p[0..n];
+}
+
/// A kind's `pa_ops`: its head, and a C function for each of its own.
pub fn ops(comptime T: type) c.pa_ops {
const F = struct {
@@ -162,73 +240,115 @@ pub fn ops(comptime T: type) c.pa_ops {
fn self(st: ?*anyopaque) ?*T {
return @ptrCast(@alignCast(st));
}
+ /// What `f(s, writer)` writes into `buf[0..n]`: its length.
+ fn write(comptime f: anytype, s: anytype, buf: [*c]u8, n: usize) u32 {
+ var w: std.Io.Writer = .fixed(buf[0..n]);
+ f(s, &w) catch {};
+ return @intCast(w.end);
+ }
fn init(a: [*c]const c.pa_api) callconv(.c) c_int {
api = a;
return c.PA_OK;
}
- fn open(_: [*c]const u8, bytes: [*c]const u8, len: u64) callconv(.c) ?*anyopaque {
+ fn open(path: [*c]const u8, bytes: [*c]const u8, len: u64) callconv(.c) ?*anyopaque {
const s = arena.create(T) catch return null;
s.* = std.mem.zeroInit(T, .{});
- if (@hasDecl(T, "open")) T.open(s, if (bytes == null) null else bytes[0..len]);
+ if (@hasDecl(T, "open")) T.open(s, if (path == null) null else std.mem.span(path), if (bytes == null) null else bytes[0..len]);
return s;
}
- fn tick(st: ?*anyopaque, now: u64, flags: u32) callconv(.c) u64 {
- return T.tick(self(st) orelse return 0, now, @bitCast(flags));
+ fn close(st: ?*anyopaque) callconv(.c) void {
+ T.close(self(st) orelse return);
+ }
+ fn tick(st: ?*anyopaque, t: [*c]c.pa_tick) callconv(.c) void {
+ const s = self(st) orelse return;
+ if (@hasDecl(T, "tick")) t.*.next = T.tick(s, t.*.now, @bitCast(t.*.flags));
+ if (@hasDecl(T, "prefix")) t.*.prefix_len = write(T.prefix, s, &t.*.prefix, t.*.prefix.len);
}
fn paint(st: ?*anyopaque, w: [*c]const c.pa_window, out: [*c]c.pa_paint) callconv(.c) void {
- T.paint(self(st) orelse return, .{ .cells = w.*.cells, .stride = w.*.stride, .cols = w.*.cols, .rows = w.*.rows, .focused = w.*.focused != 0 }, .{ .out = out });
+ T.paint(self(st) orelse return, .{ .cells = w.*.cells, .stride = w.*.stride, .cols = w.*.cols, .rows = w.*.rows, .cell_w = w.*.cell_w, .cell_h = w.*.cell_h, .focused = w.*.focused != 0, .view = w.*.view, .glyphs = w.*.glyphs != 0 }, .{ .out = out });
+ }
+ fn view(st: ?*anyopaque, v: [*c]const c.pa_view) callconv(.c) void {
+ T.view(self(st) orelse return, @as(*const View, @ptrCast(v)).*);
}
fn key(st: ?*anyopaque, k: [*c]const c.pa_key) callconv(.c) c_int {
- return @intFromBool(T.key(self(st) orelse return 0, .{ .code = @fromBackingInt(@intCast(k.*.cp)), .ctrl = k.*.ctrl != 0, .alt = k.*.alt != 0, .shift = k.*.shift != 0 }));
+ return @intFromBool(T.key(self(st) orelse return 0, @as(*const Key, @ptrCast(k)).*));
+ }
+ fn mouse(st: ?*anyopaque, m: [*c]const c.pa_mouse) callconv(.c) c_int {
+ return @intFromBool(T.mouse(self(st) orelse return 0, @as(*const Mouse, @ptrCast(m)).*));
}
- /// The body (at most 4 KiB), written whole and read in pieces.
- fn text(st: ?*anyopaque, buf: *[4096]u8) []const u8 {
+ /// The body, written whole and read in pieces.
+ fn text_(st: ?*anyopaque, buf: *[body_max]u8) []const u8 {
var w: std.Io.Writer = .fixed(buf);
- T.body(self(st) orelse return "", &w) catch {};
+ T.body(self(st) orelse return "", &w) catch if (@import("builtin").mode == .debug and !body_cut) {
+ body_cut = true;
+ std.log.warn("{s}: a body cut at {d} bytes (addon.body_max)", .{ T.head.name, body_max });
+ };
return w.buffered();
}
fn body_len(st: ?*anyopaque) callconv(.c) u64 {
- var buf: [4096]u8 = undefined;
- return text(st, &buf).len;
+ var buf: [body_max]u8 = undefined;
+ return text_(st, &buf).len;
}
fn body(st: ?*anyopaque, off: u64, out: [*c]u8, n: u32) callconv(.c) u32 {
- var buf: [4096]u8 = undefined;
- const t = text(st, &buf);
+ var buf: [body_max]u8 = undefined;
+ const t = text_(st, &buf);
const from = t[@min(off, t.len)..][0..@min(t.len -| off, n)];
@memcpy(out[0..from.len], from);
return @intCast(from.len);
}
+ fn address(st: ?*anyopaque, t: [*c]const u8, n: u32) callconv(.c) c_int {
+ return @intFromBool(T.address(self(st) orelse return 0, span(t, n)));
+ }
+ fn where(st: ?*anyopaque, buf: [*c]u8, n: u32) callconv(.c) u32 {
+ return write(T.where, self(st) orelse return 0, buf, n);
+ }
+ fn ctl(st: ?*anyopaque, line: [*c]const u8, n: u32, reply: [*c]u8, cap: u32) callconv(.c) c_int {
+ var w: std.Io.Writer = .fixed(reply[0..cap -| 1]);
+ defer reply[w.end] = 0;
+ return if (T.ctl(self(st) orelse return 1, span(line, n), &w)) c.PA_OK else 1;
+ }
fn ctl_read(st: ?*anyopaque, buf: [*c]u8, n: u32) callconv(.c) u32 {
- var w: std.Io.Writer = .fixed(buf[0..n]);
- T.ctlRead(self(st) orelse return 0, &w) catch {};
- return @intCast(w.end);
+ return write(T.ctlRead, self(st) orelse return 0, buf, n);
}
fn job_run(in: [*c]const u8, n: u32, out: [*c]c.pa_out) callconv(.c) u32 {
const gpa: Allocator = .{ .ptr = out, .vtable = &.{ .alloc = jobAlloc, .resize = Allocator.noResize, .remap = Allocator.noRemap, .free = Allocator.noFree } };
- return @intCast((T.jobRun(in[0..n], gpa) orelse return 0).len);
+ return @intCast((T.jobRun(span(in, n), gpa) orelse return 0).len);
}
fn job_done(st: ?*anyopaque, token: u32, out: [*c]const u8, n: u32) callconv(.c) void {
- T.jobDone(self(st) orelse return, token, out[0..n]);
+ T.jobDone(self(st) orelse return, token, span(out, n));
}
fn dump(st: ?*anyopaque, buf: [*c]u8, n: u32) callconv(.c) u32 {
return @intCast(T.dump(self(st) orelse return 0, buf[0..n]));
}
fn load(st: ?*anyopaque, buf: [*c]const u8, n: u32, version: u32) callconv(.c) c_int {
- return @intFromBool(!T.load(self(st) orelse return 1, buf[0..n], version));
+ return @intFromBool(!T.load(self(st) orelse return 1, span(buf, n), version));
+ }
+ fn search(st: ?*anyopaque, pat: [*c]const u8, n: u32) callconv(.c) void {
+ T.search(self(st) orelse return, span(pat, n));
}
};
+ if (T.head.name.len > 15) @compileError(@typeName(T) ++ "'s name " ++ T.head.name ++ " is over 15 bytes");
var name: [16]u8 = @splat(0);
@memcpy(name[0..T.head.name.len], T.head.name);
- var o: c.pa_ops = .{ .init = F.init, .open = F.open, .paint = F.paint, .head = .{ .size = @sizeOf(c.pa_head), .abi = c.PA_ABI, .name = name, .version = T.head.version, .exts = T.head.exts, .words = &F.words, .nwords = F.words.len } };
+ var o: c.pa_ops = .{ .init = F.init, .open = F.open, .paint = F.paint, .head = .{ .size = @sizeOf(c.pa_head), .abi = c.PA_ABI, .name = name, .version = T.head.version, .flags = if (T.head.pictures) c.PA_PICTURES else 0, .exts = T.head.exts, .words = &F.words, .nwords = F.words.len } };
// The kind's function, then the pa_ops field its wrapper fills.
- const fns = .{ .{ "tick", "tick" }, .{ "key", "key" }, .{ "body", "body_len" }, .{ "body", "body" }, .{ "ctlRead", "ctl_read" }, .{ "jobRun", "job_run" }, .{ "jobDone", "job_done" }, .{ "dump", "dump" }, .{ "load", "load" } };
+ const fns = .{
+ .{ "close", "close" }, .{ "tick", "tick" }, .{ "prefix", "tick" }, .{ "view", "view" }, .{ "key", "key" },
+ .{ "mouse", "mouse" }, .{ "body", "body_len" }, .{ "body", "body" }, .{ "address", "address" }, .{ "where", "where" },
+ .{ "ctl", "ctl" }, .{ "ctlRead", "ctl_read" }, .{ "jobRun", "job_run" }, .{ "jobDone", "job_done" }, .{ "dump", "dump" },
+ .{ "load", "load" }, .{ "search", "search" },
+ };
inline for (fns) |m| if (@hasDecl(T, m[0])) {
@field(o, m[1]) = @field(F, m[1]);
};
- // A word for its pane goes to `ctl`, which this file does not make.
- for (T.head.words) |w| if (!w.opens) @compileError(@typeName(T) ++ "'s word " ++ w.name ++ " opens no pane, and addon.zig makes no ctl to take it");
+ // A word for its pane goes to `ctl`.
+ if (!@hasDecl(T, "ctl")) for (T.head.words) |w| if (!w.opens) @compileError(@typeName(T) ++ "'s word " ++ w.name ++ " opens no pane, and it has no ctl to take it");
// A public function of another name (a typo) would be left out unsaid.
- const names = [_][]const u8{ "open", "paint", "tick", "key", "body", "ctlRead", "jobRun", "jobDone", "dump", "load" };
+ const names = [_][]const u8{ "open", "paint" } ++ blk: {
+ var ns: [fns.len][]const u8 = undefined;
+ for (fns, &ns) |m, *n| n.* = m[0];
+ break :blk ns;
+ };
inline for (@typeInfo(T).@"struct".decl_names) |d| if (comptime @typeInfo(@TypeOf(@field(T, d))) == .@"fn" and for (names) |n| {
if (std.mem.eql(u8, n, d)) break false;
} else true) @compileError(@typeName(T) ++ "." ++ d ++ " is none of a kind's functions (addon.zig's ops)");
diff --git a/src/kinds/pardes_addon.h b/src/kinds/pardes_addon.h
index a2b57155..c3bfb354 100644
--- a/src/kinds/pardes_addon.h
+++ b/src/kinds/pardes_addon.h
@@ -5,7 +5,9 @@
* names its kind. pardes calls it on its own thread, one call at a time;
* it keeps no pointer pardes hands it past the call (but its `pa_api`),
* starts no threads (it has jobs), and reads no file, clock or
- * environment (it is handed bytes and the time). Every function but
+ * environment (it is handed bytes and the time), and is back from every
+ * call within 2 ms: what takes longer goes on a job (a Debug pardes says
+ * a call over 16 ms, and `--addon-test` fails on it). Every function but
* `paint` is optional: leave it NULL and pardes does the default the
* comment beside it says.
*
@@ -16,9 +18,11 @@
* Conventions: init, ctl and load return PA_OK (0), or nonzero to refuse;
* key, mouse and address return nonzero when the event or text was theirs.
* The pa_api pointer handed to init is kept by the addon; it is about the
- * pane of the current call. ABI 2.1 adds fields at the ends of pa_api,
- * pa_paint and pa_ops: a core reads an addon's new ones by its head's
- * minor, an addon pardes's by api->size.
+ * pane of the current call. A kind's state is one thing, stepped by `tick`
+ * however many views show it; what a view sees of it is laid out by `view`
+ * and drawn by `paint`, which writes nothing a step reads. Minors after 3.0
+ * add fields at the ends of records: a core reads an addon's new ones by
+ * its head's minor, an addon pardes's by api->size.
*
* addons/fake/fake.c implements every function; it is the template. In
* Zig, src/kinds/addon.zig makes the pa_ops from a struct, and
@@ -32,10 +36,12 @@
#include <string.h> /* memcpy, for pa_copy and PA_POD */
/* Major in the high half: an addon of another major is refused. */
-#define PA_ABI_MAJOR 2u
-#define PA_ABI_MINOR 2u
+#define PA_ABI_MAJOR 3u
+#define PA_ABI_MINOR 0u
#define PA_ABI ((PA_ABI_MAJOR << 16) | PA_ABI_MINOR)
#define PA_OK 0
+#define PA_RASTER_MAX (32u << 20) /* a placement's w*h*4 above this is dropped, said once */
+#define PA_RECORD_MAX (1u << 20) /* the most a dump's record holds */
/* ---- the picture ---- */
@@ -62,18 +68,21 @@ typedef struct pa_cell {
uint8_t flags;
} pa_cell;
-/* The pane's body, which `paint` writes: `rows` rows of `cols` cells,
- * `stride` cells apart, every one zero (unpainted) when the call begins.
- * How a frontend shows the placements (glyph art, its palette) is the
- * core's words' (Petscii, Palette, Ascii), never the addon's. */
+/* The pane's body in one view, which `paint` writes: `rows` rows of
+ * `cols` cells, `stride` cells apart, every one zero (unpainted) when the
+ * call begins. How a frontend shows the placements (glyph art, its
+ * palette) is the core's words' (Petscii, Palette, Ascii), never the
+ * addon's. */
typedef struct pa_window {
pa_cell *cells;
uint32_t stride;
uint16_t rows, cols;
/* A cell's size in pixels, as the frontend draws it. */
uint16_t cell_w, cell_h;
- /* The pane has the keyboard in some view: for the picture ("paused"). */
- uint8_t focused, pad[3];
+ /* The pane has the keyboard in some view: for the picture ("paused").
+ * `view`: the id of the view painted (pa_view's), whose layout paint
+ * draws; `glyphs`: it shows pictures as glyph art. */
+ uint8_t focused, view, glyphs, pad;
} pa_window;
typedef struct pa_rect { uint32_t x, y, w, h; } pa_rect; /* pixels */
@@ -81,8 +90,8 @@ typedef struct pa_cells { uint16_t x, y, w, h; } pa_cells; /* cells of the wi
/* A picture over the cells: the `src` part of an RGBA raster (straight
* alpha, packed rows of w*4 bytes), over the `dst` cells, at `at` pixels in
- * them, or fitted there (no larger than it is) when at.w is 0. The raster
- * is the addon's and must stay as it is until the pane's next paint or
+ * them, or fitted there (no larger than it is) when at.w is 0; one of
+ * more than PA_RASTER_MAX bytes is dropped. The raster is the addon's and must stay as it is until the pane's next paint or
* close. `key` names the pixels in this pane: one key, one picture, so a
* frontend keeps what it uploaded under it. `from` is 0, or the key of a
* picture a frontend may still hold of which rows dirty_y .. dirty_y +
@@ -100,27 +109,18 @@ typedef struct pa_placement {
} pa_placement;
/* What `paint` hands back beside the cells: placements (room for `cap`,
- * at least 64, lowest first) and the start of the pane's tag, which the
- * core follows with one space, its own words for a picture shown
- * (`petscii:on palette:commodore ascii:off`, when this frame placed one),
- * and the pane's path; empty, the kind's name. paint is called once a
- * frame, body and prefix together, never over no cells. 2.1: `at` and
- * `span`, where the window is in the pane's whole (the share above it and
- * the share it shows, 0 to 1), are the rail's thumb; 0 and 0, none. A kind
- * writes them only to a core whose api->size says 2.1. 2.2: `pointer`, the
- * pointer a frontend shows over the pane (PA_POINTER_*), which a terminal
- * ignores. In paint, not in mouse's answer: what is under a resting pointer
- * is known after the motion (a PDF's link, found on a tick), and the field
- * takes the record's tail padding, so its size stays. */
+ * at least 64, lowest first); `at` and `span`, where the window is in the
+ * pane's whole (the share above it and the share it shows, 0 to 1), the
+ * rail's thumb, 0 and 0 for none; and `pointer`, the pointer a frontend
+ * shows over the pane (PA_POINTER_*), which a terminal ignores. paint is
+ * called once a frame in each view, never over no cells. */
#define PA_POINTER_DEFAULT 0u
#define PA_POINTER_LINK 1u
typedef struct pa_paint {
pa_placement *placements;
uint32_t cap, n;
- char prefix[96];
- uint32_t prefix_len;
float at, span;
- uint32_t pointer;
+ uint32_t pointer, pad;
} pa_paint;
/* ---- input ---- */
@@ -138,9 +138,11 @@ typedef struct pa_paint {
#define PA_KEY_PAGE_UP 0xF0007u
#define PA_KEY_PAGE_DOWN 0xF0008u
#define PA_KEY_DELETE 0xF0009u
+/* `view`: the id of the view it came from (pa_view's), whose layout it is
+ * about (a key's count of lines, a click's cell). */
typedef struct pa_key {
uint32_t cp;
- uint8_t ctrl, alt, shift, pad;
+ uint8_t ctrl, alt, shift, view;
} pa_key;
#define PA_LEFT 0
@@ -154,29 +156,28 @@ typedef struct pa_key {
#define PA_RELEASE 1
#define PA_MOTION 2
#define PA_DRAG 3
-/* A pointer event in the window's cells; a motion at col and row 0xffff
- * when the pointer leaves the window. 2.2: `amount`, a wheel's turn in
- * notches, a touchpad's fraction of one (a terminal's are whole; 0 from an
- * older core: one; an older kind is told each turn as a notch). */
+/* A pointer event in the cells of view `view`'s window; a motion at col
+ * and row 0xffff when the pointer leaves the window. `amount`: a wheel's
+ * turn in notches, a touchpad's fraction of one (a terminal's are whole). */
typedef struct pa_mouse {
- uint8_t button, action, ctrl, shift, alt, pad;
+ uint8_t button, action, ctrl, shift, alt, view;
uint16_t col, row;
float amount;
} pa_mouse;
/* ---- what pardes does for an addon ---- */
-/* The pane as its next paint will see it (2.1, api->view): its window, a
- * cell's pixels; the theme's text, paper, selection and link colours
- * (PA_RGB); and the raster a picture is wanted at: `dpi`, at most `max_px`
- * a side, and never smaller than the pixels it covers when `fill` is set. */
+/* A view of the pane (`view`, `id` 1 and up): its window, a cell's
+ * pixels; the theme's text, paper, selection and link colours (PA_RGB);
+ * the raster a picture is wanted at: `dpi`, at most `max_px` a side, and
+ * never smaller than the pixels it covers when `fill` is set; and
+ * `glyphs`, 1 when the frontend shows placements as glyph art (a terminal
+ * without graphics). */
typedef struct pa_view {
uint16_t cols, rows, cell_w, cell_h;
uint32_t fg, bg, sel, link;
uint16_t dpi, max_px;
- /* 2.2: `glyphs`, 1 when the frontend shows placements as glyph art (a
- * terminal without graphics; 0 from an older core). */
- uint8_t fill, glyphs, pad[2];
+ uint8_t fill, glyphs, id, pad;
} pa_view;
/* Valid during any call pardes makes for a pane, and about that pane. */
@@ -200,19 +201,21 @@ typedef struct pa_api {
* restored from a dump is a new one: a kind keeps its seed in its record
* to reseed alike. */
uint64_t (*seed)(void);
- /* 2.1 (api->size >= 96): memory of pardes's that outlives a call, as
- * realloc's (n 0 frees it), on any thread at any time: what a pane's
- * arena cannot hold, a cache, a library's own heap. */
+ /* Memory of pardes's that outlives a call, as realloc's (n 0 frees it),
+ * on any thread at any time: what a pane's arena cannot hold, a cache, a
+ * library's own heap. */
void *(*heap)(void *ptr, size_t n);
- /* The pane's window and the theme now (pa_view). */
- void (*view)(pa_view *out);
/* Run `text` as a middle click would. */
void (*exec)(const char *text, uint32_t n);
/* The text the pane has selected now, which a yank, a chord's Snarf and
* a keyboard Look take; n 0, none. */
void (*select)(const char *text, uint32_t n);
- /* 2.2 (api->size >= 104): the core's PA_ABI, so a kind reads the 2.2
- * fields it is given (pa_mouse.amount) only from a core that sets them. */
+ /* A job's answer not yet come is dropped (a job running runs on). */
+ void (*cancel)(uint32_t token);
+ /* `place text` rows, a line each, onto the pane's +Search list: from
+ * `search`, or later (a job_done). */
+ void (*found)(const char *rows, uint32_t n);
+ /* The core's PA_ABI. */
uint32_t abi, pad;
} pa_api;
@@ -244,20 +247,36 @@ typedef struct pa_word {
} pa_word;
#define PA_WORD(nm, ld, a, op, dc) { .name = (nm), .leader = (ld), .arg = (a), .opens = (op), .doc = (dc) }
-/* tick's flags: the pane has the keyboard in some view; 2.2: a frame of it
- * was drawn since the last tick. */
+/* tick's in and out. `now`, monotonic, any origin (--addon-test's starts
+ * at 1 s); `flags`: PA_FOCUSED, the pane has the keyboard in some view,
+ * PA_FRAMED, a frame of it was drawn since the last tick. `next`: the
+ * absolute time of the next step, 0 for none. `prefix`: the start of the
+ * pane's tag after this step, which the core follows with one space, its
+ * art words for a kind of PA_PICTURES, and the pane's path; empty, the
+ * kind's name. */
#define PA_FOCUSED 0x1u
#define PA_FRAMED 0x2u
+typedef struct pa_tick {
+ uint64_t now;
+ uint32_t flags, pad;
+ uint64_t next;
+ char prefix[96];
+ uint32_t prefix_len, pad2;
+} pa_tick;
+
+/* head.flags: its panes show pictures, and the core says how in their tag
+ * (`petscii:on palette:commodore ascii:off`, Petscii, Palette, Ascii). */
+#define PA_PICTURES 0x1u
typedef struct pa_head {
uint32_t size, abi;
/* The pane's kind word in /index, NUL-padded. */
char name[16];
- uint32_t version;
+ uint32_t version, flags;
/* The extensions it opens, space-separated (".png .jpg"), or "". */
const char *exts;
const pa_word *words;
- uint32_t nwords;
+ uint32_t nwords, pad;
} pa_head;
typedef struct pa_ops {
@@ -270,19 +289,17 @@ typedef struct pa_ops {
void *(*open)(const char *path, const uint8_t *bytes, uint64_t len);
/* The pane closes; its arena is freed after. */
void (*close)(void *st);
- /* Time has come to now_ns (monotonic, any origin; --addon-test's starts
- * at 1 s): step, and return the absolute time of the next step, 0 for
- * none. Called when that time comes and once after open, a taken key or
- * mouse, ctl, job_done, load, and a change of PA_FOCUSED in `flags` (2.1:
- * or of its pa_view): a kind that returned 0 is woken by the next thing
- * that happens to it.
- * Absent, the pane repaints when the core repaints. */
- uint64_t (*tick)(void *st, uint64_t now_ns, uint32_t flags);
- /* Required. Pure: the same state paints the same, and changes nothing. */
+ /* Time has come to t->now: step the state, once however many views show
+ * it, and set t->next and t->prefix (pa_tick). Called when that time
+ * comes and once after open, a taken key or mouse, ctl, job_done, load,
+ * view, and a change of PA_FOCUSED: a kind that set no next is woken by
+ * the next thing that happens to it. Absent: the prefix is the name. */
+ void (*tick)(void *st, pa_tick *t);
+ /* Required. Pure over the state and win->view's layout: the same paints
+ * the same, and changes nothing. */
void (*paint)(void *st, const pa_window *win, pa_paint *out);
- /* Every key but Esc, which leaves; nonzero if taken. A key not taken goes
- * to the editor's own navigation. Absent: no keys. 2.1: Esc too, first;
- * not taken, it leaves. */
+ /* Every key, Esc first; nonzero if taken. A key not taken goes to the
+ * editor's own navigation (Esc: it leaves). Absent: no keys. */
int (*key)(void *st, const pa_key *k);
/* Nonzero if taken. Absent: a click focuses the pane. */
int (*mouse)(void *st, const pa_mouse *m);
@@ -308,18 +325,24 @@ typedef struct pa_ops {
uint32_t (*job_run)(const uint8_t *in, uint32_t n, pa_out *out);
/* Back on pardes's thread; `out` is gone after the call. */
void (*job_done)(void *st, uint32_t token, const uint8_t *out, uint32_t n);
- /* The pane's record for a dump: its length, written in `n` bytes (n at
- * least 1 MiB), or a length past n, unwritten, to be called again with that
- * many; 0 is no record (load is not called and the pane reopens from its
- * path, its `where` and its words' last values), and so is having no dump. */
+ /* The pane's record for a dump, the kind's own small state (its file is
+ * the pane's path, read again at a Restore): its length, at most n
+ * (PA_RECORD_MAX); 0 is no record (load is not called and the pane
+ * reopens from its path, its `where` and its words' last values), and so
+ * is having no dump. */
uint32_t (*dump)(void *st, uint8_t *buf, uint32_t n);
- /* On the state open(path, bytes, len) returned, with the writer's
- * head.version: PA_OK, or nonzero to refuse (the pane waits as a
- * placeholder, its record kept). */
+ /* On the state open(path, bytes, len) made from the file as it is, with
+ * the writer's head.version: PA_OK, or nonzero to refuse (the pane waits
+ * as a placeholder, its record kept). */
int (*load)(void *st, const uint8_t *buf, uint32_t n, uint32_t version);
- /* 2.1: the pane's own search for the core's `/`: rows `place text`, a
- * line each, into `buf`; their length. Absent: `/` finds nothing here. */
- uint32_t (*search)(void *st, const char *pat, uint32_t n, char *buf, uint32_t cap);
+ /* The pane's own search for the core's `/`, which returns at once: its
+ * rows go to api->found, now or from a job_done. Absent: `/` finds
+ * nothing here. */
+ void (*search)(void *st, const char *pat, uint32_t n);
+ /* A view shows the pane (its facts, or new ones), or stops (cols 0): lay
+ * out for v->id, ask for its rasters. Absent: paint lays out from the
+ * window. */
+ void (*view)(void *st, const pa_view *v);
} pa_ops;
/* The records' sizes on a 64-bit target: an addon built against another
@@ -329,11 +352,11 @@ _Static_assert(sizeof(pa_cell) == 20, "pa_cell");
_Static_assert(sizeof(pa_window) == 24, "pa_window");
_Static_assert(sizeof(pa_rect) == 16 && sizeof(pa_cells) == 8, "pa_rect");
_Static_assert(sizeof(pa_placement) == 80, "pa_placement");
-_Static_assert(sizeof(pa_paint) == 128 && sizeof(pa_view) == 32, "pa_paint");
+_Static_assert(sizeof(pa_paint) == 32 && sizeof(pa_view) == 32 && sizeof(pa_tick) == 128, "pa_paint");
_Static_assert(sizeof(pa_key) == 8 && sizeof(pa_mouse) == 16, "pa_key");
-_Static_assert(sizeof(pa_api) == 104 && sizeof(pa_out) == 16, "pa_api");
+_Static_assert(sizeof(pa_api) == 112 && sizeof(pa_out) == 16, "pa_api");
_Static_assert(sizeof(pa_word) == 32 && sizeof(pa_head) == 56, "pa_head");
-_Static_assert(sizeof(pa_ops) == 200, "pa_ops");
+_Static_assert(sizeof(pa_ops) == 208, "pa_ops");
#endif
/* ---- helpers ---- */
@@ -382,8 +405,8 @@ static inline uint32_t pa_copy(const void *src, uint64_t len, uint64_t off, void
return version != (ver) || n != sizeof(type) ? 1 : (memcpy(st, buf, sizeof(type)), PA_OK); }
/* An addon's head, its size and ABI filled:
- * const pa_ops pardes_addon = { .head = PA_ADDON("game", 1, "", words, 1), .paint = paint }; */
-#define PA_ADDON(nm, ver, ex, ws, nws) \
- { .size = sizeof(pa_head), .abi = PA_ABI, .name = nm, .version = (ver), .exts = (ex), .words = (ws), .nwords = (nws) }
+ * const pa_ops pardes_addon = { .head = PA_ADDON("game", 1, 0, "", words, 1), .paint = paint }; */
+#define PA_ADDON(nm, ver, fl, ex, ws, nws) \
+ { .size = sizeof(pa_head), .abi = PA_ABI, .name = nm, .version = (ver), .flags = (fl), .exts = (ex), .words = (ws), .nwords = (nws) }
#endif