Re: generals observations about completion system

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

On Sep 17,  7:33pm, E. Jay Berkenbilt wrote:
} Subject: generals observations about completion system
}
} I suspect most users will probably not customize it too much or write
} too many of their own completion functions, and, based on the manual,
} I suspect the authors share this belief.
} 
} So that means that it would be good if the "standard" completion
} functions, i.e., those installed by default, were easily customizable
} by users.

Have you tried using "compinstall"?  It does an question-and-answer menu-
driven session to establish likely completion customizations, so that an
"ordinary user" doesn't have to comprehend all the details at once, and
you end up with nice examples of style usage to look at.

} The zsh documentation [...] naturally is still somewhat incomplete

There's also PWS's work-in-progess on-line user's guide:

    http://sunsite.auc.dk/zsh/Guide/zshguide.html

} about how specific completion functions can be customized through
} styles.

It does tend to be easier to add new completion functions than it is to
document them.

} I will give a few specific examples of what I'm talking about.
} 
}      compdef -a _rlogin krlogin krsh rcp
} 
}      This, however, did not work because the code in the _rlogin
}      function hard-codes the names of the commands and uses them
}      in conditions to decide what specific behavior to use.

This same problem exists for _ssh (which it would be nice to use for
the ssh1 and ssh2 versions of those commands), and probably a couple
of others.

}      It seems to me that it would have been better to have three
}      separate completion functions here that can share common
}      functions to avoid this.

The reason that *wasn't* done was to be able to keep all the related
functions together in one file, which has to have the same name as the
function invoked for each of the commands named in the #compdef line.

However ... there isn't any reason the file _rlogin couldn't define
several functions, and issue new `compdef' commands to point rcp and
rsh at different functions.  (In fact, on systems that have `remsh',
`rsh' is not an rlogin-related function at all.)  Stay tuned.

}  2.  The ssh completion function does not use the user-hosts style
}      even though this style is documented.  (If it uses it, I've
}      missed it.)

It does use it; see the _ssh_users and _ssh_hosts functions, at the
end of Completion/User/_ssh.  They get at it via the _combination
helper function.  As documented under the users-hosts style entry:

     If set for the my-accounts tag, this is used for commands such as
     rlogin and ssh; in this case the style should contain the names of
     the user's own accounts on remote hosts.  If set for the
     other-accounts tag, it is used for commands such as talk and
     finger and should contain other people's accounts.  Finally, it
     may also be used by some commands with the accounts tag.

The trouble is that ^Xh can't descend all the way through _combination
to show you the styles and tags that it supports, so all you see are the
separate hosts and users tags.  I don't know what would be involved in
fixing that.

If you've set users-hosts and are still having trouble getting ssh to
use them, it may have something to do with that completer style we've
been discussing in the other thread.

}  3.  Sometimes I think it would be nice to have an "advice"-like
}      capability (as in lisp).  That way it would be easier to write
}      wrappers for things.

There actually is such a capability, sort of, but only compiled zmodload
modules can make use of it.  It might be possible to write an "advice"
module to expose the facility at the user level.  (I'm not going to try
that anytime soon.)

However, maybe what you're looking for is this, from "Utility Functions"
in zsh.info:
----------------------
When writing completion functions or other ZLE widgets that call
completion, it might be interesting to know about two more features
offered by the _main_complete function. The arrays compprefuncs and
comppostfuncs may be set to contain names of functions that are to be
called immediately before or after completion has been tried. The
functions will only be called once, unless they put themselves into the
arrays again.
----------------------

Hmm, it really ought to say a bit more about it than that ...

}  4.  It's very hard to know what features are documented reliable
}      parts of the interface and what parts aren't.

If it's in the documentation, then it's documented. :-)

There's also Etc/completion-style-guide in the distribution, if you're
planning to write functions that can be included in the standard system.

}      Certainly the guideline that things that start with _
}      are not intended to be called directly by users is a start, but
}      then what about things like my workaround for krlogin?

I'd have followed the advice about copying one of the existing completion
functions and modifying it, rather than rely on calling through to it.
(Hmm, I thought that advice appeared somewhere in either the docs or in
completion-style-guide, but now I can't find it.)

More from zsh.info:
----------------------
This describes the shell code for the new completion system.  It
consists of various shell functions; those beginning `comp' are to be
called directly by the user, while those beginning `_' are called by the
completion code.  The shell functions of the second set which implement
completion behaviour and which may be bound to keystrokes, are referred
to as `widgets'.

In the source distribution, the files are contained in various
subdirectories of the Completion directory.  They may have been
installed in the same structure, or into one single function directory.
The following is a description of the files found in the original
directory structure.  If you wish to alter an installed file, you will
need to copy it to some directory which appears earlier in your fpath
than the standard directory where it appears.

The convention for autoloaded functions used in completion is that they
start with an underscore; as already mentioned, the fpath/FPATH
parameter must contain the directory in which they are stored.

When compinit is run, it searches all such files accessible via
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 # is part of the tag name and no white space is allowed after it.
The #compdef tags use the compdef function described below; the main
difference is that the name of the function is supplied implicitly.

Descriptions follow for utility functions that may be useful when
writing completion functions.  Most of these reside in the Core
subdirectory. 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.
----------------------

(The above is clipped from several chapters, you won't find it in that
order anywhere in the document.)

} Anyway, I understand that I'm using a development release of an
} experimental version of zsh, so these aren't intended as complaints or
} criticisms but more as comments or questions.  Perhaps a lot of this
} has already been discussed.

The new completion system is the reason zsh-workers had nearly as many
messages in 1999 as in its entire previous history.  It took a lot of
discussion to get it to where it is now ...

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net