Zsh Mailing List Archive
Messages sorted by:
Re: comments toward completion system docs
- X-seq: zsh-workers 22752
- From: Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>
- To: Roman Neuhauser <neuhauser@xxxxxxxxxx>, Zsh Hackers' List <zsh-workers@xxxxxxxxxx>
- Subject: Re: comments toward completion system docs
- Date: Wed, 20 Sep 2006 22:54:40 +0100
- In-reply-to: <20060919000634.GA29030@xxxxxxxxxxxxxxxx>
- Mailing-list: contact zsh-workers-help@xxxxxxxxxx; run by ezmlm
- References: <20060919000634.GA29030@xxxxxxxxxxxxxxxx>
Note this has been moved to zsh-workers.
I've included some of your suggestions in the documentation and added
minor bits of my own. I haven't touched _arguments any further yet.
I haven't changed the order of the manual, since it's a reference work
which is designed to put the basic parts first, but I've tried to ensure
the reader knows where to go. As I mentioned, the new roadmap is an
important part of this.
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.191
diff -u -r1.191 compsys.yo
--- Doc/Zsh/compsys.yo 20 Sep 2006 14:09:56 -0000 1.191
+++ Doc/Zsh/compsys.yo 20 Sep 2006 21:50:58 -0000
@@ -5,12 +5,84 @@
-This describes the shell code for the new completion system. It consists
-of various shell functions; those beginning `tt(comp)' are to be called
-directly, while those beginning `tt(_)' are called by the
-completion code. The shell functions of the second set, which implement
+This describes the shell code for the `new' completion system, referred
+to as tt(compsys). It is written in shell functions based on the
+features described in
+ifnzman(the previous chapter, noderef(Completion Widgets)).
+The features are contextual, sensitive to the point at which completion is
+started. Many completions are already provided.
+For this reason, a user can perform a great many tasks without
+knowing any details beyond how to initialize the system, which is
+ifzman(below in INITIALIZATION)\
+The context that decides what completion is to be performed may be
+an argument or option position: these describe the position on the
+command line at which completion is requested. For example `first argument
+to rmdir, the word being completed names a directory';
+a special context, denoting an element in the shell's syntax. For example
+`a word in command position' or `an array subscript'.
+A full context specification contains other elements, as we shall describe.
+Besides commands names and contexts, the system employs two more
+concepts, em(styles) and em(tags). These provide ways for the user
+to configure the system's behaviour.
+Tags play a dual role. They serve as a classification system for
+the matches, typically indicating a class of object that the user
+may need to distinguish. For example, when completing arguments of the
+tt(ls) command the user may prefer to try tt(files) before tt(directories),
+so both of these are tags. They also appear as the rightmost
+element in a context specification.
+Styles modify various operations of the completion system, such as
+output formatting, but also what kinds of completers are used (and in
+what order), or which tags are examined. Styles may accept arguments
+and are manipulated using the tt(zstyle) command described in
+ifnzman(noderef(The zsh/zutil Module)).
+In summary, tags describe em(what) the completion objects are, and style
+tt(how) they are to be completed. At various points of execution, the
+completion system checks what styles and/or tags are defined for the
+current context, and uses that to modify its behavior. The full
+description of context handling, which determines how tags and other
+elements of the context influence the behaviour of styles, is described
+ifzman(below in COMPLETION SYSTEM CONFIGURATION)\
+ifnzman(in noderef(Completion System Configuration)).
+When a completion is requested, a dispatcher function is called;
+see the description of tt(_main_complete) in the list of control functions
+below. This dispatcher decides which function should
+be called to produce the completions, and calls it. The result is
+passed to one or more em(completers), functions that implement
+individual completion strategies: simple completion, error correction,
+completion with error correction, menu selection, etc.
+More generally, the shell functions contained in the completion system are
+of two types:
+those beginning `tt(comp)' are to be called directly; there are only
+a few of these;
+those beginning `tt(_)' are called by the
+completion code. The shell functions of this set, which implement
completion behaviour and may be bound to keystrokes, are referred to
+as `widgets'. These proliferate as new completions are required.
@@ -464,8 +536,9 @@
completion system. The context used for lookup may vary during the same
call to the completion system.
-The context string always consists of the following fields, separated
-by colons and with a leading colon before the first:
+The context string always consists of a fixed set of fields, separated
+by colons and with a leading colon before the first, in the form
+tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)tt(tag). These have the following meaning:
@@ -510,13 +583,19 @@
UNIX-style options and arguments, so many completions do not set this.
-The var(tag). Tags are used to discriminate between the types
-of matches a completion function can generate in a certain context and
-are described further below.
+The var(tag). As described previously, tags are used to discriminate between
+the types of matches a completion function can generate in a certain context.
+Any completion function may use any tag name it likes, but a list of the
+more common ones is given below.
-As an example, the context name
+The context is gradually put together as the functions are executed, starting
+with the main entry point, which adds tt(:completion:) and the var(function)
+element if necessary. The completer then adds the var(completer) element.
+The contextual completion adds the var(command) and var(argument) options.
+Finally, the var(tag) is added when the types of completion are known.
+For example, the context name
@@ -527,12 +606,7 @@
and the completion function will generate filenames.
-Each type of completion the system can perform in a given context is
-described by a `tag', a short descriptive string such as tt(files) in
-the example above. Any completion function may use any tag name it
-likes, but a list of the more common ones is given below.
-Usually completion will be tried by all possible tags in an order given
+Usually completion will be tried for all possible tags in an order given
by the completion function. However, this can be altered by using the
tt(tag-order) style. Completion is then restricted to the list of given
tags in the given order.
@@ -591,7 +665,7 @@
). For example,
-example(tt(ztyle -e ':completion:*' hosts 'reply=($myhosts)'))
+example(tt(zstyle -e ':completion:*' hosts 'reply=($myhosts)'))
This forces the value of the tt(hosts) style to be read from the
variable tt(myhosts) each time a host name is needed; this is useful
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compwid.yo,v
retrieving revision 1.38
diff -u -r1.38 compwid.yo
--- Doc/Zsh/compwid.yo 7 Mar 2006 12:52:28 -0000 1.38
+++ Doc/Zsh/compwid.yo 20 Sep 2006 21:50:59 -0000
@@ -11,9 +11,9 @@
ifnzman(the next chapter, noderef(Completion System)),
and users with no interest in adding to that system (or, potentially,
-writing their own DASH()- see dictionary entry for `hubris') should skip this
-section. The older system based on the tt(compctl) builtin command is
+writing their own DASH()- see dictionary entry for `hubris') should skip
+the current section. The older system based on the tt(compctl) builtin
+command is described in
ifnzman(noderef(Completion Using compctl)).
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/roadmap.yo,v
retrieving revision 1.7
diff -u -r1.7 roadmap.yo
--- Doc/Zsh/roadmap.yo 15 Feb 2006 09:43:38 -0000 1.7
+++ Doc/Zsh/roadmap.yo 20 Sep 2006 21:50:59 -0000
@@ -40,14 +40,33 @@
tt(HISTSIZE) and tt(SAVEHIST) in ifzman(zmanref(zshparam))\
ifnzman(noderef(Parameters Used By The Shell)).
-The line editor provides an extensive completion system and the shell
-is supplied with completions for many commonly used commands. Note
-that the new completion system referred to as tt(compsys) is preferred
-over the older tt(compctl) system. The completion system must be enabled
-explicitly when the shell starts. For more information see
+Completion is a feature present in many shells. It allows the user to
+type only a part (usually the prefix) of a word and have the shell fill
+in the rest. The completion system in zsh is programmable. For
+example, the shell can be set to complete email addresses in
+arguments to the mail command from your tt(~/.abook/addressbook);
+usernames, hostnames, and even remote paths in arguments to scp, and so
+on. Anything that can be written in or glued together with zsh can be
+the source of what the line editor offers as possible completions.
+Zsh has two completion systems, an old, so called tt(compctl) completion
+(named after the builtin command that serves as its complete and only
+user interface), and a new one, referred to as tt(compsys),
+organized as library of builtin and user-defined functions.
+The two systems differ in their interface for specifying the completion
+behavior. The new system is more customizable and is supplied with
+completions for many commonly used commands; it is therefore to be
+The completion system must be enabled explicitly when the shell starts.
+For more information see
+subsect(Extending the line editor)
Apart from completion, the line editor is highly extensible by means of
shell functions. Some useful functions are provided with the shell; they
provide facilities such as:
Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/
Messages sorted by: