//! 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, `` 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] == '[') "" else piece}) catch {}; } const row = std.mem.endsWith(u8, leaf.path, "[]"); try w.print("{s}", .{lw.buffered()}); try w.splatByteAll(' ', @max(1, 41 -| lw.buffered().len)); 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//patterns///pitch u8\n") != null); try testing.expect(std.mem.indexOf(u8, out.written(), "state/grid/ 3 i16, blank-separated\n") != null); }