From: Junio C Hamano <hidden> Date: 2016-06-15 22:53:36
Felipe Contreras [off-list ref] writes:
On Mon, Apr 16, 2012 at 12:37 AM, Jonathan Nieder [off-list ref] wrote:
quoted
The completion script has so far stuck to a limited namespace:
_git_* (completion functions)
__git_* (everything else, including public interfaces like __git_ps1)
A name like __git_complete should work, presumably.
Perhaps it's time to avoid the __ prefix for public interfaces;
otherwise how would people know they are public?
We could do the same as __git_ps1, no? People know to use it already;
they know it is public.
I am OK with introducing git_ps1 while keeping __git_ps1 as an equivalent
and declare that git_$anything will be the surface interface for end users
to *use* the machinery we provide, though. Then git_complete could be
introduced without __git_complete equivalent. Probably _git_$name has to
stay an implementation detail (i.e. the users can use it but it is their
responsibility to update their using script when the implementation
changes).
From: Jonathan Nieder <hidden> Date: 2016-06-15 22:53:36
Junio C Hamano wrote:
I am OK with introducing git_ps1 while keeping __git_ps1 as an equivalent
and declare that git_$anything will be the surface interface for end users
to *use* the machinery we provide, though.
The problem is that completion scripts are often included implicitly
in .profile through the bash completion machinery. Users do not have
to explicitly ask for them, so there is no reason for users to expect
that the function name "more_cowbell" is dangerous to use in .profile
because some day the completion script for the "more" command will
start using it.
Because of these considerations, the convention is that every
identifier provided by a completion script, including public ones,
starts with an underscore.
From: Felipe Contreras <hidden> Date: 2016-06-15 22:53:36
On Mon, Apr 16, 2012 at 7:07 PM, Jonathan Nieder [off-list ref] wrote:
Junio C Hamano wrote:
quoted
I am OK with introducing git_ps1 while keeping __git_ps1 as an equivalent
and declare that git_$anything will be the surface interface for end users
to *use* the machinery we provide, though.
The problem is that completion scripts are often included implicitly
in .profile through the bash completion machinery. Users do not have
to explicitly ask for them, so there is no reason for users to expect
that the function name "more_cowbell" is dangerous to use in .profile
because some day the completion script for the "more" command will
start using it.
Sure, that's why we would have _git_cowbell instead, so for *most* of
functions the user would have no trouble, it would *only* be
git_completion the one without prefix, and I think the name is quite
safe. There's quite likely few, probably nobody, actually using that
function name in their profiles.
Also, the script would now be loaded only *after*, the user types 'git
<TAB>'. And there's already a bunch of functions that are already
exported by just having bash completion: have(), quote(), dequote(),
quote_readline(). And there's at least one script that uses a function
without a prefix: ri_get_methods()
I would like to see a completion script that actually has a function
supposed to be exported and that still uses the _ prefix anyway.
Cheers.
--
Felipe Contreras
From: Jonathan Nieder <hidden> Date: 2016-06-15 22:53:36
Felipe Contreras wrote:
On Mon, Apr 16, 2012 at 11:09 PM, Jonathan Nieder [off-list ref] wrote:
quoted
Felipe Contreras wrote:
quoted
quoted
I would like to see a completion script that actually has a function
supposed to be exported and that still uses the _ prefix anyway.
The /etc/bash_completion library itself exports lots and lots of
functions with a _ prefix.
We are not making a bash_completion library; I mean a bash completion
script (other than the library).
Ok. If you refuse to put two and two together, then I will (as usual
when this happens) just be a little passive aggressive and annoyed and
let you talk to other people.
Cheers,
Jonathan
From: Felipe Contreras <hidden> Date: 2016-06-15 22:53:36
On Mon, Apr 16, 2012 at 11:33 PM, Jonathan Nieder [off-list ref] wrote:
Felipe Contreras wrote:
quoted
On Mon, Apr 16, 2012 at 11:09 PM, Jonathan Nieder [off-list ref] wrote:
quoted
Felipe Contreras wrote:
quoted
quoted
quoted
I would like to see a completion script that actually has a function
supposed to be exported and that still uses the _ prefix anyway.
The /etc/bash_completion library itself exports lots and lots of
functions with a _ prefix.
We are not making a bash_completion library; I mean a bash completion
script (other than the library).
Ok. If you refuse to put two and two together, then I will (as usual
when this happens) just be a little passive aggressive and annoyed and
let you talk to other people.
Just to be clear; we are making a completion script for the 'git'
command, so if we are looking for guidance on what other 'foo' command
completion scripts do, the bash completion library itself is not good
guidance.
My gut feeling is that there's no completion script that exports
functions meant to be used directly by the user, so there's really no
guidance for this.
Now, even if you use the bash completion library, it still does export
functions without a prefix, so why take the ones with prefix as a
rule, and ignore the other ones? It seems like there's no real
guideline for what gets a prefix and what doesn't, even in the bash
completion library itself, which I don't think should be used a
guideline anyway.
The closest relative of 'git_complete' would be 'complete', both of
course are meant for public usage. I have not seen any other functions
that are similar.
Cheers.
--
Felipe Contreras
From: Jonathan Nieder <hidden> Date: 2016-06-15 22:53:36
(cc-ing the bash-completion-devel list)
Felipe Contreras wrote:
On Mon, Apr 16, 2012 at 11:46 PM, Jonathan Nieder [off-list ref] wrote:
quoted
Felipe Contreras wrote:
quoted
quoted
Now, even if you use the bash completion library, it still does export
functions without a prefix
Are you sure? "complete" is a bash builtin and has nothing to do with
the bash completion library except that the latter uses it.
I already provided examples:
have(), quote(), dequote(), quote_readline()
Ah, that's what you mean. Thanks for the pointers, and sorry to have
misunderstood.
There's a little oddity here. "have" is clearly an unwanted backward
compatibility feature:
# @deprecated should no longer be used; generally not needed with dynamically
# loaded completions, and _have is suitable for runtime use.
have()
[...]
unset -f have
unset have
But "quote", "dequote", and "quote_readline" do not get the same
treatment. Perhaps they are for backward compatibility, too, but are
so widely used that there is no hope of ever getting rid of them.
Hopefully this information helps clarify to what extent the leading
underscores in functions exposed by completion scripts are meant or
are not meant as a convention.
Jonathan
_______________________________________________
Bash-completion-devel mailing list
Bash-completion-devel@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/bash-completion-devel
From: Ville Skyttä <hidden> Date: 2016-06-15 22:53:38
On 2012-04-16 23:59, Jonathan Nieder wrote:
Hopefully this information helps clarify to what extent the leading
underscores in functions exposed by completion scripts are meant or
are not meant as a convention.
From: Felipe Contreras <hidden> Date: 2016-06-15 22:53:38
On Sat, Apr 21, 2012 at 10:20 AM, Ville Skyttä [off-list ref] wrote:
On 2012-04-16 23:59, Jonathan Nieder wrote:
quoted
Hopefully this information helps clarify to what extent the leading
underscores in functions exposed by completion scripts are meant or
are not meant as a convention.
Thank you for pointing this out. This means I was correct; there
was/is no convention for public APIs.
According to that thread, the closest there is to a convention would
be to name it _GIT_complete. That would certainly avoid conflicts with
any current namespace, so I feel it's much better than __git_complete.
Still, I don't see the point in avoiding 'git_complete' and making our
lifes more difficult. Bash public functions, like *complete*, don't
have any special namespace, they just snatch them, and that's the end
of it. In the particular case of git, where would have only a couple
(currently 2) public functions, I don't see what's the big deal.
Cheers.
--
Felipe Contreras
From: Ville Skyttä <hidden> Date: 2016-06-15 22:53:38
On 2012-04-21 18:41, Felipe Contreras wrote:
Still, I don't see the point in avoiding 'git_complete' and making our
lifes more difficult.
I'm not aware of ways it'd make people's lifes more difficult, but if
git_complete is a function intended for completion purposes, I'd
personally not name it git* because it'd interfere for example with
completing git<TAB> by being included in the suggested completions even
though it's never meant to be used that way. Prefixing for example with
underscore doesn't avoid the problem completely, but makes it less
likely to happen.
From: Felipe Contreras <hidden> Date: 2016-06-15 22:53:38
2012/4/21 Ville Skyttä [off-list ref]:
On 2012-04-21 18:41, Felipe Contreras wrote:
quoted
Still, I don't see the point in avoiding 'git_complete' and making our
lifes more difficult.
I'm not aware of ways it'd make people's lifes more difficult, but if
git_complete is a function intended for completion purposes, I'd
personally not name it git* because it'd interfere for example with
completing git<TAB> by being included in the suggested completions even
though it's never meant to be used that way. Prefixing for example with
underscore doesn't avoid the problem completely, but makes it less
likely to happen.
That's actually a good point, I forgot that functions are also completed.
Cheers.
--
Felipe Contreras