//! pardes's text pane as a library: the `pardes-editor` module a package //! that depends on pardes imports (build.zig's `library` with `.editor = //! true`, docs/next-editor.md). In-memory editing with helix's keys: no //! files, commands, builtins, prompts or views, which come back to the //! caller as an `action`. Nothing is copied here: a key runs the editor's //! own normal.zig and edit.zig, built with `pardes_config.lib`, where a //! text has no pane and its characters are its own. //! //! The editor is a value of plain data (`Editor(capacity)`): no pointer, //! no allocator, every capacity in its type, so it can be kept where a //! program keeps its state, copied anywhere, and outlive the code that //! made it. Each call is handed an allocator it may use and drop (a //! frame's arena): the value is thawed into the structures pardes edits, //! the key runs, and they are frozen back. const std = @import("std"); const modal = @import("modal.zig"); const Text = @import("Text.zig"); const Registers = @import("Registers.zig"); const Context = @import("Editor.zig"); const normal = @import("normal.zig"); const edit = @import("edit.zig"); const syntax_impl = @import("syntax.zig"); /// pardes's syntax (src/lib_syntax.zig): its grammars, highlighting, /// themes and line arithmetic. A file belongs to one module, so a package /// imports this module or `pardes-syntax`, not both. pub const syntax = @import("lib_syntax.zig"); /// A key read: its codepoint or one of the specials (`Key.enter`, /// `Key.left`...), the text it types, its modifiers. pub const Key = @import("plain").Key; /// A range as helix has it: byte offsets between characters. pub const Selection = modal.Selection; pub const Role = modal.Normal.Role; /// What a normal-mode key means: a role, its count and the character it /// takes. Built by the caller too, for `run`. pub const Action = modal.Normal.Action; pub const RegexMode = modal.Normal.RegexMode; pub const max_selections = Text.max_selections; /// A grammar handed in at run time (syntax.zig): its tree-sitter /// language and its queries' sources, told by `ext`. pub const Language = syntax_impl.Language; pub const Capacity = struct { /// Bytes of text. text: u32 = 64 * 1024, /// Bytes of undo, and as many again of redo: whole-text snapshots, the /// oldest dropped to make room. At least `text`, so every text that /// fits is a snapshot that fits. undo: u32 = 256 * 1024, /// Bytes of every register's values together. registers: u32 = 16 * 1024, /// Ranges, the primary among them. selections: u16 = 256, }; /// Why a key was not taken: what it made does not fit the value's /// capacities, or the allocator handed in ran out. The value is as it was /// before the key. pub const Refusal = enum { text_full, registers_full, selections_full, out_of_memory }; pub const Outcome = union(enum) { /// The key did what helix does with it (a motion, an edit, a mode). done, /// A count, a prefix (`g`, `m`, `"x`) or a pair's character is awaited: /// `pending()` says which. pending, /// Helix binds nothing to it: the caller's to give a meaning. unbound: Key, /// Bound, but not the text's to do (a view, `:`, `/`, `s`, LSP, a /// macro): the caller's. The text and its ranges are as they were. action: Action, refused: Refusal, }; pub const Mode = enum { normal, insert, select }; /// Text's fields that say where the cursor and the ranges are and what is /// pending, kept here under their names: thaw and freeze copy each. pub const Cursor = struct { mode: Text.Mode = .normal, cur_pinned: bool = false, cur_row: i32 = 0, cur_col: i32 = 0, vsel: Text.CharSel = .{}, nsel: u16 = 0, select: bool = false, sticky_col: i32 = -1, restore_cursor: bool = false, last_edit: @FieldType(Text, "last_edit") = null, reg_wait: bool = false, normal: modal.Normal.State = .{}, find_op: ?modal.Normal.Find = null, find_ch: u21 = 0, }; /// Records of whole bytes in a ring, each `[len][payload][len]`, the newest /// at `head`: pushing over a full ring drops the oldest. A record keeps its /// place while it is held, so a push changes the pages it is written to and /// no others. pub fn Ring(comptime size: u32) type { return struct { const R = @This(); bytes: [size]u8 = @splat(0), head: u32 = 0, used: u32 = 0, count: u32 = 0, fn copyOut(r: *const R, at: u32, out: []u8) void { const first = @min(out.len, size - at); @memcpy(out[0..first], r.bytes[at..][0..first]); @memcpy(out[first..], r.bytes[0 .. out.len - first]); } fn copyIn(r: *R, at: u32, in: []const u8) void { const first: u32 = @intCast(@min(in.len, size - at)); @memcpy(r.bytes[at..][0..first], in[0..first]); @memcpy(r.bytes[0 .. in.len - first], in[first..]); } fn lenAt(r: *const R, at: u32) u32 { var b: [4]u8 = undefined; r.copyOut(at, &b); return std.mem.readInt(u32, &b, .little); } /// Where the record `skip` records below the newest ends. fn endOf(r: *const R, skip: u32) u32 { var at = r.head; for (0..skip) |_| at = (at + size - (r.lenAt((at + size - 4) % size) + 8)) % size; return at; } /// The payload of the record `skip` below the newest, copied out. pub fn get(r: *const R, a: std.mem.Allocator, skip: u32) ![]u8 { const end = r.endOf(skip); const len = r.lenAt((end + size - 4) % size); const out = try a.alloc(u8, len); r.copyOut((end + size - 4 - len) % size, out); return out; } pub fn pop(r: *R) void { if (r.count == 0) return; const len = r.lenAt((r.head + size - 4) % size); r.head = (r.head + size - (len + 8)) % size; r.used -= len + 8; r.count -= 1; } /// False when the payload alone is more than the ring holds. pub fn fits(len: usize) bool { return len + 8 <= size; } pub fn push(r: *R, payload: []const u8) void { std.debug.assert(fits(payload.len)); const len: u32 = @intCast(payload.len); while (r.used + len + 8 > size) { const tail = (r.head + size - r.used) % size; r.used -= r.lenAt(tail) + 8; r.count -= 1; } var n: [4]u8 = undefined; std.mem.writeInt(u32, &n, len, .little); r.copyIn(r.head, &n); r.copyIn((r.head + 4) % size, payload); r.copyIn((r.head + 4 + len) % size, &n); r.head = (r.head + len + 8) % size; r.used += len + 8; r.count += 1; } pub fn clear(r: *R) void { r.used = 0; r.count = 0; } }; } /// A snapshot's place in a ring record, before its text. const SnapMeta = extern struct { cur_row: i32, cur_col: i32, vrow: i32, vcol: i32, active: u8, explicit: u8, has_text: u8, _: u8 = 0 }; fn snapBytes(a: std.mem.Allocator, s: Text.Snapshot) ![]u8 { const text = if (s.ovl) |o| o.text else ""; const out = try a.alloc(u8, @sizeOf(SnapMeta) + text.len); const meta: SnapMeta = .{ .cur_row = s.cur_row, .cur_col = s.cur_col, .vrow = s.vsel.row, .vcol = s.vsel.col, .active = @intFromBool(s.vsel.active), .explicit = @intFromBool(s.vsel.explicit), .has_text = @intFromBool(s.ovl != null), }; @memcpy(out[0..@sizeOf(SnapMeta)], std.mem.asBytes(&meta)); @memcpy(out[@sizeOf(SnapMeta)..], text); return out; } fn snapOf(bytes: []u8) Text.Snapshot { var meta: SnapMeta = undefined; @memcpy(std.mem.asBytes(&meta), bytes[0..@sizeOf(SnapMeta)]); return .{ .ovl = if (meta.has_text != 0) .{ .text = bytes[@sizeOf(SnapMeta)..] } else null, .cur_row = meta.cur_row, .cur_col = meta.cur_col, .vsel = .{ .active = meta.active != 0, .row = meta.vrow, .col = meta.vcol, .explicit = meta.explicit != 0 }, }; } /// What a key runs on: the value thawed (`Text`, `Registers`), the replay's /// state, and what was thawed from the rings, to tell what the key did to /// them. const Live = struct { text: Text, registers: Registers = .{}, register: u21 = 0, multi_first: bool = true, multi_stop: bool = false, multi_index: usize = 0, multi_count: usize = 1, retired_edit: ?[]u8 = null, failed: bool = false, syntax: ?*Syntax = null, undo_thawed: usize = 0, redo_thawed: usize = 0, /// The ring records thawed, by their text's address: a snapshot still /// in a history after the key is one of them when its text is. undo_from: [1]?[*]const u8 = @splat(null), redo_from: [2]?[*]const u8 = @splat(null), fn context(l: *Live, a: std.mem.Allocator) Context { return .{ .gpa = a, .scratch = a, .registers = &l.registers, .register = &l.register, .multi_first = &l.multi_first, .multi_stop = &l.multi_stop, .multi_index = &l.multi_index, .multi_count = &l.multi_count, .retired_edit = &l.retired_edit, .p = {}, .failed = &l.failed, .syntax = l.syntax, }; } }; fn textPtr(s: Text.Snapshot) ?[*]const u8 { return if (s.ovl) |o| o.text.ptr else null; } pub fn Editor(comptime cap: Capacity) type { if (cap.undo < cap.text + @sizeOf(SnapMeta) + 8) @compileError("pardes-editor: an undo ring holds at least one whole text"); if (cap.selections < 1 or cap.selections > Text.max_selections) @compileError("pardes-editor: 1 to max_selections ranges"); return struct { const Self = @This(); pub const capacity = cap; /// The text as a gap buffer: `front` bytes at its start and `back` /// at its end, the gap where the last edit was, so that typing /// changes the page it types into and not every page after it. text: [cap.text]u8 = @splat(0), front: u32 = 0, back: u32 = 0, /// One more for each key that changed the text: what a parse of it /// (`Syntax`) is kept against. revision: u32 = 0, cursor: Cursor = .{}, /// The ranges beside the primary, `cursor.nsel` of them. sels: [cap.selections - 1]Text.SelRange = @splat(.{ .row = 0, .col = 0, .arow = 0, .acol = 0 }), undo: Ring(cap.undo) = .{}, redo: Ring(cap.undo) = .{}, /// Every register, `[name][count]` then each value `[len][bytes]`. registers: [cap.registers]u8 = @splat(0), registers_len: u32 = 0, last_search: u21 = '/', pub fn len(ed: *const Self) usize { return ed.front + ed.back; } /// The text, copied whole into `out` (at least `len()` bytes). pub fn read(ed: *const Self, out: []u8) []u8 { @memcpy(out[0..ed.front], ed.text[0..ed.front]); @memcpy(out[ed.front..][0..ed.back], ed.text[cap.text - ed.back ..]); return out[0..ed.len()]; } /// The text in `a`'s memory. pub fn bytes(ed: *const Self, a: std.mem.Allocator) error{OutOfMemory}![]u8 { return ed.read(try a.alloc(u8, ed.len())); } /// A new text, nothing to undo, the cursor at its start, the /// registers kept. pub fn load(ed: *Self, text: []const u8) error{TextFull}!void { if (text.len > cap.text) return error.TextFull; @memcpy(ed.text[0..text.len], text); ed.front = @intCast(text.len); ed.back = 0; ed.revision +%= 1; ed.cursor = .{}; ed.undo.clear(); ed.redo.clear(); } pub fn mode(ed: *const Self) Mode { return switch (ed.cursor.mode) { .insert => .insert, else => if (ed.cursor.select) .select else .normal, }; } /// What the next key completes, null when nothing is awaited. pub fn pending(ed: *const Self) ?Role { return ed.cursor.normal.match_sub orelse ed.cursor.normal.prefix; } /// The ranges in document order and which is the primary. pub fn ranges(ed: *const Self, a: std.mem.Allocator, out: *[max_selections]Selection) error{OutOfMemory}!struct { n: usize, primary: usize } { const live = try ed.thaw(a, null); const got = live.text.ranges(live.text.own.?, 0, out); return .{ .n = got.n, .primary = got.pri }; } /// A key, as a text pane in normal or insert mode takes it. With /// `syn`, the tree-sitter walks (Alt-o and kin, `]f`, `mif`) run on /// its parse, made again if the text has changed; without, they /// come back as actions (`mif` does nothing). pub fn key(ed: *Self, a: std.mem.Allocator, syn: ?*Syntax, k: Key) Outcome { const live = ed.thaw(a, syn) catch return .{ .refused = .out_of_memory }; const parsed = normal.textKey(live.context(a), &live.text, k); switch (parsed) { .unbound => return ed.keep(a, live, .{ .unbound = k }), .pending => return ed.keep(a, live, .pending), .ignored => return ed.keep(a, live, .done), .action => |act| { if (!normal.textRole(act.role, syn != null)) { // the parse's state goes on; nothing ran ed.cursor.normal = live.text.normal; return .{ .action = act }; } return ed.keep(a, live, .done); }, } } /// A normal-mode action, as its key would run it: across every /// range unless it is the selection's as a whole. pub fn run(ed: *Self, a: std.mem.Allocator, syn: ?*Syntax, act: Action) Outcome { if (!normal.textRole(act.role, syn != null)) return .{ .action = act }; const live = ed.thaw(a, syn) catch return .{ .refused = .out_of_memory }; normal.runAction(live.context(a), &live.text, act); return ed.keep(a, live, .done); } /// helix's `s` (select), `S` (split), `K` (keep) and `Alt-K` /// (remove) with `pattern` over the ranges there are. pub fn selectRegex(ed: *Self, a: std.mem.Allocator, pattern: []const u8, how: RegexMode) Outcome { const live = ed.thaw(a, null) catch return .{ .refused = .out_of_memory }; const t = &live.text; // as pardes's prompt answers it (look.submitSearch): helix // keeps the pattern in `/` if (pattern.len > 0) { live.registers.put(a, '/', pattern, 0, 1, true) catch return .{ .refused = .out_of_memory }; live.registers.last_search = '/'; } var snap: [max_selections]Selection = undefined; const got = t.ranges(t.own.?, 0, &snap); normal.selectByRegex(live.context(a), t, snap[0..got.n], got.pri, t.vsel.active and t.vsel.explicit, pattern, how); return ed.keep(a, live, .done); } /// Replace the whole text with `text`, as one step to undo. pub fn setText(ed: *Self, a: std.mem.Allocator, text: []const u8) Outcome { const live = ed.thaw(a, null) catch return .{ .refused = .out_of_memory }; const e = live.context(a); const t = &live.text; edit.pushUndo(e, t) catch return .{ .refused = .out_of_memory }; edit.setEditText(e, t, a.dupe(u8, text) catch return .{ .refused = .out_of_memory }) catch return .{ .refused = .out_of_memory }; t.clampCursor(t.own.?, 0); return ed.keep(a, live, .done); } /// The bytes from `from` to `to` replaced with `with`, as one step /// to undo, the ranges following as an edit moves them (one inside /// the bytes goes to their start). `join`: part of the step before /// it instead, as the frames of a drag after its first, so one undo /// takes the whole drag back. pub fn replace(ed: *Self, a: std.mem.Allocator, from: usize, to: usize, with: []const u8, join: bool) Outcome { std.debug.assert(from <= to and to <= ed.len()); const live = ed.thaw(a, null) catch return .{ .refused = .out_of_memory }; edit.replaceBytes(live.context(a), &live.text, from, to, with, !join) catch return .{ .refused = .out_of_memory }; return ed.keep(a, live, .done); } /// The register `name`'s values, one per range that wrote it. pub fn register(ed: *const Self, a: std.mem.Allocator, name: u21) error{OutOfMemory}!?[]const []const u8 { var r: Registers = .{}; try ed.readRegisters(a, &r); const reg = r.get(name) orelse return null; return @ptrCast(reg.values); } /// Write register `name` (the system clipboard's `+`, a pattern's /// `/`): one value. pub fn setRegister(ed: *Self, a: std.mem.Allocator, name: u21, value: []const u8) Outcome { const live = ed.thaw(a, null) catch return .{ .refused = .out_of_memory }; live.registers.put(a, name, value, 0, 1, true) catch return .{ .refused = .out_of_memory }; return ed.keep(a, live, .done); } fn thaw(ed: *const Self, a: std.mem.Allocator, syn: ?*Syntax) error{OutOfMemory}!*Live { const live = try a.create(Live); live.* = .{ .text = .{ .what = .body, .own = try ed.bytes(a), .gpa = a }, .syntax = syn }; if (syn) |s| s.at(ed.revision); const t = &live.text; inline for (@typeInfo(Cursor).@"struct".field_names) |name| @field(t, name) = @field(ed.cursor, name); if (ed.cursor.nsel > 0) { t.sels = try a.alloc(Text.SelRange, Text.max_selections - 1); @memcpy(t.sels[0..ed.cursor.nsel], ed.sels[0..ed.cursor.nsel]); } // Of the histories, what one key can reach: the snapshot an // undo goes back to (or a new one is compared with), and the // two newest a redo has, which tell a redo (one gone) from // an edit forgetting them (both). if (ed.undo.count > 0) { t.ed_undo[0] = snapOf(try ed.undo.get(a, 0)); t.ed_undo_len = 1; live.undo_thawed = 1; live.undo_from[0] = textPtr(t.ed_undo[0]); } const nr = @min(ed.redo.count, 2); for (0..nr) |i| { t.ed_redo[i] = snapOf(try ed.redo.get(a, @intCast(nr - 1 - i))); live.redo_from[i] = textPtr(t.ed_redo[i]); } t.ed_redo_len = nr; live.redo_thawed = nr; try ed.readRegisters(a, &live.registers); return live; } fn readRegisters(ed: *const Self, a: std.mem.Allocator, r: *Registers) error{OutOfMemory}!void { r.last_search = ed.last_search; var at: usize = 0; const b = ed.registers[0..ed.registers_len]; while (at < b.len) { const name: u21 = @intCast(std.mem.readInt(u32, b[at..][0..4], .little)); const n = std.mem.readInt(u32, b[at + 4 ..][0..4], .little); at += 8; const values = try a.alloc([]u8, n); for (values) |*v| { const l = std.mem.readInt(u32, b[at..][0..4], .little); v.* = try a.dupe(u8, b[at + 4 ..][0..l]); at += 4 + l; } try r.list.append(a, .{ .name = name, .values = values }); } } /// How many of `thawed` snapshots are still at the bottom of /// `now`, in order. fn kept(from: []const ?[*]const u8, now: []const Text.Snapshot) usize { var k: usize = 0; while (k < from.len and k < now.len and textPtr(now[k]) == from[k]) k += 1; return k; } /// Freeze what the key made back into `ed`: all of it fits, or /// none of it is written and the key is refused. fn keep(ed: *Self, a: std.mem.Allocator, live: *Live, out: Outcome) Outcome { const t = &live.text; if (live.failed) return .{ .refused = .out_of_memory }; const text = t.own orelse ""; if (text.len > cap.text) return .{ .refused = .text_full }; if (t.nsel > cap.selections - 1) return .{ .refused = .selections_full }; var regs: std.ArrayList(u8) = .empty; for (live.registers.list.items) |reg| { var w: [4]u8 = undefined; std.mem.writeInt(u32, &w, reg.name, .little); regs.appendSlice(a, &w) catch return .{ .refused = .out_of_memory }; std.mem.writeInt(u32, &w, @intCast(reg.values.len), .little); regs.appendSlice(a, &w) catch return .{ .refused = .out_of_memory }; for (reg.values) |v| { std.mem.writeInt(u32, &w, @intCast(v.len), .little); regs.appendSlice(a, &w) catch return .{ .refused = .out_of_memory }; regs.appendSlice(a, v) catch return .{ .refused = .out_of_memory }; } } if (regs.items.len > cap.registers) return .{ .refused = .registers_full }; const undo_kept = kept(live.undo_from[0..live.undo_thawed], t.ed_undo[0..t.ed_undo_len]); const redo_kept = kept(live.redo_from[0..live.redo_thawed], t.ed_redo[0..t.ed_redo_len]); var undo_new: [Text.history_max][]u8 = undefined; var redo_new: [Text.history_max][]u8 = undefined; for (t.ed_undo[undo_kept..t.ed_undo_len], 0..) |s, i| undo_new[i] = snapBytes(a, s) catch return .{ .refused = .out_of_memory }; for (t.ed_redo[redo_kept..t.ed_redo_len], 0..) |s, i| redo_new[i] = snapBytes(a, s) catch return .{ .refused = .out_of_memory }; const nu = t.ed_undo_len - undo_kept; const nr = t.ed_redo_len - redo_kept; // Everything fits: write it. const old = ed.bytes(a) catch return .{ .refused = .out_of_memory }; if (!std.mem.eql(u8, old, text)) { // ponytail: O(text) a key, the text compared and placed // whole; a DSL of a few KiB does not notice. The way up is // one Buffer under File and the library (the survey's R3): // the splice journal and line index pardes has for files. var head: usize = 0; while (head < old.len and head < text.len and old[head] == text[head]) head += 1; var tail: usize = 0; while (tail < old.len - head and tail < text.len - head and old[old.len - 1 - tail] == text[text.len - 1 - tail]) tail += 1; // the gap goes where the edit ended const front = text.len - tail; @memcpy(ed.text[0..front], text[0..front]); @memcpy(ed.text[cap.text - tail ..], text[front..]); ed.front = @intCast(front); ed.back = @intCast(tail); ed.revision +%= 1; } inline for (@typeInfo(Cursor).@"struct".field_names) |name| @field(ed.cursor, name) = @field(t, name); @memcpy(ed.sels[0..t.nsel], t.sels[0..t.nsel]); if (live.undo_thawed > undo_kept) ed.undo.pop(); for (undo_new[0..nu]) |s| ed.undo.push(s); // both thawed redos gone: an edit forgot them all if (live.redo_thawed == 2 and redo_kept == 0) ed.redo.clear() else for (redo_kept..live.redo_thawed) |_| ed.redo.pop(); for (redo_new[0..nr]) |s| ed.redo.push(s); @memcpy(ed.registers[0..regs.items.len], regs.items); ed.registers_len = @intCast(regs.items.len); ed.last_search = live.registers.last_search; return out; } }; } /// A text's parse, made again from its bytes and a `Language` when the /// text has changed: derived, never stored (a tree holds pointers into /// the grammar's code, which a reload unloads). Drop it (`forget`) at a /// reload. pub const Syntax = struct { tree: ?*syntax.ts.Tree = null, revision: u32 = 0, /// The grammar the tree is parsed in: the last `parse`'s, or set by a /// caller that hands this to `key` before parsing. None, and a walk /// does nothing, as in a text without a grammar. lang: ?Language = null, /// helix's object_selections, what Alt-o grew from for Alt-i to go back /// to (normal.nodeSelect): the tree's, dropped with it. In the page /// allocator, which holds nothing of the code that made it. history: std.ArrayList(Context.NodeStep) = .empty, path: [64]u8 = undefined, /// The tree of `ed`'s text in `lang`, parsed again when the text has /// changed since the last; null when the language cannot parse. pub fn parse(s: *Syntax, a: std.mem.Allocator, ed: anytype, lang: Language) ?*syntax.ts.Tree { s.lang = lang; s.at(ed.revision); if (s.tree == null) _ = s.walkTree(ed.bytes(a) catch return null); return s.tree; } /// What is kept of another revision of the text dropped: the tree and /// Alt-o's history. fn at(s: *Syntax, revision: u32) void { if (s.revision == revision) return; s.drop(); s.revision = revision; } fn drop(s: *Syntax) void { if (s.tree) |tree| tree.destroy(); s.tree = null; for (s.history.items) |step| std.heap.page_allocator.free(step.ranges); s.history.clearAndFree(std.heap.page_allocator); } /// The parse of `text`, the text at `revision`, as a key's walks read /// it (normal.nodeTree): made the first time one asks for it. pub fn walkTree(s: *Syntax, text: []const u8) ?Context.Tree { const lang = s.lang orelse return null; const path = lang.path(&s.path); if (s.tree == null) { if (!syntax_impl.addLanguage(lang)) return null; s.tree = @ptrCast(@alignCast(syntax_impl.parseTree(path, text, null) orelse return null)); } return .{ .root = s.tree.?, .path = path, .history = &s.history, .gpa = std.heap.page_allocator }; } /// One `Syn` a byte of `ed`'s text from `from` to `to`, in `a`. pub fn colors(a: std.mem.Allocator, ed: anytype, lang: Language, from: usize, to: usize) ![]syntax.Syn { const text = try ed.bytes(a); if (!syntax_impl.addLanguage(lang)) return error.TooManyLanguages; var buf: [64]u8 = undefined; return @ptrCast(try syntax_impl.highlightFileRange(a, lang.path(&buf), text, from, to)); } /// The tree gone, and every language handed in (at a reload: their /// code is about to go). pub fn forget(s: *Syntax) void { s.drop(); s.* = .{}; syntax_impl.forgetLanguages(); } };