Lightpanda: the headless browser designed for AI and automation
fish completion: describe values and complete comma lists
Adrià Arrufat9a00cdc83d8d
diff --git a/src/completion.zig b/src/completion.zigindex 3896ff505..33c6426e0 100644--- a/src/completion.zig+++ b/src/completion.zig@@ -56,7 +56,21 @@ pub fn write(w: *Writer, shell: Shell, exec_name: []const u8) !void {}fn writeFish(w: *Writer, exec_name: []const u8) !void {- try w.print("complete -c {s} -f\n", .{exec_name});+ const ident: Ident = .{ .name = exec_name };+ // Candidates for a comma-separated list: the items not chosen yet, after+ // what's typed up to the last comma.+ try w.print(+ \\complete -c {s} -f+ \\function __{f}_list+ \\ set -l prefix (string match -r -- '.*,' (commandline -ct))+ \\ set -l chosen (string split , -- $prefix)+ \\ for item in $argv+ \\ set -l value (string split -m1 \t -- $item)[1]+ \\ contains -- $value $chosen; or printf '%s%s\n' "$prefix" $item+ \\ end+ \\end+ \\+ , .{ exec_name, ident });for (commands) |command| {try w.print("complete -c {s} -n __fish_use_subcommand -a {s} -d '", .{ exec_name, command.name });try writeText(w, commandSummary(command.name), exec_name, .fish);@@ -75,6 +89,7 @@ fn writeFish(w: *Writer, exec_name: []const u8) !void {},};for (command.flags) |flag| {+ const block = flagBlock(help_text, flag.name);try w.print(condition ++ " -l {s}", .{ exec_name, command.name, flag.name[2..] });if (flag.short) |short| try w.print(" -s {c}", .{short});switch (flag.values) {@@ -82,13 +97,23 @@ fn writeFish(w: *Writer, exec_name: []const u8) !void {.any => try w.writeAll(" -x"),.path => try w.writeAll(" -r -F"),.one_of, .list_of => |values| {+ const list = flag.values == .list_of;try w.writeAll(" -x -a '");- try writeJoined(w, values);+ if (list) try w.print("(__{f}_list ", .{ident});+ for (values, 0..) |value, i| {+ if (i > 0) try w.writeAll(" ");+ try w.writeAll(value);+ // Even when empty, or fish shows the flag's description.+ try w.writeAll("\\t\"");+ try writeText(w, valueSummary(block, value), exec_name, .fish_value);+ try w.writeAll("\"");+ }+ if (list) try w.writeAll(")");try w.writeAll("'");},}try w.writeAll(" -d '");- try writeText(w, describe(help_text, flag.name), exec_name, .fish);+ try writeText(w, summary(block), exec_name, .fish);try w.writeAll("'\n");}}@@ -198,7 +223,7 @@ fn writeZsh(w: *Writer, exec_name: []const u8) !void {for (commands, help_texts) |command, help_text| {try w.print(" {s})\n _arguments -s", .{command.name});for (command.flags) |flag| {- const description = describe(help_text, flag.name);+ const description = summary(flagBlock(help_text, flag.name));try writeZshFlag(w, flag.name, flag.values, description, exec_name);if (flag.short) |short| {try writeZshFlag(w, &.{ '-', short }, flag.values, description, exec_name);@@ -272,7 +297,8 @@ const Ident = struct {/// Writes help.zon text into a single-quoted string: `{0s}` becomes the exec/// name and each line break with its indentation a single space. zsh also/// needs `[]` escaped, as descriptions sit inside `--flag[description]`.-fn writeText(w: *Writer, text: []const u8, exec_name: []const u8, comptime quoting: enum { fish, zsh }) !void {+/// `fish_value` is a double-quoted string inside the single-quoted `-a`.+fn writeText(w: *Writer, text: []const u8, exec_name: []const u8, comptime quoting: enum { fish, fish_value, zsh }) !void {var i: usize = 0;while (i < text.len) : (i += 1) {if (std.mem.startsWith(u8, text[i..], "{0s}")) {@@ -291,6 +317,12 @@ fn writeText(w: *Writer, text: []const u8, exec_name: []const u8, comptime quoti'\\', '\'' => try w.print("\\{c}", .{c}),else => try w.writeByte(c),},+ .fish_value => switch (c) {+ '\\' => try w.writeAll("\\\\\\\\"),+ '"', '$' => try w.print("\\\\{c}", .{c}),+ '\'' => try w.writeAll("\\'"),+ else => try w.writeByte(c),+ },.zsh => switch (c) {'\'' => try w.writeAll("'\\''"),'[', ']' => try w.print("\\{c}", .{c}),@@ -313,37 +345,73 @@ fn commandSummary(name: []const u8) []const u8 {return "";}-/// The first sentence of the flag's description, from the command's own help-/// or else the common options. It can span lines, as written in help.zon.-fn describe(help_text: []const u8, flag: []const u8) []const u8 {- return findDescription(help_text, flag) orelse findDescription(Help.common_options, flag) orelse "";+/// The indented lines documenting the flag, from the command's own help or+/// else the common options.+fn flagBlock(help_text: []const u8, flag: []const u8) []const u8 {+ return findBlock(help_text, flag) orelse findBlock(Help.common_options, flag) orelse "";}-fn findDescription(text: []const u8, flag: []const u8) ?[]const u8 {+fn findBlock(text: []const u8, flag: []const u8) ?[]const u8 {var lines = std.mem.splitScalar(u8, text, '\n');while (lines.next()) |line| {if (!std.mem.startsWith(u8, line, " -")) continue;var tokens = std.mem.tokenizeAny(u8, line, " ,");while (tokens.next()) |token| {- if (std.mem.eql(u8, token, flag)) return firstSentence(lines.rest());+ if (!std.mem.eql(u8, token, flag)) continue;+ const rest = lines.rest();+ var end: usize = 0;+ var block = std.mem.splitScalar(u8, rest, '\n');+ while (block.next()) |block_line| {+ // Blank lines can separate the rows of a table.+ if (block_line.len == 0) continue;+ if (!std.mem.startsWith(u8, block_line, " ")) break;+ end = block.index orelse rest.len;+ }+ return rest[0..end];}}return null;}-/// `text` starts with the indented description lines that follow a flag.-fn firstSentence(text: []const u8) []const u8 {+/// The block's first sentence, which can span lines.+fn summary(block: []const u8) []const u8 {var end: usize = 0;- var lines = std.mem.splitScalar(u8, text, '\n');+ var lines = std.mem.splitScalar(u8, block, '\n');while (lines.next()) |line| {const trimmed = std.mem.trimStart(u8, line, " ");- if (trimmed.len == line.len or- std.mem.startsWith(u8, trimmed, "Defaults") or+ if (std.mem.startsWith(u8, trimmed, "Defaults") orstd.mem.startsWith(u8, trimmed, "Allowed values") orstd.mem.startsWith(u8, trimmed, "e.g.")) break;- end = lines.index orelse text.len;+ end = lines.index orelse block.len;+ }+ return firstSentence(block[0..end]);+}++/// The value's description in the block's `Allowed values:` table, where a+/// row is the value, then its description, wrapped at the same column.+fn valueSummary(block: []const u8, value: []const u8) []const u8 {+ const table = block[(std.mem.indexOf(u8, block, "Allowed values:\n") orelse return "")..];+ var lines = std.mem.splitScalar(u8, table, '\n');+ _ = lines.next();+ while (lines.index) |line_start| {+ const line = lines.next().?;+ const row = std.mem.trimStart(u8, line, " ");+ if (!std.mem.startsWith(u8, row, value) or !std.mem.startsWith(u8, row[value.len..], " ")) continue;++ const column = line.len - std.mem.trimStart(u8, row[value.len..], " ").len;+ var end = line_start + line.len;+ while (lines.peek()) |next| {+ if (next.len - std.mem.trimStart(u8, next, " ").len < column) break;+ end = lines.index.? + next.len;+ _ = lines.next();+ }+ return firstSentence(table[line_start + column .. end]);}- const body = std.mem.trim(u8, text[0..end], " \n");+ return "";+}++fn firstSentence(text: []const u8) []const u8 {+ const body = std.mem.trim(u8, text, " \n");return body[0 .. sentenceEnd(body) orelse std.mem.trimEnd(u8, body, ".").len];}@@ -361,7 +429,7 @@ fn sentenceEnd(text: []const u8) ?usize {test "completion: every flag is documented" {for (commands, help_texts) |command, help_text| {for (command.flags) |flag| {- if (describe(help_text, flag.name).len == 0) {+ if (summary(flagBlock(help_text, flag.name)).len == 0) {std.debug.print("{s} {s} has no entry in help.zon\n", .{ command.name, flag.name });return error.Undocumented;}@@ -371,12 +439,27 @@ test "completion: every flag is documented" {}test "completion: describe" {- try std.testing.expectEqualStrings("Path to a file to load cookies from (read-only)", describe(Help.fetch, "--cookie"));+ try std.testing.expectEqualStrings("Path to a file to load cookies from (read-only)", summary(flagBlock(Help.fetch, "--cookie")));// e.g. doesn't end the sentence.- try std.testing.expectEqualStrings("The host to advertise, e.g. in the /json/version response", describe(Help.serve, "--advertise-host"));+ try std.testing.expectEqualStrings("The host to advertise, e.g. in the /json/version response", summary(flagBlock(Help.serve, "--advertise-host")));// Found in the common options.- try std.testing.expectEqualStrings("The log level", describe(Help.serve, "--log-level"));- try std.testing.expectEqualStrings("", describe(Help.serve, "--nope"));+ try std.testing.expectEqualStrings("The log level", summary(flagBlock(Help.serve, "--log-level")));+ try std.testing.expectEqualStrings("", summary(flagBlock(Help.serve, "--nope")));+}++test "completion: valueSummary" {+ const dump = flagBlock(Help.fetch, "--dump");+ try std.testing.expectEqualStrings("Serialized HTML of the DOM", valueSummary(dump, "html"));+ // Wrapped rows keep their line break until written.+ try std.testing.expectEqualStrings(+ "Text-only rendering of the page as a\n PDF file (base64 with --json)",+ valueSummary(dump, "pdf"),+ );+ // `semantic_tree` is a prefix of `semantic_tree_text`.+ try std.testing.expectEqualStrings("JSON-serialized semantic tree", valueSummary(dump, "semantic_tree"));+ try std.testing.expectEqualStrings("", valueSummary(dump, "wpt"));+ // Inline lists have no per-value descriptions.+ try std.testing.expectEqualStrings("", valueSummary(flagBlock(Help.agent, "--effort"), "low"));}test "completion: fish" {@@ -389,7 +472,8 @@ test "completion: fish" {"complete -c lp -n __fish_use_subcommand -a fetch -d 'fetches the specified URL'\n","complete -c lp -n '__fish_seen_subcommand_from fetch' -l with-base -d ","complete -c lp -n '__fish_seen_subcommand_from fetch' -l cookie -r -F -d ",- "complete -c lp -n '__fish_seen_subcommand_from fetch' -l dump -x -a 'html markdown ",+ "complete -c lp -n '__fish_seen_subcommand_from fetch' -l dump -x -a 'html\\t\"Serialized HTML of the DOM\" markdown\\t\"Converts content to Markdown\" png\\t\"Text-only rendering of the page as a PNG image (base64 with --json)\" ",+ "complete -c lp -n '__fish_seen_subcommand_from fetch' -l load-resources -x -a '(__lp_list image\\t\"<img> sources, so that load/error reflects the real HTTP status\" iframe\\t\"When enabled, <iframe> elements are fully loaded\" worker\\t\"Enable loading dedicated and shared workers\" stylesheet\\t","complete -c lp -n '__fish_seen_subcommand_from agent' -l attach -s a -r -F -d ","complete -c lp -n '__fish_seen_subcommand_from run' -F\n","complete -c lp -n '__fish_seen_subcommand_from completion' -a 'bash fish zsh'\n",