From: Bart Schaefer <schaefer@brasslantern.com>
To: zsh-users@zsh.org
Subject: Re: completion
Date: Fri, 09 Jan 2015 21:33:06 -0800 [thread overview]
Message-ID: <150109213306.ZM21785@torch.brasslantern.com> (raw)
In-Reply-To: <54AEBA78.8040302@eastlink.ca>
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
next prev parent reply other threads:[~2015-01-10 5:33 UTC|newest]
Thread overview: 56+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-12-10 23:15 completion Ray Andrews
2014-12-10 23:31 ` completion Lawrence Velázquez
2014-12-11 0:34 ` completion Oliver Kiddle
2014-12-11 1:17 ` completion Ray Andrews
2014-12-11 5:44 ` completion Bart Schaefer
2014-12-11 16:40 ` completion Ray Andrews
2014-12-11 17:28 ` completion Bart Schaefer
2014-12-11 19:34 ` completion Ray Andrews
2015-01-07 15:01 ` completion Vincent Lefevre
2015-01-07 15:28 ` completion Peter Stephenson
2015-01-07 16:58 ` completion Mikael Magnusson
2015-01-07 17:06 ` completion Peter Stephenson
2015-01-07 18:33 ` completion Ray Andrews
[not found] ` <CAH+w=7Z_B2ghc21QgHxA8FEV7W8uQnjEwtPqK3tL-kjPihjicA@mail.gmail.com>
2015-01-07 19:54 ` completion Bart Schaefer
2015-01-07 18:48 ` completion Bart Schaefer
2015-01-07 19:24 ` completion Ray Andrews
2015-01-07 19:33 ` completion Lawrence Velázquez
2015-01-07 20:06 ` completion Ray Andrews
2015-01-07 19:51 ` completion Bart Schaefer
2015-01-07 20:15 ` completion Ray Andrews
2015-01-07 20:42 ` completion Bart Schaefer
2015-01-07 23:00 ` completion Ray Andrews
2015-01-08 5:09 ` completion Bart Schaefer
2015-01-08 8:31 ` completion Bart Schaefer
2015-01-08 16:52 ` completion Ray Andrews
2015-01-08 0:43 ` completion Vincent Lefevre
2015-01-08 0:57 ` completion ZyX
2015-01-08 1:15 ` completion Vincent Lefevre
2015-01-08 6:03 ` completion Bart Schaefer
2015-01-08 5:26 ` completion Bart Schaefer
2015-01-08 12:36 ` completion Vincent Lefevre
2015-01-10 2:12 ` completion Bart Schaefer
2015-01-12 9:09 ` completion Vincent Lefevre
2015-01-12 16:43 ` completion Bart Schaefer
2015-01-13 16:03 ` completion Vincent Lefevre
2015-01-14 2:56 ` completion Bart Schaefer
2015-01-08 17:12 ` completion Ray Andrews
2015-01-09 9:37 ` completion Vincent Lefevre
2015-01-10 5:33 ` Bart Schaefer [this message]
-- strict thread matches above, loose matches on Subject: below --
2012-12-03 17:44 completion Ray Andrews
2012-12-03 18:31 ` completion Ray Andrews
2007-05-15 15:27 Completion Anonymous bin ich
2007-05-15 16:23 ` Completion Peter Stephenson
2006-02-20 12:54 Completion Etienne Chové
2006-02-20 18:51 ` Completion Clint Adams
2006-02-20 19:47 ` Completion Etienne Chové
2003-12-22 23:15 Completion Seth Kurtzberg
2000-02-22 14:58 Completion Sven Wischnowsky
2000-02-22 14:47 Completion Sven Wischnowsky
2000-02-22 15:01 ` Completion Andy Spiegl
2000-02-22 11:36 Completion Sven Wischnowsky
2000-02-22 14:24 ` Completion Andy Spiegl
2000-02-22 18:01 ` Completion Bart Schaefer
2000-02-15 8:42 Completion Claus Alboege
2000-02-21 22:20 ` Completion Bart Schaefer
2000-02-22 10:37 ` Completion Andy Spiegl
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=150109213306.ZM21785@torch.brasslantern.com \
--to=schaefer@brasslantern.com \
--cc=zsh-users@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).