Re: Let's finish this new completion stuff

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

Matt Armstrong wrote:

> > Before I get tired of asking the same questions again and
> > again, I'll write down all the things I'm thinking about
> > and which I'd like to discuss before we start implementing
> > them.
> >
> > *Please* take the time to send comments, suggestions, answers,
> > questions or whatever.
> 
> I think the completion stuff is one of the most important aspects of zsh 
> (it is what motivated me to switch to zsh from tcsh).  So, I'd love to 
> contribute to this discussion.
> 
> However, I must admit that I haven't understood most of the completion 
> related discussion to date.  I think this is in part because it is a 
> complex subject, but also because I came in in the middle of the 
> development.
> 
> The thing that'd help me understand most is an easy way to see a 
> function call trace when __complete_expand-or-complete and friends get 
> called.  Is something like that possible?

This is for normal completion (the one not bound to special keys):

- The C-Code calls `_main_complete', that is the completion widget.
- This function first looks up the entry for `-first-' in the
  associative array `comps' which is used as the table to connect
  command names (and a few special names like `-first-', `-default-',
  etc) with the names of the functions that generate the completions
  for that command.
  If there is an entry for `-first-', the function is called, after
  that `COMPSKIP' is tested (the replacement for `compctl -t'): if it
  is set, no other completions are generated.
  All functions generating matches get the words from the command line 
  as positional parameters.
- When other completions (vaguely speaking: for the command itself)
  are to be generated, `_main_complete' looks at the value of
  `CONTEXT' to find out which function to call. For contexts like
  mathematical expressions and so on, other special names surrounded
  by hyphens are used for looking at `comps'. Again, the function
  found, if any, is invoked.
- Completion in command position and in arguments is handled in
  another function: `_normal'. For completion in command position it
  just calls the entry for `-command-' in the `comps' array. For
  arguments this function first gets the command name to use. These
  may actually be two names: if a path is given on the line, the whole
  path and the last component are tried. If the name on the line starts
  with `=' the full pathname is used. Otherwise the name on the line
  and the pathname of that command is used.
  With these names, the (normal) array `patcomps' is searched. Entries 
  in this array look like `pat func', i.e.: a pattern and the name of
  a function separated by a space. Whenever an element is found whose
  pattern matches one of the command names produced, the function is
  invoked to generate matches. After that, `COMPSKIP' is tested again.
  After the patterns were tried, lookup in the associative array
  `comps' is done again, with the two command names (one after
  another), if no entry for them is found, the entry for `-default-'
  is used again. As soon as an entry is found, the function is
  invoked.

So, the call chain for normal argument-completion is:

  C-Code
    _main_complete
      _normal
        functions for patterns, if any
        function for the command or for `-default-

For non-argument-or-command completion the call chain is:

  C-Code
    _main_complete
      function for special context or for `-default-'

Completion bound to special keys just calls the function for that key
directly with no intervening helper functions.

The functions generating the matches may call `compalso <name> <args>'
to let the completion code generate matches for another command named
`<name>', where the `<args>' are the words from the line (i.e. the
positional parameters). That function looks at `comps' to find the
function to call. Completion generating functions that need to do
sub-command completion (e.g. `find' between `-(ok|exec)' and `\;') can 
simple call `_normal' to do the completion-lookup and match-generation 
on the word-range which is normally set by invoking one of the
modifying condition codes.

Hope this helps.

Bye
 Sven


--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx