1.  Introduction
2.  Adding completions
    2.1.  Local
    2.2.  System
3.  Unit testing
4.  Questions
5.  Environment variables
6.  Cache
    6.1.  Considerations




1.  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 cancel `alias'
   $> 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 the `test' 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 the `foo' 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'
   



4.  Questions


- Is it possible to define a `catch-all' completion?  This would remove the
  burden of `bash_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 of `expand'?  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
    of `bash_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 of `COMP_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.
    Use `COMP_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 to `comp_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 <TAB>' 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 sets `COMP_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 the `complete' 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
