| 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: |