From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2493 invoked from network); 20 Sep 2006 21:54:58 -0000 X-Spam-Checker-Version: SpamAssassin 3.1.5 (2006-08-29) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-2.4 required=5.0 tests=AWL,BAYES_00, FORGED_RCVD_HELO autolearn=ham version=3.1.5 Received: from news.dotsrc.org (HELO a.mx.sunsite.dk) (130.225.247.88) by ns1.primenet.com.au with SMTP; 20 Sep 2006 21:54:58 -0000 Received-SPF: none (ns1.primenet.com.au: domain at sunsite.dk does not designate permitted sender hosts) Received: (qmail 89890 invoked from network); 20 Sep 2006 21:54:50 -0000 Received: from sunsite.dk (130.225.247.90) by a.mx.sunsite.dk with SMTP; 20 Sep 2006 21:54:50 -0000 Received: (qmail 21213 invoked by alias); 20 Sep 2006 21:54:48 -0000 Mailing-List: contact zsh-workers-help@sunsite.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 22752 Received: (qmail 21202 invoked from network); 20 Sep 2006 21:54:47 -0000 Received: from news.dotsrc.org (HELO a.mx.sunsite.dk) (130.225.247.88) by sunsite.dk with SMTP; 20 Sep 2006 21:54:47 -0000 Received: (qmail 89675 invoked from network); 20 Sep 2006 21:54:47 -0000 Received: from mtaout01-winn.ispmail.ntl.com (81.103.221.47) by a.mx.sunsite.dk with SMTP; 20 Sep 2006 21:54:45 -0000 Received: from aamtaout03-winn.ispmail.ntl.com ([81.103.221.35]) by mtaout01-winn.ispmail.ntl.com with ESMTP id <20060920215443.ZEYB15018.mtaout01-winn.ispmail.ntl.com@aamtaout03-winn.ispmail.ntl.com>; Wed, 20 Sep 2006 22:54:43 +0100 Received: from pwslaptop.csr.com ([81.107.41.155]) by aamtaout03-winn.ispmail.ntl.com with SMTP id <20060920215442.EFKA11710.aamtaout03-winn.ispmail.ntl.com@pwslaptop.csr.com>; Wed, 20 Sep 2006 22:54:42 +0100 Date: Wed, 20 Sep 2006 22:54:40 +0100 From: Peter Stephenson To: Roman Neuhauser , Zsh Hackers' List Subject: Re: comments toward completion system docs Message-Id: <20060920225440.abbb9456.p.w.stephenson@ntlworld.com> In-Reply-To: <20060919000634.GA29030@dagan.sigpipe.cz> References: <20060919000634.GA29030@dagan.sigpipe.cz> X-Mailer: Sylpheed version 2.2.7 (GTK+ 2.8.20; i386-redhat-linux-gnu) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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. Index: Doc/Zsh/compsys.yo =================================================================== 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 @@ cindex(completion, controlling) sect(Description) -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 +ifzman(zmanref(zshcompwid))\ +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 +described +ifzman(below in INITIALIZATION)\ +ifnzman(in noderef(Initialization)). + +The context that decides what completion is to be performed may be +startitemize() +itemiz(\ +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'; +) +itemiz(\ +a special context, denoting an element in the shell's syntax. For example +`a word in command position' or `an array subscript'. +) +enditemize() + +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 +ifzman(see zmanref(zshmodules))\ +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: +startitemize() +itemiz(\ +those beginning `tt(comp)' are to be called directly; there are only +a few of these; +) +itemiz(\ +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'. +as `widgets'. These proliferate as new completions are required. +) +enditemize() startmenu() menu(Initialization) @@ -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: startitemize() itemiz(\ @@ -510,13 +583,19 @@ UNIX-style options and arguments, so many completions do not set this. ) itemiz(\ -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. ) enditemize() -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 example(tt(:completion::complete:dvips:option-o-1:files)) @@ -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 @@ ifnzman(noderef(Completion Widgets)))\ ). 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 Index: Doc/Zsh/compwid.yo =================================================================== 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 @@ ifzman(zmanref(zshcompsys))\ 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 -described in +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 ifzman(zmanref(zshcompctl))\ ifnzman(noderef(Completion Using compctl)). Index: Doc/Zsh/roadmap.yo =================================================================== 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 +subsect(Completion) + +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 +preferred. + +The completion system must be enabled explicitly when the shell starts. +For more information see ifzman(zmanref(zshcompsys))\ ifnzman(noderef(Completion System)). +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 Web page now at http://homepage.ntlworld.com/p.w.stephenson/