The README file

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

Sorry if this is just noise to you, but I was asked to post the
complete README file (by Helmut) because the patch for the _list
completer didn't apply to his README. Maybe that was just a missing
5916, but maybe I've made the patch to some non-canonical version of it.

Bye
 Sven

The subdirectories contain code for the new function-based completion
system.  Broadly speaking, this uses shell functions defined for each
command to determine how the arguments of a command should be completed.

You should copy all the files you need or want to a directory of your own,
which should be included in your autoload path as defined by $fpath.  Then
in your .zshrc you should source the file which appears here in
Core/compinit.  It is recommnded that you use the -d option, which outputs
a file containing the necessary variables, bindkeys etc., making later
loading much faster.  For example,
  [[ -f ~/completion/compinit ]] && . ~/completion/compinit -d
The name of the file to use may be given as an extra argument.

This will rebind any keys which do completion to use the new system.
For more detailed instructions, including how to add new completions, see
the top of Core/compinit. For information about how to configure the code,
see the section below.

The subdirectories contain:

Core:
  The basic functions and files to be sourced.  You will certainly need
  these, and will most likely not want to alter them --- if you do, it
  would probably help to give your version a different name.  The files
  are:
  compinit
    As already described, this is not a function, but is sourced once
    (with the `source' or `.' commands) to set up the completion system.
  compdump
    This dumps the completions status for faster initialisation.  The
    easiest way of doing this is to use the -d option to compinit rather
    than calling compdump directly.
  _approximate
    A completer function that does correcting completion.
  _compalso
    Utility for calling a function to add additional completions to an
    already existing set.
  _complete
    The main completer function that generates the completions by calling
    the context and command specific functions.
  _correct
    A completer function that attempts correction on the word from the
    line. Unlike _approximate this does only correction, not completion.
  _expand
    A completer function for expanding the word on the line.
  _files
    A frontend to _path_files which will default to any old file if the
    specified file was not found.
  _list
    A completer function that allows showing only a list on the first
    TAB and insert completions on the second one.
  _match
    A completer function that temporarily swicthes on pattern matching
    when comparing the string from the line with possible completions.
  _main_complete
    The main entry point called by the key bindings which compinit sets
    up (the main `completion widget' in zsh jargon). This mainly calls
    completer functions like _complete, either those given as arguments
    or (if it is called without arguments) those from the completer
    configuration key (see below).
  _multi_parts
    Utility for completion parts of words given a separator character and 
    a list of words.
  _normal
    The function called by _main_complete to handle the most common
    cases, such as completing a command name or its arguments.  This
    function dispatches to the various other functions for individual
    commands.  (Actually, the system is fairly context-sensitive, so
    it is wider than just command+argument.)
  _path_files
    The function usually called to complete filenames and directories.  It
    replaces the standard -f, -g and -/ options for the basic completion
    commands:  it can do various extra tricks, such as expanding a whole
    path at once, e.g. F/C/C/_p<TAB> -> Functions/Completion/Core/_path_files
  _sep_parts
    Utility used for completing words with multiple separate parts, such as
    `<user>@<host>'
Base:
  You will almost certainly want these files, too, which handle standard
  tasks like completing files.  However, you may want to edit them for
  your own particular setup.  Files are:
  _command_names
    This handles completion of the command word, i.e. the first thing
    on the command line.  You may want to alter this, for example,
    to complete parameters to assign to.
  _condition
    This handles completing inside [[ ... ]] .
  _default
    This handles completion of command arguments when no special function
    exists.  Usually this means completing files, but you can modify this
    as you wish.
  _long_options
    This handles options beginning with `--', as in many GNU commands.
    The command must accept the --help option to list the possible options.
    __long_options can also take arguments to help it decide what to
    complete as the value of the option.  Note that this is potentially
    dangerous because the command from the line will be called with the
    --help option and hence could cause damage if used with a command
    that does not support it.
  _match_pattern
  _match_test
    These are used by Base/_path_files (and hence also Base/_files)
    and Base/_sep_parts for file completion with control over
    matching (whether to complete case-insensitively, or to allow
    insertion before `.', etc.)  See _match_test for instructions.
    Note _path_files expects these files to be present.
  _precommand
    Allows completion when the first word on the line has to be ignored,
    for example `noglob ...' should ignore the noglob and just complete
    as if it wasn't there.  Add other such commands to the top line.
  _redirect
    Completes after `<' or `>': this version calls _files.
  _subscript
    For completion in subscripts of parameters, e.g $foo[...].
  _vars
    Completion for commands which need variables (so this could also be in
    the Builtins directory), but also in math environments such as ((...)).
  _tilde
    Completion after `~', defaults to user names and named directories.
  _equal
    Completion after `=', normally command and alias names are used.
  _parameter
  _brace_parameter
    For completion inside parameter expansions ($... and ${...).
Builtins:
  Define completions for various shell builtins.  The top line of each file
  says which builtins they apply to; in many cases you can guess from the
  name.  Note in particular that _zftp defines completions for all commands
  beginning `zf', not just for the module command zftp.  This is only
  really useful if you use zftp with the zf* function suite (zfopen, zfget,
  ...).
User:
  This contains a pot pourri of completions for various external commands.
  Not all will work unmodified on your system.
Commands:
  These functions define separate completion commands which do not use
  the usual context information, and hence have to be bound separately
  to keys.  As they appear, they have bindings which you can change or
  delete by altering the top line of the file.  To bind a function
  (strictly speaking, the corresponding completion widget) yourself
  after completion is loaded, use `bindkey '<key-string>' <_function_name>'.
  The files are:
  _correct_filename, bound to \C-xc
    Correct the word under the cursor as a filename.  This is significantly
    more powerful than the standard \e$ (spell-word) binding.
  _most_recent_file, bound to \C-xm
    Insert the name of the most recent file matching the pattern
    so far on the command line.


Configuration

You can configure several aspects of the completion functions and the
overall completion behavior using the compconf shell function defined
in compinit. This function get any number of arguments of the form
`key=value', where `key' is one of the keys described below and `value'
is any string. Most configuration keys are defined by the completer
functions.

The completion widget function _main_complete currently understands
one configuration key:

  completer
    This should be set to the names of the functions to generate the
    matches separated by colons. E.g. with

      compconf completer=_complete:_correct:_approximate

    the code will first try normal completion. If that doesn't yield
    any matches, correction is tried and if that doesn't yield
    anything either, correcting completion is attempted.

The keys understood by the _approximate completer function are:

  approximate_accept
    This should be set to a number, specifying the maximum number
    of errors that should be accepted. If the string also contains
    a `n' or `N', the code will use the numeric argument as the
    maximum number of errors if a numeric argument was given. If no
    numeric argument was given, the number from the value of this
    key will be used. E.g. with `compconf approximate_accept=2n' two
    errors will be accepted, but if the user gives another number
    with the numeric argument, this will be prefered. Also, with
    `compconf approximate_accept=0n', normally no correction will be
    tried, but if a numeric argument is given, automatic correction
    will be used. On the other hand, if the string contains an `!'
    and a `n' or `N', correction is not attempted if a numeric
    argument is given. Once the number of errors to accept is
    determined, the code will repeatedly try to generate matches by
    allowing one error, two errors, and so on. Independent of the
    number of errors the user wants to accept, the code will allow
    only fewer errors than there are characters in the string from
    the line.

  approximate_original
    This value is used to determine if the original string should
    be included in the list (and thus be presented to the user when
    cycling through the corrections). If it is set to any non-empty
    value, the original string will be offered. If it contains the
    sub-string `last', the original string will appear as the last
    string when cycling through the corrections, otherwise it will
    appear as the first one (so that the command line does not
    change immediately). Also, if the value contains the sub-string
    `always', the original string will always be included, whereas
    normally it is included only if more than one possible
    correction was generated.

  approximate_prompt
    This can be set to a string that should be printed before the
    list of corrected strings when cycling through them. This string
    may contain the control sequences `%n', `%B', etc. known from
    the `-X' option of `compctl'. Also, the sequence `%e' will be
    replaced by the number of errors accepted to generate the
    corrected strings.

  approximate_insert
    If this is set to a string starting with `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
    `approximate_original'. If no sensible string could be found,
    one can cycle through the corrected strings as usual.

If any of these keys is not set, but the the same key with the
prefix `correct' instead of `approximate' is set, that value will
be used. The forms beginning with `correct' are also used by the
_correct completer function, and this function uses only them, not
the ones starting with `approximate'. This allows one to give
different value to be used with correction and correcting
completion. For example, with:

  compconf completer=_complete:_correct:_approximate
  compconf correct_accept='2n!' approximate_accept=3n

correction will accept up to two errors. If a numeric argument is
given, correction will not be used, but correcting completion will
and it 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.

The _match completer function, which allows to give patterns on the
command line and complete all strings matching it from the set of
possible completions, understands the following key:

  match_original
    If this is set to a `only', pattern matching will only be tried
    with the string from the line. If it is set to any other non-empty
    string, the original pattern will be tried first and if that yields
    no completions, matching will be tried again with a `*' inserted
    at the cursor position. If this key is not set or set to an empty
    string, matching will only be attempted with the `*' inserted.

The _expand completer allows one to do expansion on the word from the
line. Note that you may either want to use the configuration keys or
not use this completer at all if you also use the _match completer
because the _expand completer will otherwise expand patterns before
they are seen by the _match completer.
Configuration keys supported are:

  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 $(...) and
    ${...}). If this is set to an non-empty string it should be 
    an expression usable inside a $[...] arithmetical expression.
    In this case, expansion of substitutions will be done if the
    expression evaluates to `1'. For example, with

      compconf expand_substitute='NUMERIC != 1'

    substitution will be performed only if given an explicit numeric
    argument other than `1', as by typing ESC 2 TAB.

  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 expand_substitute.

  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 ommand line,
    replacing the original string. However, if this key is set to an
    non-empty string, the user can cycle through the expansion as in
    a menucompletion. Unless the value contains the sub-string `only',
    the user will still be offered all expansions at once as one of
    the strings to insert in the command line. Also, if the value
    contains the sub-string `last', the string with all expansion will
    be offered first, whereas normally it is offered as the last string
    to insert. Finally, if the value contains the sub-string `sort',
    the expansions will be sorted alphabetically, normally they are
    kept in the order the expansion produced them in.
    
  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 sub-string
    `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 immediatly).

  expand_prompt
    This may be set to a string that should be displayed before the
    possible expansions. This is given to the -X option and thus may
    contain the control sequences `%n', `%B', etc. Also, the sequence
    `%o' in this string will be replaced by the original string.

The _list 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:

  list_condition
    If this key is unset or set to the empty string, this completer
    will delay the insertion of matches unconditionally. However,
    if this value is set, it should be set to an expression usable
    inside a $[...] arithmetical expression. In this case, delaying
    will be done if the expression evaluates to `1'.
    For example, with

      compconf list_condition='NUMERIC != 1'

    delaying will be done only if given an explicit numeric argument
    other than `1'.

  list_word
    To find out if only listing should be done, 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 completion was called on the last time will not
    delay the generation of matches.


For more information about what the completers do, see the files
containing them (_complete, _correct, _approximate, _match, and
_expand in the Core directory).

--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx