You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: html/bash/a-programmable-completion-example.html
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
<h1class="section">A Programmable Completion Example</h1><p>The most common way to obtain additional completion functionality beyond the default actions <code>complete</code> and <code>compgen</code> provide is to use a shell function and bind it to a particular command using <code>complete -F</code>. </p><p>The following function provides completions for the <code>cd</code> builtin. It is a reasonably good example of what shell functions must do when used for completion. This function uses the word passed as <code>$2</code> to determine the directory name to complete. You can also use the <code>COMP_WORDS</code> array variable; the current word is indexed by the <code>COMP_CWORD</code> variable. </p><p>The function relies on the <code>complete</code> and <code>compgen</code> builtins to do much of the work, adding only the things that the Bash <code>cd</code> does beyond accepting basic directory names: tilde expansion (see <ahref="tilde-expansion.html">Tilde Expansion</a>), searching directories in <var>$CDPATH</var>, which is described above (see <ahref="bourne-shell-builtins.html">Bourne Shell Builtins</a>), and basic support for the <code>cdable_vars</code> shell option (see <ahref="the-shopt-builtin.html">The Shopt Builtin</a>). <code>_comp_cd</code> modifies the value of <var>IFS</var> so that it contains only a newline to accommodate file names containing spaces and tabs – <code>compgen</code> prints the possible completions it generates one per line. </p><p>Possible completions go into the <var>COMPREPLY</var> array variable, one completion per array element. The programmable completion system retrieves the completions from there when the function returns. </p><divclass="example"><preclass="example"># A completion function for the cd builtin
1
+
<h1class="section" id="A-Programmable-Completion-Example-1">A Programmable Completion Example</h1><p>The most common way to obtain additional completion functionality beyond the default actions <code>complete</code> and <code>compgen</code> provide is to use a shell function and bind it to a particular command using <code>complete -F</code>. </p><p>The following function provides completions for the <code>cd</code> builtin. It is a reasonably good example of what shell functions must do when used for completion. This function uses the word passed as <code>$2</code> to determine the directory name to complete. You can also use the <code>COMP_WORDS</code> array variable; the current word is indexed by the <code>COMP_CWORD</code> variable. </p><p>The function relies on the <code>complete</code> and <code>compgen</code> builtins to do much of the work, adding only the things that the Bash <code>cd</code> does beyond accepting basic directory names: tilde expansion (see <aclass="pxref" href="tilde-expansion.html">Tilde Expansion</a>), searching directories in <varclass="var">$CDPATH</var>, which is described above (see <aclass="pxref" href="bourne-shell-builtins.html">Bourne Shell Builtins</a>), and basic support for the <code>cdable_vars</code> shell option (see <aclass="pxref" href="the-shopt-builtin.html">The Shopt Builtin</a>). <code>_comp_cd</code> modifies the value of <varclass="var">IFS</var> so that it contains only a newline to accommodate file names containing spaces and tabs – <code>compgen</code> prints the possible completions it generates one per line. </p><p>Possible completions go into the <varclass="var">COMPREPLY</var> array variable, one completion per array element. The programmable completion system retrieves the completions from there when the function returns. </p><divclass="example"><preclass="example-preformatted"># A completion function for the cd builtin
2
2
# based on the cd completion function from the bash_completion package
3
3
_comp_cd()
4
4
{
@@ -45,11 +45,11 @@ <h1 class="section">A Programmable Completion Example</h1> <p>The most common wa
45
45
return 0
46
46
}
47
47
</pre>
48
-
</div><p>We install the completion function using the <samp>-F</samp> option to <code>complete</code>: </p><divclass="example"><preclass="example"># Tell readline to quote appropriate and append slashes to directories;
48
+
</div><p>We install the completion function using the <sampclass="option">-F</samp> option to <code>complete</code>: </p><divclass="example"><preclass="example-preformatted"># Tell readline to quote appropriate and append slashes to directories;
49
49
# use the bash default completion for other arguments
50
50
complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
51
51
</pre>
52
-
</div><p>Since we’d like Bash and Readline to take care of some of the other details for us, we use several other options to tell Bash and Readline what to do. The <samp>-o filenames</samp> option tells Readline that the possible completions should be treated as filenames, and quoted appropriately. That option will also cause Readline to append a slash to filenames it can determine are directories (which is why we might want to extend <code>_comp_cd</code> to append a slash if we’re using directories found via <var>CDPATH</var>: Readline can’t tell those completions are directories). The <samp>-o nospace</samp> option tells Readline to not append a space character to the directory name, in case we want to append to it. The <samp>-o bashdefault</samp> option brings in the rest of the "Bash default" completions – possible completions that Bash adds to the default Readline set. These include things like command name completion, variable completion for words beginning with ‘<samp>$</samp>’ or ‘<samp>${</samp>’, completions containing pathname expansion patterns (see <ahref="filename-expansion.html">Filename Expansion</a>), and so on. </p><p>Once installed using <code>complete</code>, <code>_comp_cd</code> will be called every time we attempt word completion for a <code>cd</code> command. </p><p>Many more examples – an extensive collection of completions for most of the common GNU, Unix, and Linux commands – are available as part of the bash_completion project. This is installed by default on many GNU/Linux distributions. Originally written by Ian Macdonald, the project now lives at <ahref="https://github.com/scop/bash-completion/">https://github.com/scop/bash-completion/</a>. There are ports for other systems such as Solaris and Mac OS X. </p><p>An older version of the bash_completion package is distributed with bash in the <samp>examples/complete</samp> subdirectory. </p><divclass="_attribution">
52
+
</div><p>Since we’d like Bash and Readline to take care of some of the other details for us, we use several other options to tell Bash and Readline what to do. The <sampclass="option">-o filenames</samp> option tells Readline that the possible completions should be treated as filenames, and quoted appropriately. That option will also cause Readline to append a slash to filenames it can determine are directories (which is why we might want to extend <code>_comp_cd</code> to append a slash if we’re using directories found via <varclass="var">CDPATH</var>: Readline can’t tell those completions are directories). The <sampclass="option">-o nospace</samp> option tells Readline to not append a space character to the directory name, in case we want to append to it. The <sampclass="option">-o bashdefault</samp> option brings in the rest of the “Bash default” completions – possible completions that Bash adds to the default Readline set. These include things like command name completion, variable completion for words beginning with ‘<sampclass="samp">$</samp>’ or ‘<sampclass="samp">${</samp>’, completions containing pathname expansion patterns (see <aclass="pxref" href="filename-expansion.html">Filename Expansion</a>), and so on. </p><p>Once installed using <code>complete</code>, <code>_comp_cd</code> will be called every time we attempt word completion for a <code>cd</code> command. </p><p>Many more examples – an extensive collection of completions for most of the common GNU, Unix, and Linux commands – are available as part of the bash_completion project. This is installed by default on many GNU/Linux distributions. Originally written by Ian Macdonald, the project now lives at <aclass="url" href="https://github.com/scop/bash-completion/">https://github.com/scop/bash-completion/</a>. There are ports for other systems such as Solaris and Mac OS X. </p><p>An older version of the bash_completion package is distributed with bash in the <sampclass="file">examples/complete</samp> subdirectory. </p><aclass="index-entry-id" id="index-History_002c-how-to-use"></a><divclass="_attribution">
0 commit comments