summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 01:52:03 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit3e5ad32c529c4c566989ef8201159100a4a3e32c (patch)
treedac282e335b4c09fb7c5753af9020114e54e815f /src
parentcf347f91ee838759dc44ed34ec6ff320186e90ce (diff)
downloadsketchbook-3e5ad32c529c4c566989ef8201159100a4a3e32c.tar.gz
sketchbook-3e5ad32c529c4c566989ef8201159100a4a3e32c.zip
The State as files: state/ in the 9P tree, a directory per struct and array
state/ serves the running sketch's State nested: a directory per struct and per array, a file per value, state/tracker/songs/3/bpm. A read is the value as get shows it, and a newline; a write is the console's set with the file's path (control.zig builds `set tracker.songs[3].bpm 90` and runs it through runLine, so it stops a replay, logs, marks a jump and notes the line like any set). Numbers, bools and enums are written; optionals, unions and the like read as `<N bytes>` and refuse writes. An array of scalars (a vector's lanes, talk.text) is one file of its values, blank-separated; an array of arrays is a directory of such rows (grid/1 for grid[1] of a [2][3]i16). So a file is one value or one row, the run of values one set names, and stays the size of a row however large the array; and paths keep the State's own shape. An array of structs is a directory of indices: drat-meout's patterns, 8x16x16x4 of {pitch, velocity}, are state/tracker/songs/<n>/patterns/<n>/<n>/<n>/ pitch, reached by walking, listed a dimension at a time. state_files.zig does the walking from a (Layout, bytes) alone: lookup, readdir, read, the set path and a README line per file, so the save's newest State and a sketch's defaults can be served the same way. A node is the layout's first leaf under it, its depth and the element's offset, with bit 62 set (bit 63 stays the sketch's). A node a reload made stale is refused, "StateLayoutChangedWalkAgain". fields.setRow sets a row from its words, all or none, and the console's set takes it: `set talk.text 104 105 0`. The engine keeps names up to 64 bytes (from 28), for long field names. Tests: test-control (now also "the State as files" and "a row of scalars"): 40/40 steps, 9/9 tests. Live, headless, the replay fixture over plan9port 9p: ls state, read and write dots/buffer/3/kind and the position vector, a bad value refused as InvalidValue. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'src')
-rw-r--r--src/host/Console.zig2
-rw-r--r--src/host/control.zig60
-rw-r--r--src/host/fields.zig37
-rw-r--r--src/host/root.zig1
-rw-r--r--src/host/state_files.zig303
5 files changed, 396 insertions, 7 deletions
diff --git a/src/host/Console.zig b/src/host/Console.zig
index 3046132..b1915bb 100644
--- a/src/host/Console.zig
+++ b/src/host/Console.zig
@@ -270,7 +270,7 @@ pub fn execute(self: *Console, host: *Host, line: []const u8, now: u64) ![]const
const leaf = host.state.layout.find(path) orelse return error.UnknownField;
if (rest.len == 0) return error.ExpectedValue;
try stop(host);
- try fields.set(leaf, host.live(), std.mem.trim(u8, rest, " "));
+ if (leaf.whole()) try fields.setRow(host.state.layout, host.live(), path, rest) else try fields.set(leaf, host.live(), std.mem.trim(u8, rest, " "));
self.print("{s} = {s}", .{ path, std.mem.trim(u8, rest, " ") });
},
.quit, .exit => {
diff --git a/src/host/control.zig b/src/host/control.zig
index 33b186b..1a8da92 100644
--- a/src/host/control.zig
+++ b/src/host/control.zig
@@ -4,17 +4,18 @@ const c9 = @import("cloud9");
const c = @import("c");
const Host = @import("Host.zig");
const Presentation = @import("Presentation.zig");
+const state_files = @import("state_files.zig");
const fs = c9.fs;
const transport = c9.transport;
const Backend = struct {
pub const Req = fs.Req;
pub const Reply = fs.Reply;
};
-const Server = fs.Server(Backend, .{ .fid_capacity = 32, .slot_capacity = 4 });
+const Server = fs.Server(Backend, .{ .fid_capacity = 32, .slot_capacity = 4, .name_capacity = 64 });
const msize = 16384;
/// The files, a row each: what lookup, readdir and getattr answer. A
/// file's node is its number here.
-const File = enum(u64) { @"/" = 1, ctl, status, log, @"screen.png", profile, @"profile-trace", @"timing-trace", @"presentation-trace" };
+const File = enum(u64) { @"/" = 1, ctl, status, log, @"screen.png", profile, @"profile-trace", @"timing-trace", @"presentation-trace", state = @bitCast(state_files.root) };
const files = std.enums.EnumArray(File, struct { mode: u16 = 0o400, doc: []const u8 }).init(.{
.@"/" = .{ .mode = 0o700, .doc = "" },
.ctl = .{ .mode = 0o600, .doc = "write console lines, a line each; screenshot captures the next frame, profile-reset clears profile" },
@@ -25,6 +26,7 @@ const files = std.enums.EnumArray(File, struct { mode: u16 = 0o400, doc: []const
.@"profile-trace" = .{ .doc = "with --profile-gpu: label,sample,ns, the samples kept, as CSV" },
.@"timing-trace" = .{ .doc = "index,frame_ns,work_ns,outside_work_ns, the frames kept, as CSV" },
.@"presentation-trace" = .{ .doc = "on Wayland: presentation feedback per frame, as CSV" },
+ .state = .{ .mode = 0o700, .doc = "the sketch's State: a directory per struct and array, a file per value; a read is the value, a write what set does (a jump); an array of numbers is one file of its values, blank-separated" },
});
/// The verbs `ctl` takes beside the console's lines.
@@ -148,6 +150,7 @@ pub const Control = struct {
}
fn respond(self: *Control, host: *Host, conn: *Connection, req: fs.Req, reply: *fs.Reply, buffer: []u8) ![]const u8 {
+ if (req.node & @as(u64, @bitCast(state_files.root)) != 0) return stateRespond(host, req, reply, buffer);
const file = std.enums.fromInt(File, req.node) orelse return error.UnknownFile;
switch (req.op) {
.lookup => {
@@ -188,8 +191,8 @@ pub const Control = struct {
for (std.enums.values(File)[1..], 0..) |f, index| {
if (index < req.off) continue;
const name = @tagName(f);
- std.mem.writeInt(u64, buffer[used..][0..8], index + 2, .little);
- buffer[used + 8] = 0;
+ std.mem.writeInt(u64, buffer[used..][0..8], @backingInt(f), .little);
+ buffer[used + 8] = @intFromBool(f == .state);
buffer[used + 9] = @intCast(name.len);
@memcpy(buffer[used + 10 ..][0..name.len], name);
used += 10 + name.len;
@@ -225,7 +228,7 @@ pub const Control = struct {
}
break :blk writer.buffered();
},
- .@"/" => return error.NotFile,
+ .@"/", .state => return error.NotFile,
};
return window(bytes, req.off, req.size);
},
@@ -305,7 +308,7 @@ pub const Control = struct {
fn attr(self: *Control, node: u64) fs.Attr {
const file: File = @fromBackingInt(@intCast(node));
- return .{ .name = @tagName(file), .node = node, .dir = file == .@"/", .mode = files.get(file).mode, .size = if (file == .@"screen.png") self.png.len else 0, .version = if (file == .@"screen.png") @truncate(self.generation) else 0 };
+ return .{ .name = @tagName(file), .node = node, .dir = file == .@"/" or file == .state, .mode = files.get(file).mode, .size = if (file == .@"screen.png") self.png.len else 0, .version = if (file == .@"screen.png") @truncate(self.generation) else 0 };
}
pub fn capture(self: *Control, surface: *c.SDL_Surface) void {
@@ -329,6 +332,51 @@ pub const Control = struct {
}
};
+/// Under `state/`: the live State as files (state_files.zig), a write
+/// run as the console's `set`.
+fn stateRespond(host: *Host, req: fs.Req, reply: *fs.Reply, buffer: []u8) ![]const u8 {
+ const layout = host.state.layout;
+ const node: state_files.Node = @bitCast(req.node);
+ if (!state_files.valid(layout, node)) return error.StateLayoutChangedWalkAgain;
+ const dir = state_files.isDir(layout, node);
+ const mode: u16 = if (dir) 0o700 else if (state_files.writable(layout, node)) 0o600 else 0o400;
+ switch (req.op) {
+ .lookup => {
+ if (!dir) return error.NotDirectory;
+ const child = state_files.lookup(layout, node, req.data) orelse return error.UnknownField;
+ const child_dir = state_files.isDir(layout, child);
+ reply.attr = .{ .node = @bitCast(child), .dir = child_dir, .mode = if (child_dir) 0o700 else if (state_files.writable(layout, child)) 0o600 else 0o400 };
+ },
+ .getattr => reply.attr = .{ .node = req.node, .dir = dir, .mode = mode },
+ .setattr => {
+ if (mode != 0o600 or !req.truncate) return error.ReadOnly;
+ reply.attr = .{ .node = req.node, .mode = mode };
+ },
+ .open, .release => {},
+ .readdir => {
+ if (!dir) return error.NotDirectory;
+ return buffer[0..state_files.readdir(layout, node, req.off, buffer)];
+ },
+ .read => {
+ if (dir) return error.NotFile;
+ var w: std.Io.Writer = .fixed(buffer);
+ state_files.read(layout, host.live(), node, &w) catch return error.ValueTooLong;
+ return window(w.buffered(), req.off, req.size);
+ },
+ .write => {
+ if (mode != 0o600) return error.ReadOnly;
+ var w: std.Io.Writer = .fixed(buffer);
+ w.writeAll("set ") catch unreachable;
+ state_files.path(layout, node, &w) catch return error.ValueTooLong;
+ w.writeByte(' ') catch return error.ValueTooLong;
+ for (std.mem.trim(u8, req.data, " \t\r\n")) |byte| w.writeByte(if (byte == '\n') ' ' else byte) catch return error.ValueTooLong;
+ try host.runLine(w.buffered(), c.SDL_GetTicksNS());
+ reply.written = @intCast(req.data.len);
+ },
+ }
+ return &.{};
+}
+
fn window(bytes: []const u8, offset: u64, count: u32) []const u8 {
if (offset >= bytes.len) return &.{};
const start: usize = @intCast(offset);
diff --git a/src/host/fields.zig b/src/host/fields.zig
index 2e70414..fc1a1e7 100644
--- a/src/host/fields.zig
+++ b/src/host/fields.zig
@@ -123,6 +123,25 @@ pub fn set(leaf: Leaf, memory: []u8, text: []const u8) !void {
}
}
+/// Sets every value of the row of scalars `path` names (an array of
+/// numbers, a vector, `grid[1]` of a `grid: [3][2]u16`), in memory order,
+/// from `text`'s words, one each; nothing when one is not a value.
+pub fn setRow(layout: Layout, memory: []u8, path: []const u8, text: []const u8) !void {
+ for (layout.fields) |leaf| {
+ if (leaf.whole() or !std.mem.endsWith(u8, leaf.path, "[]")) continue;
+ const at = abi.layout.match(leaf.path[0 .. leaf.path.len - 2], leaf.dims[0 .. leaf.dims.len - 1], path) orelse continue;
+ const d = leaf.dims[leaf.dims.len - 1];
+ var scratch: [16]u8 = undefined;
+ var words = std.mem.tokenizeAny(u8, text, " \t\n");
+ for (0..d.count) |_| try set(leaf.at(0), &scratch, words.next() orelse return error.TooFewValues);
+ if (words.next() != null) return error.TooManyValues;
+ words.reset();
+ for (0..d.count) |i| try set(leaf.at(leaf.offset + at + i * d.stride), memory, words.next().?);
+ return;
+ }
+ return error.UnsupportedField;
+}
+
/// True when the field's formatted value equals `text` (enum names compare
/// with or without the leading dot).
pub fn matches(leaf: Leaf, memory: []const u8, text: []const u8) bool {
@@ -206,6 +225,24 @@ test "fields format, parse and compare by kind" {
try std.testing.expectError(error.InvalidValue, set(layout.find("x").?, bytes, "banana"));
}
+test "a row of scalars is set from its words, all or none" {
+ const S = struct { grid: [3][2]i16 = @splat(@splat(0)), pos: @Vector(2, f32) = .{ 0, 0 } };
+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+ defer arena.deinit();
+ const layout = try Layout.copy(arena.allocator(), abi.layout.of(S, .state));
+ var s: S = .{};
+ const bytes = std.mem.asBytes(&s);
+ try setRow(layout, bytes, "grid[1]", "4 -5");
+ try std.testing.expectEqual([2]i16{ 4, -5 }, s.grid[1]);
+ try setRow(layout, bytes, "pos", "1.5\n2");
+ try std.testing.expectEqual(@as(f32, 2), s.pos[1]);
+ try std.testing.expectError(error.TooFewValues, setRow(layout, bytes, "grid[2]", "7"));
+ try std.testing.expectError(error.TooManyValues, setRow(layout, bytes, "grid[2]", "7 8 9"));
+ try std.testing.expectError(error.InvalidValue, setRow(layout, bytes, "grid[2]", "7 x"));
+ try std.testing.expectEqual([2]i16{ 0, 0 }, s.grid[2]);
+ try std.testing.expectError(error.UnsupportedField, setRow(layout, bytes, "grid", "1 2"));
+}
+
test "indexed paths reach array elements and vector lanes" {
const S = struct { pos: @Vector(2, f32) = .{ 250, 3 }, boids: struct { buffer: [4]struct { pos: [2]f32 = .{ 0, 0 }, mood: enum(u8) { calm = 1, wild = 2 } = .calm } = @splat(.{}), len: u32 = 0 } = .{} };
var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
diff --git a/src/host/root.zig b/src/host/root.zig
index 42362d3..44512b2 100644
--- a/src/host/root.zig
+++ b/src/host/root.zig
@@ -216,5 +216,6 @@ test {
_ = @import("audio.zig");
_ = @import("Console.zig");
_ = @import("control.zig");
+ _ = @import("state_files.zig");
_ = @import("timing_marker.zig");
}
diff --git a/src/host/state_files.zig b/src/host/state_files.zig
new file mode 100644
index 0000000..016b9fe
--- /dev/null
+++ b/src/host/state_files.zig
@@ -0,0 +1,303 @@
+//! The State as files: a directory per struct and per array, a file per
+//! value, `state/tracker/songs/3/bpm`. An array of scalars (a vector's
+//! lanes, `talk.text`) is one file, its values blank-separated; an array
+//! of arrays is a directory of such rows, so a file is always one value or
+//! one row, the run of values one `set` names. Everything here reads a
+//! `(Layout, bytes)` alone: the running host's, the save's newest State,
+//! or a sketch's defaults.
+//!
+//! A node names a leaf of the layout (its first under a directory), how
+//! many names deep it is, and the offset of the element it stands for:
+//! the indices on its way, every later one zero. Nodes have bit 62 set;
+//! bit 63 is the sketch's (control.zig).
+const std = @import("std");
+const memory = @import("memory.zig");
+const fields = @import("fields.zig");
+const Layout = memory.Layout;
+const Leaf = Layout.Leaf;
+
+pub const Node = packed struct(u64) {
+ offset: u40 = 0,
+ depth: u6 = 0,
+ leaf: u16 = 0,
+ state: u1 = 1,
+ sketch: u1 = 0,
+};
+
+/// `state/` itself.
+pub const root: Node = .{};
+
+/// The names of a leaf's pattern: a field's name, or `[]` for an index.
+const Pieces = struct {
+ rest: []const u8,
+
+ fn next(p: *Pieces) ?[]const u8 {
+ if (p.rest.len > 0 and p.rest[0] == '.') p.rest = p.rest[1..];
+ if (p.rest.len == 0) return null;
+ const end = if (std.mem.startsWith(u8, p.rest, "[]")) 2 else std.mem.indexOfAny(u8, p.rest, ".[") orelse p.rest.len;
+ defer p.rest = p.rest[end..];
+ return p.rest[0..end];
+ }
+};
+
+/// How deep a leaf's file is: its names, an innermost index not counted
+/// (a row of scalars is one file).
+fn fileDepth(leaf: Leaf) usize {
+ var p: Pieces = .{ .rest = leaf.path };
+ var n: usize = 0;
+ while (p.next()) |_| n += 1;
+ return if (std.mem.endsWith(u8, leaf.path, "[]")) n - 1 else n;
+}
+
+/// Where `leaf` is under `dir`: its offset at the directory's indices (the
+/// rest zero), and how many of its dimensions they used; null when it is
+/// not under it.
+fn under(layout: Layout, dir: Node, leaf: Leaf) ?struct { offset: usize, dim: usize } {
+ if (leaf.kind == .array or fileDepth(leaf) < dir.depth) return null;
+ if (dir.depth == 0) return .{ .offset = leaf.offset, .dim = 0 };
+ const own = layout.fields[dir.leaf];
+ var a: Pieces = .{ .rest = own.path };
+ var b: Pieces = .{ .rest = leaf.path };
+ var rest: usize = @intCast(dir.offset -| own.offset);
+ var dim: usize = 0;
+ var offset: usize = leaf.offset;
+ for (0..dir.depth) |_| {
+ const x = a.next() orelse return null;
+ if (!std.mem.eql(u8, x, b.next() orelse return null)) return null;
+ if (x[0] != '[') continue;
+ const index = rest / own.dims[dim].stride;
+ rest %= own.dims[dim].stride;
+ if (index >= leaf.dims[dim].count) return null;
+ offset += index * leaf.dims[dim].stride;
+ dim += 1;
+ }
+ return .{ .offset = offset, .dim = dim };
+}
+
+/// The name a leaf has `depth` names down.
+fn pieceAt(leaf: Leaf, depth: usize) []const u8 {
+ var p: Pieces = .{ .rest = leaf.path };
+ for (0..depth) |_| _ = p.next();
+ return p.next().?;
+}
+
+/// Whether `node` still names something in `layout` (a reload may have
+/// changed it under an open fid).
+pub fn valid(layout: Layout, node: Node) bool {
+ if (node.depth == 0) return true;
+ if (node.leaf >= layout.fields.len) return false;
+ const leaf = layout.fields[node.leaf];
+ return leaf.kind != .array and node.depth <= fileDepth(leaf) and node.offset >= leaf.offset and node.offset < layout.size;
+}
+
+pub fn isDir(layout: Layout, node: Node) bool {
+ return node.depth == 0 or node.depth < fileDepth(layout.fields[node.leaf]);
+}
+
+/// The child of directory `dir` called `child`.
+pub fn lookup(layout: Layout, dir: Node, child: []const u8) ?Node {
+ for (layout.fields, 0..) |leaf, j| {
+ const at = under(layout, dir, leaf) orelse continue;
+ if (fileDepth(leaf) == dir.depth) continue;
+ const piece = pieceAt(leaf, dir.depth);
+ var offset = at.offset;
+ if (piece[0] == '[') {
+ if (child.len == 0 or !std.ascii.isDigit(child[0])) return null;
+ const index = std.fmt.parseInt(u32, child, 10) catch return null;
+ if (index >= leaf.dims[at.dim].count) return null;
+ offset += index * leaf.dims[at.dim].stride;
+ } else if (!std.mem.eql(u8, piece, child)) continue;
+ return .{ .leaf = @intCast(j), .depth = dir.depth + 1, .offset = @intCast(offset) };
+ }
+ return null;
+}
+
+/// The entries of directory `dir` from the `from`-th, as cloud9's readdir
+/// records (`node:u64le dir:u8 len:u8 name`), as many as `out` holds: the
+/// bytes written.
+pub fn readdir(layout: Layout, dir: Node, from: u64, out: []u8) usize {
+ var used: usize = 0;
+ var index: u64 = 0;
+ var last: []const u8 = "";
+ for (layout.fields, 0..) |leaf, j| {
+ const at = under(layout, dir, leaf) orelse continue;
+ if (fileDepth(leaf) == dir.depth) continue;
+ const piece = pieceAt(leaf, dir.depth);
+ if (std.mem.eql(u8, piece, last)) continue;
+ last = piece;
+ const is_dir = fileDepth(leaf) > dir.depth + 1;
+ const count = if (piece[0] == '[') leaf.dims[at.dim].count else 1;
+ for (0..count) |i| {
+ defer index += 1;
+ if (index < from) continue;
+ var buf: [16]u8 = undefined;
+ const text = if (piece[0] == '[') std.fmt.bufPrint(&buf, "{d}", .{i}) catch unreachable else piece;
+ if (used + 10 + text.len > out.len) return used;
+ const offset = at.offset + if (piece[0] == '[') i * leaf.dims[at.dim].stride else 0;
+ const node: Node = .{ .leaf = @intCast(j), .depth = dir.depth + 1, .offset = @intCast(offset) };
+ std.mem.writeInt(u64, out[used..][0..8], @bitCast(node), .little);
+ out[used + 8] = @intFromBool(is_dir);
+ out[used + 9] = @intCast(text.len);
+ @memcpy(out[used + 10 ..][0..text.len], text);
+ used += 10 + text.len;
+ }
+ }
+ return used;
+}
+
+/// The row of scalars at a file node: its first element and its length
+/// and stride; null for a file of one value.
+fn rowOf(layout: Layout, node: Node) ?struct { first: Leaf, count: usize, stride: usize } {
+ const leaf = layout.fields[node.leaf];
+ if (!std.mem.endsWith(u8, leaf.path, "[]") or node.depth != fileDepth(leaf)) return null;
+ const d = leaf.dims[leaf.dims.len - 1];
+ return .{ .first = leaf.at(node.offset), .count = d.count, .stride = d.stride };
+}
+
+/// A file's value, as `get` shows one value, a row's blank-separated,
+/// and a newline.
+pub fn read(layout: Layout, bytes: []const u8, node: Node, w: *std.Io.Writer) std.Io.Writer.Error!void {
+ if (rowOf(layout, node)) |row| {
+ for (0..row.count) |i| {
+ if (i > 0) try w.writeByte(' ');
+ try fields.format(row.first.at(row.first.offset + i * row.stride), bytes, w);
+ }
+ } else try fields.format(layout.fields[node.leaf].at(node.offset), bytes, w);
+ try w.writeByte('\n');
+}
+
+/// The path `get` and `set` take for a node: `tracker.songs[3].bpm`, and
+/// for a row the array's (`talk.text`).
+pub fn path(layout: Layout, node: Node, w: *std.Io.Writer) std.Io.Writer.Error!void {
+ const leaf = layout.fields[node.leaf];
+ var p: Pieces = .{ .rest = leaf.path };
+ var rest: usize = @intCast(node.offset - leaf.offset);
+ var dim: usize = 0;
+ for (0..node.depth) |k| {
+ const piece = p.next().?;
+ if (piece[0] == '[') {
+ try w.print("[{d}]", .{rest / leaf.dims[dim].stride});
+ rest %= leaf.dims[dim].stride;
+ dim += 1;
+ } else try w.print("{s}{s}", .{ if (k == 0) "" else ".", piece });
+ }
+}
+
+/// Whether `set` takes the file: numbers, bools and enums.
+pub fn writable(layout: Layout, node: Node) bool {
+ return switch (layout.fields[node.leaf].kind) {
+ .int, .uint, .float, .bool, .@"enum" => true,
+ else => false,
+ };
+}
+
+/// A README line for every file of the layout: its path, `<n>` for an
+/// index, and what it holds.
+pub fn readme(layout: Layout, w: *std.Io.Writer) std.Io.Writer.Error!void {
+ for (layout.fields) |leaf| {
+ if (leaf.kind == .array) continue;
+ var line: [256]u8 = undefined;
+ var lw: std.Io.Writer = .fixed(&line);
+ var p: Pieces = .{ .rest = leaf.path };
+ const depth = fileDepth(leaf);
+ lw.writeAll("state") catch {};
+ for (0..depth) |_| {
+ const piece = p.next().?;
+ lw.print("/{s}", .{if (piece[0] == '[') "<n>" else piece}) catch {};
+ }
+ const row = std.mem.endsWith(u8, leaf.path, "[]");
+ try w.print("{s}", .{lw.buffered()});
+ try w.splatByteAll(' ', 40 -| lw.buffered().len + 1);
+ if (row) try w.print("{d} ", .{leaf.dims[leaf.dims.len - 1].count});
+ switch (leaf.kind) {
+ .int, .uint, .float => try w.print("{s}{d}", .{ switch (leaf.kind) {
+ .int => "i",
+ .uint => "u",
+ else => "f",
+ }, leaf.size * 8 }),
+ .bool => try w.writeAll("bool"),
+ .@"enum" => {
+ var tags = std.mem.tokenizeScalar(u8, leaf.tags, ',');
+ var first = true;
+ while (tags.next()) |pair| : (first = false) try w.print("{s}.{s}", .{ if (first) "" else " ", pair[0 .. std.mem.indexOfScalar(u8, pair, '=') orelse pair.len] });
+ },
+ else => try w.print("{d} bytes, read-only", .{leaf.size}),
+ }
+ if (row) try w.writeAll(", blank-separated");
+ try w.writeByte('\n');
+ }
+}
+
+const testing = std.testing;
+
+fn walk(layout: Layout, to: []const u8) ?Node {
+ var node = root;
+ var names = std.mem.tokenizeScalar(u8, to, '/');
+ while (names.next()) |n| node = lookup(layout, node, n) orelse return null;
+ return node;
+}
+
+/// The names in a directory, a blank after each, a slash after a directory's.
+fn ls(layout: Layout, dir: Node, buf: []u8) []const u8 {
+ var records: [4096]u8 = undefined;
+ const bytes = records[0..readdir(layout, dir, 0, &records)];
+ var w: std.Io.Writer = .fixed(buf);
+ var i: usize = 0;
+ while (i < bytes.len) : (i += 10 + bytes[i + 9]) {
+ const node: Node = @bitCast(std.mem.readInt(u64, bytes[i..][0..8], .little));
+ // Each entry is what a lookup of its name answers.
+ const text = bytes[i + 10 ..][0..bytes[i + 9]];
+ std.debug.assert(lookup(layout, dir, text).? == node);
+ w.print("{s}{s} ", .{ text, if (bytes[i + 8] != 0) "/" else "" }) catch {};
+ }
+ return w.buffered();
+}
+
+test "the State as files: a directory per struct and array, a file per value or row" {
+ const S = struct {
+ scene: enum(u8) { room, street } = .street,
+ talk: struct { text: [4]u8 = .{ 104, 105, 0, 0 }, len: u8 = 2 } = .{},
+ songs: [2]struct { bpm: u16 = 120, patterns: [2][3]struct { pitch: u8 = 0, velocity: u8 = 0 } = @splat(@splat(.{})) } = @splat(.{}),
+ grid: [2][3]i16 = @splat(@splat(0)),
+ pos: @Vector(2, f32) = .{ 250, 3 },
+ };
+ var arena: std.heap.ArenaAllocator = .init(testing.allocator);
+ defer arena.deinit();
+ const layout = try Layout.copy(arena.allocator(), @import("abi").layout.of(S, .state));
+ var s: S = .{};
+ s.songs[1].patterns[1][2].pitch = 64;
+ s.grid[1] = .{ 1, -2, 3 };
+ const bytes = std.mem.asBytes(&s);
+ var buf: [256]u8 = undefined;
+ try testing.expectEqualStrings("scene talk/ songs/ grid/ pos ", ls(layout, root, &buf));
+ try testing.expectEqualStrings("text len ", ls(layout, walk(layout, "talk").?, &buf));
+ try testing.expectEqualStrings("0/ 1/ ", ls(layout, walk(layout, "songs").?, &buf));
+ try testing.expectEqualStrings("bpm patterns/ ", ls(layout, walk(layout, "songs/1").?, &buf));
+ try testing.expectEqualStrings("0/ 1/ 2/ ", ls(layout, walk(layout, "songs/1/patterns/1").?, &buf));
+ try testing.expectEqualStrings("0 1 ", ls(layout, walk(layout, "grid").?, &buf));
+ const cases = [_][3][]const u8{
+ .{ "scene", "scene", ".street\n" },
+ .{ "talk/text", "talk.text", "104 105 0 0\n" },
+ .{ "songs/1/bpm", "songs[1].bpm", "120\n" },
+ .{ "songs/1/patterns/1/2/pitch", "songs[1].patterns[1][2].pitch", "64\n" },
+ .{ "grid/1", "grid[1]", "1 -2 3\n" },
+ .{ "pos", "pos", "250 3\n" },
+ };
+ for (cases) |case| {
+ const node = walk(layout, case[0]).?;
+ try testing.expect(!isDir(layout, node) and valid(layout, node) and writable(layout, node));
+ var w: std.Io.Writer = .fixed(&buf);
+ try path(layout, node, &w);
+ try testing.expectEqualStrings(case[1], w.buffered());
+ w = .fixed(&buf);
+ try read(layout, bytes, node, &w);
+ try testing.expectEqualStrings(case[2], w.buffered());
+ }
+ for ([_][]const u8{ "nope", "songs/2", "songs/x", "songs/01x", "grid/1/0", "scene/x", "talk/text/0" }) |bad| try testing.expect(walk(layout, bad) == null);
+ var out: std.Io.Writer.Allocating = .init(testing.allocator);
+ defer out.deinit();
+ try readme(layout, &out.writer);
+ try testing.expect(std.mem.indexOf(u8, out.written(), "state/scene .room .street\n") != null);
+ try testing.expect(std.mem.indexOf(u8, out.written(), "state/songs/<n>/patterns/<n>/<n>/pitch u8\n") != null);
+ try testing.expect(std.mem.indexOf(u8, out.written(), "state/grid/<n> 3 i16, blank-separated\n") != null);
+}