---

13.8.2 Implementing TAB completion in Gnuastro ¶

The basics of Bash auto-completion was reviewed in Bash TAB completion tutorial. Gnuastro is a very complex package of many programs, that have many similar features, so implementing those principles in an easy to maintain manner requires a modular solution. As a result, Bash’s TAB completion is implemented as multiple files in Gnuastro:

bin/completion.bash.built (in build directory, automatically created)

This file contains the values of all Gnuastro options or arguments that take fixed strings as values (not file names). For example, the names of Arithmetic’s operators (see Arithmetic operators), or spectral line names (like --obsline in CosmicCalculator input options).

This file is created automatically during the building of Gnuastro. The recipe to build it is available in Gnuastro’s top-level Makefile.am (under the target bin/completion.bash). It parses the respective Gnuastro source file that contains the necessary user-specified strings. All the acceptable values values are then stored as shell variables (within a function).

bin/completion.bash.in (in source directory, under version control)

All the low-level completion functions that are common to all programs are stored here. It thus contains functions that will parse the command-line or files, or suggest the completion replies.

PROGNAME-complete.bash (in source directory, under version control)

All Gnuastro programs contain a PROGNAME-complete.bash script within their source (for more on the fixed files of each program, see Program source). This file contains the very high-level (program-specific) Bash programmable completion features that are almost always defined in Gnuastro-generic Bash completion file (bin/completion.bash.in).

The top-level function that is called by Bash should be called _gnuastro_autocomplete_PROGNAME and its last line should be the complete command of Bash which calls this function. The contents of _gnuastro_autocomplete_PROGNAME are almost identical for all the programs, it is just a very high-level function that either calls _gnuastro_autocomplete_PROGNAME_arguments to manage suggestions for the program’s arguments or _gnuastro_autocomplete_PROGNAME_option_value to manage suggestions for the program’s option values.

The scripts above follow the following conventions. After reviewing the list, please also look into the functions for examples of each point.

• No global shell variables in any completion script: the contents of the files above are directly loaded into the user’s environment. So to keep the user’s environment clean and avoid annoyance to the users, everything should be defined as shell functions, and any variable within the functions should be set as local.
• All the function names should start with ‘_gnuastro_autocomplete_’, again to avoid populating the user’s function name-space with possibly conflicting names.
• Outputs of functions should be written in the local variables of the higher-level functions that called them.