Debian Codegraph @

testsuite/completion.00-init/030-zsh-procs.exp

raw
1 ##############################################################################
2 # Modules Revision 3.0
3 # Providing a flexible user environment
4 #
5 # File: completion.00-init/%M%
6 # Revision: %I%
7 # First Edition: 2026/08/10
8 # Last Mod.: %U%, %G%
9 #
10 # Authors: Xavier Delaruelle, [email protected]
11 #
12 # Description: Test procedures
13 # Command:
14 # Sub-Command:
15 #
16 # Comment: %C{
17 # Defines the test procedures driving a real zsh pty to
18 # exercise the module Tab completion script exactly as a
19 # user pressing Tab would, then collect the resulting
20 # candidate word list. This mirrors 020-bash-procs.exp's
21 # completion_bash_{start,raw,list,close} set (see that
22 # file's header for why each shell gets its own), but
23 # the zsh line editor (zle) redraws candidates through a
24 # completely different byte stream than readline, so the
25 # raw-output parsing below is specific to zsh: no bell
26 # is rung when a Tab silently extends the typed word to
27 # a longer (still ambiguous) common prefix -- unlike
28 # readline, only a Tab that cannot insert anything at
29 # all rings the bell -- and every candidate list is
30 # preceded by a cursor-up escape sequence that this file
31 # uses as the reliable end-of-list marker, plus (for
32 # option flags, which zsh's _arguments lists one per
33 # line together with a "-- description" suffix, unlike
34 # bash's bare compgen listing) a per-line " -- " cut
35 # that drops the description text before it can pollute
36 # the candidate word list
37 # }C%
38 #
39 ##############################################################################
40
41 # tail pattern matching zero or more trailing ANSI CSI escape sequences (eg
42 # the bracketed-paste mode toggle zle emits right after redrawing a prompt);
43 # folded into every prompt-wait regexp below since such sequences may or may
44 # not have landed in the read buffer yet by the time the prompt text itself
45 # is matched
46 set completion_zsh_csitail {(\x1b\[[0-9;?]*[a-zA-Z])*}
47
48 # start a fresh zsh session with the completion script under test wired into
49 # FPATH and 'module' completion registered (via the script's own '#compdef
50 # module' pragma, picked up by compinit), ready to accept commands
51 proc completion_zsh_start {} {
52 global zshbin zshcompletion completion_prompt completion_zsh_spawn_id
53 global completion_zsh_csitail TCLSH MODULECMD verbose
54
55 if {$verbose > 1} {
56 send_user "\tStarting zsh for completion test\n"
57 }
58
59 spawn $zshbin -f
60 set completion_zsh_spawn_id $spawn_id
61
62 # Expect's default 'match_max' (2000 bytes) truncates (silently drops
63 # the oldest bytes of) any read buffer that grows past it before a
64 # pattern matches -- a real risk here: a wide pty (see below) pads every
65 # candidate line out to the terminal width, so even a modest listing of
66 # option flags with descriptions is several thousand bytes: raise it
67 # well past the largest listing this file can produce (module bare
68 # 'module ', dozens of sub-commands, still under it)
69 match_max -i $completion_zsh_spawn_id 100000
70
71 # a narrow (default 80-column) pty can make a long completed line wrap,
72 # which makes zle redraw it with extra escape sequences that can be
73 # mistaken for stray inserted characters (e.g. a trailing space) by
74 # anything matching on raw output; go wide enough that no cmdline used
75 # in these tests is ever at risk of wrapping
76 stty rows 40 columns 500 < $spawn_out(slave,name)
77
78 set spawn_id $completion_zsh_spawn_id
79 expect {
80 -re {[%#] } {}
81 timeout { unresolved {completion zsh did not start}; return }
82 }
83
84 # every wait up to (not including) the PS1 change below deliberately
85 # does not anchor on end-of-buffer ('$'): zsh's stock, unconfigured
86 # prompt is still followed by a bracketed-paste-mode escape sequence
87 # (until the first command below disables it) that may or may not have
88 # already landed in the read buffer by the time the prompt text itself
89 # is matched, same problem completion_zsh_csitail works around further
90 # down -- except here that toggle has not been disabled yet, so its
91 # exact tail length cannot be predicted; every setup command after this
92 # point goes through completion_zsh_raw, which matches on the
93 # (by-then-custom) prompt plus completion_zsh_csitail
94 send -- "zle_bracketed_paste=()\r"
95 expect -re {[%#] }
96 # zsh pads the line with reverse-video spaces (ending in a highlighted
97 # '%') before any prompt whose previous line did not end with a newline,
98 # to visually flag the truncation -- since every command here is sent
99 # terminated with a bare '\r', that marker would otherwise appear before
100 # every single prompt redraw
101 send -- "unsetopt PROMPT_SP PROMPT_CR\r"
102 expect -re {[%#] }
103 send -- "PROMPT_EOL_MARK=''\r"
104 expect -re {[%#] }
105 # zle asks "Do you wish to see all N possibilities (M lines)?" instead
106 # of listing outright once matches exceed this threshold (100 by
107 # default; 0 instead falls back to comparing against the terminal
108 # size, which a mere 40-row pty would still trip for a long listing);
109 # some completions here (e.g. bare 'module', dozens of sub-commands)
110 # go well past the default
111 send -- "LISTMAX=100000\r"
112 expect -re {[%#] }
113 # avoid filename-completion color codes (eg from a LS_COLORS inherited
114 # from the invoking terminal) getting mixed into the raw output the
115 # 'use' directory-completion test parses
116 send -- "unset LS_COLORS\r"
117 expect -re {[%#] }
118 send -- "PS1='$completion_prompt'\r"
119 expect {
120 -re "$completion_prompt$completion_zsh_csitail\$" {}
121 timeout { unresolved {completion zsh prompt setup timed out}; return }
122 }
123
124 completion_zsh_raw {zstyle ':completion:*' list-colors ''}
125 # put the built completion script's directory at the front of FPATH and
126 # load it; compinit registers 'module' completion itself, from the
127 # script's own '#compdef module' pragma -- '-u' skips the
128 # owner/group-writability check compinit would otherwise run on every
129 # function file found on FPATH, which would need real ownership of the
130 # (sandboxed, throwaway) test tree to pass
131 completion_zsh_raw "fpath=('[file dirname $zshcompletion]' \$fpath)"
132 completion_zsh_raw {autoload -Uz compinit}
133 completion_zsh_raw {compinit -u}
134 # a real 'module' command is needed since the completion script shells
135 # out to it (module avail/spider) to list candidate module names
136 completion_zsh_raw "eval \"\$('$TCLSH' '$MODULECMD' zsh autoinit)\""
137 }
138
139 # send a line to the completion zsh session and wait for the next prompt;
140 # used for setup commands whose output is not asserted on
141 proc completion_zsh_raw {line} {
142 global completion_zsh_spawn_id completion_prompt completion_zsh_csitail
143 global verbose
144
145 set spawn_id $completion_zsh_spawn_id
146 send -- "$line\r"
147 expect {
148 -re "\r\n$completion_zsh_csitail$completion_prompt$completion_zsh_csitail\$" {}
149 timeout { unresolved "completion setup command timed out: $line" }
150 }
151 if {$verbose > 1} {
152 send_user "\tcompletion> $line\n"
153 }
154 }
155
156 # strip every ANSI CSI escape sequence from a chunk of raw zle output; used
157 # by both completion_zsh_list and completion_zsh_inline once the byte range
158 # of interest has been isolated
159 proc completion_zsh_strip_csi {str} {
160 return [regsub -all {\x1b\[[0-9;?]*[a-zA-Z]} $str {}]
161 }
162
163 # clean up the text zle inserted right after a cmdline's echo: drop the
164 # cursor-left/spaces/cursor-left triplet zle uses to erase whatever longer
165 # text (eg a prior candidate, or the old end of the line) used to occupy
166 # the redrawn region, then strip any other escape sequence and the
167 # trailing carriage returns coming from zle's redraw -- a real bell
168 # character, if present, is deliberately left untouched. Used by both
169 # completion_zsh_inline and completion_zsh_list's single-candidate fallback
170 proc completion_zsh_clean_suffix {suffix} {
171 regsub -all {\x1b\[[0-9]*D[ ]*\x1b\[[0-9]*D} $suffix {} suffix
172 set suffix [completion_zsh_strip_csi $suffix]
173 regsub -all {[\r\x08]} $suffix {} suffix
174 return $suffix
175 }
176
177 # send a partial command line followed by a double-Tab (the first Tab
178 # silently inserts any further common prefix zsh can determine and rings the
179 # bell only if that leaves the completion still ambiguous; the second Tab is
180 # what makes zle list every ambiguous match, per the 'AUTO_MENU' option this
181 # also puts zle into menu-selection -- inserting the first listed candidate
182 # inline -- but that is discarded here along with the rest of the line by
183 # the trailing ^U), and return the sorted, de-duplicated list of candidate
184 # words zle displayed. Unlike bash, where an option-bearing sub-command's
185 # candidate set always includes its option flags alongside its
186 # modulefile/collection candidates (so it is never accidentally a single
187 # candidate), zsh's _module.in offers only one of the two at a time (gated
188 # on whether the word being completed starts with '-', same as bash's own
189 # _module_avail() internally does for its half) -- so a cmdline whose
190 # non-flag candidate set genuinely has only one member (eg a sub-command
191 # ground-truth check against a fixture with only one loaded module) hits a
192 # unique completion instead of a listing; that case is detected by the
193 # absence of the epilogue marker below and handled by reconstructing the
194 # single candidate from the inline insertion instead, the same way
195 # completion_zsh_inline does
196 proc completion_zsh_list {cmdline} {
197 global completion_zsh_spawn_id completion_prompt completion_last_cmdline
198 global completion_zsh_csitail verbose
199
200 set completion_last_cmdline $cmdline
201 set spawn_id $completion_zsh_spawn_id
202 set recmdline [completion_re_escape $cmdline]
203
204 send -- "$cmdline\t\t"
205 # let the whole candidate block land in the pty buffer -- and zle
206 # finish drawing it -- before sending the cleanup '^U' below: sending
207 # it while zle is still mid-redraw (eg still waiting on a 'module
208 # avail'/'module spider' subprocess for some other, slower candidate
209 # set) corrupts the redraw (observed as entire leading rows of an
210 # otherwise-fine listing going missing), and interactively this margin
211 # is comfortable, but on a loaded machine it can be tight
212 after 1500
213 # clear the (uncompleted, possibly menu-selected, or already-unique)
214 # input line so the session is ready to reuse; capture everything from
215 # right after the Tabs through this cleanup in one shot, rather than
216 # trying to spot where the listing itself ends on its own -- a listing
217 # taller than the pty scrolls it, and a scrolled listing has no reliable
218 # "done" marker of its own (no cursor-up-N is emitted: there is nothing
219 # above the top row left to return the cursor to)
220 send -- "\025\r"
221 set buffer {}
222 expect {
223 -re "(?s)(.*)\r\n$completion_zsh_csitail$completion_prompt$completion_zsh_csitail\$" {
224 set buffer $expect_out(1,string)
225 }
226 timeout {
227 unresolved "completion listing timed out for '$cmdline'"
228 return {}
229 }
230 }
231 if {$verbose > 1} {
232 send_user "\tcompletion raw listing for '$cmdline':\n$buffer\n"
233 }
234
235 # the captured text starts with the raw echo of $cmdline plus the first
236 # Tab's response (a bell, or a silently inserted common-prefix
237 # extension) -- neither of which is candidate data -- followed by a
238 # real newline, then (if the completion was ambiguous) the actual
239 # multi-column (or, for option flags, one-per-line) listing. A listing
240 # short enough to fit in the pty ends in zle's 'sgr0/rmso/rmul'-alike
241 # epilogue right before it repaints the cmdline (auto-menu-selected
242 # onto its first candidate) and, after this proc's own '^U', the
243 # prompt -- a more reliable end-of-listing marker than a cursor-up-N
244 # escape sequence, which is only emitted in this same case. A listing
245 # too tall for the pty (eg bare 'module', enough sub-commands to
246 # scroll even a generously-tall terminal) instead just ends the
247 # captured text outright, with neither marker: zle leaves it as the
248 # last thing printed rather than trying to redraw a cmdline that has
249 # scrolled off
250 set epilogue {\x1b\[0m\x1b\[27m\x1b\[24m}
251 set cmdstart [string first $cmdline $buffer]
252 if {$cmdstart == -1} {
253 set cmdstart 0
254 }
255 set nl [string first "\n" $buffer $cmdstart]
256 # this exact epilogue also prefixes every ordinary prompt redraw (eg the
257 # fresh prompt this proc's own '^U' produces), so search for it starting
258 # only from the real listing's start, not from the top of the buffer --
259 # otherwise a straggler byte or two of the *previous* completion_zsh_list/
260 # _inline call's own prompt redraw, still in flight when this call's
261 # Tabs were sent and thus prepended ahead of $cmdstart, would match here
262 # first and be mistaken for this listing's own end
263 set have_epilogue [expr {$nl != -1\
264 && [regexp -indices -start $nl -- $epilogue $buffer epi_range]}]
265
266 # the escape sequences that epilogue matches are only emitted when the
267 # pty has standout/underline capability in the first place -- on a pty
268 # with none (eg observed on GitHub Actions' own runners), the exact same
269 # auto-menu-selected redraw happens with no escape sequences around it
270 # at all, just a bare bell plus plain erase-and-reprint. Since that
271 # redraw always re-echoes the prompt immediately followed by $cmdline
272 # verbatim (eg 'module -' becoming 'MODULESTEST> module --color=',
273 # 'module ' becoming "MODULESTEST> module \x07aliases"), that pair
274 # reappearing anywhere after the listing starts is a reliable,
275 # escape-sequence-independent fallback signal for the exact same
276 # end-of-listing boundary -- matching on the prompt too, not just
277 # $cmdline alone, keeps this from cutting the listing short if some
278 # candidate or description text happens to itself contain $cmdline as a
279 # substring (eg $cmdline "module " inside a "-- ... module list ..."
280 # description)
281 set reecho [string first "$completion_prompt$cmdline" $buffer\
282 [expr {$nl + 1}]]
283
284 if {$have_epilogue} {
285 lassign $epi_range epi_start epi_end
286 set listing [string range $buffer $nl+1 $epi_start-1]
287 } elseif {$nl != -1 && $reecho != -1} {
288 set listing [string range $buffer $nl+1 $reecho-1]
289 } elseif {$nl != -1 && [string first "\n" $buffer $nl+1] != -1} {
290 # no epilogue and no cmdline re-echo either, but more than one line
291 # of content followed the echo: a scrolled, too-tall-for-the-pty
292 # listing (see above) rather than a single-candidate insertion,
293 # which never spans more than one line
294 set listing [string range $buffer $nl+1 end]
295 } else {
296 # neither: the second Tab found a single, already-unique candidate
297 # and inserted it inline instead of listing anything (see this
298 # proc's header); reconstruct that one candidate from the inline
299 # insertion. When the sub-command accepts more than one modulefile
300 # (eg 'unload'/'delete'), that second Tab can go on to immediately
301 # re-trigger completion for the (again unique) next argument too,
302 # duplicating the same word right after itself -- split on
303 # whitespace and de-duplicate rather than returning that whole
304 # blob as one candidate
305 set suffix {}
306 regexp "(?s)${recmdline}(.*)" $buffer -> suffix
307 set suffix [string trim [completion_zsh_clean_suffix $suffix]]
308 if {$suffix eq {} || $suffix eq "\a"} {
309 return {}
310 }
311 return [lsort -unique [split $suffix]]
312 }
313
314 set listing [completion_zsh_strip_csi $listing]
315
316 # collapse the listing into a flat, sorted word list: a plain line (eg a
317 # module/collection/modulepath candidate) is split as-is, while a line
318 # zsh's _arguments describes (eg an option flag) has its trailing
319 # '-- description text' cut off first, since that description is made of
320 # ordinary words that would otherwise pollute the candidate list
321 set words {}
322 foreach line [split $listing "\r\n"] {
323 set sep [string first { -- } $line]
324 if {$sep != -1} {
325 set line [string range $line 0 $sep-1]
326 }
327 foreach word [split $line] {
328 if {$word ne {}} {
329 lappend words $word
330 }
331 }
332 }
333 return [lsort -unique $words]
334 }
335
336 # send a partial command line followed by a single Tab, and return the text
337 # zle inserted inline (no listing involved) -- a bell ('\a') if nothing at
338 # all could be completed, otherwise the extra characters zle appended (which
339 # may itself be just a further common-prefix extension, silently, with no
340 # bell, if the completion remains ambiguous beyond it -- unlike readline,
341 # see this file's header). Used to check unique, unambiguous completions --
342 # eg that a directory-style entry gets completed with a trailing '/' and no
343 # trailing space. cmdline must be a prefix with exactly one match, or with a
344 # common prefix short enough that no further Tab is needed to reach it,
345 # otherwise a single Tab may extend by less than a full match
346 proc completion_zsh_inline {cmdline} {
347 global completion_zsh_spawn_id completion_prompt completion_last_cmdline
348 global completion_zsh_csitail verbose
349
350 set completion_last_cmdline $cmdline
351 set spawn_id $completion_zsh_spawn_id
352 set recmdline [completion_re_escape $cmdline]
353
354 send -- "$cmdline\t"
355 # let every byte zle is going to redraw land in the pty buffer before
356 # reading it: an 'expect' pattern ending in a lazy '(.*)$' would
357 # otherwise match the instant the plain cmdline echo arrives, racing
358 # ahead of e.g. a trailing space that is still in flight
359 after 300
360 set suffix {}
361 expect {
362 -re "(?s)${recmdline}(.*)\$" {
363 set suffix $expect_out(1,string)
364 }
365 timeout {
366 unresolved "completion inline insert timed out for '$cmdline'"
367 }
368 }
369
370 # clear the (possibly completed) input line so the session is ready to
371 # reuse, same technique as completion_zsh_list
372 send -- "\025\r"
373 expect -re "\r\n$completion_zsh_csitail$completion_prompt$completion_zsh_csitail\$"
374
375 set suffix [completion_zsh_clean_suffix $suffix]
376
377 if {$verbose > 1} {
378 send_user "\tcompletion inline insert for '$cmdline': \[$suffix\]\n"
379 }
380
381 return $suffix
382 }
383
384 proc completion_zsh_close {} {
385 global completion_zsh_spawn_id
386
387 if {[info exists completion_zsh_spawn_id]} {
388 set spawn_id $completion_zsh_spawn_id
389 catch {send -- "exit\r"}
390 catch {expect eof}
391 catch {close -i $completion_zsh_spawn_id}
392 catch {wait -i $completion_zsh_spawn_id}
393 unset completion_zsh_spawn_id
394 }
395 }
396
397 # vim:set tabstop=3 shiftwidth=3 expandtab autoindent: