| 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/08 |
| 8 |
# Last Mod.: %U%, %G% |
| 9 |
# |
| 10 |
# Authors: Xavier Delaruelle, [email protected] |
| 11 |
# |
| 12 |
# Description: Fetch ground-truth completion data from 'module help' |
| 13 |
# Command: |
| 14 |
# Sub-Command: |
| 15 |
# |
| 16 |
# Comment: %C{ |
| 17 |
# Parse the 'module help' usage message into the set of |
| 18 |
# documented sub-commands, global switches and, for each |
| 19 |
# sub-command, the option flags and expected positional |
| 20 |
# argument kind (module, collection, directory, ...) that |
| 21 |
# apply to it, so completion tests can check that |
| 22 |
# Tab-completion proposes exactly this set -- neither |
| 23 |
# less nor more. Shell-agnostic: built once here and |
| 24 |
# reused by every shell's test file |
| 25 |
# }C% |
| 26 |
# |
| 27 |
############################################################################## |
| 28 |
|
| 29 |
if {$verbose} { |
| 30 |
send_user "\tParsing 'module help' output ...\n" |
| 31 |
} |
| 32 |
|
| 33 |
catch {exec $TCLSH $MODULECMD bash help} help_output |
| 34 |
|
| 35 |
# every documented sub-command name (aliases counted separately, eg 'add' |
| 36 |
# and 'load' on the same usage line both end up in this list) |
| 37 |
set help_subcmds {} |
| 38 |
|
| 39 |
# option flags (short and long forms) that apply to a given sub-command, |
| 40 |
# indexed by every alias name it goes by; a sub-command with no options at |
| 41 |
# all (eg 'purge') simply has no entry |
| 42 |
array set help_subcmd_opts {} |
| 43 |
|
| 44 |
# the kind of positional argument a sub-command's own usage synopsis |
| 45 |
# documents, indexed by every alias name it goes by: 'module' (a module |
| 46 |
# name/version, eg 'modulefile'/'modfile'/'mod1'/'mod2'/'mod'), |
| 47 |
# 'collection' (a saved collection name, eg 'collection'/'coll'), 'dir' (a |
| 48 |
# filesystem/modulepath directory, eg 'dir'/'modulepath'), 'stash' (a stash |
| 49 |
# collection name), 'file' (an arbitrary file, eg 'scriptfile'/ |
| 50 |
# 'shellscript'), or 'freeform' for anything else (a search string, shell |
| 51 |
# name, variable name, config value, ...) or no argument at all -- neither |
| 52 |
# of which bash completion can meaningfully complete against, so no |
| 53 |
# candidate beyond the sub-command's own options is expected there |
| 54 |
array set help_subcmd_argtype {} |
| 55 |
|
| 56 |
proc completion_help_classify_argtype {word} { |
| 57 |
switch -glob -- $word { |
| 58 |
modulepath { return dir } |
| 59 |
mod* { return module } |
| 60 |
coll* { return collection } |
| 61 |
dir { return dir } |
| 62 |
stash { return stash } |
| 63 |
scriptfile - shellscript { return file } |
| 64 |
default { return freeform } |
| 65 |
} |
| 66 |
} |
| 67 |
|
| 68 |
# short and long forms of the global switches listed under 'Options:' -- |
| 69 |
# these apply regardless of sub-command, and are what a bare |
| 70 |
# 'module -<Tab>' (no sub-command typed yet) proposes |
| 71 |
set help_switches {} |
| 72 |
|
| 73 |
# 'Switches:' section entries, keyed by short form: switch_long(-x) is a |
| 74 |
# list of {longform annotated_subcmds} pairs. Most short forms only ever |
| 75 |
# mean one thing (eg '-f' is always '--force'), but a couple are reused |
| 76 |
# with a different meaning on a specific sub-command (eg '-a' is '--all' |
| 77 |
# almost everywhere but '--append' on 'use', '-d' is '--default' for |
| 78 |
# avail/spider but '--delim' for the *-path commands) -- disambiguated |
| 79 |
# below using the "... (on 'x' sub-command)" annotation those entries carry |
| 80 |
array set switch_long {} |
| 81 |
|
| 82 |
# extract every '-'-prefixed token from a line, only counting tokens that |
| 83 |
# start a new word (preceded by line start, a space, '[' or '|') so a hyphen |
| 84 |
# embedded in a plain word (eg 'add-any') is never mistaken for an option. A |
| 85 |
# token immediately glued to '=' or '[=' (eg '--output=LIST', |
| 86 |
# '--color[=WHEN]') yields both the bare and the '=' form, since bash |
| 87 |
# completion offers both |
| 88 |
proc completion_help_extract_opts {line} { |
| 89 |
set opts {} |
| 90 |
set matches [regexp -all -inline -- {(^|[ \[|])(-{1,2}[A-Za-z][A-Za-z-]*)(=|\[=)?} $line] |
| 91 |
foreach {whole bound tok eq} $matches { |
| 92 |
lappend opts $tok |
| 93 |
if {$eq ne {}} { lappend opts "${tok}=" } |
| 94 |
} |
| 95 |
return $opts |
| 96 |
} |
| 97 |
|
| 98 |
# resolve a short flag used by a given sub-command to its long form(s) via |
| 99 |
# the Switches: table built while parsing |
| 100 |
proc completion_help_resolve_long {short_flag subcmd_name} { |
| 101 |
global switch_long |
| 102 |
|
| 103 |
if {![info exists switch_long($short_flag)]} { |
| 104 |
return {} |
| 105 |
} |
| 106 |
set candidates $switch_long($short_flag) |
| 107 |
if {[llength $candidates] == 1} { |
| 108 |
return [lindex $candidates 0 0] |
| 109 |
} |
| 110 |
foreach candidate $candidates { |
| 111 |
lassign $candidate long annotated_subcmds |
| 112 |
if {$subcmd_name in $annotated_subcmds} { |
| 113 |
return $long |
| 114 |
} |
| 115 |
} |
| 116 |
foreach candidate $candidates { |
| 117 |
lassign $candidate long annotated_subcmds |
| 118 |
if {[llength $annotated_subcmds] == 0} { |
| 119 |
return $long |
| 120 |
} |
| 121 |
} |
| 122 |
return {} |
| 123 |
} |
| 124 |
|
| 125 |
set section none |
| 126 |
set cur_names {} |
| 127 |
set cur_argtype_set 0 |
| 128 |
|
| 129 |
# state for the Switches: entry currently being accumulated -- its |
| 130 |
# description can wrap over several lines, possibly carrying the "(on 'x' |
| 131 |
# sub-command)" annotation on any of them |
| 132 |
set sw_short {} |
| 133 |
set sw_long {} |
| 134 |
set sw_desc {} |
| 135 |
|
| 136 |
proc completion_help_flush_switch {} { |
| 137 |
global sw_short sw_long sw_desc switch_long |
| 138 |
|
| 139 |
if {$sw_short eq {} && [llength $sw_long] == 0} { |
| 140 |
return |
| 141 |
} |
| 142 |
set annotated_subcmds {} |
| 143 |
if {[string match {*sub-command*} $sw_desc]} { |
| 144 |
foreach {whole name} [regexp -all -inline {'([A-Za-z][A-Za-z0-9_-]*)'} $sw_desc] { |
| 145 |
lappend annotated_subcmds $name |
| 146 |
} |
| 147 |
} |
| 148 |
if {$sw_short ne {}} { |
| 149 |
lappend switch_long($sw_short) [list $sw_long $annotated_subcmds] |
| 150 |
} |
| 151 |
set sw_short {} |
| 152 |
set sw_long {} |
| 153 |
set sw_desc {} |
| 154 |
} |
| 155 |
|
| 156 |
foreach line [split $help_output "\n"] { |
| 157 |
if {[regexp {^[A-Za-z][^:]*:$} $line]} { |
| 158 |
if {$section eq {switches}} { completion_help_flush_switch } |
| 159 |
if {[string match {*Options:} $line]} { |
| 160 |
set section options |
| 161 |
} elseif {[string match {*Switches:} $line]} { |
| 162 |
set section switches |
| 163 |
} elseif {[regexp {^[A-Za-z].* commands:$} $line]} { |
| 164 |
set section subcmds |
| 165 |
} else { |
| 166 |
set section none |
| 167 |
} |
| 168 |
set cur_names {} |
| 169 |
continue |
| 170 |
} |
| 171 |
if {[string trim $line] eq {}} { |
| 172 |
if {$section eq {switches}} { completion_help_flush_switch } |
| 173 |
set cur_names {} |
| 174 |
continue |
| 175 |
} |
| 176 |
|
| 177 |
if {$section eq {subcmds}} { |
| 178 |
# a plain description-continuation line (36-space indent, matching |
| 179 |
# the column every sub-command's description is aligned to) carries |
| 180 |
# no names or options of its own |
| 181 |
if {[string range $line 0 35] eq [string repeat { } 36]} { |
| 182 |
continue |
| 183 |
} |
| 184 |
set remainder $line |
| 185 |
if {[regexp {^ ([A-Za-z][A-Za-z0-9_-]*(?: \| [A-Za-z][A-Za-z0-9_-]*)*)} $line all names]} { |
| 186 |
# a new sub-command entry: remember its alias names, so option |
| 187 |
# tokens on any wrapped usage-synopsis continuation line (indented |
| 188 |
# less than the description column) still get attributed to it |
| 189 |
set cur_names [regexp -all -inline {[A-Za-z][A-Za-z0-9_-]*} $names] |
| 190 |
foreach n $cur_names { lappend help_subcmds $n } |
| 191 |
set cur_argtype_set 0 |
| 192 |
set remainder [string range $line [string length $all] end] |
| 193 |
} |
| 194 |
set opts [completion_help_extract_opts $line] |
| 195 |
foreach n $cur_names { |
| 196 |
foreach o $opts { lappend help_subcmd_opts($n) $o } |
| 197 |
} |
| 198 |
if {!$cur_argtype_set} { |
| 199 |
# strip every option bracket (content starting with '-'), so the |
| 200 |
# first word left over is the positional argument's own name (eg |
| 201 |
# 'modulefile' out of '[-i] [modulefile ...]') rather than an |
| 202 |
# option's; a sub-command with no positional argument at all |
| 203 |
# leaves only its description text here, whose first word never |
| 204 |
# matches a known keyword and safely falls back to 'freeform' -- |
| 205 |
# the same "nothing specific to complete" classification a real |
| 206 |
# freeform argument gets |
| 207 |
set stripped [regsub -all {\[-[^\]]*\]} $remainder {}] |
| 208 |
if {[regexp {[A-Za-z][A-Za-z0-9_-]*} $stripped word]} { |
| 209 |
set argtype [completion_help_classify_argtype $word] |
| 210 |
foreach n $cur_names { set help_subcmd_argtype($n) $argtype } |
| 211 |
set cur_argtype_set 1 |
| 212 |
} |
| 213 |
} |
| 214 |
} elseif {$section eq {options}} { |
| 215 |
if {[string index $line 2] ne {-}} { continue } |
| 216 |
foreach tok [completion_help_extract_opts $line] { |
| 217 |
lappend help_switches $tok |
| 218 |
} |
| 219 |
} elseif {$section eq {switches}} { |
| 220 |
# a new entry starts at a line indented by exactly 2 spaces; |
| 221 |
# anything indented further is a continuation of the current entry's |
| 222 |
# description |
| 223 |
if {[string range $line 0 1] eq { } && [string index $line 2] ne { }} { |
| 224 |
completion_help_flush_switch |
| 225 |
foreach t [completion_help_extract_opts $line] { |
| 226 |
if {[string match {--*} $t]} { |
| 227 |
lappend sw_long $t |
| 228 |
} elseif {$sw_short eq {}} { |
| 229 |
set sw_short $t |
| 230 |
} |
| 231 |
} |
| 232 |
} |
| 233 |
append sw_desc { } [string trim $line] |
| 234 |
} |
| 235 |
} |
| 236 |
if {$section eq {switches}} { completion_help_flush_switch } |
| 237 |
|
| 238 |
set help_subcmds [lsort -unique $help_subcmds] |
| 239 |
set help_switches [lsort -unique $help_switches] |
| 240 |
|
| 241 |
# combine each sub-command's short-form options (as documented in its own |
| 242 |
# usage synopsis) with their resolved long form(s), plus whichever tokens |
| 243 |
# were already long-form only (eg '--auto', '--tag=LIST') |
| 244 |
foreach n [array names help_subcmd_opts] { |
| 245 |
set full {} |
| 246 |
foreach tok [lsort -unique $help_subcmd_opts($n)] { |
| 247 |
lappend full $tok |
| 248 |
if {![string match {--*} $tok]} { |
| 249 |
foreach long [completion_help_resolve_long $tok $n] { |
| 250 |
lappend full $long |
| 251 |
} |
| 252 |
} |
| 253 |
} |
| 254 |
set help_subcmd_opts($n) [lsort -unique $full] |
| 255 |
} |
| 256 |
|
| 257 |
if {$verbose > 1} { |
| 258 |
send_user "\tfetched [llength $help_subcmds] sub-commands, [llength $help_switches] switches\n" |
| 259 |
} |
| 260 |
|
| 261 |
# vim:set tabstop=3 shiftwidth=3 expandtab autoindent: |