Welcome to the iproute2-bashtabcompletion wiki!
Bash has the ability to provide "hints" to the user of what are appropriate "next words" to type, which is normally invoked by pressing the
Please read the Bash documentation for a complete description of this facility. The important part is that it can invoke a user-defined function which returns a list of valid options based on the current word-fragment, and those are either displayed to the user, or used to expand a short prefix to a full word.
(The default selection of options that are "valid" restricts the options to those which have the current fragment as a prefix, or all possible options on an empty fragment. However other selections are possible, including complete replacement of the current word by a dissimilar one.)
This script defines such a function, which is invoked when the command line starts with the word
This function approximates an LALR(1) parser.
The starting state is
START, which accepts dash-prefixed options and then the main keyword. What happens after that depends on which keywords are encountered. There is a state-stack, and the top item on that stack determines what is expected "next".
The core is one large case-statement that attempts to match the pairing of topmost-state and current-word.
(If you look back at the GIT history, you'll see that it originally had separate case-statements for managing state transitions and for enumerating available options; that proved to be problematic as the two sections basically repeated all the same information and often got out of sync, particularly in respect of state-names. It turned out that with a few magic shell functions the same case-statement could perform both roles.)
The names of the states are arbitrary, but related things usually have a common prefix which allows some simplification when matching the same keyword under multiple states. (However sometimes I've just resorted to numeric tags when nothing else seemed appropriate at the time; sorry.)
There are a lot of dependencies on Bash features, but, well, it is only intended to provide command-line completion for Bash. The following features probably won't work in other shells, even posix-compliant ones:
continuewith multiple levels and from within functions;
Currently it's only been tested in Bash version 4; it will probably mostly work with version 3 but I haven't tested it.
In a few cases, valid options are read from kernel filesystems
I have tried as far as possible to use only shell built-in functions, which means there is no invocation of external processes. This isn't important in most contexts now, but in a device with restricted memory or CPU it could make a difference. (Remember, this function is invoked every time the user hits
tab, and they might hold it down, auto-repeating up to 20 times per second.)
There will likely be exceptions to this in future, especially where information is not readily available from the kernel filesystems.