Debian Codegraph @

testsuite/completion.00-init/007-module_help.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/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: