[PATCH 4/4] _normal: Add -P to reset precommands

[PATCH 4/4] _normal: Add -P to reset precommands

[Matthew Martin]

Add the ability to reset the precommands array to empty. Will be useful
for zsh -c and perhaps some other situations. Again the texi is
cargo-culted.

---
 Completion/Base/Core/_normal | 3 ++-
 Doc/Zsh/compsys.yo           | 9 +++++++--
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/Completion/Base/Core/_normal b/Completion/Base/Core/_normal
index 7732837ac..0d84eae87 100644
--- a/Completion/Base/Core/_normal
+++ b/Completion/Base/Core/_normal
@@ -3,8 +3,9 @@
 local _comp_command1 _comp_command2 _comp_command precommand
 local -A opts
 
-zparseopts -A opts -D - p+:-=precommand s
+zparseopts -A opts -D - P p+:-=precommand s
 (( $+opts[-s] )) || _compskip=
+(( $+opts[-P] )) && precommands=()
 (( $#precommand )) && precommands+=(${precommand#-p})
 
 # Check for a history reference to complete modifiers.
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index af47f1fdb..f3f32db1e 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -4658,7 +4658,7 @@ fi
 return ret)
 )
 findex(_normal)
-xitem(tt(_normal) [ tt(-p) var(precommand) ])(
+xitem(tt(_normal) [ tt(-P) | tt(-p) var(precommand) ])(
 This is the standard function called to handle completion outside
 any special tt(-)var(context)tt(-).  It is called both to complete the command
 word and also the arguments for a command.  In the second case,
@@ -4674,9 +4674,14 @@ then calls `tt(_normal) tt(-p) tt($service)'.  The effect is that
 `tt(nohup) var(cmd ...)' is treated in the same way as `var(cmd ...)'.
 
 startitem()
+item(tt(-P))(
+Reset the list of precommands. Should be used if completing a command
+line which allows internal commands (e.g. builtins and functions)
+regardless of prior precommands (e.g. `tt(zsh) tt(-c)').
+)
 item(tt(-p) var(precommand))(
 Append var(precommand) to the list of precommands. Should be used in
-nearly all cases.
+nearly all cases in which tt(-P) is not applicable.
 )
 enditem()
 
-- 
2.21.0

Re: [PATCH 4/4] _normal: Add -P to reset precommands

[dana]

On 1 Apr 2019, at 22:13, Matthew Martin <phy1729@gmail.com> wrote:
>Add the ability to reset the precommands array to empty. Will be useful
>for zsh -c and perhaps some other situations. Again the texi is
>cargo-culted.

I like it. The documentation looks mostly OK to me, but:

>+xitem(tt(_normal) [ tt(-P) | tt(-p) var(precommand) ])(

I know it wasn't your fault, but i think this should be item()(), not
xitem()(). I don't fully understand the distinction, but xitem() seems to be
used only when there are multiple headings (describing different ways to use
the command); left here, it breaks the man-page formatting for the paragraphs
you added.

> completes after pre-command specifiers such as tt(nohup), removes the

Also not your fault, but this is the only place in the documentation
(including your changes) where 'pre-command' is hyphenated. Maybe fix that?

>+Append var(precommand) to the list of precommands. Should be used in
>+Reset the list of precommands. Should be used if completing a command

This clipped style (ommitting the subject of the sentence) isn't used anywhere
else in the documentation that i can see.

>+  '*::arguments: _normal -p $service'

The 'arguments' here is superfluous.

idk if you planned to do another pass, but i noticed several straight-forward
examples of other functions that could make use of `_normal -p`: _env,
_fakeroot, _nice, _stdbuf, _timeout, &c. _env is kind of a special case,
though, in that it (ab)uses _normal's standard behaviour to provide
variable-assignment completion too. Maybe there's a general solution for that

dana

Re: [PATCH 4/4] _normal: Add -P to reset precommands

[Daniel Shahaf]

dana wrote on Tue, 02 Apr 2019 17:47 +00:00:
> On 1 Apr 2019, at 22:13, Matthew Martin <phy1729@gmail.com> wrote:
> >+xitem(tt(_normal) [ tt(-P) | tt(-p) var(precommand) ])(
> 
> I know it wasn't your fault, but i think this should be item()(), not
> xitem()(). I don't fully understand the distinction, but xitem() seems to be
> used only when there are multiple headings (describing different ways to use
> the command); left here, it breaks the man-page formatting for the paragraphs
> you added.

There should be zero or more xitem() [with one pair of parens each]
followed by exactly one item()() [with two pairs of parens, the second
one being multiline).

Since I'm replying: I don't understand why `tt(foo) tt(bar) tt(baz)` is
spelled with three macros; I think`tt(foo bar baz)` would be fine… but
of course this is minor.

Cheers,

Daniel

Re: [PATCH 4/4] _normal: Add -P to reset precommands

[Matthew Martin]

On Tue, Apr 02, 2019 at 04:27:41PM -0400, Daniel Shahaf wrote:
> dana wrote on Tue, 02 Apr 2019 17:47 +00:00:
> > On 1 Apr 2019, at 22:13, Matthew Martin <phy1729@gmail.com> wrote:
> > >+xitem(tt(_normal) [ tt(-P) | tt(-p) var(precommand) ])(
> > 
> > I know it wasn't your fault, but i think this should be item()(), not
> > xitem()(). I don't fully understand the distinction, but xitem() seems to be
> > used only when there are multiple headings (describing different ways to use
> > the command); left here, it breaks the man-page formatting for the paragraphs
> > you added.
> 
> There should be zero or more xitem() [with one pair of parens each]
> followed by exactly one item()() [with two pairs of parens, the second
> one being multiline).

Thanks for the explanation.

> Since I'm replying: I don't understand why `tt(foo) tt(bar) tt(baz)` is
> spelled with three macros; I think`tt(foo bar baz)` would be fine… but
> of course this is minor.

Because _multi_parts just above does something similar (although it's
alone in this file using that style). Fixed.

> > > completes after pre-command specifiers such as tt(nohup), removes the
> > 
> > Also not your fault, but this is the only place in the documentation
> > (including your changes) where 'pre-command' is hyphenated. Maybe fix that?

Fixed.

> > >+Append var(precommand) to the list of precommands. Should be used in
> > >+Reset the list of precommands. Should be used if completing a command
> > 
> > This clipped style (ommitting the subject of the sentence) isn't used anywhere
> > else in the documentation that i can see.

It's used with the other helper functions that describe their options in
a list (cf. _completers, _dir_sep, _email_addresses, although only -f
for _path_files). I think the imperative generally results in more
concise documentation for flags ("specifies that" doesn't add anything);
but if the declarative is preferred, I can change the patch to match.

> > >+  '*::arguments: _normal -p $service'
> > 
> > The 'arguments' here is superfluous.

Fixed.

> > idk if you planned to do another pass, but i noticed several straight-forward
> > examples of other functions that could make use of `_normal -p`: _env,

I'm planning to review uses of _normal next. This round was just
cleaning up completers that already used precommands.