Debian Codegraph @

dh_shell_completions

raw
1 #!/usr/bin/perl
2
3 use v5.36;
4 use File::Spec;
5 use File::Temp qw( tempdir );
6 use Debian::Debhelper::Dh_Lib;
7
8
9 my %SHELLS = (
10 bash => '/usr/share/bash-completion/completions',
11 fish => '/usr/share/fish/vendor_completions.d',
12 zsh => '/usr/share/zsh/vendor-completions',
13 );
14
15 use constant MODE_UNKNOWN => '(unknown)';
16
17 =head1 NAME
18
19 dh_shell_completions - install shell completions for package
20
21 =head1 SYNOPSIS
22
23 B<dh_shell_completions> [S<I<debhelper options>>]
24
25 =head1 DESCRIPTION
26
27 dh_shell_completions is a debhelper addon for installing completion scripts for
28 multiple shells, respecting conventions of each shell.
29
30 It currently supports B<bash>, B<fish>, and B<zsh>.
31
32 To use it, B<Build-Depends> on it, and pass B<--with shell_completions> to
33 debhelper.
34
35 There are several modes of action, listed in B<MODES>. The first has highest
36 precedence, the last lowest.
37
38 For all modes, mentioned files can have comment lines, starting with `#`.
39
40 I<$package> in file names, if omitted, will be the first binary package defined
41 in debian/control.
42
43 =head1 MODES
44
45 =head2 Generation
46
47 If a file named I<debian/[$package.]shell-completions> exists, and its first
48 non-comment line is:
49
50 mode=gen
51
52 Then the remaining lines should be one or more stanzas, each in the format:
53
54 command=command-to-generate --completions _SHELL_ [--write-to _PATH_]
55 shells=bash,fish,zsh
56 name=foo
57
58 =over
59
60 =item I<command>
61
62 command to generate a completion script. Assumed to print to stdout
63 unless it contains the I<_PATH_> placeholder.
64
65 B<_SHELL_> is a placeholder for each shell in I<shells>.
66
67 B<_PATH_> is an optional placeholder for the path to write the completion
68 script to, if the command works that way.
69
70 =item I<shells>
71
72 a comma separated list of supported shell names to generate for.
73
74 =item I<name>
75
76 an optional line to specify the name of generated completions other than
77 I<$package>.
78
79 =back
80
81 I<command> will be run for each I<_SHELL_> specified in I<shells>, and installs
82 the resulting completions with specified I<name>.
83
84 =head2 Composite
85
86 If a file named I<debian/[$package.]shell-completions> exists, and is in the
87 format:
88
89 $shell completions/foo # installed as foo
90 $shell completions/bar baz # installed as baz
91
92 then for each line, the referenced file will be installed as a completion
93 script for I<$shell>, named as the comments suggest.
94
95 =head2 Separate
96
97 If a file named I<debian/[$package.]$shell-completions> exists for a supported
98 I<$shell>, then one of two actions are taken, depending on its content.
99
100 If it's of the following format:
101
102 completions/foo # installed as foo
103 completions/bar baz # installed as baz
104
105 then the referenced file(s) will be installed as completion(s) for I<$shell>,
106 named as the comments above suggest.
107
108 Otherwise, it's taken as a full completion script, and installed for I<$shell>,
109 named I<$package>. This is in line with dh_bash-completion.
110
111 =cut
112
113 # A simple, probably naive heuristic: if no line in the file has more than 3
114 # "words" separated by whitespace, it's considered a file list. Shell scripts,
115 # especially completions scripts, should normally have lines that has more than
116 # 3 words.
117 sub is_file_list($path) {
118 open(FILE, '<', $path) || error("cannot read $path: $!");
119 while(<FILE>) {
120 s/^\s+//;
121 next if /^($|#)/;
122 chomp;
123
124 my @split = split(/\s+/, $_, 4);
125 if(defined($split[3])) {
126 close(FILE);
127 verbose_print("$path is not file list");
128 return 0;
129 }
130 }
131 close(FILE);
132 verbose_print("$path is file list");
133 return 1;
134 }
135
136 sub check_mode($comp_list) {
137 open(FILE, '<', $comp_list) || error("cannot read $comp_list: $!");
138 while (<FILE>) {
139 s/^\s+//;
140 next if /^($|#)/;
141 chomp;
142
143 if(/^mode\s*=/) {
144 s/^mode\s*=\s*//;
145 return $_;
146 }
147 }
148 close(FILE);
149 return MODE_UNKNOWN;
150 }
151
152 sub install_completion($name, $shell, $comp_dir, $comp_file) {
153 $name = "$name.fish" if $shell eq 'fish' and $name !~ /\.fish$/;
154 $name = "_$name" if $shell eq 'zsh' and $name =~ /^[^_]/;
155 install_dir($comp_dir);
156 install_file($comp_file, File::Spec->catfile($comp_dir, $name));
157 }
158
159 sub process_completion_list($pkg, $shell, $comp_list) {
160 if(defined($shell) and !is_file_list($comp_list)) {
161 verbose_print("shell is defined: $shell, $comp_list is not file list, installing it as completion");
162 my $comp_dir = File::Spec->catdir(tmpdir($pkg), $SHELLS{$shell});
163 return install_completion($pkg, $shell, $comp_dir, $comp_list);
164 }
165
166 verbose_print("shell is undefined or $comp_list seems like file list, processing as file list");
167 open(FILE, '<', $comp_list) || error("cannot read $comp_list: $!");
168 while (<FILE>) {
169 s/^\s+//;
170 next if /^($|#)/;
171 chomp;
172
173 my @split = split(/\s+/, $_, 3);
174 my $this_shell = $shell || shift(@split);
175 error("$comp_list line $.: unknown shell $this_shell")
176 unless defined($SHELLS{$this_shell});
177 my $comp_file = $split[0];
178 my $name = $split[1] || $pkg;
179 verbose_print("parsed file list line: shell $this_shell, comp file $comp_file, install name $name");
180 my $comp_dir = File::Spec->catdir(tmpdir($pkg), $SHELLS{$this_shell});
181 install_completion($name, $this_shell, $comp_dir, $comp_file);
182 }
183 close(FILE);
184 }
185
186 sub process_gen($pkg, $comp_list) {
187 open(FILE, '<', $comp_list) || error("cannot read $comp_list: $!");
188
189 my @stanzas = ();
190
191 my $command;
192 my @shells;
193 my $name;
194
195 while(<FILE>) {
196 s/^\s+//;
197 next if /^($|#)/;
198 next if /^mode\s*=/;
199 chomp;
200
201 error("$comp_list mode=gen line $.: empty value")
202 if /=\s*$/;
203
204 if(/^command\s*=/) {
205 s/^command\s*=\s*//;
206 error("$comp_list mode=gen line $.: command `$_` lacks placeholder _SHELL_")
207 unless /_SHELL_/;
208
209 $command = $_ and next
210 unless defined($command);
211
212 if(@shells == 0) {
213 my $ln = $. - 1;
214 error("$comp_list mode=gen line $ln: stanza lacks shells list");
215 }
216 $name = $pkg
217 unless defined($name);
218
219 my $stanza = {command => $command, name => $name};
220 @{$stanza->{shells}} = @shells;
221 push(@stanzas, $stanza);
222
223 $command = $_;
224 @shells = ();
225 $name = undef;
226 next;
227 }
228
229 if(/^shells\s*=/) {
230 s/^shells\s*=\s*//;
231 @shells = split(/,/, $_);
232 foreach my $shell (@shells) {
233 error("$comp_list mode=gen line $.: unknown shell $shell")
234 unless defined($SHELLS{$shell});
235 }
236 next;
237 }
238
239 if(/^name\s*=/) {
240 s/^name\s*=\s*//;
241 $name = $_;
242 next;
243 }
244
245 error("$comp_list mode=gen line $.: unknown line `$_`");
246 }
247
248 if(defined($command) and @shells != 0) {
249 my $stanza = {command => $command, name => $name};
250 @{$stanza->{shells}} = @shells;
251 push(@stanzas, $stanza);
252 my $name_print = $name || '';
253 verbose_print("mode=gen stanza: name=$name_print, command=`$command`, shells=@shells");
254 }
255
256 error("$comp_list mode=gen: no stanza defined")
257 if @stanzas == 0;
258
259 my $dir = tempdir("dh-shell-completions.gen.XXXX", CLEANUP => 1, DIR => "debian");
260
261 foreach my $stanza (@stanzas) {
262 my $name = $stanza->{name} || $pkg;
263 foreach my $shell (@{$stanza->{shells}}) {
264 my $out = File::Spec->catdir($dir, "$name.$shell");
265 my $err = File::Spec->catdir($dir, "$name.$shell.err");
266 my $command = $stanza->{command};
267 $command =~ s/_SHELL_/$shell/g;
268 if($command =~ /_PATH_/) {
269 $command =~ s/_PATH_/$out/g;
270 } else {
271 $command .= " >$out";
272 }
273
274 nonquiet_print("mode=gen run: name=$name command=`$command`");
275 my $result = `$command 2>$err`;
276
277 if($? == -1) {
278 error("$comp_list mode=gen: command `$command` failed: $!");
279 } if($?) {
280 open(my $efh, '<', $err);
281 $/ = undef;
282 my $stderr = <$efh>;
283 my $code = $? >> 8;
284 error("$comp_list mode=gen: command `$command` failed, code $code:\n$stderr");
285 }
286 my $comp_dir = File::Spec->catdir(tmpdir($pkg), $SHELLS{$shell});
287 install_completion($name, $shell, $comp_dir, $out);
288 }
289 }
290 }
291
292 sub main {
293 foreach my $pkg (@{$dh{DOPACKAGES}}) {
294 next if is_udeb($pkg);
295
296 foreach my $shell (keys %SHELLS) {
297 my $comp_list = pkgfile($pkg, "$shell-completions");
298 next unless -f $comp_list;
299 verbose_print("processing $comp_list");
300 process_completion_list($pkg, $shell, $comp_list);
301 }
302
303 my $comp_list = pkgfile($pkg, "shell-completions");
304 next unless -f $comp_list;
305 verbose_print("processing $comp_list");
306 my $mode = check_mode($comp_list);
307 verbose_print("$comp_list mode is $mode");
308
309 process_completion_list($pkg, undef, $comp_list)
310 and next if $mode eq MODE_UNKNOWN;
311
312 # given/when is deprecated so we resort to this for now.
313 if($mode eq 'gen') {
314 process_gen($pkg, $comp_list);
315 } else {
316 error("$comp_list: unknown mode `$mode`");
317 }
318 }
319 }
320
321 init();
322 main();
323
324 =head1 SEE ALSO
325
326 L<debhelper(1)>
327
328 =head1 AUTHOR
329
330 Blair Noctis <[email protected]>
331
332 =cut