zsh-workers
 help / color / mirror / code / Atom feed
* How about separating "_arguments --" into a new function?
@ 2021-10-08 16:12 Jun. T
  2021-10-12 16:04 ` Daniel Shahaf
  0 siblings, 1 reply; 8+ messages in thread
From: Jun. T @ 2021-10-08 16:12 UTC (permalink / raw)
  To: zsh-workers

Not sure this was discussed before or not:

_gnu_generic works rather well for basenc, and '_arguments --'
caches the option specs generated from the --help text in a variable
_args_cache_basenc. So I created _basenc by

% compdef _gnu_generic basenc
% basenc <TAB>
% echo ${(F)${(qqq)_args_cache_basenc}} > _basenc
and edited _basenc (to add option groups etc.).

If we separate the part of _arguments that generates the option specs
(around lines 36 - 323) into an auto-loadable function, say help2specs,
then we will be able to do something like

% help2specs cmd > _cmd
(and edit _cmd to improve it)

If this seems useful I'll work on it.
Or just using $_args_cache_cmd is enough?

If _arguments is separated into two, tracing the history by 'git blame'
etc. would be a little bit tedious.



^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-08 16:12 How about separating "_arguments --" into a new function? Jun. T
@ 2021-10-12 16:04 ` Daniel Shahaf
  2021-10-14 10:58   ` Jun T
  0 siblings, 1 reply; 8+ messages in thread
From: Daniel Shahaf @ 2021-10-12 16:04 UTC (permalink / raw)
  To: Jun. T; +Cc: zsh-workers

Jun. T wrote on Sat, Oct 09, 2021 at 01:12:42 +0900:
> _gnu_generic works rather well for basenc, and '_arguments --'
> caches the option specs generated from the --help text in a variable
> _args_cache_basenc. So I created _basenc by
> 
> % compdef _gnu_generic basenc
> % basenc <TAB>
> % echo ${(F)${(qqq)_args_cache_basenc}} > _basenc
> and edited _basenc (to add option groups etc.).
> 

Nice :)

> If we separate the part of _arguments that generates the option specs
> (around lines 36 - 323) into an auto-loadable function, say help2specs,
> then we will be able to do something like
> 
> % help2specs cmd > _cmd
> (and edit _cmd to improve it)
> 
> If this seems useful I'll work on it.

A tool that takes some command's --help output and produces a skeleton
completion function would certainly be nice for people writing
completion functions.  However, creating a new completion function isn't
a common task; I suspect it's more common to update an existing
completion function with more custom logic or with new options.  So,
perhaps the tool could be designed with an eye towards updating existing
completion functions?  For instance, perhaps the tool could inspect the
existing _cmd file and omit from the output any lines where the
--foo[lorem ipsum] part already appears in the file?

Perhaps make the tool a filter, in order to support, say, «ssh foo
'lorem --help' | help2specs»?

The docs of _arguments say one should declare «local context state
state_descr line; typeset -A opt_args» whenever one uses -> actions.
Some tool (not necessarily the same tool as the proposed help2specs
tool) that prefills those lines would be nice to have: that would
prevent people from forgetting or overlooking those declarations, and
having them prefilled would be easier than copying them from the manual.

> Or just using $_args_cache_cmd is enough?

If it is enough, then it should be made more discoverable.

> If _arguments is separated into two, tracing the history by 'git blame'
> etc. would be a little bit tedious.

Well, yes, but on the other hand, _arguments would then be "doing one
thing and doing it well", and its documentation would be clearer.  And
_arguments' own source code might be clearer too.  (I don't have
a strong opinion; I'm just playing Devil's advocate.)

Of course, if _arguments does get splitted, it may then be needed to
update __arguments.

Cheers,

Daniel


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-12 16:04 ` Daniel Shahaf
@ 2021-10-14 10:58   ` Jun T
  2021-10-17 16:49     ` Daniel Shahaf
  0 siblings, 1 reply; 8+ messages in thread
From: Jun T @ 2021-10-14 10:58 UTC (permalink / raw)
  To: zsh-workers


> 2021/10/13 1:04, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> 
> perhaps the tool could be designed with an eye towards updating existing
> completion functions?  For instance, perhaps the tool could inspect the
> existing _cmd file and omit from the output any lines where the
> --foo[lorem ipsum] part already appears in the file?

Such a tool is useful, of cause, but analyzing the existing _cmd is
would be quite complicated, I guess.

> Perhaps make the tool a filter, in order to support, say, «ssh foo
> 'lorem --help' | help2specs»?

Of course it must read the help text from stdin (if cmd is not given
as argument) since in _arguments 'cmd --help' is run by _call_program
and the output is passed to help2specs via pipe.


>> Or just using $_args_cache_cmd is enough?
> 
> If it is enough, then it should be made more discoverable.

I guess it is enough since no one is requesting to separate _arguments.
How about the following?


diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 89b918d60..c00270f3d 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -4237,6 +4237,17 @@ as `tt(-)tt(-enable-foo)', but the script also accepts the negated form
 
 example(_arguments -- -s "LPAR()(#s)--enable- --disable-RPAR()")
 
+The list of var(spec)s derived from the help text is saved in an array
+parameter `tt(_arg_cache_)var(cmd)' where `var(cmd)' is the name of the
+command.  If `tt(_arguments -)tt(-)' (or tt(_gnu_generic)) does not work
+satisfactorily for a commnd `tt(foo)', you can save the specs in a file
+`tt(_foo)' by
+
+example(echo ${(qqq)_arg_chache_foo} > _foo)
+
+and use it as a draft of your own completion function for the command
+`tt(foo)'.
+
 em(Miscellaneous notes)
 
 Finally, note that tt(_arguments) generally expects to be the primary





^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-14 10:58   ` Jun T
@ 2021-10-17 16:49     ` Daniel Shahaf
  2021-10-18  4:40       ` Jun T
  0 siblings, 1 reply; 8+ messages in thread
From: Daniel Shahaf @ 2021-10-17 16:49 UTC (permalink / raw)
  To: Jun T; +Cc: zsh-workers

Jun T wrote on Thu, Oct 14, 2021 at 19:58:17 +0900:
> 2021/10/13 1:04, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> > perhaps the tool could be designed with an eye towards updating existing
> > completion functions?  For instance, perhaps the tool could inspect the
> > existing _cmd file and omit from the output any lines where the
> > --foo[lorem ipsum] part already appears in the file?
> 
> Such a tool is useful, of cause, but analyzing the existing _cmd is
> would be quite complicated, I guess.
> 

Well, the tool doesn't need to update the file by itself.  Even if it
simply spat options grouped into three categories — "definitely in the
file", "definitely not in the file", and everything else — that'd still
save most of the work in updating the file.

> >> Or just using $_args_cache_cmd is enough?
> > 
> > If it is enough, then it should be made more discoverable.
> 
> I guess it is enough since no one is requesting to separate _arguments.
> How about the following?
> 

Are we happy with documenting it as a first-class feature, i.e., one
that we would be expected to continue supporting?  Or would we rather
document this as a "we may change this in the future" thing?

Flow-wise, the mention of _gnu_generic seems to me to be oddly placed:
it's right between mentioning the variable's existence and use.
I suppose I'm suggesting to reorder the information being added.  Not
a blocker, of course; just nice to have.

Typos: "commnd", "chache".

Would prefer «print -r --» in case of backslashes, or perhaps just
«typeset -p».

Cheers,

Daniel


> diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
> index 89b918d60..c00270f3d 100644
> --- a/Doc/Zsh/compsys.yo
> +++ b/Doc/Zsh/compsys.yo
> @@ -4237,6 +4237,17 @@ as `tt(-)tt(-enable-foo)', but the script also accepts the negated form
>  
>  example(_arguments -- -s "LPAR()(#s)--enable- --disable-RPAR()")
>  
> +The list of var(spec)s derived from the help text is saved in an array
> +parameter `tt(_arg_cache_)var(cmd)' where `var(cmd)' is the name of the
> +command.  If `tt(_arguments -)tt(-)' (or tt(_gnu_generic)) does not work
> +satisfactorily for a commnd `tt(foo)', you can save the specs in a file
> +`tt(_foo)' by
> +
> +example(echo ${(qqq)_arg_chache_foo} > _foo)
> +
> +and use it as a draft of your own completion function for the command
> +`tt(foo)'.
> +
>  em(Miscellaneous notes)
>  
>  Finally, note that tt(_arguments) generally expects to be the primary
> 
> 
> 
> 


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-17 16:49     ` Daniel Shahaf
@ 2021-10-18  4:40       ` Jun T
  2021-10-21 14:15         ` Daniel Shahaf
  0 siblings, 1 reply; 8+ messages in thread
From: Jun T @ 2021-10-18  4:40 UTC (permalink / raw)
  To: zsh-workers


> 2021/10/18 1:49, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> 
>>>> Or just using $_args_cache_cmd is enough?
>>> 
>>> If it is enough, then it should be made more discoverable.
>> 
>> I guess it is enough since no one is requesting to separate _arguments.
>> How about the following?
>> 
> 
> Are we happy with documenting it as a first-class feature, i.e., one
> that we would be expected to continue supporting?  Or would we rather
> document this as a "we may change this in the future" thing?

I personally feel we don't need to document it (it's a kind of hidden
feature). But you said it should be more discoverable. So where should
it be documented? At the end ofEtc/completion-style-guide? Or as a
comment at the top of _arguments?


> Typos: "commnd", "chache".


Thanks.

> Would prefer «print -r --» in case of backslashes,

I think (qqq) takes care of backslashes etc., but will use print -r
if it looks safer.



^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-18  4:40       ` Jun T
@ 2021-10-21 14:15         ` Daniel Shahaf
  2021-10-24  9:53           ` Jun. T
  0 siblings, 1 reply; 8+ messages in thread
From: Daniel Shahaf @ 2021-10-21 14:15 UTC (permalink / raw)
  To: Jun T; +Cc: zsh-workers

Jun T wrote on Mon, Oct 18, 2021 at 13:40:09 +0900:
> 
> > 2021/10/18 1:49, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> > 
> >>>> Or just using $_args_cache_cmd is enough?
> >>> 
> >>> If it is enough, then it should be made more discoverable.
> >> 
> >> I guess it is enough since no one is requesting to separate _arguments.
> >> How about the following?
> >> 
> > 
> > Are we happy with documenting it as a first-class feature, i.e., one
> > that we would be expected to continue supporting?  Or would we rather
> > document this as a "we may change this in the future" thing?
> 
> I personally feel we don't need to document it (it's a kind of hidden
> feature). But you said it should be more discoverable. So where should
> it be documented? At the end ofEtc/completion-style-guide? Or as a
> comment at the top of _arguments?

Happy to leave the decision to you.  Either of these options sounds good
to me.

> > Would prefer «print -r --» in case of backslashes,
> 
> I think (qqq) takes care of backslashes etc., but will use print -r
> if it looks safer.

It's not just "looks safer"; it's a matter of correctness.  The content
of ${_args_cache_foo} need to be escaped once for their transit through
lex.c when _foo will be read by compinit, and once against «echo»'s
treatment of backslashes.  Thus, «print -r --» should be used _in
addition_ to ${(qqq)}, not instead of it.

Cheers,

Daniel


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-21 14:15         ` Daniel Shahaf
@ 2021-10-24  9:53           ` Jun. T
  2021-10-25 19:46             ` Daniel Shahaf
  0 siblings, 1 reply; 8+ messages in thread
From: Jun. T @ 2021-10-24  9:53 UTC (permalink / raw)
  To: zsh-workers


> 2021/10/21 23:15, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:

> The content
> of ${_args_cache_foo} need to be escaped once for their transit through
> lex.c when _foo will be read by compinit, and once against «echo»'s
> treatment of backslashes.

I know.
But if the output of 'cmd --help' already has '\', for example
    --escape     replace $ by \$
then 'print -r' does not work either (if the output of 'print -r' is used
as a spec for _arguments as is).
Using (qq) (instead of (qqq)) may or may not help, but then users must
unset RC_QUOTE (before calling print/echo).
But anyway $_args_cache_cmd is just a 'draft' of _cmd, and users
must edit it manually (usually lots of editing are required).

I'll push the following soon, so feel free to modify/improve it.


diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide
index 62e6a2787..4fa0040a5 100644
--- a/Etc/completion-style-guide
+++ b/Etc/completion-style-guide
@@ -570,3 +570,13 @@ Misc. remarks
       data derived from another command's output to the helper. Consider
       using some variation of the `q` expansion flag to deal with this:
       `_call_program vals $words[1] ${(q-)myfile}'
+10) If you are going to create a new completion function '_cmd' for a
+    command 'cmd', and if the 'cmd' supports the --help option, then you
+    may try
+      compdef _gnu_generic cmd
+      cmd -<TAB>
+    _gnu_generic may not work sufficiently well for 'cmd', but the specs
+    for _arguments generated from the help text are cached in a variable
+    '_args_cache_cmd', and you can save them in a file '_cmd' by
+      print -r -- ${(F)${(@qqq)_args_cache_cmd}} > _cmd
+    and use the file as a draft of the new completion function.








^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: How about separating "_arguments --" into a new function?
  2021-10-24  9:53           ` Jun. T
@ 2021-10-25 19:46             ` Daniel Shahaf
  0 siblings, 0 replies; 8+ messages in thread
From: Daniel Shahaf @ 2021-10-25 19:46 UTC (permalink / raw)
  To: Jun. T; +Cc: zsh-workers

Jun. T wrote on Sun, Oct 24, 2021 at 18:53:52 +0900:
> 
> > 2021/10/21 23:15, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> 
> > The content
> > of ${_args_cache_foo} need to be escaped once for their transit through
> > lex.c when _foo will be read by compinit, and once against «echo»'s
> > treatment of backslashes.
> 
> I know.
> But if the output of 'cmd --help' already has '\', for example
>     --escape     replace $ by \$
> then 'print -r' does not work either (if the output of 'print -r' is used
> as a spec for _arguments as is).

The output of `print -r` should not be used as an _arguments spec as-is;
backslashes, colons, and square brackets need to be escaped.

> Using (qq) (instead of (qqq)) may or may not help, but then users must
> unset RC_QUOTE (before calling print/echo).
> But anyway $_args_cache_cmd is just a 'draft' of _cmd, and users
> must edit it manually (usually lots of editing are required).
> 
> I'll push the following soon, so feel free to modify/improve it.
> 

LGTM.

Thanks,

Daniel


^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2021-10-25 19:47 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-08 16:12 How about separating "_arguments --" into a new function? Jun. T
2021-10-12 16:04 ` Daniel Shahaf
2021-10-14 10:58   ` Jun T
2021-10-17 16:49     ` Daniel Shahaf
2021-10-18  4:40       ` Jun T
2021-10-21 14:15         ` Daniel Shahaf
2021-10-24  9:53           ` Jun. T
2021-10-25 19:46             ` Daniel Shahaf

Code repositories for project(s) associated with this 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).