* Re: Rewrite of compsys.yo
2003-04-14 18:15 Rewrite of compsys.yo Peter Stephenson
@ 2003-04-18 13:17 ` Oliver Kiddle
2003-04-23 17:25 ` Peter Stephenson
0 siblings, 1 reply; 3+ messages in thread
From: Oliver Kiddle @ 2003-04-18 13:17 UTC (permalink / raw)
To: Zsh hackers list
On 14 Apr, Peter wrote:
> I have spent hours and hours rewriting Doc/Zsh/compsys.yo; unfortunately
I have now read through your changes and have a few comments. There is
also a patch below for some things which I have fixed myself. I worked
out the point of $compcontext so have added a bit about that and used
it to make zcalc complete in math context.
I'm not sure the warning added at the end of the old-matches style
description is necessary. If anyone tries to use it and _all_matches
with their main list of completers, they'll soon see the problem. The
style is mainly useful where _all_matches is used as a separate
(_generic based) widget.
For _arguments, there seems to now be no documentation for the option
descriptions that appear in square brackets.
Your description of _argument's return code is also dodgy. This I have
corrected but you may be able to improve my wording. Entering a state
does not imply a non zero return code (consider:
_arguments '-a[a]::val:->val' '*:other:(one two)' after -a
The old documentation also seemed to be implying that setting $context,
$line and $opt_args was dependant on using -R.
> Since nothing serious has cropped up I hope to finish this and release
> 4.1.1 soon after my return. (I realise this is not the traditional way
> round.)
It depends on what you regard as serious but the patch for compiling on
recent Cygwin has not, I think gone in but I don't have access to
cygwin to test. The _arguments seg fault might rate as serious. Also,
someone has recently posted about a bug with pwd and metafy() to the
sourceforge tracker which probably needs looking at.
Oliver
Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.165
diff -u -r1.165 compsys.yo
--- Doc/Zsh/compsys.yo 14 Apr 2003 18:10:39 -0000 1.165
+++ Doc/Zsh/compsys.yo 18 Apr 2003 13:02:54 -0000
@@ -177,7 +177,7 @@
If the tt(#compdef) line contains one of the options tt(-p) or tt(-P),
the words following are taken to be patterns. The function will be
-called when completion is attempt for a command or context that matches
+called when completion is attempted for a command or context that matches
one of the patterns. The options tt(-p) and tt(-P) are used to specify
patterns to be tried before or after other completions respectively.
Hence tt(-P) may be used to specify default actions.
@@ -206,7 +206,7 @@
)
item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
This is similar to tt(-k) except that only one var(key-sequences)
-argument may be given for each var(widget-name) var(style) parir.
+argument may be given for each var(widget-name) var(style) pair.
However, the entire set of three arguments may be repeated with a
different set of arguments. Note in particular that the
var(widget-name) must be distinct in each set. If it does not begin with
@@ -263,7 +263,7 @@
)
kindex(-command-, completion context)
item(tt(-command-))(
-A word In command position
+A word in command position
)
kindex(-condition-, completion context)
item(tt(-condition-))(
@@ -317,13 +317,13 @@
Default implementations are supplied for each of these
contexts. In most cases the context tt(-)var(context)tt(-) is
-implemented by the function tt(_)var(context), for example the context
-`tt(-tilde-)' and the function `tt(_tilde)').
+implemented by a corresponding function tt(_)var(context), for example
+the context `tt(-tilde-)' and the function `tt(_tilde)').
The contexts tt(-redirect-) and tt(-value-) allow extra context-specific
information. (Internally, this is handled by the functions for each
context calling the function tt(_dispatch).) The extra
-information is added separate by commas.
+information is added separated by commas.
For the tt(-redirect-) context, the extra information is in the form
`tt(-redirect-,)var(op)tt(,)var(command)', where var(op) is the
@@ -334,7 +334,7 @@
For the tt(-value-) context, the form is
`tt(-value-,)var(name)tt(,)var(command)', where var(name) is the name of
the parameter. In the case of elements of an associative array, for
-example `tt(assoc=LPAR()key <TAB>)', var(name) is eexpanded to
+example `tt(assoc=LPAR()key <TAB>)', var(name) is expanded to
`var(name)tt(-)var(key)'. In certain special contexts, such as
completing after `tt(make CFLAGS=)', the var(command) part gives the
name of the command, here tt(make); otherwise it is empty.
@@ -530,7 +530,7 @@
example(tt(:completion::complete:dvips:option-o-1:files))
-says that normal completion was attempted as the first arguement to the
+says that normal completion was attempted as the first argument to the
option tt(-o) of the command tt(dvips):
example(tt(dvips -o ...))
@@ -544,7 +544,7 @@
Usually completion will be tried by 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 limited to the list of given
+tt(tag-order) style. Completion is then restricted to the list of given
tags in the given order.
The tt(_complete_help) bindable command shows all the contexts and tags
@@ -610,7 +610,7 @@
uses the value `tt(_complete)' for the tt(completer) style in most
contexts, but the value `tt(_complete _approximate)' when the first word
-on the command line is `tt(cvs)'. This is probably more conviently done
+on the command line is `tt(cvs)'. This is probably more conveniently done
by specifying the style for two different contexts. This form can be
slow and should be avoided for commonly examined styles such
as tt(menu) and tt(list-rows-first).
@@ -1104,13 +1104,12 @@
)
kindex(call-command, completion style)
item(tt(call-command))(
-Currently this is only used by the function completing tt(make)
-targets. If it is set to `true' and the installed version of the
-tt(make) command allows it, tt(make) is called in such a way as to
-generate all possible targets. The default value of this style is `false'
-since calling tt(make) can potentially take a very long time and in
-some cases may even cause actions from the makefile be executed
-despite the options passed to tt(make).
+This style is used in the function for commands such as tt(make) and
+tt(ant) where calling the command directly to generate matches suffers
+problems such as being slow or, as in the case of tt(make) can
+potentially causes actions in the makefile to be executed. If it is set
+to `true' the command is called to generate matches. The default value
+of this style is `false'.
)
kindex(command, completion style)
item(tt(command))(
@@ -1232,13 +1231,13 @@
kindex(fake, completion style)
item(tt(fake))(
This style may be set for any completion context. It
-specifies additional strings that may always be completed in that
+specifies additional strings that will always be completed in that
context. The form of each string is `var(value)tt(:)var(description)';
the colon and description may be omitted, but any literal colons in
var(value) must be quoted with a backslash. Any var(description)
provided is shown alongside the value in completion listings.
-It is important to use a sufficiently restricted context when specifying
+It is important to use a sufficiently restrictive context when specifying
fake strings. Note that the styles tt(fake-files) and tt(fake-parameters)
provide additional features when completing files or parameters.
)
@@ -1282,7 +1281,7 @@
such specifications separated by spaces.
The var(pattern) is a pattern that is to be used to generate filenames.
-Any occurence of the sequence `tt(%p)' is replaced by any pattern(s)
+Any occurrence of the sequence `tt(%p)' is replaced by any pattern(s)
passed by the function calling tt(_files). Colons in the pattern must
be preceded by a backslash to make them distinguishable from the colon
before the var(tag). If more than one pattern is needed, the patterns
@@ -1436,8 +1435,8 @@
)
kindex(group-order, completion style)
item(tt(group-order))(
-This style is additional the tt(group-name) style to put the groups
-defined by that style into order for display (compare tt(tag-order),
+This style is additional to the tt(group-name) style to specify the
+order for display of the groups defined by that style (compare tt(tag-order),
which determines which completions appear at all). The groups named
are shown in the given order; any other groups
are shown in the order defined by the completion function.
@@ -1535,7 +1534,7 @@
enditem()
Excluded values act in a similar fashion to values of the
-tt(ignored-patterns) style, so they can be restored to consideratoin by
+tt(ignored-patterns) style, so they can be restored to consideration by
the tt(_ignored) completer.
)
kindex(ignored-patterns, completion style)
@@ -1567,10 +1566,10 @@
immediately to a set of possible IDs, and menu completion will be started
to cycle through them.
-If the value of the style is `tt(single)'
+If the value of the style is `tt(single)',
the shell will wait until the user has typed enough to make the command
unique before converting the name to an ID; attempts at completion will
-be unsuccessul until that point. If the value is any other
+be unsuccessful until that point. If the value is any other
string, menu completion will be started when the string typed by the
user is longer than the common prefix to the corresponding IDs.
)
@@ -1597,9 +1596,9 @@
kindex(insert-unambiguous, completion style)
item(tt(insert-unambiguous))(
This is used by the tt(_match) and tt(_approximate) completers.
-These styles are often used with menu completion since the word typed
+These completers are often used with menu completion since the word typed
may bear little resemblance to the final completion.
-However, if this the style is `true', the completer will start menu
+However, if this style is `true', the completer will start menu
completion only if it could find no unambiguous initial string at
least as long as the original string typed by the user.
@@ -1666,7 +1665,7 @@
withe the `tt((group))' syntax allowed by the tt(ZLS_COLORS) and
tt(ZLS_COLOURS) parameters and simply using the tt(default) tag.
-It is possible to use any color specifications alrady set up for the GNU
+It is possible to use any color specifications already set up for the GNU
version of the tt(ls) command:
example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS})
@@ -1781,8 +1780,8 @@
)
kindex(matcher-list, completion style)
item(tt(matcher-list))(
-This style is a list of match specifications that are valid everywhere.
-Match specifications are described in
+This style can be set to a list of match specifications that are to
+be applied everywhere. Match specifications are described in
ifzman(the section `Matching Control' in zmanref(zshcompwid))\
ifnzman(noderef(Matching Control))\
.
@@ -1829,7 +1828,7 @@
Where multiple specifications are useful, note that the em(entire)
completion is done for each element of tt(matcher-list), which can
-quickly reduce the shell's performance. As a rough rule of thum,
+quickly reduce the shell's performance. As a rough rule of thumb,
one to three strings will give acceptable performance. On the other
hand, putting multiple space-separated values into the same string does
not have an appreciable impact on performance.
@@ -1892,9 +1891,9 @@
In the form `tt(yes=)var(num)', where `tt(yes)' may be any of the
true values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)'),
-menu completion will be turned on if there at least var(num) matches.
+menu completion will be turned on if there are at least var(num) matches.
In the form `tt(yes=long)', menu completion will be turned on
-if the list does not fit onto the screen. This does not activate menu
+if the list does not fit on the screen. This does not activate menu
completion if the widget normally only lists completions, but menu
completion can be activated in that case with the value `tt(yes=long-list)'
(Typically, the value `tt(select=long-list)' described later is more
@@ -1905,9 +1904,9 @@
The value of this widget also controls menu selection, as implemented by
the tt(zsh/complist) module. The following values may appear either
-alongside or instead of the values bbavoe.
+alongside or instead of the values above.
-If the value contains the string `tt(select)', menu selection (as
+If the value contains the string `tt(select)', menu selection
will be started unconditionally.
In the form `tt(select=)var(num)', menu selection will only be started if
@@ -1923,7 +1922,7 @@
only performs listing, use the value `tt(select=long-list)'.
To turn on menu completion or menu selection when a there are a certain
-number of matches em(or) the list of matches does not fit onto the
+number of matches em(or) the list of matches does not fit on the
screen, both of `tt(yes=)' and `tt(select=)' may be given twice, once
with a number and once with `tt(long)' or `tt(long-list)'.
@@ -1983,7 +1982,7 @@
item(tt(old-matches))(
This is used by the tt(_all_matches) completer to decide if an old
list of matches should be used if one exists. This is selected by one of
-the `true' values or to the string `tt(only)'. If
+the `true' values or by the string `tt(only)'. If
the value is `tt(only)', tt(_all_matches) will only use an old list
and won't have any effect on the list of matches currently being
generated.
@@ -2048,7 +2047,7 @@
)
kindex(ports, completion style)
item(tt(ports))(
-A a list of Internet service names (network ports) to complete. If this is
+A list of Internet service names (network ports) to complete. If this is
not set, service names are taken from the file `tt(/etc/services)'.
)
kindex(prefix-hidden, completion style)
@@ -2146,6 +2145,9 @@
added separately using tag names of the form `tt(manual.)var(X)',
where var(X) is the section number. When the tt(group-name) style is
also in effect, pages from different sections will appear separately.
+This style is also used similarly with the tt(words) style when
+completing words for the dict command. It allows words from different
+dictionary databases to be added separately.
The default for this style is `false'.
)
kindex(single-ignored, completion style)
@@ -2355,7 +2357,7 @@
example:
example(zstyle -e '*:-command-:*' tag-order '
- if [[ -n $PREFIX ]]; then
+ if [[ -n $PREFIX$SUFFIX ]]; then
reply=( )
else
reply=( - )
@@ -2626,13 +2628,15 @@
mentioned above as possible arguments to the tt(#compdef) tag.
Before trying to find a function for a specific context, tt(_complete)
-checks if the parameter `tt(compcontext)' is set. If it is set to an
-array, the elements are taken to be the possible matches which will be
-completed using the tag `tt(values)' and the description
-`tt(value)'. If it is set to an associative array, the keys are used
-as the possible completions and the values (if non-empty) are used as
-descriptions for the matches. If `tt(compcontext)' is set to a string
-containing colons, it should be of
+checks if the parameter `tt(compcontext)' is set. Setting
+`tt(compcontext)' allows the usual completion dispatching to be
+overridden which is useful in places such as a function that uses
+tt(vared) for input. If it is set to an array, the elements are taken
+to be the possible matches which will be completed using the tag
+`tt(values)' and the description `tt(value)'. If it is set to an
+associative array, the keys are used as the possible completions and
+the values (if non-empty) are used as descriptions for the matches. If
+`tt(compcontext)' is set to a string containing colons, it should be of
the form `var(tag)tt(:)var(descr)tt(:)var(action)'. In this case the
var(tag) and var(descr) give the tag and description to use and the
var(action) indicates what should be completed in one of the forms
@@ -3077,7 +3081,7 @@
different name for the argument context field.
)
findex(_arguments)
-item(tt(_arguments) [ tt(-ACS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)(
+item(tt(_arguments) [ tt(-swWACRS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)(
This function can be used to give a complete specification for
completion for a command whose arguments follow standard UNIX option and
argument conventions. The following forms specify individual sets of
@@ -3088,7 +3092,7 @@
xitem(var(n)tt(:)var(message)tt(:)var(action))
item(var(n)tt(::)var(message)tt(:)var(action))(
This describes the var(n)'th normal argument. The var(message) will be
-printed above the matches generated and the var(action) indiciates what can
+printed above the matches generated and the var(action) indicates what can
be completed in this position (see below). If there are two colons
before the var(message) the argument is optional. If the
var(message) contains only white space, nothing will be printed above
@@ -3241,8 +3245,9 @@
must be preceded by a backslash, `tt(\:)'.
Each of the forms above may be preceded by a list in parentheses
-of option names and argument numbers. If the given option is completed,
-the options and arguments indicated will not be offered. For example,
+of option names and argument numbers. If the given option is on
+the command line, the options and arguments indicated in parentheses
+will not be offered. For example,
`tt((-two -three 1)-one:...)' completes the option `tt(-one)'; if this
appears on the command line, the options tt(-two) and tt(-three) and the
first ordinary argument will not be completed after it.
@@ -3296,7 +3301,7 @@
example(tt(:foo:LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR()))
The matches will be listed together with their descriptions if the
-tt(description) style is set in the context with the tt(values) tag.
+tt(description) style is set with the tt(values) tag in the context.
)
item(tt(->)var(string))(
vindex(context, use of)
@@ -3308,20 +3313,22 @@
for generating completions. For example, functions that implement a state
machine can use this type of action.
-If tt(_arguments) handles the completion by itself, it returns status
-zero. Otherwise, it returns a non-zero status; if this was because it
-encountered a `tt(->)var(string)' action, it will strip all leading and
-trailing whitespace from var(string) and set the array tt(state) to the set
-of all var(strings)s for which the action is to be performed. Hence
-tt($state) must be tested to determine whether actions need to be handled.
-
-If the tt(-R) option is given to tt(_arguments), the function will instead
-return a status of 300 to indicate that tt($state) is valid. In this case
-it also sets the global parameters `tt(context)', `tt(line)' and
-`tt(opt_args)' as described below, and does not reset any changes made to
-the special parameters such as tt(PREFIX) and tt(words). This gives the
-calling function the choice of resetting these parameters or propagating
-changes in them.
+Where tt(_arguments) encounters a `tt(->)var(string)', it will strip
+all leading and trailing whitespace from var(string) and set the array
+tt(state) to the set of all var(strings)s for which an action is to be
+performed.
+
+By default and in common with all other well behaved completion
+functions, _arguments returns zero if it was able to add matches and
+non-zero otherwise. However, if the tt(-R) option is given,
+tt(_arguments) will instead return a status of 300 to indicate that
+tt($state) is to be handled.
+
+In addition to tt($state), tt(_arguments) also sets the global
+parameters `tt(context)', `tt(line)' and `tt(opt_args)' as described
+below, and does not reset any changes made to the special parameters
+such as tt(PREFIX) and tt(words). This gives the calling function the
+choice of resetting these parameters or propagating changes in them.
A function calling tt(_arguments) with at least
one action containing a `tt(->)var(string)' therefore must declare
@@ -3473,12 +3480,16 @@
The option tt(-C) tells tt(_arguments) to modify
the tt(curcontext) parameter for an action of the form
`tt(->)var(state)'. This is the standard parameter used to keep track of
-the current context. Here it should be made local to the calling function
+the current context. Here it (and not the tt(context) array) should be
+made local to the calling function
to avoid passing back the modified value and should be initialised to the
current value at the start of the function:
example(local curcontext="$curcontext")
+This is useful where it is not possible for multiple states to be valid
+together.
+
The option `tt(--)' allows tt(_arguments) to work out the names of long
options that support the `tt(-)tt(-help)' option which is standard in many
GNU commands. The command word is called with the argument
@@ -3655,7 +3666,7 @@
)
findex(_describe)
item(tt(_describe) [ tt(-o) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
-This option associates completions with descriptions.
+This function associates completions with descriptions.
Multiple groups separated by tt(-)tt(-) can be supplied, potentially with
different completion options var(opts).
Index: Functions/Misc/zcalc
===================================================================
RCS file: /cvsroot/zsh/zsh/Functions/Misc/zcalc,v
retrieving revision 1.8
diff -u -r1.8 zcalc
--- Functions/Misc/zcalc 9 Jan 2002 11:58:05 -0000 1.8
+++ Functions/Misc/zcalc 18 Apr 2003 13:02:54 -0000
@@ -106,6 +106,7 @@
trap zcalc_restore HUP INT QUIT EXIT
local line ans base defbase forms match mbegin mend psvar optlist opt arg
+local compcontext="-math-"
integer num outdigits outform=1
forms=( '%2$g' '%.*g' '%.*f' '%.*E' )
^ permalink raw reply [flat|nested] 3+ messages in thread