path: root/Doc/Zsh/compsys.yo

texinode(Completion System)(Zftp Function System)(Zsh Modules)(Top)
chapter(Completion System)
cindex(completion, system)
cindex(completion, programmable)
cindex(completion, controlling)
sect(Description)

This describes the shell code for the new completion system.  It consists
of two scripts and a few other files that define shell functions.
The shell functions which implement completion behaviour and which may
be bound to keystrokes, are referred to as `widgets'.  All are contained
in the following subdirectories of the tt(Completion) directory of the main
distribution directory.

startitem()
item(tt(Core))(
The core scripts and functions.  You will certainly need these, though will
probably not need to alter them.  The contents of this directory is
described in more detail below.
)
item(tt(Base))(
Other functions you will almost certainly want if you are going to use
any of the standard completion functions.  You may want to edit some of
these files.
)
item(tt(Builtins))(
Functions for completing arguments of shell builtin commands.
)
item(tt(User))(
Functions for completing arguments of external commands and suites of
commands.  They may need modifying for your system.
)
item(tt(Commands))(
Functions which implement special types of completion to be bound to
keystrokes rather than called by context.
)
enditem()

You should decide which files you will be using and copy them to a
directory (or multiple directories) of your own which should appear in your
tt($fpath) variable so that the functions can be autoloaded.

startmenu()
menu(Initialisation)
menu(Control Functions)
menu(Completion Functions)
endmenu()

texinode(Initialisation)(Control Functions)()(Completion System)
sect(Initialisation)

The script tt(compinstall) can be run by a user to set up the completion
system for use.  It will usually insert code into tt(.zshrc), although if
that is not writeable it will save it in another file and tell you that
file's locations.  Note that it is up to you to make sure that the lines
added to tt(.zshrc) are actually run; you may, for example, need to move
them to an earlier place in the file if tt(.zshrc) usually returns early.
So long as you keep them all together (including the comment lines at the
start and finish), you can rerun tt(compinstall) and it will correctly
locate and modify these lines.  Note, however, that any code you add to
this section by hand is likely to be lost if you rerun tt(compinstall).

You can run it as `tt(source )var(<path>)tt(/compinstall)' or
`tt(. )var(<path>)tt(/compinstall)', where var(<path>) is where the
completion functions are stored.  It will ask you various questions about
how you would like completion set up.  It is in two parts; the basic part
locates the completion files and decides where to put your personal
dumpfile, used to speed up initialisation after the first time.  After
that, you will be asked if you wish to go on to the advanced set-up; if you
answer tt(n), you can rerun tt(compinstall) later without having to
re-enter any of the basic settings.

You can abort the installation any time you are being prompted for
information, and your tt(.zshrc) will not be altered at all.

subsect(Use of compinit)

This section describes the use of tt(compinit) to initialize completion for
the current session when run directly by the user; if you have run
tt(compinstall) it will be called automatically from your tt(.zshrc).

To initialise the system, the script tt(compinit) should be sourced with
`tt(source )var(<path>)tt(/compinit)' or
`tt(. )var(<path>)tt(/compinit)'. This will define a few utility functions,
arrange for all the necessary shell functions to be autoloaded, and will
then re-bind all keys that do completion to use the new system.

To speed up the running of tt(compinit), it can be made to produce a dumped
configuration which will be read in on future invocations.  The easiest way
to do this is by adding the option tt(-d) whenever tt(compinit) is sourced.
In this case the dumped file will have the same name as the sourced file,
but with tt(.dump) appended to the end, or, if that is not writeable by the
user, the file tt(.zcompdump) in the same directory as the startup files
(i.e. tt($ZDOTDIR) or tt($HOME)); alternatively, an explicit file name can
be given following the tt(-d).  On the next call to tt(compinit -d), the
dumped file will be read instead.

The other option accepted by tt(compinit) is tt(-f var(dir)), which gives
the directory in which tt(compinit) resides.  If you source tt(compinit) by
its full pathname, and the option tt(FUNCTION_ARGZERO) is set, as it is by
default unless tt(zsh) is emulating tt(sh) or tt(ksh), this is unnecessary
as tt(compinit) can deduce the directory for itself.  It is used in two
ways: to find the program tt(compdump) used by the tt(-d) option, and to
check if the directory should be added to the function search path to find
the completion functions (see below).

If the number of completion files changes, tt(compinit) will recognise this
and produce a new dump file.  However, if the name of a function or the
arguments in the first line of a tt(#compdef) funcion (as described below)
change, it is easiest to delete the dump file by hand so that the next time
tt(compinit) will re-create it.

The dumping is actually done by another script, tt(compdump), but you will
only need to source this yourself if you change the configuration
(e.g. using tt(compdef)) and then want to dump the new one.  The name of
the old dumped file will be remembered for this.

subsect(Autoloaded files)

The convention for autoloaded functions used in completion is that they
start with an underscore; as already mentioned, the tt(fpath/FPATH)
parameter must contain the directory in which they are stored.  If
tt(compinit) does not find enough files beginning with an underscore (fewer
than twenty) in the search path, it will try to find more by adding its own
directory to the search path.  If you keep all the completion files in this
directory, this means you never have to alter tt(fpath/FPATH) yourself.
Furthermore, if the directory in question ends in the path segment
tt(Core), or has a subdirectory named tt(Core), tt(compinit) will add all
subdirectories of the directory where tt(Core) is to the path: this allows
the functions to be in the same format as in the tt(zsh) source
distribution.

When tt(compinit) is sourced, it searches all such files accessible via
tt(fpath/FPATH) and reads the first line of each of them.  This line should
contain one of the tags described below. Files whose first line does not
start with one of these tags are not considered to be part of the
completion system and will not be treated specially.

The tags are:

startitem()
item(tt(#compdef) var(names...))(
The file will be made autoloadable and the function defined 
in it will be called when completing var(names), each of which is
either the name of a command whose arguments are to be completed or one of
a number of special contexts in the form tt(-)var(context)tt(-) described
below for the tt(_complete) function.
)
item(tt(#compdef -p) var(pattern))(
The file will be made autoloadable and the function defined in it will be
called when completing for a command whose name matches the given
var(pattern) (a standard globbing pattern).  Note that only one
var(pattern) may be given.
)
item(tt(#compdef -k) var(style key-sequences...))(
This can be used bind special completion functions to the
var(key-sequences).  It creates a widget behaving like the builtin widget
var(style), which must be one of those that perform completion, namely
tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
tt(menu-expand-or-complete), or tt(reverse-menu-complete).

The widget is then bound to all the var(key-sequences) given, if any: when
one of the var(key-sequences) is typed, the function in the file will
be invoked to generate the matches. The widget created has the same
name as the file and can also be bound to other keys using tt(bindkey) 
as usual.
)
item(tt(#autoload))(
This is used for files defining utility function that are not to be
called directly as completion functions but should be loaded automatically
when invoked.  Typically they are to be called from within one of the
completion functions.
)
enditem()

Note that the tt(#) is part of the tag name and no white space is allowed
after it.  The tt(#compdef) tags use the tt(compdef) function defined
below; the main difference is that the name of the function is supplied
implicitly.

subsect(Functions)

The tt(compinit) file defines the following functions, which may
also be called directly by the user.

startitem()
xitem(tt(compdef) [ tt(-an) ] var(function names...))
xitem(tt(compdef -d) var(names...))
xitem(tt(compdef -p) [ tt(-a) ] var(function pattern))
item(tt(compdef -k) [ tt(-a) ] var(function style key-sequences...))(
The first form tells the completion system to call the given
var(function) when completing for the contexts or commands
whose var(names) are given:  this is like the tt(#compdef) tag.  If the
tt(-n) option is given, any existing completion behaviour for particular
contexts or commands will not be altered.  These definitions can be deleted
by giving the tt(-d) option as in the second form.

The third form is similar to the first, but var(function) will be called
for all commands whose name matches the var(pattern); this is like the
tt(#compdef -p) function tag.

The fourth form defines a widget with the same name as the var(function)
which will be called for each of the var(key-sequences); this is like the
tt(#compdef -k) tag.  The function should generate the completions needed
and will otherwise behave like the builtin widget whose name is given as
the var(style) argument. The widgets usable for this are:
tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
tt(menu-expand-or-complete), and tt(reverse-menu-complete).

In each of the forms supporting it the tt(-a) option makes the
var(function) autoloadable (exactly equivalent to
tt(autoload )var(function)).
)
xitem(tt(compconf) var(definitions...))
xitem(tt(compconf) [ tt(-L) ] )
item(tt(compconf) [ tt(-l) ] [ tt(-L) ] var(keys...))(
Several aspects of the completion system can be configured by the
user. The configuration values are stored under the keys described
below in the associative array `tt(compconfig)'.  After sourcing
tt(compinit), configuration values can either be set directly as in
`tt(compconfig[completer]=_complete)' or by calling this utility function.

Each var(definition) may be either a simple `var(key)', which sets this
key in the tt(compconfig) array to an empty string, or of the form
`var(key=value)' which stores the `var(value)' under key `var(key)'.

Since the completion system also uses the array for internal purposes,
you should not set all values at once by doing `tt(compconfig=(...))'.

In the second form (without arguments), this function lists all keys
and their values. If given the tt(-l) option as its first argument, as 
in the last form, the other arguments are taken as names of keys and
the values of these keys are printed one per line. In either case, if the
tt(-L) option is given, the keys and values are printed as calls to this
function, usable to be put in a setup script.
)
enditem()

texinode(Control Functions)(Completion Functions)(Initialisation)(Completion System)
sect(Control Functions)

The initialisation script tt(compinit) re-binds all the keys which perform
completion to newly created widgets that all call the supplied widget
function tt(_main_complete). This function acts as a wrapper calling
the so-called `completer' functions that generate matches. If
tt(_main_complete) is
called with arguments, these are taken as the names of completer
functions to be called in the order given.  If no arguments are given, the
set of functions to try is taken from the colon-separated list in the
configuration key tt(completer). For example, to use normal
completion and correction if that doesn't generate any matches:

indent(
nofill(tt(compconf completer=_complete:_correct))
)

after sourcing tt(compinit). The default value for this configuration key
set up in tt(compinit) is `tt(_complete)', i.e. normally only ordinary
completion is tried. The tt(_main_complete) function uses the return value
of the completer functions to decide if other completers should be
called. If the return value is zero, no other completers are tried and the
tt(_main_complete) function returns.

The following completer functions are contained in the distribution (users
may write their own):

startitem()
item(tt(_complete))(
This completer generates all possible completions in a context-sensitive
manner, i.e. using the tt(compdef) function
explained above and the current settings of all special parameters.

To complete arguments of commands, tt(_complete) uses the utility function
tt(_normal), which is in turn responsible for finding the particular
function; it is described below.  Various contexts of the form
tt(-)var(context)tt(-), as mentioned above for the tt(#compdef) tag, are
handled specially.  These are:

startitem()
item(tt(-equal-))(
for completion after an equal sign, other than one occurring in a
shell-variable assignment.
)
item(tt(-tilde-))(
for completion after a tilde (`tt(~)') character, but before a slash.
)
item(tt(-redirect-))(
for completion after a redirection operator.
)
item(tt(-math-))(
for completion inside mathematical contexts, such as
`tt(LPAR()LPAR())...tt(RPAR()RPAR())'.
)
item(tt(-subscript-))(
for completion inside subscripts.
)
item(tt(-value-))(
for completion on the right hand side of an assignment.
)
item(tt(-array-value-))(
for completion on the right hand side of an array-assignment
(`tt(foo=LPAR()...RPAR())').
)
item(tt(-condition-))(
for completion inside conditions (`tt([[...]])').
)
item(tt(-parameter-))(
for completing the name of a parameter expansion (`tt($...)').
)
item(tt(-brace-parameter-))(
for completing the name of a parameter expansion within braces
(`tt(${...})').
)
item(tt(-first-))(
for adding completions before any other other completion functions are
tried (similar to the `tt(-T)' flag of tt(compctl)); if this
function sets the tt(_compskip) parameter to any value, the completion
system will not call any other function to generate matches.
)
item(tt(-default-))(
for generating completions when no special completion function is used 
(similar to the `tt(-D)' option of tt(compctl)).
)
item(tt(-command-))(
for completing in a command position (as with the `tt(-C)' option of
tt(compctl)).
)
enditem()

Default implementations are supplied for each of these
contexts, in most cases named after the context itself
(e.g. completion for the `tt(-tilde-)' context is done by the function 
named `tt(_tilde)').

Before trying to find a function for a specific context, tt(_complete) 
checks if the parameter `tt(compcontext)' is set to a non-empty
value. If it is, the value is taken as the name of the context to use
and the function defined for that context will be called.
)
item(tt(_approximate))(
This completer function uses the tt(_complete) completer to generate
a list of strings for the context the cursor is currently in, allowing 
you to specify a maximum number of errors:  see the description of
approximate matching in
ifzman(\
zmanref(zshexpn)
)\
ifnzman(\
noderef(Filename Generation)
)\
for how errors are
counted. The resulting list of corrected and completed strings is then
presented to the user. The intended use of this completer function is to
try after the normal tt(_complete) completer by setting:

indent(
nofill(tt(compconf completer=_complete:_approximate))
)

This will give correcting completion if and only if
normal completion doesn't yield any possible completions. When
corrected completions are found, the completer will normally start
menucompletion allowing you to cycle through these strings.

The exact behavior of this completer can be changed by using the
following configuration keys:

startitem()
item(tt(approximate_accept))(
This should be set to the number of errors the correction code should
accept. The completer will try to generate completions by first allowing
one error, then two errors, and so on, until either a match
was found or the maximum number of errors given by this key has
been reached.

If the value for this key contains a lower- or upper-case `tt(n)', the 
completer function will take any numeric argument as the
maximum number of errors allowed. For example, with

indent(
nofill(tt(compconf approximate_accept=2n))
)

two errors will be allowed if no numeric argument is given. However,
with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
errors are accepted.  Hence with a value of `tt(0n)', no correcting
completion will be attempted unless a numeric argument is given.

If the value contains `tt(n)' or `tt(N)' and a exclamation mark
(`tt(!)'), tt(_approximate) will var(not) try to generate corrected
completions when given a numeric argument, so in this case the number given
should be greater than zero.  For example, `tt(2n!)' specifies that
correcting completion with two errors will usually be performed, but if a
numeric argument is given, correcting completion will not be performed.
)
item(tt(approximate_original))(
This key is used to specify whether the original string on which correcting 
completion was attempted is to be included in the list of possible
corrections. If it is set to any non-empty string, the original string 
will be offered when cycling through the completions. Normally it will 
appear as the first string, so that the command line does not change
immediately; consecutive completion attempts will cycle through the
corrected strings.  If the value for this key contains the substring
`tt(last)', the original string will be the last one in the list, so
that it appears just before wrapping around to the first corrected
string again.  Also, if the value contains the substring `tt(always)',
the original string will always be included; normally it is
included only if more than one possible correction was generated.
)
item(tt(approximate_prompt))(
This can be set to a string to be displayed on top of the
corrected strings generated when cycling through them. This string
may contain the control sequences `tt(%n)', `tt(%B)', etc. known from
the `tt(-X)' option of tt(compctl). Also, the sequence `tt(%e)' will
be replaced by the number of errors accepted to generate the corrected 
strings.
)
item(tt(approximate_insert))(
If this is set to a string starting with `tt(unambig)', the code will try
to insert a usable unambiguous string in the command line instead of
always cycling through the corrected strings. If such a unambiguous
string could be found, the original string is not used, independent of
the setting of tt(approximate_original). If no sensible string could be
found, one can cycle through the corrected strings as usual.
)
enditem()

If any of these keys is not set, but the the same key with the prefix
`tt(correct)' instead of `tt(approximate)' is set, that value will be
used. The forms beginning with `tt(correct)' are also used by the
tt(_correct) completer function.

The keys with the `tt(approximate)' prefix have no default values, but 
tt(compinit) defines default values for tt(correct_accept) (which 
is set to `tt(2n)'), and tt(correct_prompt).
)
item(tt(_correct))(
Generate corrections (but not completions) for the current word; this is
similar to spell-checking.  This calls tt(_approximate), but only the
configuration parameters beginning tt(correct_) are used.

For example, with:

indent(tt(
nofill(compconf completer=_complete:_correct:_approximate)
nofill(compconf correct_accept='2n!' approximate_accept=3n))
)

correction will accept up to two errors. If a numeric argument is
given, correction will not be performed, but correcting completion will be,
and will accept as many errors as given by the numeric argument.
Without a numeric argument, first correction and then correcting
completion will be tried, with the first one accepting two errors 
and the second one accepting three errors.

This completer function is intended to be used without the
tt(_approximate) completer or, as in the example, just before
it. Using it after the tt(_approximate) completer is useless since
tt(_approximate) will at least generate the corrected strings
generated by the tt(_correct) completer -- and probably more.
)
item(tt(_match))(
This completer is intended to be used after the tt(_complete)
completer. It allows one to give patterns on the command line and
to complete all strings metching these patterns from the set of possible
completions for the context the cursor is in, without having to set
the tt(GLOB_COMPLETE) option.

Normally this will be done by taking the pattern from the line,
inserting a `tt(*)' at the cursor position and comparing the resulting
pattern with the possible completions generated. However, if the
configuration key tt(match_original) has a value of `tt(only)', no
`tt(*)' will be inserted. If tt(match_original) has any other non-empty
string as its value, this completer will first try to generate matches
without, then with a `tt(*)' inserted at the cursor position.
)
item(tt(_expand))(
This completer function does not really do completion, but instead
checks if the word on the command line is eligible for expansion and,
if it is, gives detailed control over how this expansion is done. When 
using this, one should not use the tt(expand-or-complete) widget, but
instead use tt(complete-word), as otherwise tt(expand-or-complete)
will expand the string on the line before the completion widget is
called. Also, this completer should be called before the tt(_complete) 
completer function.

Control over how the expanded string will be treated is possible with the 
following configuration keys:

startitem()
item(tt(expand_substitute))(
If this is unset or set to the empty string, the code will first try
to expand all substitutions in the string (such as
`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an
non-empty string it should be an expression usable inside a `tt($((...)))'
arithmetical expression. In this case, expansion of substitutions will
be done if the expression evaluates to `tt(1)'. For example, with

indent(
nofill(tt(compconf expand_substitute='NUMERIC != 1'))
)

substitution will be performed only if given an explicit numeric
argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'.
)
item(tt(expand_glob))(
If this is unset or set to an empty string, globbing will be attempted
on the word resulting from substitution or the original string. The
values accepted for this key are the same as for tt(expand_substitute).
)
item(tt(expand_menu))(
If this is unset or set to the empty string, the words resulting from
expansion (if any) will simply be inserted in the command line,
replacing the original string. However, if this key is set to a
non-empty string, the user can cycle through the expansion as in
menucompletion. Unless the value contains the substring `tt(only)',
the user will still be offered all expansions at once as one of the
strings to insert in the command line; normally, this possibility is
offered first, but if the value contains the
substring `tt(last)', it is offered last. Finally, if the value contains
the substring `tt(sort)', the expansions will be sorted alphabetically,
normally they are kept in the order the expansion produced them in.
)
item(tt(expand_original))(
If this is set to an non-empty string, the original string from the
line will be included in the list of strings the user can cycle
through as in a menucompletion. If the value contains the substring
`tt(last)', the original string will appear as the last string, with
other values it is inserted as the first one (so that the command line
does not change immediately).
)
item(tt(expand_prompt))(
This may be set to a string that should be displayed before the
possible expansions. This is passed to the `tt(-X)' option of
tt(compadd) and thus may contain the control sequences `tt(%n)',
`tt(%B)', etc. Also, the sequence `tt(%o)' in this string will be
replaced by the original string.
)
enditem()

None of these configuration keys has a default value.
)
item(tt(_list))(
This completer allows one to delay the insertion of matches until
completion is attempted a second time without the word on the line
being changed. On the first attempt, only the list of matches will be
shown. Configuration keys understood are:

startitem()
item(tt(list_condition))(
If this key is unset or set to the empty string, the insertion of
matches will be delayed unconditionally. If this value is set, it
should be set to an expression usable inside a `tt($((...)))'
arithmetical expression. In this case, delaying will be done if the
expression evaluates to `tt(1)'. For example, with

indent(
nofill(tt(compconf list_condition='NUMERIC != 1'))
)

delaying will be done only if given an explicit numeric argument
other than `tt(1)'.
)
item(tt(list_word))(
To find out if listing should be performed on its own, the code normally
compares the contents of the line with the contents the line had at the
time of the last invocation. If this key is set to an non-empty string,
comparison is done using only the current word. So if it is set,
attempting completion on a word equal to the one when completion was called
the last time will not delay the generation of matches.
)
enditem()
)
item(tt(_menu))(
This completer is a simple example function implemented to show how
menucompletion can be done in shell code. It should be used as the
first completer and has the effect of making the code perform
menucompletion. Note that this is independent of the setting of the
tt(MENU_COMPLETE) option and does not work with the other
menucompletion widgets such as tt(reverse-menu-complete), or
tt(accept-and-menu-complete).
)
item(tt(_oldlist))(
This completer controls how the standard completion widgets behave when
there is an existing list of completions which may have been generated by a
special completion (i.e. a separately-bound completion command).  It should
appear in the list of completers before any of the widgets which generate
matches.  It understands two configuration keys:

startitem()
item(tt(oldlist_list))(
If this is set to tt(always), then standard widgets which perform listing
will retain the current list of matches, however they were generated.  If
it is set to tt(never), this will not be done (the behaviour without the
tt(_oldlist) completer).  If it is unset, or any other value, then the
existing list of completions will be displayed if it is not already;
otherwise, the standard completion list will be generated:  this is the
default behaviour of tt(_oldlist).

For example, suppose you type tt(^Xc) to use the tt(_correct_word)
widget, which generates a list of corrections for the word under the
cursor.  Usually, typing tt(^D) would generate a standard list of
completions for the word on the command line, and show that.  With
tt(_oldlist), it will instead show the list of corrections already
generated.
)
item(tt(oldlist_menu))(
Controls how menu completion behaves when a completion has already been
inserted and the user types a standard completion key type as tt(TAB).
The default behaviour of tt(_oldlist) is that menu completion always
continues with the existing list of completions.  If this key is set to
tt(never), however, a new completion is started if the old list was
generated by a different completion command (the behaviour without the
tt(_oldlist) completer).
For example, suppose you type tt(^Xc) to generate a list of corrections,
and menu completion is started in one of the usual ways.  Usually, typing
tt(TAB) at this point would start trying to complete the line as it now
appears.  With tt(_oldlist), it will instead continue to cycle through the
list of completions. 
)
enditem()
)
enditem()

texinode(Completion Functions)()(Control Functions)(Completion System)
sect(Utility Functions)

Descriptions follow for utility functions that may be
useful when writing completion functions.  Most of these reside in the
tt(Core) subdirectory except where noted. Like the example 
functions for commands in the distribution, the utility functions
generating matches all follow the convention of returning zero if they
generated completions and non-zero if no matching completions could be 
added.

startitem()
item(tt(_compalso))(
This function looks up the definitions for the context and command
names given as arguments and calls the handler functions for them if
there is a definition (given with the tt(compdef) function). For
example, the function completing inside subscripts might use
`tt(_compalso -math-)' to include the completions generated for
mathematical environments.
)
item(tt(_normal))(
This function is used for normal command completion.  If
completion is attempted on the first word, command names are
completed. Otherwise, the arguments are completed by calling the
functions defined for this command, including those functions defined
for patterns matching the command name. This function can also be
called by other completion functions if they have to complete a range
of words as a separate command. For example, the function to complete after
the pre-command specifiers such as tt(nohup) removes the first word from
the tt(words) array, decrements the tt(CURRENT) parameter, then calls this
function.

When calling a function defined for a pattern, this function also
checks if the parameter tt(_compskip) is set. If it was set by the
function called, no further completion functions are called. With this 
one can write a pattern completion function that keeps other functions 
from being tried simply by setting this parameter to any value.
)
item(tt(_multi_parts))(
This functions gets two arguments: a separator character and an
array.  As usual, the array may be either the
name of an array parameter or a literal array in the form
`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white 
space in parentheses). With these arguments, this function will
complete to strings from the array where the parts separated by the
separator character are completed independently. For example, the
tt(_tar) function from the distribution caches the pathnames from the
tar file in an array and then calls this function to complete these
names in the way normal filenames are completed by the
tt(_path_files) function.

Like other utility functions, this function accepts the `tt(-V)',
`tt(-J)', and `tt(-X)' options with an argument and passes them to the
tt(compadd) builtin.
)
item(tt(_sep_parts))(
This function gets as arguments alternating arrays and separators.
The arrays specify completions for parts of strings to be separated by the
separators. The arrays may be the names of array parameters or
a quoted list of words in parentheses. For example, with the array
`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will
complete the string  `tt(f)' to `tt(foo)' and the string `tt(b@n)' to
`tt(bar@news)'.

This function passes the `tt(-V)', `tt(-J)', and `tt(-X)' options and
their arguments to the tt(compadd) builtin used to add the matches.
)
item(tt(_path_files) and tt(_files))(
The function tt(_path_files) is used throughout the shell code
to complete filenames. The advantage over the builtin
completion functions is that it allows completion of partial paths. For
example, the string `tt(/u/i/s/sig)' may be completed to
`tt(/usr/include/sys/signal.h)'.  The options `tt(-/)', `tt(-f)', `tt(-g)',
and `tt(-W)' are available as for the tt(compctl)
and tt(compgen) builtins; tt(-f) is the default. Additionally, the `tt(-F)'
option from the tt(compadd) builtin is supported, giving direct control
over which filenames should be ignored as done by the tt(fignore)
parameter in normal completion.

The function tt(_files) calls tt(_path_files) with all the arguments
it was passed and, if that generated no matches, call tt(_path_files) again
without any tt(-g) or tt(-/) option, thus generating all filenames.

These functions also accept the `tt(-J)', `tt(-V)', `tt(-X)', `tt(-P)',
`tt(-S)', `tt(-q)', `tt(-r)', and `tt(-R)' options from the
tt(compadd) builtin.

Finally, the tt(_path_files) function supports one configuration key:
tt(path_expand). If this is set to any non-empty string, the partially
typed path from the line will be expanded as far as possible even if
trailing pathname components can not be completed.
)
item(tt(_parameters))(
This should be used to complete parameter names if you need some of the
extra options of tt(compadd). It first tries to complete only non-local
parameters. All arguments are passed unchanged to the tt(compadd) builtin.
)
item(tt(_options))(
This can be used to complete option names. The difference to the
`tt(-o)' option of tt(compgen) is that this function uses a matching
specification that ignores a leading `tt(no)', ignores underscores and 
allows the user to type upper-case letters, making them match their
lower-case counterparts. All arguments passed to this function are
propagated unchanged to the tt(compgen) builtin.
)
item(tt(_set_options) and tt(_unset_options))(
These functions complete only set or unset options, with the same
matching specification used in the tt(_options) function.

Note that you need to uncomment a few lines in the tt(_main_complete)
function for these functions to work properly. The lines in question
are used to store the option settings in effect before the completion
widget locally sets the options it needs.
)
item(tt(_long_options))(
This function resides in the tt(Base) subdirectory of the example
completion system because it is not used by the core system.

This function is used to complete long options for commands that
support the `tt(--help)' option as, for example, most of the GNU
commands do. For this it invokes the command from the line with the
`tt(--help)' option and then parses the output to find possible option
names. Note that this means that you should be careful to make sure
that this function is not called for a command that does not support
this option.

For options that get an argument after a `tt(=)', the function also
automatically tries to find out what should be completed as the argument.
The possible completions for option-arguments can be described with
the arguments to this function. This is done by giving pairs of
patterns and actions as consecutive arguments. The actions specify
what should be done to complete arguments of those options whose
description match the pattern. The action may be a list of words in
brackets or in parentheses, separated by spaces. A list in square brackets
denotes possible values for an optional argument, a list in parentheses
gives words to complete for mandatory arguments. If the action does
not start with a square bracket or parenthesis, it should be the name of a
command (probably with arguments) that should be invoked to complete 
after the equal sign. Example:

indent(
nofill(tt(_long_options '*\*'     '(yes no)' \))
nofill(tt(              '*=FILE*' '_files' \))
nofill(tt(              '*=DIR*'  '_files -/'))
)

Here, `tt(yes)' and `tt(no)' will be completed as the argument of
options whose description ends in a star, file names for options that
contain the substring `tt(=FILE)' in the description, and paths for
options whose description contains `tt(=DIR)'. In fact, the last two
patterns are not needed since this function always completes files
for option descriptions containing `tt(=FILE)' and paths for option
descriptions that contain `tt(=DIR)' or `tt(=PATH)'. These builtin
patterns can be overridden by patterns given as arguments, however.

This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)'
options which are passed unchanged to `tt(compadd)'. Finally, it
accepts the option `tt(-t)'; if this is given, completion is only done
on words starting with two hyphens.
)
enditem()