diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 110 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 6 | ||||
| -rw-r--r-- | Doc/Zsh/roadmap.yo | 29 |
4 files changed, 125 insertions, 26 deletions
diff --git a/ChangeLog b/ChangeLog index adf966b03..e90bf8ecd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2006-09-21 Peter Stephenson <p.w.stephenson@ntlworld.com> + + * 22752: + Roman Neuhauser: Doc/Zsh/compsys.yo, + Doc/Zsh/compwid.yo, Doc/Zsh/roadmap.yo: improved introduction + to completion. + 2006-09-21 Peter Stephenson <pws@csr.com> * 22739: arno: Functions/Prompt/promptinit: change test diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 7591ac5ce..1a81eea3f 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -5,12 +5,84 @@ cindex(completion, programmable) 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 @@ em(styles), context-sensitive options that can be used to configure the 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 @@ this is only the case if the command line is parsed with standard 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 @@ example(tt(dvips -o ...)) 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 @@ ifzman(see zmanref(zshcompwid))\ 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 diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index 8ffc96a2e..697d1df04 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -11,9 +11,9 @@ features is described in 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)). diff --git a/Doc/Zsh/roadmap.yo b/Doc/Zsh/roadmap.yo index 8cae5b409..17f005b9b 100644 --- a/Doc/Zsh/roadmap.yo +++ b/Doc/Zsh/roadmap.yo @@ -40,14 +40,33 @@ variables (referred to in the documentation as parameters) tt(HISTFILE), 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: |