1. Introduction

2. Adding completions 2.1. Local 2.2. System

3. Unit testing 3.1. Library functions 3.1.1. expect_completions() 3.1.2. test_command()

4. Questions

5. Environment variables

6. Cache 6.1. Considerations

7. Introduction

All completions run through a central function comp_load'. The first time completion is invoked for a specific command,comp_load' will load the specific command completion function, run it and install it for subsequent invocations. For example:

$> complete -p alias complete -F comp_load alias # First completion uses comp_load' $> alias <TAB> ..= l= ls= lt= $> alias ^C # Press CTRL-C to cancelalias' $> complete -p alias complete -F _alias alias # Subsequent completions use `_alias'

To prevent name collisions, all completion install functions are prefixed with `comp_'.

The function `have' which checked if a given command is present on the system, has been removed: the run-time loading of completion now prevents bulky functions in memory if we don't need them.

The minimum requirements for the completion package is bash-3. No efforts has been made to keep the completions compatible with bash-2. Since bash_completions_lib aims for speed, the latest features of bash-3 are used. If one desires bash-2, the original bash_completion can be used.

Completions are tested with unit tests using the DejaGnu test suite. Tests can be run by executing ./runCompletion' from thetest' directory.

An environment setting COMP_RESTRICT_BY_EXTENSION' lets you decide whether restricted completion is enabled, e.g. whether "acroread TAB" will only show files with extension.pdf'. Default is false (0).

2. Adding completions

2.1. Local

Use `bcl add' to add completions to the local ~/.bash_completion_lib.d/completions directory.

2.1. System

Use the command script/generate' to add completions to the bash_completion_lib core. For example, say you wish to create completion for thefoo' command:

$ script/generate foo _foo ' -o filenames'

The command above will generate the following files:

./completions/complete -o filenames/foo ./test/completionDebian/foo.exp ./test/completionLib/foo.exp ./test/completionOrig/foo.exp ./test/lib/completions/foo.exp

NOTE: These test files are for normal tests. If you wish to test complete-restrict-by-extension, take a look at the test files for `acroread'.

3. Unit testing

The following test suites are available:

       command                          test objectives

runCompletionLib Tab completions using `bash_completion_lib'

runCompletionOrig Tab completions using `bash_completion-20060301'

runCompletionDebian Tab completions using `bash_completion-20060301-4' (Debian)

runInstall Install `bash_completion_lib'

3.1. Library functions

3.1.1. expect_completions()

Example:

set test "-L should complete with installed packages"
if {[test_command {dpkg --get-selections | cut -f1 | sort} $test packages]} {
    # Try completion
set cmd "dpkg -L "
send "$cmd\t"
expect_completions $packages $test $cmd
}; # if

3.1.2. test_command()

Example:

set test "ant should be available"
if {[test_command {ant --help} $test result]} {

source "lib/completions/ant.exp"

}; # if

4. Questions

• Is it possible to define a catch-all' completion? This would remove the burden ofbash_completion_lib' to attach `comp_load' to each and every completion that might be triggered.

• Doesn't `bash_completion_lib' make completion too complicated? For instance the fact that the completion definition changes after an initial complete, can be surprising when debugging.

• Prefix all completion methods with _comp_' instead of_', e.g. _comp_expand' instead ofexpand'? This way the completion methods would be less prone to name collisions with user bash scripts. See comp_install() in file bash_completion_lib.

• The bash-completion meta-options cannot be accessed by a completion function. It concerns the `-o COMP-OPTION' options:

  • bashdefault
  • default
  • dirnames
  • filenames
  • nospace Because these options cannot be modified from within a completion function, it is impossible to create a generic run-time completion installer.

  As a workaround - to be able to install a large group of completions at once

  • `bash_completion_lib' groups completions into directories named after their meta-options:
  • complete -o default
  • complete -o default -o filenames
  • complete -o default -o nospace
  • complete -o dirnames
  • complete -o filenames
  • complete -o filenames -o nospace
  • complete -o nospace

  The other directories:

  • complete-cd
  • complete-linux
  • complete-nohostcomplete
  • complete-restrict-by-extension
  • complete-tar contain a completion initialization file `.complete' which sets meta-options at run-time depending on the user configuration.

  A solution would be to propagate these options into bash constants or a new builtin which can then be used by a completion function. (1)

  See also:

:[http://groups.google.nl/group/gnu.bash.bug/browse_thread/thread/281698132559a422/272f82f6f2f8b0fd?hl=nl&lnk=raot#272f82f6f2f8b0fd Temporarily change completion options] ;There are thoughts about a new builtin that would accept the same set of -o options as complete/compgen.

5. Environment variables

COMP_CACHE If COMP_CACHE' is defined and points to a writable file, completions will be read from this file. Completions are stored in this file after the first run ofbash_completion_lib'. Default is `~/.bash_completion_lib.d/cache~'.

COMP_CACHE_VERSION Version of bash_completion_lib while cache was generated.
Every time bash_completion_lib loads the cache, the value of COMP_CACHE_VERSION' is compared with the value ofCOMP_VERSION'. If the versions differ, the cache is regenerated.

COMP_DIR Directory of `bash_completion_lib'. This variable is automatically set.

COMP_INSTALL True (1, default) if real completion must be installed after a first completion. If set to False (0), the default completion handler `comp_load' will not be replaced with the actual completion handler after the first completion.

COMP_LIB Array version of COMP_PATH'. Not used anymore because an array cannot be exported to a bash subshell. UseCOMP_PATH' instead. Deprecated as of bash_completion_lib >= 1.2.6.

COMP_LOAD_DEINIT True (1, default) if comp_load' must deinitialize itself after having installed the actual completion handler. Deinitializing means removing variables and functions which are only useful tocomp_load'. If set to False (0), the variables and functions remain defined.

COMP_PATH String variable containing directories to search for completions, separated by a colon (:). By default `COMP_PATH' contains these directories:

• $HOME/.bash_completion_lib.d/completions
• $COMP_DIR/completions Bash-completion-lib uses the first directory in which a completion is found.

COMP_RESTRICT_BY_EXTENSION True (1) if restricted completion is enabled, False (0, default) if not. Example: if enabled, `acroread ' will only show files with a .pdf extension.

COMP_VERSION Version of bash_completion_lib. If this variable is non-empty, bash_completion_lib will return without loading any completions. This prevents bash_completion_lib from doing too much work if bash_completion_lib is sourced for a second time within the same shell. If the value of COMP_VERSION' differs from the value of COMP_CACHE_VERSION', the cache will be regenerated.

6. Cache

Bash_completion_lib' has a fast algorithm to install completions. During startup, all completions in the ./completions directory are converted to complete comp_load ...' commands. By caching the conversion result however, this fast startup time can even be reduced significantly (0.20 sec -> 0.10 sec = 50%).

Bash_completion_lib' automatically setsCOMP_CACHE' if it does not already exist:

COMP_CACHE=$HOME/.bash_completion_lib.d/cache~

To disable caching, set COMP_CACHE to be empty:

COMP_CACHE=

Care must be taken to empty the cache file after updates have been made to the ./completions directory. The cache can be emptied with this bash command ($ = bash prompt):

$ > $COMP_CACHE

NOTE: The cache need only be reset, if completions have been added, moved or deleted, or when the arguments to complete' have changed. Other modifications like an improved completion function are automatically loaded - remember: it's only thecomplete' installments which are cached. Example:

1. You moved ./completions/*/cd to another directory. The cache must be cleared.
2. You improved the _cd completion within ./completions/*/cd. You don't have to clear the cache.

6.1. Considerations

Should cache be enabled by default?

I think it should, because the cache offers important speed gains: I was able to reduce the load time from 0.20 seconds to 0.10 seconds.

With cache enabled, changes in the ./completions directory aren't reflected in the cache. But do updates to ./completions occur frequent? I think not. What if a ./completions update would reset the cache? This way, 99% of the users would benefit from a speedy bash startup.

Furthermore, it's only the `complete' installments which are cached - not the completion functions themselves - so many improvements are coming through anyway, even though complete installments are being cached.

7. Todo

See http://code.google.com/p/bash-completion-lib/issues/list

(1) See sources bash-3.2:

• pcomplete.c, programmable_completions() The variable `foundp' returns the cs->options as they were set during completion install