escriba_command/ex.rs
1//! The ex-command NAME GRAMMAR — vim's abbreviations, resolved in one place.
2//!
3//! `:wq` is not a command name. It is a *spelling* of one, and vim has a
4//! whole grammar of them: every ex command has a full name, a minimum prefix
5//! that selects it, and an optional `!`. `:w`, `:wr`, `:writ`, `:write` are
6//! one command; `:q`, `:qu`, `:quit` are another; `:qa` and `:quita` are a
7//! third, and the reason `:qu` is not the third is that `quitall`'s minimum
8//! is five characters, not one.
9//!
10//! The runtime used to carry that knowledge as three arms —
11//! `"w" => "save", "q" => "quit", "u" => "undo"` — and every other spelling
12//! fell through to a registry lookup that could not possibly hold it. `:wq`
13//! reported "command not found" while both halves of it worked.
14//!
15//! So the grammar is a TABLE, not a chain of ifs, and the table is the only
16//! thing that knows how a typed word becomes a registered command. Two
17//! properties follow, and both are asserted rather than asserted-to:
18//!
19//! - **Every valid abbreviation resolves.** For each verb, every prefix from
20//! its minimum to its full spelling selects it (`abbreviations_all_resolve`).
21//! - **No abbreviation is ambiguous.** No typed word is a valid abbreviation
22//! of two verbs (`no_abbreviation_is_ambiguous`) — which is a property of
23//! the *minimums*, and the reason vim gives `quitall` a five-character one.
24//!
25//! A word the grammar does not know is passed through UNCHANGED to the
26//! registry, so `:noh`, `:picker.files` and every plugin-registered command
27//! still dispatch. The grammar covers the vim vocabulary; it does not fence
28//! the command namespace.
29
30/// One ex command's spelling rule.
31///
32/// `plain` and `forced` are separate registered command names rather than one
33/// name plus a bang argument. A command body receives `&[String]` and nothing
34/// else, so a bang passed as an argument is a convention every body has to
35/// remember to read — and the one that forgets quits without asking. Two
36/// names cannot be misread, and both show up in `--commands` saying what they
37/// do. Verbs for which `!` changes nothing (writing has no force semantics
38/// here — escriba has no read-only flag to override) point both fields at the
39/// same command, which is the honest encoding of "the bang is accepted and
40/// means nothing".
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub struct ExVerb {
43 /// The full spelling, as `:help ex-cmd-index` writes it.
44 pub full: &'static str,
45 /// The fewest characters that select it. `full[..min]` is what vim
46 /// prints in square-bracket notation: `:q[uit]` is `("quit", 1)`.
47 pub min: usize,
48 /// The registered command the plain form dispatches to.
49 pub plain: &'static str,
50 /// The registered command the `!` form dispatches to.
51 pub forced: &'static str,
52}
53
54impl ExVerb {
55 /// Does `word` spell this verb? Prefix of the full name, at least `min`
56 /// characters long — vim's rule exactly.
57 #[must_use]
58 pub fn spelled_by(&self, word: &str) -> bool {
59 word.len() >= self.min && self.full.len() >= word.len() && self.full.starts_with(word)
60 }
61
62 /// The command name for this verb, banged or not.
63 #[must_use]
64 pub const fn command(&self, bang: bool) -> &'static str {
65 if bang { self.forced } else { self.plain }
66 }
67}
68
69/// The vim write/quit family plus the two verbs the old three-arm table
70/// carried, with vim's own minimum prefixes.
71///
72/// Deliberately NOT the whole ex vocabulary: a verb belongs here once escriba
73/// has something for it to dispatch to. An entry naming a command that is not
74/// registered would report "declared but not implemented yet" — announced,
75/// per [`crate::CommandError::Unhandled`], but still a promise the editor
76/// cannot keep.
77pub const VERBS: &[ExVerb] = &[
78 // ── write ────────────────────────────────────────────────────────
79 ExVerb {
80 full: "write",
81 min: 1,
82 plain: "save",
83 forced: "save",
84 },
85 ExVerb {
86 full: "wall",
87 min: 2,
88 plain: "buffer.write-all",
89 forced: "buffer.write-all",
90 },
91 // ── write-and-quit ───────────────────────────────────────────────
92 ExVerb {
93 full: "wq",
94 min: 2,
95 plain: "write-quit",
96 forced: "write-quit",
97 },
98 ExVerb {
99 full: "wqall",
100 min: 3,
101 plain: "write-quit-all",
102 forced: "write-quit-all",
103 },
104 // `:x` differs from `:wq` by ONE thing and it is the thing that matters
105 // to anything watching the file: it writes only when the buffer is
106 // modified, so `:x` on an untouched file leaves the mtime alone and a
107 // watching build does not rebuild.
108 ExVerb {
109 full: "xit",
110 min: 1,
111 plain: "exit-write",
112 forced: "exit-write",
113 },
114 ExVerb {
115 full: "xall",
116 min: 2,
117 plain: "write-quit-all",
118 forced: "write-quit-all",
119 },
120 ExVerb {
121 full: "exit",
122 min: 3,
123 plain: "exit-write",
124 forced: "exit-write",
125 },
126 // ── quit ─────────────────────────────────────────────────────────
127 ExVerb {
128 full: "quit",
129 min: 1,
130 plain: "quit",
131 forced: "quit!",
132 },
133 ExVerb {
134 full: "qall",
135 min: 2,
136 plain: "quit-all",
137 forced: "quit-all!",
138 },
139 ExVerb {
140 full: "quitall",
141 min: 5,
142 plain: "quit-all",
143 forced: "quit-all!",
144 },
145 // ── the two the old table carried ────────────────────────────────
146 ExVerb {
147 full: "undo",
148 min: 1,
149 plain: "undo",
150 forced: "undo",
151 },
152 ExVerb {
153 full: "redo",
154 min: 3,
155 plain: "redo",
156 forced: "redo",
157 },
158];
159
160/// The verb `word` spells, if any. `word` carries no `!` and no arguments.
161#[must_use]
162pub fn resolve(word: &str) -> Option<&'static ExVerb> {
163 VERBS.iter().find(|v| v.spelled_by(word))
164}
165
166/// A parsed ex line: which command to run, and with what.
167#[derive(Debug, Clone, PartialEq, Eq)]
168pub struct Invocation {
169 /// The registered command name to dispatch.
170 pub command: String,
171 /// Everything after the command word.
172 pub args: Vec<String>,
173}
174
175/// Parse a command line into the command to dispatch and its arguments.
176///
177/// `None` for an empty line — `:` then `<CR>` does nothing, as in vim, rather
178/// than dispatching the empty name and reporting it missing.
179///
180/// A word the grammar knows resolves through [`VERBS`]; anything else is
181/// passed through with its `!` intact, so what the operator typed is what the
182/// "not found" report names. Silently stripping a bang off an unknown word
183/// would turn `:Ghost!` into a report about `:Ghost`, which is a report about
184/// a different thing than the one that failed.
185#[must_use]
186pub fn parse(line: &str) -> Option<Invocation> {
187 let line = line.trim();
188 let line = line.strip_prefix(':').unwrap_or(line);
189 let mut parts = line.split_whitespace();
190 let word = parts.next()?;
191 let args: Vec<String> = parts.map(str::to_string).collect();
192 let (head, bang) = word
193 .strip_suffix('!')
194 .map_or((word, false), |stripped| (stripped, true));
195 let command = resolve(head).map_or_else(|| word.to_string(), |v| v.command(bang).to_string());
196 Some(Invocation { command, args })
197}
198
199#[cfg(test)]
200mod tests {
201 use super::*;
202
203 /// Every abbreviation vim would accept reaches its verb. This is the
204 /// all-variants proof: it walks the table rather than sampling it, so a
205 /// verb added with a wrong `min` fails here rather than in an operator's
206 /// hands.
207 #[test]
208 fn abbreviations_all_resolve() {
209 for v in VERBS {
210 for len in v.min..=v.full.len() {
211 let word = &v.full[..len];
212 assert_eq!(
213 resolve(word),
214 Some(v),
215 "`:{word}` must resolve to `{}`",
216 v.full,
217 );
218 }
219 }
220 }
221
222 /// No typed word spells two verbs. Ambiguity here is invisible in normal
223 /// use — [`resolve`] takes the first match, so the SECOND verb simply
224 /// becomes unreachable at that spelling, which nothing else would notice.
225 #[test]
226 fn no_abbreviation_is_ambiguous() {
227 for v in VERBS {
228 for len in v.min..=v.full.len() {
229 let word = &v.full[..len];
230 let hits: Vec<&str> = VERBS
231 .iter()
232 .filter(|c| c.spelled_by(word))
233 .map(|c| c.full)
234 .collect();
235 assert_eq!(hits.len(), 1, "`:{word}` is ambiguous: {hits:?}");
236 }
237 }
238 }
239
240 /// A shorter-than-minimum prefix resolves to nothing rather than to the
241 /// wrong thing. `:q` must never be `:qall`.
242 #[test]
243 fn below_the_minimum_selects_nothing() {
244 for v in VERBS {
245 for len in 1..v.min {
246 let word = &v.full[..len];
247 let hit = resolve(word);
248 assert!(
249 hit.is_none_or(|h| h.full != v.full),
250 "`:{word}` is below `{}`'s minimum and must not select it",
251 v.full,
252 );
253 }
254 }
255 }
256
257 #[test]
258 fn the_write_quit_family_reaches_its_commands() {
259 for (typed, expect) in [
260 ("w", "save"),
261 ("write", "save"),
262 ("wq", "write-quit"),
263 ("wq!", "write-quit"),
264 ("wqa", "write-quit-all"),
265 ("wqall", "write-quit-all"),
266 ("x", "exit-write"),
267 ("xit", "exit-write"),
268 ("xa", "write-quit-all"),
269 ("exi", "exit-write"),
270 ("exit", "exit-write"),
271 ("wa", "buffer.write-all"),
272 ("q", "quit"),
273 ("q!", "quit!"),
274 ("quit", "quit"),
275 ("qa", "quit-all"),
276 ("qa!", "quit-all!"),
277 ("quita", "quit-all"),
278 ("quitall", "quit-all"),
279 ("u", "undo"),
280 ("red", "redo"),
281 ] {
282 assert_eq!(
283 parse(typed).map(|i| i.command),
284 Some(expect.to_string()),
285 "`:{typed}`",
286 );
287 }
288 }
289
290 #[test]
291 fn a_leading_colon_and_surrounding_space_are_not_part_of_the_name() {
292 assert_eq!(parse(":wq").map(|i| i.command), Some("write-quit".into()));
293 assert_eq!(
294 parse(" wq ").map(|i| i.command),
295 Some("write-quit".into())
296 );
297 }
298
299 #[test]
300 fn an_empty_line_dispatches_nothing() {
301 assert_eq!(parse(""), None);
302 assert_eq!(parse(" "), None);
303 assert_eq!(parse(":"), None);
304 }
305
306 #[test]
307 fn an_unknown_word_passes_through_with_its_bang() {
308 // Registry names must survive the grammar untouched…
309 assert_eq!(parse("noh").map(|i| i.command), Some("noh".into()));
310 assert_eq!(
311 parse("picker.files").map(|i| i.command),
312 Some("picker.files".into()),
313 );
314 // …and an unknown bang is reported as the operator typed it.
315 assert_eq!(parse("Ghost!").map(|i| i.command), Some("Ghost!".into()));
316 }
317
318 #[test]
319 fn arguments_survive_the_verb() {
320 let i = parse("w foo.txt bar").expect("a verb with arguments parses");
321 assert_eq!(i.command, "save");
322 assert_eq!(i.args, vec!["foo.txt".to_string(), "bar".to_string()]);
323 }
324}