completion parameter suggestion

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

(I'm asking a lot of questions lately, but I hope you agree that this
is correct behavior.)

Here is what I'm planning for the special completion parameters. Some
of this has been mentioned already, but this is more complete and
slightly different from what I said in my last mail (incorporating
suggestions from Bart and Peter):

Most of the stuff will be put in an associative array named
`compstate', but first:

- I'd like to keep `PREFIX', `SUFFIX', and `IPREFIX' (probably
  renaming the last one), since I guess that `PREFIX[...]' will be
  used quite often and is much easier to type and read than
  `compstate[prefix][...]'. Also, `PREFIX[...]=...' may occasionally
  be useful and multiple subscripts on the left hand side of an
  assignment is not supported.
- I'd also like to keep `CURRENT' to improve readibility and make it
  an index into the array `words'. Slight problem with `ksharrays'
  here, I'd like to make `CURRENT' use the range [1,n] and explicitly
  describe the problem in the manual.
- The `words' array would contain all words from the line, including
  the command. Functions like `_precommand' would only have to do
  `shift words; (( CURRENT-- ))'. No fiddling with `compstate' since
  the `comamnd' and `argument' contexts would be merged into one.
- Finally the context information, an associative array. Contrary to
  the previous parameters this one will not automatically be restored
  on exit of a function. The keys are:

  - `matcher':     the string(!) of the global matcher
  - `matcher_num': what now is `MATCHER' which will be removed
  - `num_matches': what now is `NMATCHES'
  - `context':     the former `CONTEXT'
                   - no `argument' value
		   - the `value' context could be split into `value'
		     and `array_value'
		   - a new value `parameter' for completion in `$...'
  - `parameter':   the name of the parameter for the `value' and
                   `subscript' contexts
  - `quote':       either a ` or a ", depending on the quoting the
                   code thinks we are in
  - `norestore':   this is always restored on exit of a function; if
                   it is set on exit, the parameters above will not be 
		   reset to the values they had when the function was
		   entered (with this we can finally implement helper
		   functions that do tests and modify the parameters
		   without having to make the helpers call other
		   functions that produce the matches)

  (I'm not yet too sure about the following ones, suggestions are
  especially welcome.)

  - `list':        on entry to the completion widget this is set to
                   one of `list', `autolist', `ambiguous', or it is
		   unset (or set to an empty string); this means that
		   the list will be shown always (for `list' and
		   `autolist'), probably (`ambiguous'), or not at all;
		   after the completion widget returns the completion
		   code uses the value to find out if the list should
		   be shown
  - `insert':      on entry this would be set to `menu', `automenu',
                   `unambiguous', or it is unset (or set to the empty
		   string); after executing the completion widget, the 
		   C-code will use this value to decide what should be 
		   inserted into the line: the first metach, starting
		   menucompletion (`menu' or `automenu'), the
		   unambiguous string (`...'), or nothing at all
  - `exact':       the completion code searches for exact matches on
                   the fly anyway, so we could make this information
		   available; this would be unset (or empty) if no
		   exact match was found; it will be set while
		   generating matches when an exact match is found;
		   then the value would be `insert' if one was found
		   and it should be inserted in the line (recexact)
		   and to `yes' (or something better) when one was
		   found but the user didn't set recexact

And then I'd like to make the following information available but
haven't found keys in which these could be combined (trying to avoid
too many keys and having to use too many keys for whatever purpose):

  - if there currently is an older and still valid set of matches
  - if this set is displayed on the screen
  - if this set should be kept, the set build by the completion widget 
    would be discarded (this new set will be empty in most cases)
  - if we are currently in a menucompletion, with that, probably:
    - the total number of matches in the set we are menucompleting
    - the number of the match currently on the line
    - make the code insert the n'th (or n'th next/previous) match
    - make the code accept the current match and continue
      menucompletion

And the we might want to add suport for as yet unheard of things:

  - list only the matches form certain groups
  - complete only matches from certain groups
  - skip over to another group
  - etc.

Bye
 Sven


--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx