RE: bash convert: new completion system skeleton?

[Borzenkov Andrey <Andrey.Borzenkov@siemens.com>]

> i have lots of bash completers for my daily needs that i can't live
> without.  but bash-style completers resemble zsh's old completion
> style, which is inferiour to zsh's new system.
> 
> my completers have the following properties:  the program which's
> arguments have to be completed have some help or list function which
> i can use to enumerate the possible completions, then i just grep(1)
> out the likely candidates.
> 

First, _arguments has direct support for some simple cases when a command is
using --help; look in Completion/Unix/Command/_configure for direct example.
In short, you describe patterns how to interpret command help output and
what functions to use to complete specific parameters.

This works for simple case but does not allow you to supply description text
for a particular argument.

Speaking in general, if you need just to complete a list of command
arguments, you simply call _arguments passing it array of arguments names.
There are many examples, look in _texinfo (at the end, case $state item) )
for a perverse example of using shell substitutions :)) or _cvs where it
completes available commands.

But preferred way (if you know command arguments in advance) is to use
_arguments together with table of command arguments and descriptions. Like


#compdef foo
_arguments \
  'foo-arg-1[Argument 1]' \
  'foo-arg-2[Argument that takes some
parameters]::_function_to_complete_parameters'

in the simplest case it is just 

_arguments foo-arg-1 foo-arg-2

but then you won't ever get descriptions :)

> example:  there's an anti-spam system called qconfirm
> <URL:http://smarden.org/qconfirm/>, the bash completer for which is:
> 

For you specific function, look at _cvs or _rpm completion, i.e. completion
of command with subcommands. In general this would be like something like
following (unverified), see _cvs for excellent example and technique how to
dynamically call subcommands.

=========================
#compdef qconfirm

_qconfirm_subcommand ()
{
   local which
   case $line[2] in
     ac*|b[ao]*|dr*)
		which=pending
	;;
    re*|pe*)
 		which=ok
	;;
    *)
 		which=ok
	;;
  esac
  compadd "$@" -- $(qconfirm $opt_args list $which | sed ... | egrep ...)
  # note that both sed and grep cam be replaced
  # with internal Zsh substitution. See _texinfo (near bottom) for
absolutely
  # braindamage example that really works :)
}

_qconfirm ()
{
  _arguments \
     '-arg1[It is arg1 that does useful thing]' \
     '-arg2[It is arg 2 that does even more useful thing]' \
     '::possible subcommands:(cmd1:"description 1" cmd2:"Description 2"
...)' \
     '*::completin subcommand:_qconfirm_subcommand'
}

_qconfirm "$@"

======================

and call _qconfirm and put somewhere in your fpath. Note that _arguments
already extracts options so you need not worry about it and it will format
output according to your styles etc etc. In general, _arguments is what you
need for your own custom completion.

Of course, if subcommand may take flags you may need write completion for
each one separately etc Again look in _cvs for excellent example.

> {
> 	local i cur qopts qcmd
 	local -a COMPREPLY
> 	qopts=""
 	qcmd=${words[2]}
>         # collect possible options to hand over 1:1
> 	for (( i=1 ; i<=COMP_CWORD ; i++ ))
> 	do
> 		cur="${COMP_WORDS[$i]}"
> 		#echo $cur >&2
> 		case $cur in
> 		    -*)
> 			qopts="$qopts $cur"
> 			;;
> 		    *)
> 			qcmd=${cur}
> 			break
> 			;;
> 		esac
> 	done
>         # select the database depending on the subcommand used
> 	case $qcmd in
> 	    ac*|b[ao]*|dr*)
> 		which=pending
> 		;;
> 	    re*|pe*)
> 		which=ok
> 		;;
> 	    *)
> 		which=ok
> 		;;
> 	esac
>         # here's the meat:  list the relevant database and pick the
>         # right completion
> 	cur=${COMP_WORDS[COMP_CWORD]}
> 	COMPREPLY=( $(qconfirm $qopts list "${which}" |
> 		cut -d" " -s -f2 |
> 		egrep -i "${cur}" ))
> 	return 0
> }
> # tell the completion system which function is responsible for qconfirm
> complete -F _qconfirm qconfirm
> 
> similiar code exists for gnu-make, autoconf's configure, openssl etc.

All of them are already included with zsh.

> 
> could somebody please offer the skeleton of a completer for the new
> system, complete with which share/zsh/4.0.6/function/_<FUNC>s to
> call, how to name the zstyle and the contexts?
> 
> i'm simply lost in all the files of the distribution, especially
> those _<helper> functions.  any pointers appreciated.  is there
> already a wiki for zsh specialists and users?
>

the only one known to me is at zsh site, it is a good start anyway.

 
>   clemens