From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 29257 invoked by alias); 10 Jan 2015 05:33:18 -0000 Mailing-List: contact zsh-users-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Users List List-Post: List-Help: X-Seq: 19721 Received: (qmail 19517 invoked from network); 10 Jan 2015 05:33:15 -0000 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.2 X-CMAE-Score: 0 X-CMAE-Analysis: v=2.1 cv=Ko/6AtSI c=1 sm=1 tr=0 a=FT8er97JFeGWzr5TCOCO5w==:117 a=kj9zAlcOel0A:10 a=q2GGsy2AAAAA:8 a=oR5dmqMzAAAA:8 a=-9mUelKeXuEA:10 a=YNv0rlydsVwA:10 a=VfE1U9h_hUJrTc70GRgA:9 a=mlMyF3GzdF_yKU9x:21 a=romC3xVZ-zPzBmtk:21 a=CjuIK1q_8ugA:10 From: Bart Schaefer Message-id: <150109213306.ZM21785@torch.brasslantern.com> Date: Fri, 09 Jan 2015 21:33:06 -0800 In-reply-to: <54AEBA78.8040302@eastlink.ca> Comments: In reply to Ray Andrews "Re: completion" (Jan 8, 9:12am) References: <5488D414.6010300@eastlink.ca> <30453.1418258082@thecus.kiddle.eu> <5488F0AC.2040901@eastlink.ca> <141210214454.ZM12261@torch.brasslantern.com> <5489C8F4.8030703@eastlink.ca> <141211092824.ZM13349@torch.brasslantern.com> <5489F1BC.5000900@eastlink.ca> <20150107150109.GA14088@ypig.lip.ens-lyon.fr> <20150108004323.GA7954@xvii.vinc17.org> <54AEBA78.8040302@eastlink.ca> X-Mailer: OpenZMail Classic (0.9.2 24April2005) To: zsh-users@zsh.org Subject: Re: completion MIME-version: 1.0 Content-type: text/plain; charset=us-ascii On Jan 8, 9:12am, Ray Andrews wrote: } } Ah! So I find myself reaching for a better word. 'ambiguity' = } uncertainty or confusion. What we have here, then, is not confusion, } but rather a carefully expanded space of possibilities, or freedoms. Yes, that's basically on the right track. Here's some additional text for the compsys documentation that might help. Also moved a couple of things around to introduce them sooner. Still could probably use work. diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 920b590..2cdc57a 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -533,21 +533,41 @@ generated. subsect(Overview) When completion is attempted somewhere on the command line the -completion system first works out the context. This takes account of a +completion system begins building the context. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position. This takes account of a number of things including the command word (such as `tt(grep)' or `tt(zsh)') and options to which the current word may be an argument (such as the `tt(-o)' option to tt(zsh) which takes a shell option as an argument). -This context information is condensed into a string consisting of -multiple fields separated by colons, referred to simply as `the context' -in the remainder of the documentation. This is used to look up -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 starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on). Therefore the context will vary during the +same call to the completion system. + +This context information is condensed into a string consisting of multiple +fields separated by colons, referred to simply as `the context' in the +remainder of the documentation. Note that a user of the completion system +rarely needs to compose a context string, unless for example a new +function is being written to perform completion for a new command. What a +user may need to do is compose a em(style) pattern, which is matched +against a context when needed to look up context-sensitive options that +configure the completion system. + +The next few paragraphs explain how a context is composed within the +completion function suite. Following that is discussion of how em(styles) +are defined. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control. They +are defined with the tt(zstyle) builtin command (\ +ifzman(see zmanref(zshmodules))\ +ifnzman(noderef(The zsh/zutil Module))). 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 +by colons and with a leading colon before the first. Fields which are +not yet known are left empty, but the surrounding colons appear anyway. +The fields are always in the order tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)tt(tag). These have the following meaning: startitemize() @@ -628,17 +648,13 @@ described in ifzman(the section `Bindable Commands' below)\ ifnzman(noderef(Bindable Commands)). -Styles determine such things as how the matches are generated, similarly -to shell options but with much more control. They can have any number -of strings as their value. They are defined with the tt(zstyle) builtin -command (\ -ifzman(see zmanref(zshmodules))\ -ifnzman(noderef(The zsh/zutil Module))). - When looking up styles the completion system uses full context names, -including the tag. Looking up the value of a style therefore consists -of two things: the context, which may be matched as a pattern, and the -name of the style itself, which must be given exactly. +including the tag. Looking up the value of a style therefore consists of +two things: the context, which is matched to the most specific (best +fitting) style pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that style patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances. For example, many completion functions can generate matches in a simple and a verbose form and use the tt(verbose) style to decide