From 7e8e2655567cab1c28597f44d0aec79e46b0deb8 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 29 Sep 2026 22:31:27 -0300 Subject: Zig files go to zls as a child process through the protocol client, as every other language does: the in-process ZLS backend goes lsp_zls.zig (1,522 lines), the zls dependency, build.zig's zls wiring and the import graph it baked into the options only for it, and main.zig's reference go. lsp_client's table gains a zls row (PARDES_LSP_ZIG overrides it); Hover, Rename, Diagnostics, WsSymbols, Lspinfo and gd answer through it (checked with lspprobe and the snapshots against zls 0.16.1-dev). What changes for a user: zls must be on PATH; a completion's rows are zls's candidates at the cursor, where the linked analyser gave each one's declaration; document symbols carry no signature. The Zig snapshots (lsp, lspcomplete, lspcompletemoved, lspdebug, lsprelpath) run the real zls now: lspdebug reads the client's explain and report, lsprelpath spells gr's rows where it spelled a completion's, and their goldens are recorded again (stable over three runs). Lspinfo still opens with its backend line. The ReleaseFast tty binary is 105.35 MB to 96.28 MB, the Debug one 296.5 MB to 245.9 MB. docs/lsp.md, web.md, design.typ and the README say so. Co-Authored-By: Claude Opus 5.5 --- docs/lsp.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/lsp.md') diff --git a/docs/lsp.md b/docs/lsp.md index 82586344..ae350156 100644 --- a/docs/lsp.md +++ b/docs/lsp.md @@ -1,8 +1,9 @@ # Language intelligence Native hosts, including detached sessions, run language queries on workers. -Zig uses the linked ZLS analyser; other languages use the protocol client in -`src/lsp/lsp_client.zig`. Web and board builds have no language backend. +Every language, Zig included, goes through the protocol client in +`src/lsp/lsp_client.zig`, which runs its server as a child process: Zig's is +`zls`, which must be on PATH. Web and board builds have no language backend. `Lspinfo` (`SPC l i`) reports backend versions, server state, capabilities, recent timings and errors. `Lspwhy` (`SPC l w`) traces resolution at the cursor. @@ -37,14 +38,13 @@ without starting a query. Formatting and same-file rename apply as one undo transaction. A workspace rename spanning other files opens a preview; it does not partially apply the -rename. The linked Zig analyser resolves current-file references and relative -imports, but does not run the build runner to discover dependency modules. +rename. ## Configuration and testing -`PARDES_LSP_RS`, `_C`, `_GO`, `_TS` and `_PY` override the server executable -for each language. An empty value disables that server. `ZIG_LIB_DIR` overrides -the stdlib path recorded at build time. `Lspinfo` shows the effective settings. +`PARDES_LSP_ZIG`, `_RS`, `_C`, `_GO`, `_TS` and `_PY` override the server +executable for each language. An empty value disables that server. `Lspinfo` +shows the effective settings. The protocol client keeps one child server per configured language, negotiates position encoding, and handles both push and pull diagnostics. Startup and @@ -52,8 +52,9 @@ request waits have deadlines; failed starts back off before retrying. Worker status messages reach the host event queue. `zig build lspprobe -- gd :` queries the same backend from -the command line. `zig build lspbench` measures it. Snapshot tests use a Zig -mock server with deterministic answers while exercising the real client, +the command line. `zig build lspbench` measures it. The Zig snapshot tests +(lsp, lspcomplete, lspdebug and the rest) run the real `zls`; the protocol +ones use a Zig mock server with deterministic answers while exercising the real client, including process startup, framing, edits and undo. `zig build fs-test` also checks language-worker delivery in TTY and detached sessions over 9P. -- cgit v1.3 From b1485c97b493f7eaf65c6afdfb82e3065306b8fe Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 29 Sep 2026 22:58:53 -0300 Subject: The PDF benches share their clock, fatal exit, hash, count parser and effect drain, and lspprobe is lspbench's probe subcommand B4: test/bench_util.zig holds what pdf_bench, pdf_pointer_bench, pdf_scroll_bench and pdf_sections_bench each copied (nowNs x4, fatal x3 named per bench, mix x3, parsePositive/parseCount x3, drainEffects x2). They stay four entry points: pdf_bench links its own mupdf module (with its C source and c_heap) where the others link the core's, which one executable cannot import under one name, and their reports and identities are each bench's own. pdf_sections_bench had rotted since the pane's cursor and selections moved to its body and the render revision became next_raster_revision; it builds and runs again. C6: tools/lspprobe.zig is lspbench's `probe` subcommand (zig build lspbench -- probe :), and the lspprobe build step goes; docs/lsp.md names the new command. Co-Authored-By: Claude Opus 5.5 --- build.zig | 16 +--- docs/lsp.md | 2 +- test/bench_util.zig | 43 +++++++++++ test/lspbench.zig | 169 ++++++++++++++++++++++++++++++++++++++++ test/pdf_bench.zig | 23 ++---- test/pdf_pointer_bench.zig | 14 +--- test/pdf_scroll_bench.zig | 43 +++-------- test/pdf_sections_bench.zig | 65 +++++----------- tools/lspprobe.zig | 184 -------------------------------------------- 9 files changed, 251 insertions(+), 308 deletions(-) create mode 100644 test/bench_util.zig delete mode 100644 tools/lspprobe.zig (limited to 'docs/lsp.md') diff --git a/build.zig b/build.zig index fcb4b0b7..eef05b44 100644 --- a/build.zig +++ b/build.zig @@ -1370,7 +1370,7 @@ pub fn build(b: *std.Build) void { if (b.args) |args| run_lspbench.addArgs(args); run_lspbench.setCwd(b.path(".")); run_lspbench.has_side_effects = true; - const lspbench_step = b.step("lspbench", "language-backend latency + feature matrix (-- [--json] [--check] [repo-root])"); + const lspbench_step = b.step("lspbench", "language-backend latency + feature matrix (-- [--json] [--check] [repo-root]), or one query (-- probe : [arg] [--reps N])"); lspbench_step.dependOn(&run_lspbench.step); const run_lspbench_check = b.addRunArtifact(lspbench); run_lspbench_check.addArg("--check"); @@ -1380,20 +1380,6 @@ pub fn build(b: *std.Build) void { const lspbench_check_step = b.step("lspbench-check", "require every configured language probe to complete correctly"); lspbench_check_step.dependOn(&run_lspbench_check.step); - const lspprobe = b.addExecutable(.{ - .name = "pardes-lspprobe", - .root_module = b.createModule(.{ - .target = target, - .optimize = optimize, - .root_source_file = b.path("tools/lspprobe.zig"), - .link_libc = true, - }), - }); - lspprobe.root_module.addImport("pardes", core_module); - const run_lspprobe = b.addRunArtifact(lspprobe); - if (b.args) |args| run_lspprobe.addArgs(args); - const lspprobe_step = b.step("lspprobe", "one language query against the real seam (-- : [arg] [--reps N])"); - lspprobe_step.dependOn(&run_lspprobe.step); const locations_bench_step = b.step("locations-bench", "measure cold/warm result formatting (-Doptimize=ReleaseFast; CSV on stderr)"); if (optimize != .ReleaseFast) { diff --git a/docs/lsp.md b/docs/lsp.md index ae350156..22cf1b90 100644 --- a/docs/lsp.md +++ b/docs/lsp.md @@ -51,7 +51,7 @@ position encoding, and handles both push and pull diagnostics. Startup and request waits have deadlines; failed starts back off before retrying. Worker status messages reach the host event queue. -`zig build lspprobe -- gd :` queries the same backend from +`zig build lspbench -- probe gd :` queries the same backend from the command line. `zig build lspbench` measures it. The Zig snapshot tests (lsp, lspcomplete, lspdebug and the rest) run the real `zls`; the protocol ones use a Zig mock server with deterministic answers while exercising the real client, diff --git a/test/bench_util.zig b/test/bench_util.zig new file mode 100644 index 00000000..9b91e621 --- /dev/null +++ b/test/bench_util.zig @@ -0,0 +1,43 @@ +//! What the PDF benches share: a clock, a fatal exit named for the bench, a +//! seeded hash, a count parser and the core's effect drain. +const std = @import("std"); + +pub fn nowNs() u64 { + var ts: std.c.timespec = undefined; + _ = std.c.clock_gettime(.MONOTONIC, &ts); + return @as(u64, @intCast(ts.sec)) *| 1_000_000_000 +| @as(u64, @intCast(ts.nsec)); +} + +/// `fatal` for the bench called `who`: says so, prefixed, and exits 1. +pub fn Fatal(comptime who: []const u8) type { + return struct { + pub fn f(comptime format: []const u8, args: anytype) noreturn { + std.debug.print(who ++ ": " ++ format ++ "\n", args); + std.process.exit(1); + } + }; +} + +/// A seeded hash of `value`'s bytes; a comptime integer hashes as a u64. +pub fn mix(seed: u64, value: anytype) u64 { + const Value = @TypeOf(value); + const Stable = switch (@typeInfo(Value)) { + .comptime_int => u64, + else => Value, + }; + var stable: Stable = value; + return std.hash.Wyhash.hash(seed, std.mem.asBytes(&stable)); +} + +/// A flag's value as a count in 1..`maximum`, or `fatal` saying why not. +pub fn parsePositive(comptime fatal: anytype, name: []const u8, text: []const u8, maximum: usize) usize { + const value = std.fmt.parseUnsigned(usize, text, 10) catch + fatal("{s} expects a positive integer", .{name}); + if (value == 0 or value > maximum) + fatal("{s} must be in 1..{d}", .{ name, maximum }); + return value; +} + +pub fn drainEffects(core: anytype) void { + while (core.nextEffect()) |_| {} +} diff --git a/test/lspbench.zig b/test/lspbench.zig index e094ed69..02138d24 100644 --- a/test/lspbench.zig +++ b/test/lspbench.zig @@ -114,6 +114,7 @@ pub fn main(init: std.process.Init) !void { const gpa = std.heap.page_allocator; const args = try init.minimal.args.toSlice(init.arena.allocator()); + if (args.len > 1 and std.mem.eql(u8, args[1], "probe")) return probeCommand(init); const options = try Options.parse(args[1..]); const rss0 = rssKib(); @@ -295,3 +296,171 @@ fn rssKib() u64 { } return 0; } + +// ---- probe: one query from the command line ---- + +fn nowUs() u64 { + var ts: std.c.timespec = undefined; + _ = std.c.clock_gettime(.MONOTONIC, &ts); + return @as(u64, @intCast(ts.sec)) *| 1_000_000 +| @as(u64, @intCast(ts.nsec)) / 1000; +} + +const aliases = .{ + .{ "gd", lsp.Kind.definition }, + .{ "gD", lsp.Kind.declaration }, + .{ "gy", lsp.Kind.type_definition }, + .{ "gi", lsp.Kind.implementation }, + .{ "gr", lsp.Kind.references }, +}; + +fn probeUsage() noreturn { + std.debug.print( + \\usage: pardes-lspbench probe : [arg] [--reps N] [--warm S] + \\ kind: gd gD gy gi gr, or any lsp.Kind tag (hover, references, + \\ document_symbols, workspace_symbols, incoming_calls, ...) + \\ arg: the new name for rename, the query for workspace_symbols + \\ --warm sleep S seconds after the first (cold) query — long enough + \\ for an indexing server to reach ready, narrated on stderr + \\ + , .{}); + std.process.exit(2); +} + +/// The editor's message row, here: the client's reader threads narrate server +/// state through the same sink the shells register, printed to stderr so the +/// rows on stdout stay clean. +fn statusSink(ctx: ?*anyopaque, text: []const u8) void { + _ = ctx; + std.debug.print("# status: {s}\n", .{text}); +} + +extern "c" fn usleep(usec: c_uint) c_int; + +/// `lspbench probe`: one language query against the real seam, from the +/// command line (the old lspprobe): `probe : [arg] +/// [--reps N] [--warm S]`, rows on stdout, the timing on stderr. +fn probeCommand(init: std.process.Init) !void { + const gpa = std.heap.page_allocator; + const arena = init.arena.allocator(); + const io = std.Io.Threaded.global_single_threaded.io(); + + // args[1] is `probe`: the rest are where lspprobe's were. + const all = try init.minimal.args.toSlice(arena); + const args = all[1..]; + if (args.len < 4) probeUsage(); + + // comma-separated kinds share ONE server instance and its index — the + // whole battery against a big workspace pays the cold cost once + var kinds: [16]lsp.Kind = undefined; + var nkinds: usize = 0; + var kit = std.mem.tokenizeScalar(u8, args[1], ','); + while (kit.next()) |word| { + if (nkinds == kinds.len) probeUsage(); + kinds[nkinds] = blk: { + inline for (aliases) |a| if (std.mem.eql(u8, word, a[0])) break :blk a[1]; + break :blk std.meta.stringToEnum(lsp.Kind, word) orelse probeUsage(); + }; + nkinds += 1; + } + if (nkinds == 0) probeUsage(); + + var pz: [4096:0]u8 = undefined; + const pz_s = std.fmt.bufPrintSentinel(&pz, "{s}", .{args[2]}, 0) catch probeUsage(); + var realbuf: [4096]u8 = undefined; + const path = std.mem.span(realpath(pz_s.ptr, &realbuf) orelse { + std.debug.print("cannot resolve {s}\n", .{args[2]}); + std.process.exit(1); + }); + const source = std.Io.Dir.cwd().readFileAllocOptions( + io, + path, + arena, + .limited(64 << 20), + .of(u8), + 0, + ) catch { + std.debug.print("cannot read {s}\n", .{path}); + std.process.exit(1); + }; + + const colon = std.mem.indexOfScalar(u8, args[3], ':') orelse probeUsage(); + const line = std.fmt.parseInt(u32, args[3][0..colon], 10) catch probeUsage(); + const col = std.fmt.parseInt(u32, args[3][colon + 1 ..], 10) catch probeUsage(); + if (line == 0 or col == 0) probeUsage(); + + var arg: []const u8 = ""; + var reps: u32 = 1; + var warm_s: u32 = 0; + var i: usize = 4; + while (i < args.len) : (i += 1) { + if (std.mem.eql(u8, args[i], "--reps")) { + i += 1; + if (i >= args.len) probeUsage(); + reps = @max(1, std.fmt.parseInt(u32, args[i], 10) catch probeUsage()); + } else if (std.mem.eql(u8, args[i], "--warm")) { + i += 1; + if (i >= args.len) probeUsage(); + warm_s = std.fmt.parseInt(u32, args[i], 10) catch probeUsage(); + } else arg = args[i]; + } + + lsp.setStatusSink(null, statusSink); + + // 1-based line:col -> byte offset + var off: usize = 0; + var ln: u32 = 1; + while (ln < line and off < source.len) : (off += 1) { + if (source[off] == '\n') ln += 1; + } + off = @min(off + col - 1, source.len); + + const root = std.fs.path.dirname(path) orelse "/"; + const timings = try arena.alloc(u64, reps); + var stdout_buf: [64 * 1024]u8 = undefined; + var stdout = std.Io.File.stdout().writer(io, &stdout_buf); + var first_query = true; + + for (kinds[0..nkinds]) |kind| { + var rows: []const u8 = ""; + for (0..reps) |r| { + // one warm pause for the whole battery, right after the very + // first (cold, server-spawning) query — the status lines on + // stderr narrate what the server does with the time + var out: std.Io.Writer.Allocating = .init(gpa); + defer out.deinit(); + var scratch: std.heap.ArenaAllocator = .init(gpa); + defer scratch.deinit(); + const t0 = nowUs(); + try lsp.query(gpa, scratch.allocator(), .{ + .kind = kind, + .path = path, + .source = source, + .offset = @intCast(off), + .arg = arg, + .root = root, + }, &out.writer); + timings[r] = nowUs() -| t0; + rows = try arena.dupe(u8, out.written()); + if (first_query) { + first_query = false; + if (warm_s > 0) for (0..warm_s * 10) |_| { + _ = usleep(100_000); + }; + } + } + + try stdout.interface.print("## {t}\n", .{kind}); + try stdout.interface.writeAll(rows); + try stdout.interface.flush(); + + const n = std.mem.count(u8, rows, "\n"); + const cold = timings[0]; + std.mem.sort(u64, timings[0..reps], {}, std.sort.asc(u64)); + if (reps == 1) + std.debug.print("# {t}: {d} row(s) in {d}us\n", .{ kind, n, cold }) + else + std.debug.print("# {t}: {d} row(s); first {d}us, min {d}us, median {d}us ({d} reps)\n", .{ + kind, n, cold, timings[0], timings[reps / 2], reps, + }); + } +} diff --git a/test/pdf_bench.zig b/test/pdf_bench.zig index 0f09f72a..23565106 100644 --- a/test/pdf_bench.zig +++ b/test/pdf_bench.zig @@ -13,6 +13,9 @@ //! filesystem cache is deliberately uncontrolled), while warm scenarios //! retain one Document. const std = @import("std"); +const bench_util = @import("bench_util.zig"); +const nowNs = bench_util.nowNs; +const fatal = bench_util.Fatal("pdf-bench").f; const pdf = @import("mupdf"); pub const std_options: std.Options = .{ .log_level = .err }; @@ -205,14 +208,6 @@ fn parseArgs(args: []const []const u8) Config { return config; } -fn parsePositive(name: []const u8, text: []const u8, maximum: usize) usize { - const value = std.fmt.parseUnsigned(usize, text, 10) catch - fatal("{s} expects a positive integer", .{name}); - if (value == 0 or value > maximum) - fatal("{s} must be in 1..{d}", .{ name, maximum }); - return value; -} - fn usage() noreturn { printUsage(); std.process.exit(2); @@ -226,13 +221,6 @@ fn printUsage() void { ); } -fn nowNs() u64 { - var ts: std.c.timespec = undefined; - _ = std.c.clock_gettime(.MONOTONIC, &ts); - return @as(u64, @intCast(ts.sec)) *| 1_000_000_000 +| - @as(u64, @intCast(ts.nsec)); -} - fn measure( config: Config, profile_index: usize, @@ -617,7 +605,6 @@ fn reportJson( std.Io.File.stdout().writeStreamingAll(io, out.buffered()) catch {}; } -fn fatal(comptime format: []const u8, args: anytype) noreturn { - std.debug.print("pdf-bench: " ++ format ++ "\n", args); - std.process.exit(1); +fn parsePositive(name: []const u8, text: []const u8, maximum: usize) usize { + return bench_util.parsePositive(fatal, name, text, maximum); } diff --git a/test/pdf_pointer_bench.zig b/test/pdf_pointer_bench.zig index f1d61229..ae2de2f5 100644 --- a/test/pdf_pointer_bench.zig +++ b/test/pdf_pointer_bench.zig @@ -15,6 +15,9 @@ //! frame each step settles on. It is the no-regression proof: a change to how highlights //! are painted may change what it costs, never one presented pixel. const std = @import("std"); +const bench_util = @import("bench_util.zig"); +const nowNs = bench_util.nowNs; +const mix = bench_util.mix; const pardes = @import("pardes"); const pdf = @import("mupdf"); @@ -208,17 +211,6 @@ fn print(comptime format: []const u8, args: anytype) void { _ = std.c.write(1, line.ptr, line.len); } -fn mix(seed: u64, value: anytype) u64 { - var copy = value; - return std.hash.Wyhash.hash(seed, std.mem.asBytes(©)); -} - -fn nowNs() u64 { - var ts: std.c.timespec = undefined; - _ = std.c.clock_gettime(.MONOTONIC, &ts); - return @as(u64, @intCast(ts.sec)) * 1_000_000_000 + @as(u64, @intCast(ts.nsec)); -} - comptime { _ = pdf.Document; } diff --git a/test/pdf_scroll_bench.zig b/test/pdf_scroll_bench.zig index 33dfe70a..a4511dbe 100644 --- a/test/pdf_scroll_bench.zig +++ b/test/pdf_scroll_bench.zig @@ -42,6 +42,11 @@ //! //! Setup, teardown, checksumming, and reporting are outside every timer. const std = @import("std"); +const bench_util = @import("bench_util.zig"); +const nowNs = bench_util.nowNs; +const fatal = bench_util.Fatal("pdf-scroll-bench").f; +const mix = bench_util.mix; +const drainEffects = bench_util.drainEffects; const libc = std.c; const pardes = @import("pardes"); const pdf = @import("mupdf"); @@ -211,14 +216,6 @@ fn parseArgs(args: []const []const u8) Config { return config; } -fn parseCount(flag: []const u8, text: []const u8) usize { - const value = std.fmt.parseUnsigned(usize, text, 10) catch - fatal("{s} expects a positive integer", .{flag}); - if (value == 0 or value > 10_000) - fatal("{s} must be in 1..10000", .{flag}); - return value; -} - const Travel = struct { /// Scrollable display pixels: the whole strip minus one screenful. max_scroll: f64, @@ -520,20 +517,6 @@ fn stridedHash(seed: u64, rgba: []const u8) u64 { return hash; } -fn mix(seed: u64, value: anytype) u64 { - const Value = @TypeOf(value); - const Stable = switch (@typeInfo(Value)) { - .comptime_int => u64, - else => Value, - }; - var stable: Stable = value; - return std.hash.Wyhash.hash(seed, std.mem.asBytes(&stable)); -} - -fn drainEffects(core: *pardes.Pardes) void { - while (core.nextEffect()) |_| {} -} - fn verifyIdentity( name: []const u8, expected: *?Identity, @@ -557,13 +540,6 @@ fn verifyIdentity( } else expected.* = got; } -fn nowNs() u64 { - var ts: std.c.timespec = undefined; - _ = std.c.clock_gettime(.MONOTONIC, &ts); - return @as(u64, @intCast(ts.sec)) *| 1_000_000_000 +| - @as(u64, @intCast(ts.nsec)); -} - fn reportText(config: Config, travel: Travel, results: []const Result) void { std.debug.print("pardes PDF fast-scroll benchmark ({s})\n", .{bench_config.core_optimize}); std.debug.print( @@ -649,13 +625,12 @@ fn reportJson(io: std.Io, config: Config, travel: Travel, results: []const Resul std.Io.File.stdout().writeStreamingAll(io, out.buffered()) catch {}; } -fn fatal(comptime format: []const u8, args: anytype) noreturn { - std.debug.print("pdf-scroll-bench: " ++ format ++ "\n", args); - std.process.exit(1); -} - comptime { // The bench links the real MuPDF wrapper the core uses; keep the import // load-bearing so a build that silently dropped it fails here. _ = pdf.Document; } + +fn parseCount(flag: []const u8, text: []const u8) usize { + return bench_util.parsePositive(fatal, flag, text, 10_000); +} diff --git a/test/pdf_sections_bench.zig b/test/pdf_sections_bench.zig index b08af552..92c9ef7c 100644 --- a/test/pdf_sections_bench.zig +++ b/test/pdf_sections_bench.zig @@ -9,6 +9,11 @@ //! report nanoseconds per operation; `operations_per_sample` makes that //! normalization explicit in both output formats. const std = @import("std"); +const bench_util = @import("bench_util.zig"); +const nowNs = bench_util.nowNs; +const fatal = bench_util.Fatal("pdf-sections-bench").f; +const mix = bench_util.mix; +const drainEffects = bench_util.drainEffects; const libc = std.c; const pardes = @import("pardes"); const pdf = @import("mupdf"); @@ -107,14 +112,6 @@ fn parseArgs(args: []const []const u8) Config { return config; } -fn parseCount(flag: []const u8, text: []const u8) usize { - const value = std.fmt.parseUnsigned(usize, text, 10) catch - fatal("{s} expects a positive integer", .{flag}); - if (value == 0 or value > 10_000) - fatal("{s} must be in 1..10000", .{flag}); - return value; -} - fn measureOutline(path: []const u8, config: Config) !Result { const samples = try gpa.alloc(u64, config.reps); defer gpa.free(samples); @@ -145,7 +142,7 @@ fn measureMaterialize( var expected: ?Identity = null; for (0..config.warmup + config.reps) |round| { const started = nowNs(); - const content = try pardes.PdfSectionRows.render(gpa, path, entries); + const content = try pardes.panes.Pdf.SectionRows.render(gpa, path, entries); const elapsed = nowNs() -| started; const identity = contentIdentity(content); gpa.free(content); @@ -255,7 +252,7 @@ fn measureWorstShape(entries: []const pdf.OutlineEntry, config: Config) !Result var expected: ?Identity = null; for (0..config.warmup + config.reps) |round| { const started = nowNs(); - const content = try pardes.PdfSectionRows.render(gpa, "/tmp/near-limit.pdf", entries); + const content = try pardes.panes.Pdf.SectionRows.render(gpa, "/tmp/near-limit.pdf", entries); const elapsed = nowNs() -| started; const identity = contentIdentity(content); gpa.free(content); @@ -300,11 +297,11 @@ fn perturbReopen(prepared: PreparedReopen, operation: usize) void { const marker: i32 = @intCast(operation % 31 + 1); const output_file = &prepared.output.file.?; output_file.scroll = @intCast(operation % 17 + 1); - prepared.output.cur_row = marker; - prepared.output.cur_col = marker + 1; - prepared.output.msel.active = true; - prepared.output.vsel.active = true; - prepared.output.nsel = 1; + prepared.output.body.cur_row = marker; + prepared.output.body.cur_col = marker + 1; + prepared.output.body.msel.active = true; + prepared.output.body.vsel.active = true; + prepared.output.body.nsel = 1; prepared.owner.search_pane = null; prepared.owner.search_row = operation % 23; prepared.core.active = prepared.output_id; @@ -313,21 +310,17 @@ fn perturbReopen(prepared: PreparedReopen, operation: usize) void { fn observeReopen(prepared: PreparedReopen) u64 { const file = prepared.output.file.?; var observed: u64 = file.scroll; - observed = observed *% 131 +% @as(u64, @intCast(@max(0, prepared.output.cur_row))); - observed = observed *% 131 +% @as(u64, @intCast(@max(0, prepared.output.cur_col))); - observed = observed *% 131 +% @intFromBool(prepared.output.msel.active); - observed = observed *% 131 +% @intFromBool(prepared.output.vsel.active); - observed = observed *% 131 +% prepared.output.nsel; + observed = observed *% 131 +% @as(u64, @intCast(@max(0, prepared.output.body.cur_row))); + observed = observed *% 131 +% @as(u64, @intCast(@max(0, prepared.output.body.cur_col))); + observed = observed *% 131 +% @intFromBool(prepared.output.body.msel.active); + observed = observed *% 131 +% @intFromBool(prepared.output.body.vsel.active); + observed = observed *% 131 +% prepared.output.body.nsel; observed = observed *% 131 +% (prepared.owner.search_pane orelse std.math.maxInt(usize)); observed = observed *% 131 +% (prepared.owner.search_row orelse std.math.maxInt(usize)); observed = observed *% 131 +% prepared.core.active; return observed; } -fn drainEffects(core: *pardes.Pardes) void { - while (core.nextEffect()) |_| {} -} - fn sectionsOutputIdentity(core: *pardes.Pardes) Identity { const owner = core.panes[0] orelse fatal("PDF pane disappeared", .{}); const output_id = owner.search_pane orelse fatal("+PdfSections was not armed", .{}); @@ -347,7 +340,7 @@ fn stepIdentity(core: *pardes.Pardes) Identity { identity.checksum = mix(identity.checksum, view.page); identity.checksum = mix(identity.checksum, @as(u64, @bitCast(view.document_scroll_y))); identity.checksum = mix(identity.checksum, owner.search_row orelse std.math.maxInt(usize)); - identity.checksum = mix(identity.checksum, view.render_revision); + identity.checksum = mix(identity.checksum, view.next_raster_revision); return identity; } @@ -389,16 +382,6 @@ fn outlineIdentity(entries: []const pdf.OutlineEntry) Identity { return .{ .items = entries.len, .bytes = bytes, .checksum = checksum }; } -fn mix(seed: u64, value: anytype) u64 { - const Value = @TypeOf(value); - const Stable = switch (@typeInfo(Value)) { - .comptime_int => u64, - else => Value, - }; - var stable: Stable = value; - return std.hash.Wyhash.hash(seed, std.mem.asBytes(&stable)); -} - fn makeWorstShape() ![]pdf.OutlineEntry { const entries = try gpa.alloc(pdf.OutlineEntry, near_limit_items); for (entries, 0..) |*entry, ordinal| { @@ -457,13 +440,6 @@ fn summarize( }; } -fn nowNs() u64 { - var ts: std.c.timespec = undefined; - _ = std.c.clock_gettime(.MONOTONIC, &ts); - return @as(u64, @intCast(ts.sec)) *| 1_000_000_000 +| - @as(u64, @intCast(ts.nsec)); -} - /// A host benchmark compiler barrier. MuPDF benchmarks are build-and-run /// steps, so they never target the freestanding web backend; an empty volatile /// asm with only the abstract memory clobber is valid on every native backend @@ -545,7 +521,6 @@ fn unlink(path: []const u8) void { _ = libc.unlink(path_z); } -fn fatal(comptime format: []const u8, args: anytype) noreturn { - std.debug.print("pdf-sections-bench: " ++ format ++ "\n", args); - std.process.exit(1); +fn parseCount(flag: []const u8, text: []const u8) usize { + return bench_util.parsePositive(fatal, flag, text, 10_000); } diff --git a/tools/lspprobe.zig b/tools/lspprobe.zig deleted file mode 100644 index 0b7d772c..00000000 --- a/tools/lspprobe.zig +++ /dev/null @@ -1,184 +0,0 @@ -//! One language query against the REAL seam, from the command line. -//! -//! pardes-lspprobe : [arg] [--reps N] -//! -//! `kind` is an `lsp.Kind` tag (`definition`, `references`, ...) or its helix -//! key (`gd`, `gr`, `gy`, `gi`, `gD`). Line and column are 1-based, the way -//! the rows print them. Rows go to stdout; the timing line goes to stderr so -//! `lspprobe gd f.rs 10:5 | head` still composes. -//! -//! This is the development probe for the PROTOCOL CLIENT: point it at a file -//! in any workspace (a rust crate, a C tree with compile_commands.json) and it -//! exercises exactly what `gd` in the editor would — same seam, same client, -//! same child server. The server is spawned fresh per invocation and kept for -//! the process, so rep 0 is the true cold cost (spawn + handshake + whatever -//! indexing the deadline allows) and later reps are the warm per-press cost. -//! Generic on purpose: no project names anywhere — the workspace is whatever -//! the file's root markers say. -const std = @import("std"); -const lsp = @import("pardes").lsp; - -extern "c" fn realpath(path: [*:0]const u8, resolved: [*]u8) ?[*:0]u8; - -pub const std_options: std.Options = .{ .log_level = .err }; - -fn nowUs() u64 { - var ts: std.c.timespec = undefined; - _ = std.c.clock_gettime(.MONOTONIC, &ts); - return @as(u64, @intCast(ts.sec)) *| 1_000_000 +| @as(u64, @intCast(ts.nsec)) / 1000; -} - -const aliases = .{ - .{ "gd", lsp.Kind.definition }, - .{ "gD", lsp.Kind.declaration }, - .{ "gy", lsp.Kind.type_definition }, - .{ "gi", lsp.Kind.implementation }, - .{ "gr", lsp.Kind.references }, -}; - -fn usage() noreturn { - std.debug.print( - \\usage: pardes-lspprobe : [arg] [--reps N] [--warm S] - \\ kind: gd gD gy gi gr, or any lsp.Kind tag (hover, references, - \\ document_symbols, workspace_symbols, incoming_calls, ...) - \\ arg: the new name for rename, the query for workspace_symbols - \\ --warm sleep S seconds after the first (cold) query — long enough - \\ for an indexing server to reach ready, narrated on stderr - \\ - , .{}); - std.process.exit(2); -} - -/// The editor's message row, here: the client's reader threads narrate server -/// state through the same sink the shells register, printed to stderr so the -/// rows on stdout stay clean. -fn statusSink(ctx: ?*anyopaque, text: []const u8) void { - _ = ctx; - std.debug.print("# status: {s}\n", .{text}); -} - -extern "c" fn usleep(usec: c_uint) c_int; - -pub fn main(init: std.process.Init) !void { - const gpa = std.heap.page_allocator; - const arena = init.arena.allocator(); - const io = std.Io.Threaded.global_single_threaded.io(); - - const args = try init.minimal.args.toSlice(arena); - if (args.len < 4) usage(); - - // comma-separated kinds share ONE server instance and its index — the - // whole battery against a big workspace pays the cold cost once - var kinds: [16]lsp.Kind = undefined; - var nkinds: usize = 0; - var kit = std.mem.tokenizeScalar(u8, args[1], ','); - while (kit.next()) |word| { - if (nkinds == kinds.len) usage(); - kinds[nkinds] = blk: { - inline for (aliases) |a| if (std.mem.eql(u8, word, a[0])) break :blk a[1]; - break :blk std.meta.stringToEnum(lsp.Kind, word) orelse usage(); - }; - nkinds += 1; - } - if (nkinds == 0) usage(); - - var pz: [4096:0]u8 = undefined; - const pz_s = std.fmt.bufPrintSentinel(&pz, "{s}", .{args[2]}, 0) catch usage(); - var realbuf: [4096]u8 = undefined; - const path = std.mem.span(realpath(pz_s.ptr, &realbuf) orelse { - std.debug.print("cannot resolve {s}\n", .{args[2]}); - std.process.exit(1); - }); - const source = std.Io.Dir.cwd().readFileAllocOptions( - io, - path, - arena, - .limited(64 << 20), - .of(u8), - 0, - ) catch { - std.debug.print("cannot read {s}\n", .{path}); - std.process.exit(1); - }; - - const colon = std.mem.indexOfScalar(u8, args[3], ':') orelse usage(); - const line = std.fmt.parseInt(u32, args[3][0..colon], 10) catch usage(); - const col = std.fmt.parseInt(u32, args[3][colon + 1 ..], 10) catch usage(); - if (line == 0 or col == 0) usage(); - - var arg: []const u8 = ""; - var reps: u32 = 1; - var warm_s: u32 = 0; - var i: usize = 4; - while (i < args.len) : (i += 1) { - if (std.mem.eql(u8, args[i], "--reps")) { - i += 1; - if (i >= args.len) usage(); - reps = @max(1, std.fmt.parseInt(u32, args[i], 10) catch usage()); - } else if (std.mem.eql(u8, args[i], "--warm")) { - i += 1; - if (i >= args.len) usage(); - warm_s = std.fmt.parseInt(u32, args[i], 10) catch usage(); - } else arg = args[i]; - } - - lsp.setStatusSink(null, statusSink); - - // 1-based line:col -> byte offset - var off: usize = 0; - var ln: u32 = 1; - while (ln < line and off < source.len) : (off += 1) { - if (source[off] == '\n') ln += 1; - } - off = @min(off + col - 1, source.len); - - const root = std.fs.path.dirname(path) orelse "/"; - const timings = try arena.alloc(u64, reps); - var stdout_buf: [64 * 1024]u8 = undefined; - var stdout = std.Io.File.stdout().writer(io, &stdout_buf); - var first_query = true; - - for (kinds[0..nkinds]) |kind| { - var rows: []const u8 = ""; - for (0..reps) |r| { - // one warm pause for the whole battery, right after the very - // first (cold, server-spawning) query — the status lines on - // stderr narrate what the server does with the time - var out: std.Io.Writer.Allocating = .init(gpa); - defer out.deinit(); - var scratch: std.heap.ArenaAllocator = .init(gpa); - defer scratch.deinit(); - const t0 = nowUs(); - try lsp.query(gpa, scratch.allocator(), .{ - .kind = kind, - .path = path, - .source = source, - .offset = @intCast(off), - .arg = arg, - .root = root, - }, &out.writer); - timings[r] = nowUs() -| t0; - rows = try arena.dupe(u8, out.written()); - if (first_query) { - first_query = false; - if (warm_s > 0) for (0..warm_s * 10) |_| { - _ = usleep(100_000); - }; - } - } - - try stdout.interface.print("## {t}\n", .{kind}); - try stdout.interface.writeAll(rows); - try stdout.interface.flush(); - - const n = std.mem.count(u8, rows, "\n"); - const cold = timings[0]; - std.mem.sort(u64, timings[0..reps], {}, std.sort.asc(u64)); - if (reps == 1) - std.debug.print("# {t}: {d} row(s) in {d}us\n", .{ kind, n, cold }) - else - std.debug.print("# {t}: {d} row(s); first {d}us, min {d}us, median {d}us ({d} reps)\n", .{ - kind, n, cold, timings[0], timings[reps / 2], reps, - }); - } -} -- cgit v1.3 From fb3f5ab5a7758a628a6e343f24a6510a58802599 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 30 Sep 2026 23:04:26 -0300 Subject: The guide walks a newcomer through pardes day to day, and the cheatsheet says what Esc and Shift-Esc really do Co-Authored-By: Claude Opus 5.5 --- docs/helix-keys.md | 8 +- docs/lsp.md | 73 ---------- docs/tags.md | 222 ----------------------------- docs/typ/cheatsheet.typ | 14 +- docs/typ/guide.typ | 303 ++++++++++++++++++++++++++++++++++++++++ docs/ui-review.md | 4 +- test/snapshots/find.snap | 2 +- test/snapshots/lspcomplete.snap | 2 +- 8 files changed, 317 insertions(+), 311 deletions(-) delete mode 100644 docs/lsp.md delete mode 100644 docs/tags.md create mode 100644 docs/typ/guide.typ (limited to 'docs/lsp.md') diff --git a/docs/helix-keys.md b/docs/helix-keys.md index b1035ad6..6249fc15 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -126,8 +126,8 @@ language-backend queries, and the shell pipe. | `Esc` (insert) | back to normal mode, cursor right after the insertion (no vim left-step) | | helix-verified | | `Enter` (normal) | acme **look** chord: EXPLICIT selection, else file-ish word under cursor | pardes-specific, keep (helix normal-mode Enter unbound). Covers helix `gf`. Implicit motion residue falls back to the cursor word | pardes-specific | | `Tab` (normal) | acme **execute** chord | pardes-specific, keep; explicit-selection rule as Enter | pardes-specific | -| `:` (normal, body or tag) | in the body, focuses the pane's tag in normal mode at its remembered cursor (the first time, on `Save`); in the tag, goes back to the body; in a column or workspace tag, back to the active pane. The tag's normal and insert modes ARE the body's: every motion, selection, edit and undo works there, and `0` goes to the line's start, the path's. Tab runs the word under the cursor or the selection and Enter looks it up (in a column or workspace tag Enter runs it too), and either hands the keyboard back to the body first. Clicks choose a new cursor position and type into the tag. | Each tag keeps its own cursor during the session. The computed path/marker/page is reachable and yankable but read-only: an edit into it is refused, and typing into a file's path drafts a new name. File-name changes are staged as described in [editable tags](tags.md). | pardes-specific | -| `Ctrl-w k` / `SPC w k` (pane with nothing above) | focuses its column's tag, then the workspace tag. `Ctrl-w j` walks back to the panes, `Ctrl-w h`/`l` walk the column tags. Headers edit exactly as a pane tag does. | Column commands target that column's active pane, or its first pane when coming from elsewhere. Workspace and column text are independently editable and persist in dumps. See [editable tags](tags.md). | pardes-specific | +| `:` (normal, body or tag) | in the body, focuses the pane's tag in normal mode at its remembered cursor (the first time, on `Save`); in the tag, goes back to the body; in a column or workspace tag, back to the active pane. The tag's normal and insert modes ARE the body's: every motion, selection, edit and undo works there, and `0` goes to the line's start, the path's. Tab runs the word under the cursor or the selection and Enter looks it up (in a column or workspace tag Enter runs it too), and either hands the keyboard back to the body first. Clicks choose a new cursor position and type into the tag. | Each tag keeps its own cursor during the session. The computed path/marker/page is reachable and yankable but read-only: an edit into it is refused, and typing into a file's path drafts a new name. File-name changes are staged as described in [editable tags](typ/guide.typ). | pardes-specific | +| `Ctrl-w k` / `SPC w k` (pane with nothing above) | focuses its column's tag, then the workspace tag. `Ctrl-w j` walks back to the panes, `Ctrl-w h`/`l` walk the column tags. Headers edit exactly as a pane tag does. | Column commands target that column's active pane, or its first pane when coming from elsewhere. Workspace and column text are independently editable and persist in dumps. See [editable tags](typ/guide.typ). | pardes-specific | | `Ctrl-w` + `h/j/k/l`/arrows | directional pane focus prefix — editor normal mode only | pardes' own window handling (helix window mode skipped, section C). Runs the SAME `Left`/`Down`/`Up`/`Right` builtins `SPC w h/j/k/l` runs; Raw **tty** mode forwards Ctrl-w to the child. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode it moves focus to the neighbour's BODY, as from a body, and from the top pane `Up` reaches the column and workspace tags | pardes-specific | | `Alt-n` | new terminal below (outside raw tty) | shadows helix `Alt-n` (select next sibling), which pardes spells `Alt-right` alone | pardes-specific | | `Alt-c` | move active terminal to a fresh column (outside raw tty) | helix `Alt-c` is change-noyank; the pardes window op wins (do-not-touch contract). `Alt-d` + `i` covers the behavior | waived (`alt-c-window-op`) | @@ -135,7 +135,7 @@ language-backend queries, and the shell pipe. | `SPC y` `SPC Y` `SPC p` `SPC P` `SPC R` | helix's clipboard menu on helix's own letters: yank the selection to the system clipboard (`ClipYank`) or the PRIMARY selection alone (`ClipYankMain`), paste the system clipboard after (`ClipPaste`) / before (`ClipPasteBefore`) the selection, replace the selection with it (`ClipReplace`) | the same as `"+y`, `"+p`, `"+P`, `"+R`: register `+` (and `*`) IS the desktop's clipboard, the only register that reaches it. `SPC y` writes `+` alone, as helix's does, not the default register too. Builtins rather than bare chords because a leader path names a builtin: they land in Help's index and are executable words like every other verb. The clipboard holds one text, so N values go out joined by newlines, as helix sends them. On a tty the write is OSC 52 out and the READ is OSC 52 back, which many terminals refuse or gate — so `SPC y` works there and `SPC p` can be a no-op | out of corpus | | a paste from the OUTER terminal | one `Event.paste`, spliced in at the cursor | the tty shell enables bracketed paste and coalesces `paste_start`..`paste_end` into a single event; before that the bytes arrived as individual key presses and normal mode RAN them, which is how a pasted `d` deleted a line. The bytes deliberately never enter the yank register — clipboard and default register are separate stores in both directions | pardes-specific | | `/` (any pane) | pardes' own plain-substring search into a `+Search` output buffer: the pattern is typed on a line of its own on the pane's notice band, Enter fills the buffer, and its rows are ordinary look targets. Enter also GOES to the first row — the buffer is focused and then the step `n` is and the look Enter is run in it (`Pardes.lookFirstHit`), so `/foo` lands on the first hit with the matched span selected. A pattern that matched nothing opens its empty buffer and moves nothing | KEEP, do not touch; not in the corpus (helix `/` is regex search). Find and Grep answer with OTHER files and deliberately do NOT jump. The stepping half is the next row | pardes-specific | -| `n` / `N` (any pane) | MOTION, not a jump: move the SELECTION to the next / previous look-able text and open NOTHING. Enter — the look chord — on what it leaves selected is what opens it | KEEP, do not touch; not in the corpus (helix's `n`/`N` walk regex search hits). What a step selects is the pane's GRAIN (`output_pane.Grain`, read in `Pardes.lookSpanIn`): in FREE TEXT — a terminal, a file, a PDF, a prose answer buffer — the largest whitespace-delimited run `look.resolve` can act on (`look.lookableSpan`, wrapper punctuation peeled off both ends), several to a line; in a RESULTS BUFFER one stop per ROW, the largest run its head resolves as (`look.lookableLineSpan`), because a row there IS one location and the words after it are the match rather than a second place to go; in a COMMAND list the whole line. The walk is a RING across PANES: every pane that has performed a Look, most recent first (`Pardes.look_src`), then the output buffers that have not, newest first, and only when both are empty the active pane. Exhausting a pane enters the next at its first (forward) / last (backward) span and the end wraps to the start, so `N` is the exact inverse of `n`. What it lands on becomes an EXPLICIT `vsel` with the cursor on its FIRST column, in the pane the walk focuses. ONE motion in every pane kind and every buffer kind — a PDF steps the `+Search` buffer its own search filled, `n` to select the row and Enter to jump. The single thing a buffer may change is that grain, and it changes it by BEING a kind of buffer rather than by a branch: `output_pane.Traits.steps` (a list of locations) makes a step take one row at a time, and `Traits.commands` makes it take the WHOLE LINE, because a command list (`Themes`/`Fonts`) holds words to run and there is no path inside `Theme gruvbox` to pick out. Tab on what `n` selected wears the theme, which is the same middle click on the row is. `]d`/`[d` are helix's diagnostic motions, a different binding, and they do still jump to each diagnostic (`docs/lsp.md`) | pardes-specific | +| `n` / `N` (any pane) | MOTION, not a jump: move the SELECTION to the next / previous look-able text and open NOTHING. Enter — the look chord — on what it leaves selected is what opens it | KEEP, do not touch; not in the corpus (helix's `n`/`N` walk regex search hits). What a step selects is the pane's GRAIN (`output_pane.Grain`, read in `Pardes.lookSpanIn`): in FREE TEXT — a terminal, a file, a PDF, a prose answer buffer — the largest whitespace-delimited run `look.resolve` can act on (`look.lookableSpan`, wrapper punctuation peeled off both ends), several to a line; in a RESULTS BUFFER one stop per ROW, the largest run its head resolves as (`look.lookableLineSpan`), because a row there IS one location and the words after it are the match rather than a second place to go; in a COMMAND list the whole line. The walk is a RING across PANES: every pane that has performed a Look, most recent first (`Pardes.look_src`), then the output buffers that have not, newest first, and only when both are empty the active pane. Exhausting a pane enters the next at its first (forward) / last (backward) span and the end wraps to the start, so `N` is the exact inverse of `n`. What it lands on becomes an EXPLICIT `vsel` with the cursor on its FIRST column, in the pane the walk focuses. ONE motion in every pane kind and every buffer kind — a PDF steps the `+Search` buffer its own search filled, `n` to select the row and Enter to jump. The single thing a buffer may change is that grain, and it changes it by BEING a kind of buffer rather than by a branch: `output_pane.Traits.steps` (a list of locations) makes a step take one row at a time, and `Traits.commands` makes it take the WHOLE LINE, because a command list (`Themes`/`Fonts`) holds words to run and there is no path inside `Theme gruvbox` to pick out. Tab on what `n` selected wears the theme, which is the same middle click on the row is. `]d`/`[d` are helix's diagnostic motions, a different binding, and they do still jump to each diagnostic (`docs/typ/guide.typ`, Keys) | pardes-specific | | insert: printable text | file: real edit; terminal: typed run splice | | helix-verified (file) | | insert: `Enter` | newline; keeps the current full indent levels and adds one 4-space logical tab when the text before the cursor ends in `(`, `[`, `{`, or `)` (including `})`) | plain lines match `insert_newline`; delimiter heuristic is pardes-specific | helix-verified (plain) / pardes-specific (delimiter) | | insert: `Backspace` (+ `Shift-Backspace`) | delete prev char, joins lines at col 0; in a line's leading blanks, back to the previous 4-column indent stop (a whole unit when on one; a tab still goes alone) | matches `delete_char_backward` and its dedent; `Ctrl-h` alias in B | helix-verified | @@ -271,7 +271,7 @@ compiles a runtime pattern with no allocator, called the way sam searches haystack, so `^` and `$` match at every line's start and end and `.` never crosses a newline, and a pattern naming `\n` runs over the whole selection. Where helix's `^` is only the selection's start, this is sam's. mvzr -backtracks without bound of its own, so the step budget docs/fs.md gives +backtracks without bound of its own, so the step budget docs/typ/reference.typ gives for `addr` holds here too: a search that runs out of it (about 300 ms) keeps the matches it found so far. diff --git a/docs/lsp.md b/docs/lsp.md deleted file mode 100644 index 22cf1b90..00000000 --- a/docs/lsp.md +++ /dev/null @@ -1,73 +0,0 @@ -# Language intelligence - -Native hosts, including detached sessions, run language queries on workers. -Every language, Zig included, goes through the protocol client in -`src/lsp/lsp_client.zig`, which runs its server as a child process: Zig's is -`zls`, which must be on PATH. Web and board builds have no language backend. - -`Lspinfo` (`SPC l i`) reports backend versions, server state, capabilities, -recent timings and errors. `Lspwhy` (`SPC l w`) traces resolution at the cursor. - -## Commands - -| Keys | Action | -|---|---| -| `gd`, `gD`, `gy`, `gi`, `gr` | Definition, declaration, type, implementation, references | -| `SPC l k` | Hover | -| `SPC l r` | Rename | -| `SPC l a` | Code action | -| `SPC l h` | Select references | -| `SPC l s`, `SPC l S` | Document and workspace symbols | -| `SPC l d`, `SPC l D` | Document and workspace diagnostics | -| `]d`, `[d`, `]D`, `[D` | Next, previous, last and first diagnostic | -| `=` | Format | -| Ctrl-click | Definition | -| Insert-mode Tab after `.` | Candidate declarations | -| `SPC l c`, `SPC l C` | Incoming and outgoing calls | -| `SPC l t`, `SPC l T` | Supertypes and subtypes | - -A single goto result jumps directly; several results open a reusable search -buffer. `n`/`N` select result rows and Enter opens them. Hover opens prose. -Locations use one-based `path:line:column` or `path:line:column-endcolumn`. -Paths below the requesting pane's directory are relative to that directory; -other paths stay absolute. - -Completion lists declarations and inserts nothing. An unanswered Tab indents -only if the cursor has not moved since the request. Multicursor Tab indents -without starting a query. - -Formatting and same-file rename apply as one undo transaction. A workspace -rename spanning other files opens a preview; it does not partially apply the -rename. - -## Configuration and testing - -`PARDES_LSP_ZIG`, `_RS`, `_C`, `_GO`, `_TS` and `_PY` override the server -executable for each language. An empty value disables that server. `Lspinfo` -shows the effective settings. - -The protocol client keeps one child server per configured language, negotiates -position encoding, and handles both push and pull diagnostics. Startup and -request waits have deadlines; failed starts back off before retrying. Worker -status messages reach the host event queue. - -`zig build lspbench -- probe gd :` queries the same backend from -the command line. `zig build lspbench` measures it. The Zig snapshot tests -(lsp, lspcomplete, lspdebug and the rest) run the real `zls`; the protocol -ones use a Zig mock server with deterministic answers while exercising the real client, -including process startup, framing, edits and undo. `zig build fs-test` also -checks language-worker delivery in TTY and detached sessions over 9P. - -## Ownership - -`host_io.Lsp.Job` owns copies of the source, path, argument and root. Workers -never read the live core. A request ID and pane serial reject obsolete replies; -mutating replies also require the original file revision. Restore cancels -owned work before replacing the core. - -Backends implement `query`, `speaks` and `supports` in `src/lsp/`. The first -backend supporting the file and query answers; status queries visit all of -them. Results are written to the caller's writer. Use `lsp.row` or `spanRow` -for locations, `edit` for rename ranges, and `put` for replacement text. -Edit records use half-open byte offsets into the request's source snapshot. -The core validates the complete response before applying it. diff --git a/docs/tags.md b/docs/tags.md deleted file mode 100644 index 5d5bfab2..00000000 --- a/docs/tags.md +++ /dev/null @@ -1,222 +0,0 @@ -# Tags and columns - -Pardes has three levels of command text: the workspace tag, a tag per -column, and each pane's tag. The rule for the workspace and column tags: - -- A builtin that acts on a pane (`Del`, `Save`, `Undo`) acts on the - column's active pane (its first pane when focus comes from another - column); from the workspace tag, on the pane with the keyboard. -- A column's own words (`New`, `Tty`, `Delcol`) act on that column. -- A shell command runs as a command pane of its own, with `run` and `exit` - records, in the session's directory (where pardes started), as acme's row - and column tags have none of their own. It is never typed into the - terminal that has the keyboard. `Tty` starts there too. -- Over 9P (`/tagexec`, `col//exec`) there is no click to say which pane - is meant, so a pane's word written there is refused, pointing at - `pane//ctl`; the tag's own words and shell commands run as above. - -One run from a pane's tag or text starts in that pane's directory, and a -shell command there is typed into the pane when it is a terminal at its -prompt. Over 9P the tags are `/tag`, `/col//tag` and -`/pane//tag` ([fs.md](fs.md#columns-and-tags)). - -## Default words - -- Workspace: `Newcol Joincol Find Grep Help Changelog Tutor Dump Themes - Config Debug Exit`. -- Column: `New Tty Find Grep Joincol Delcol`. -- File pane: `Save Tty Collapse Del`; a source file with a grammar adds - `TreeContext`, a result list `LocationsConfig`. PDF: `manual.pdf [1/12] - Tty PdfSections PdfTint Collapse Del`. -- Terminal: `Tty+bash Save Mode Filter Collapse Del`. `Tty+bash` is one word - for `Tty bash`, opening another terminal on that shell (only `Tty` reads a - `+` so). `Mode` cycles raw terminal input, normal mode and insert mode. -- Command pane: ` () running`, then `exit N`, and `Kill`. - -`Undo`, `Redo` and `Mode` (on files) work typed or clicked though they are -not in the default tags. Customized tags keep their text. - -A tag word runs as acme's does, in the pane's directory with no file named: -`wc` alone waits on stdin. There is no `$%`; name the file (`wc notes.txt`), -or select the name and middle-click `wc`, which takes a held selection as its -argument. - -A program that tracks the mouse gets B1 and the wheel; B2 and B3 stay -pardes's; Shift swaps each. In raw terminal input, a program that asked for -the mouse (xterm's 1000, 1002 or 1003: htop, vim with `mouse=a`, codex) -gets B1's clicks and drags and the wheel over its grid, reported in the -format it chose and with its modifiers; Shift-B1 selects as ever and -Shift-wheel scrolls pardes's scrollback. B2 and B3 execute and look there -as in any pane, sweeps and chords included; Shift-B2 and Shift-B3 go to the -program as its buttons 2 and 3, the Shift left out. A full-screen program -that does not track the mouse gets the wheel as arrow keys (xterm's -alternate scroll, 1007). Tags, grips and gutters stay pardes's. - -`Repl python` in a terminal's tag binds it as that language's REPL -([fs.md](fs.md#repls)). `Repl` takes the languages a code fence names: ada, -bash, c, c_sharp, clojure, cpp, css, elixir, erlang, fortran, go, haskell, -html, java, javascript, json, kotlin, ocaml, markdown, pascal, php, -powershell, python, ruby, rust, scala, typst, zig, and aliases such as `py` -and `sh`. - -## Pane builtins - -`Collapse` folds a pane to its tagline, giving its rows to the nearest -expanded pane above (else below); again, it takes them back. Its text and -process are kept. - -`Del` closes a pane, giving its rows to one neighbour. `Del k` (`DelAbove`) -gives them to the nearest expanded pane above, `Del j` (`DelBelow`) below, -each falling back to the other side. Bare `Del` from the keyboard (`SPC d`), -with expanded panes above and below, asks on the notice band (`k`/Up above, -`j`/Down below, any other key keeps the pane); a click, a 9P write or an -`init` line never asks and gives the rows above. - -A pane with unsaved text is refused once: a notice `1 unsaved pane — Del -again to discard`, the pane listed in `+Unsaved`, and over 9P the write -fails (EIO). The same `Del` again, nothing edited since, discards. `Delcol` -refuses a column holding such a pane the same way, without opening -`+Unsaved` or moving focus. `Exit` and `Restore` do the same over the whole -session. A `+New` scratch under 100 bytes is never asked about. - -`Edit` runs sam's command language on the body ([fs.md](fs.md#edit)). -`Undo` and `Redo` step the body through its last 256 edits, as `u` and `U`. - -Unsaved text shows on the pane's grip, as acme's modbutton, not in the tag. -In a terminal the grip is two cells: the pane's mode (blank normal, `^` -insert, `$` tty mode), then `*` while unsaved. - -## Reviewing diffs - -Open a `.diff` or `.patch` file, or run `git diff` (or `git show`, `diff -u -old new`) as a command from any tag: once the command has finished, output -that starts as a diff does (a `diff --git` line, or a `--- ` line with `+++ -` and `@@` under it) is shown as one. Each hunk's code is coloured in the language of the file its -section names (`+++ b/`, or `--- a/` for a deleted file), its -old side (context and removed lines) and new side (context and added lines) -each parsed as one text, so a string or comment across lines colours as it -does in the file. Added and removed rows are tinted to the pane's edge, -their `+`/`-` in the tint's hue (the theme's ANSI green and red where it -has them); a file in no language pardes knows keeps the plain line colours. -Only the hunks in view are parsed, a few dozen lines at a time, each once. - -Then right-click to jump: a diff line looks up the path and line it -names, as any look does. The hover shows the whole line; the look is of -the address it names, exactly as if that text had been selected by hand -and right-clicked, with the same resolution (the pane's directory, then -the places the jumplist has been), placement and errors. On a `diff ---git`, `---` or `+++` line, anywhere on it, markers included, that is the -file: `diff --git a/x b/y` and `+++` name the new one, `---` the old one -unless the `+++` under it names another (a rename, a new file, `diff -u -old/x new/x`), the old name being the one likely gone. A `@@ -a,b +c,d -@@` line names `path:c`. On a hunk line, the `+`, `-` or space in its -first column names `path:` its new line; for a removed line, the new line -now standing where it was (the one after it, or the hunk's last when it -went from the end of the file). The code after it is words, looked at as -ever. A 9P `look` of a whole line of the diff is the same look. - -The path is the repository's name for the file. In a git section (one -with a `diff --git` line) git's side prefix is dropped when both paths on -that line carry one, different ones: `a/`/`b/`, or with -`diff.mnemonicPrefix` `c/`, `i/`, `w/`, `o/`. `--no-prefix` writes none, -so there `a/x a/x` is a real directory `a`, kept. A plain `diff -u`'s names -are used as written, past the timestamp. - -## Editing tags - -A tag is text like a body, with the body's normal and insert modes and undo. -A pane tag may hold several lines and wraps, taking a row per shown line up -to eight and leaving its body at least one; a collapsed pane shows the first. -Up on its first row in insert mode (or Alt-Up in either mode) folds a tag to -one row, Down on its last (Alt-Down) unfolds it. Column and workspace tags are -one line: a newline typed, pasted or written into one becomes a space. - -The path (and a PDF's page) at the start of a pane tag is computed and -read-only; `0` goes to its start, and motions select and yank across it. -Typing into a file's path, or clicking it, starts a draft of a new name: -Enter or Tab confirms it, Escape or leaving the pane cancels. Confirming -changes the buffer's save target and marks it unsaved; nothing on disk is -renamed until `Save`. A pane-tag command confirms a valid draft first. - -Left-click a tag to type at the click, in insert mode. Esc is normal mode: -there Tab executes the word under the cursor (or the selection); Enter looks -it up in a pane's tag and runs it in a column or workspace tag. Executing -gives the keyboard back to the body first. Paste goes to the focused tag. - -A look at a relative path is tried in this pane's directory, then in the -directories of places you've visited (the jump list). - -`:` in a body's normal mode focuses its tag (the first time, on `Save`); `:` -in a tag goes back. The window keys (`Ctrl-w`, `SPC w` with `h/j/k/l`) move -between panes; up from the top pane reaches its column's tag, then the -workspace's, and Left/Right walk the column tags. Search, `s`/`S`, pipe and -Save's path prompt get a line on the pane's notice band; in a tag `s`, `S` -and `|` act on the tag's own text, while `/` searches the body. - -## Moving and resizing - -Drag a pane's grip up or down its column and its top follows, the pane -above giving or taking rows, down to its tag alone; drop it in another -column and it moves there. In the GUI the 2 px rule between panes drags too. -A column's right edge drags its width. Drag a column's grip past a -neighbour's middle to move the whole column there; short of that it moves -the column's left edge. - -A terminal keeps its tag and 2 body rows: no drag, squeeze or smaller -window takes it below that, and `pty/ctl`'s `winsize` gives a pty 2 rows at -least. A text pane can be dragged down to its tag. - -## Empty columns - -A column can hold no pane, as acme's can: its tag stands over blank space in -the theme's `empty_col` colour. `Newcol` makes one right of the keyboard's -and gives its tag the keyboard. Closing a column's last pane leaves the -column empty, the keyboard on its tag. Only `Delcol` and `Joincol` take a -column away; `Joincol` keeps the right column's tag, its panes below. A pane -dragged onto an empty column fills it. `Delcol` of the last column leaves -the workspace tag alone; `Newcol` or `New` starts again. Unlike acme, pardes -quits when the session's last pane closes. - -## Where new panes go - -Every new pane goes through one placement, chosen by `Placement acme` (the -default) or `Placement pardes` (bare flips it; `SPC c p`). - -No placement leaves a pane shorter than its tag and 2 body rows. Where the -chosen place has not that room, the column's tallest pane is halved; where -no one pane can give it but the column holds every pane's minimum with the -new one's, the rows are shared out again; otherwise the pane is refused, -`no space for a pane in that column: each keeps its tag and 2 rows` (ENOSPC -over 9P). A pane alone in its column always fits. - -`Placement acme` is acme's makenewwindow. The active column is the one last -typed or clicked in, dropped into, whose tag was given the keyboard, or that -was given the last new pane; a Look moves the keyboard, not the active -column. A new pane goes into the column whose tag the command came from, -else the active column, never into a new column: - -- an empty column it takes whole; -- from a tag, or 9P's `pane/new`, it takes the bottom half of the column's - last pane; -- from a pane's text (a Look, `Tty`, `Alt-n`, a Grep or Find listing), it - goes under the text of the pane with the most blank rows when that is - more than 15 rows, or more than 3 and more than half the biggest pane; - otherwise it halves the biggest pane, or the asking pane when that is in - the column and not much smaller; -- `New` goes to the bottom half of its own column's last pane; -- a command pane or `+Errors` pane goes to the last column's last pane (a - command from a column's tag to that column, reusing a finished command - pane only there). With no room anywhere, `+Errors` text is logged as `msg` - records. - -`Placement pardes`: an empty column whose tag asked, or has the keyboard, is -filled; a scratch goes under the pane that asked; a shell under it or the -nearest pane with room; a document beside the last one read, or in a column -of its own on the left when there is none and the column is at least 200 -cells wide; a command pane at the foot of the last column. - -## Saved workspaces - -`Dump` and `Restore` keep workspace and column tags (empty ones too) and -empty columns ([config.md](config.md#dumps)). The column row stays above -the panes with `Tagbottom` on; on screens under three rows it is left out. diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ index d9c3f573..5069614a 100644 --- a/docs/typ/cheatsheet.typ +++ b/docs/typ/cheatsheet.typ @@ -4,8 +4,6 @@ // against the registry, the keymap and the default tags. #import "style.typ": key, btn, chord, word, tag, addr, file, cmd, doc -= pardes #h(1fr) _acme's tags and three buttons, helix's keys, terminals as panes, the editor as a 9P filesystem_ - == The mouse / #btn("B1"): select, and focus the pane. On a tag: type there. / #btn("B2"): *execute* the word or selection: a builtin, else a shell line. @@ -46,7 +44,7 @@ Typed anywhere, then #btn("B3") or #key("Enter"): Addresses are sam's: `#n`, `/re/`, `?re?`, `$`, `a,b`. #doc("fs", section: "look-and-exec") == Keys: normal mode -Helix-style: motions *select*, then an edit acts on the selection. Mode box: blank normal, `^` insert, `$` tty. +Helix-style: motions *select*, then an edit acts on the selection. Mode box: blank normal, `^` insert, `$` raw terminal. #table(columns: 2, [#key("h j k l") #key("w b e")], [move; words select], [#key("g g") #key("g e")], [first line, last line], @@ -71,9 +69,9 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla == Keys: panes #table(columns: 2, - [#key("Ctrl-w") #key("h j k l")], [focus a neighbour (anywhere)], - [#key("Esc")], [normal mode: hop to the previous pane], - [#key("Shift-Esc")], [leave, whatever Esc means here], + [#key("Ctrl-w") #key("h j k l")], [focus a neighbour (not in insert or raw `$`)], + [#key("Esc")], [back to the previous pane (from raw `$` only at an empty shell prompt)], + [#key("Shift-Esc")], [back to the previous pane from raw `$` or a PDF; in a terminal's normal mode, into raw], [#key("Ctrl-o") #key("Ctrl-i")], [jump history back, forward], [#key("Alt-n")], [new terminal below], [#key("Alt-c")], [move the pane to a new column], @@ -97,8 +95,8 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla ) == Terminals and commands -- A terminal is a pane. #key("Ctrl-b") toggles raw input (`$`) and editor mode, where the same keys move over its text, prompts hidden. -- Raw: keys go to the program; #key("Esc") at a shell prompt hops away, #key("Shift-Esc") always. +- A terminal is a pane. #key("Ctrl-b") switches it between raw (`$`) and normal mode, where the same keys move over its text, prompts hidden. +- Raw: keys go to the program; #key("Esc") at an empty shell prompt goes back to the previous pane, #key("Shift-Esc") always. - #word("Mode") cycles raw, normal, insert. #word("Filter") maps its colours to the theme. #word("Tty+bash") opens another on that shell. - #btn("B2") on any non-builtin line (`make`, `git log`) runs it with #word("Shell") `-c` in the pane's directory, in a *command pane*: #tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0") - #word("Kill") stops what pardes started (`Kill make`: those lines); #word("Exit") quits. diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ new file mode 100644 index 00000000..080ed5ea --- /dev/null +++ b/docs/typ/guide.typ @@ -0,0 +1,303 @@ +// The guide: pardes day to day, read once in about ten minutes. The +// cheatsheet is the index of keys and words; the reference has every +// 9P file; scripting has the recipes. +#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs + +pardes is a screen of columns. Each column holds panes, and each pane is a +tag (a line of words) over a body: a file, a terminal, a PDF or an image. +Above the columns runs the workspace tag, and each column has a tag of its +own. Any text anywhere can be clicked: #btn("B2") runs it, #btn("B3") looks +at it. The keys are helix's, in modes. + += Modes + +Each pane has its own mode and keeps it while you are elsewhere: leave a +terminal at its `$` and it is still `$` when you come back. The box at the +left of a pane's tag shows the mode. + +#pairs( + [normal (box blank)], [keys move and select; an edit acts on the selection. File and PDF panes start here, and so does a terminal from #key("Alt-n").], + [insert (`^`)], [keys type. #keys("i", "a", "o") and the rest enter it.], + [raw (`$`), terminals only], [keys go to the program. A terminal from #word("Tty"), the shell a bare `pardes` starts with, and a command pane start here.], +) + +#key("Ctrl-b") switches a terminal between raw and normal; in normal mode +the shell's prompts are hidden and its text is a page to move over and +copy from. #word("Mode") in the tag steps raw, normal, insert. Esc and +Shift-Esc depend on the mode: + +#pairs( + [normal], [#key("Esc"): back to the previous pane (#word("Last")). #key("Shift-Esc"): the same, except in a terminal, where it switches to raw.], + [insert], [#key("Esc"): back to normal. #key("Shift-Esc"): the same, except in a terminal, where it switches to raw.], + [raw `$`], [#key("Esc"): to the program, except at an idle, empty shell prompt, where it goes back to the previous pane. #key("Shift-Esc"): always back to the previous pane. Either way the terminal stays `$`.], + [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.], +) + +"The previous pane" is the last other pane on the jump list; with none, the +next pane down its column (wrapping), else any other pane. In raw mode +every key but #key("Ctrl-b"), Esc and the paste chords goes to the +program, so #key("Ctrl-w") and #key("Alt-n") need you out of raw mode +first (and #key("Ctrl-w") out of insert mode, where it deletes a word). + += The mouse + +#pairs( + btn("B1"), [select; a plain click puts the cursor there and gives the pane the keyboard. In a tag it starts typing at the click, in insert mode. A double click selects the word, the line (at a line's start or end), or up to the matching bracket or quote.], + btn("B2"), [execute: a builtin word runs, anything else is a shell line.], + btn("B3"), [look: open the file, address, directory or URL, or else find the word's next place.], +) + +A #btn("B2") or #btn("B3") click with no drag takes the word under it, +where a word is the run of letters, digits, non-ASCII and `. - + / : @ _ ~` +around the click; a trailing `:` is dropped. So #btn("B3") anywhere on +`src/bar.c:12:5:` in a compiler's `src/bar.c:12:5: error` opens +`src/bar.c` at line 12, byte column 5, while a click on `error` finds +`error`. Drag instead to say exactly what you mean. #key("Enter") and +#key("Tab") in normal mode look and execute the selection, or the word +under the cursor. The chords are on the cheatsheet. + += Tags + +There are three kinds, and which directory a command runs in depends on +which one you click: + +#tag("Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Config Debug Exit") +#tag("New Tty Find Grep Joincol Delcol") +#tag("Save Tty Collapse Del", path: "/home/me/notes.txt") + +- The workspace tag and the column tags run commands in the session's + directory (where pardes started). A column's own words (#word("New"), + #word("Tty"), #word("Delcol")) act on that column; a pane word + (#word("Save"), #word("Del")) acts on the column's pane with the + keyboard, or its first; from the workspace tag, on the pane with the + keyboard. +- A pane's tag runs commands in the pane's directory: a file's directory, a + terminal's current directory. + +A tag is text with undo: type a word into it and click it, or delete the +defaults. #key(":") moves the keyboard between a body and its tag. A pane +tag may wrap onto several lines; column and workspace tags are one line. +The path at the start of a pane's tag is computed: typing into it, or +clicking it, drafts a new name, #key("Enter") confirms and the next +#word("Save") writes there; #key("Esc") cancels. #word("Collapse") folds a +pane to its tag. Unsaved text shows on the grip, the box left of the tag. +Drag the grip up or down to resize, or onto another column to move the +pane there. + += The active column and the keyboard + +Two things are easy to confuse: + +- *The pane with the keyboard* is where your keys go. +- *The active column* is where new panes go. It is the column you last + typed in, #btn("B1")-clicked in, dropped a pane into or gave the keyboard + to its tag, or the one that got the last new pane. A look does not move + it. + +They usually agree. Here is how they split. You are typing in column 1, so +column 1 is active. You click #word("New") in column 2's tag: a scratch +pane opens in column 2 and takes the keyboard, and column 2 is now +active. In it you #btn("B3") `x.txt`, which is already open in column 1: +the keyboard jumps to that pane in column 1, but the active column stays +2, so the next pane a look opens lands in column 2, away from where you +are. Type or click in column 1 and it is active again. + +== Where new panes go + +#word("Placement") picks the rules: `acme` (the default) or `pardes`. +Under `acme`, a new pane goes into the column whose tag asked, else the +active column, never into a new column. An empty column it takes whole; +#word("New") and 9P's #file("pane/new") take the bottom half of the +column's last pane; a pane opened from a pane's text (a look, #word("Tty"), +#key("Alt-n")) goes under the pane with the most blank rows, or halves the +biggest; a command pane goes to the last column. #word("New") in a pane's +tag opens a `+New` scratch named in that pane's directory, in that pane's +column; from a column tag, in that column and the session's directory. +Every new pane but a command pane takes the keyboard. No pane is made +shorter than its tag and two rows; where there is no room the pane is +refused. + +A column can be empty, as in acme: closing its last pane leaves it, its +tag over blank space. #word("Delcol") and #word("Joincol") take columns +away. Closing the session's last pane quits pardes. + += Looking + +#btn("B3") (or #key("Enter")) on a path opens it, or goes to the pane that +already shows it; `file:12` goes to line 12. The address forms are on the +cheatsheet. A directory types `ls` into a terminal idle there, else opens +a terminal there. A URL opens in the browser. + +A relative path is looked for where the click was, then where you have +been: first in the looking pane's own directory, then in the directory of +each pane on the jump list, most recent first. The first that names a +file, or a pane open on that path, wins. `./x` and `../x` look only in the +pane's own directory. + += Command panes + +#btn("B2") on a line that is no builtin (`make`, `git log`) runs it with +the #word("Shell") setting's `-c`, in the directory of the tag or pane it +came from. In a terminal idle at an empty prompt, a line from that +terminal's own text is typed into its shell. Anywhere else it runs in a +command pane, a terminal of its own: + +#tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0") + +Its tag says `running`, then `exit N`. The next command for the same +directory reuses a command pane that has finished (from a column tag, only +one in that column), below what it showed; a pane still running, or one a +background job still prints to, is never reused, so a second command +meanwhile gets a pane of its own. #word("Kill") stops what pardes started +(`Kill make`: those whose line starts with `make`); #word("Exit") quits +pardes. + += Unsaved panes + +A pane whose text is unsaved is marked on its grip. #word("Del") on it +refuses once: a notice says `1 unsaved pane — Del again to discard` and the +pane is listed in `+Unsaved`. The same #word("Del") again, with nothing +edited since, discards it. #word("Exit"), #word("Restore") and +#word("Delcol") refuse once over unsaved panes the same way. A `+New` +scratch under 100 bytes and a command's output never hold anything up. + +From the keyboard (#key("SPC d")), #word("Del") on a pane with panes above +and below it also asks which neighbour takes its rows: #key("k") above, +#key("j") below, any other key keeps the pane. A click never asks, and +gives the rows to the pane above. + += Terminals + +A terminal is a pane like any other. + +#tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src") + +- `Tty+bash` opens another terminal on that shell; a bare #word("Tty") + runs the #word("Shell") setting, `$SHELL` when it is executable, else + `/bin/sh`. +- #word("Save") asks for a path on the pane's notice band and writes the + terminal's scrollback there as text; `Save path` writes it at once. +- #word("Filter") maps the program's colours through the theme. +- In raw mode Ctrl-V types what you yanked into the program (with nothing + yanked, the program gets the key), and Ctrl-Shift-V the desktop + clipboard. +- A program that tracks the mouse (htop, vim with `mouse=a`) gets + #btn("B1")'s clicks and drags and the wheel over its grid; #btn("B2") and + #btn("B3") stay pardes's. Hold Shift to swap: #btn("B1", shift: true) + selects and Shift-wheel scrolls pardes's scrollback, while + #btn("B2", shift: true) and #btn("B3", shift: true) go to the program as + its buttons 2 and 3. A full-screen program that does not track the mouse + gets the wheel as arrow keys. Tags, grips and gutters stay pardes's. +- `Repl python` in a terminal's tag makes #btn("B2") on a `.py` pane send + the text to that REPL instead of running it. + += Reviewing diffs + +Open a `.diff` or `.patch`, or run `git diff` (or `git show`, `diff -u`) as +a command: once it has finished, output that starts as a diff is shown as +one, each hunk coloured in its file's language and its added and removed +rows tinted. Then #btn("B3") to jump, with the usual look resolution: + +- a `diff --git`, `---` or `+++` line opens the file (the new one, or the + old one on a `---` line unless the `+++` under it names another); +- a `@@ -a,b +c,d @@` line goes to line `c` of the new file; +- the `+`, `-` or space in a hunk line's first column goes to that line in + the new file (for a removed line, the line now standing where it was); +- the code after it is ordinary words. + +git's `a/` and `b/` prefixes are dropped (and `c/ i/ w/ o/` with +`diff.mnemonicPrefix`); a `--no-prefix` diff's paths are kept as written. + += pardes FILE and --wait + +In a pane's shell, `pardes FILE` opens FILE in this session and returns at +once, as acme's `B` does. A FILE not there yet opens an empty pane named +for it; #word("Save") creates it, making its directories first. Something +the session refuses (a bad name) is printed and the command exits 1. + +`pardes --wait FILE` (`-w`) returns when the pane showing FILE is closed +(exit 0) or the session goes away (exit 1), as acme's `E` does. Set +`EDITOR='pardes --wait'` (`GIT_EDITOR` follows it), and `git commit`, +`crontab -e` and fish's Ctrl-O open in a pane and read the file once you +close it. Bare `pardes` inside a pane refuses and names `--nested`, which +starts a separate session whose shells do not forward to it. + += Keys + +Motions select what they cross, and an edit acts on the selection: #key("w") +then #key("d") deletes a word. #key("x") selects lines, #key("v") extends +characters, #key(";") collapses to the cursor. #key("s") makes a cursor +per regex match inside the selection, and every edit then acts at each. +#key("/") is a case-insensitive substring search, one hit a line; the +regexes are on #key("s") and #key("S"). #keys("n", "N") step through +everything a look would open, across panes. Line end is #key("g l"), and +#key("$") is helix's keep-pipe. #key("SPC") starts the leader, +#key("SPC ?") lists every path, and #word("Help") lists every key and +builtin. #word("Tutor") (#key("SPC h t")) practises them. + +The language servers run as child processes, one per language when it is +on `PATH`: `zls`, `rust-analyzer`, `clangd`, `gopls`, +`typescript-language-server` and `pyright-langserver` +(`PARDES_LSP_ZIG`, `_RS`, `_C`, `_GO`, `_TS`, `_PY` name another, empty +turns one off): + +#pairs( + [#keys("g d", "g D", "g y", "g i", "g r")], [definition, declaration, type, implementation, references; Ctrl-#btn("B1") is a definition too], + [#keys("SPC l k", "SPC l r", "SPC l a", "SPC l h")], [hover, rename, code action, select the references], + [#keys("SPC l s", "SPC l S", "SPC l d", "SPC l D")], [symbols and diagnostics, of the file and the workspace], + [#keys("SPC l c", "SPC l C", "SPC l t", "SPC l T")], [incoming and outgoing calls, supertypes and subtypes], + [#keys("] d", "[ d")], [next and previous diagnostic], + [#key("=")], [format], + [#keys("SPC l i", "SPC l w")], [#word("Lspinfo"): the servers' state; #word("Lspwhy"): why the last query found what it did], +) + +One answer jumps; several open a list where #key("Enter") on a row goes +there. In insert mode #key("Tab") after a `.` lists the candidate +declarations and inserts nothing. A format or a rename within the file is +one undo step; a rename that reaches other files opens a preview instead +of changing them. + += Sessions + +``` +pardes --detach=work & a session with no screen of its own +pardes --attach=work show it here +pardes-gui --attach=work the SDL window can attach too +``` + +The session owns the panes, shells and files; frontends come and go. +#word("Attach") `work` (#key("SPC s a")) switches this window to that +session, and #word("Detach") (#key("SPC s D")) leaves it running, shells +and all. Bare `--detach` names the session after its pid; bare `--attach` +needs exactly one session. Every attached frontend sees the same screen, +at the smallest common size. With none attached, `size C R` on the root +ctl sets the screen and messages clear by the clock. A detached session +ends when its last pane closes, as any session does. + += Config + +#word("Config") (#key("SPC f c")) opens the startup file, +`~/.config/pardes/init` (`$XDG_CONFIG_HOME/pardes/init` when that is +absolute; on macOS `~/Library/Application Support/pardes/init`). Each line +is one builtin, run at start as if executed; `#` starts a comment, and a +line that fails is skipped silently. Text that is no builtin does not run +as a shell command. + +``` +Theme atelier +Shell zsh +Placement pardes +``` + +#word("DumpConfig") opens every live setting as the line that sets it, so +it pastes back into `init` as is. The settings are listed with the root +ctl in the reference (#doc("fs", section: "settings")). Keys are +compile-time, in `src/config.zig`. + +#word("Dump") writes the workspace to `pardes--