Re: [PATCH v5] completion: add new __git_complete helper

Re: [PATCH v5] completion: add new __git_complete helper

[Felipe Contreras]

On Mon, May 14, 2012 at 5:35 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> This simplifies the completions, and would make it easier to define
> aliases in the future.

Since last version:

I renamed the wrapper function so they would end up as __git_wrap_foo,
and got rid of all the convenience to avoid specifying the prefix of
the functions; this function is not intended to be used outside git
anyway.

-- 
Felipe Contreras

[PATCH v5] completion: add new __git_complete helper

[Felipe Contreras]

This simplifies the completions, and would make it easier to define
aliases in the future.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 contrib/completion/git-completion.bash |   70 +++++++++++++++-----------------
 t/t9902-completion.sh                  |    2 +-
 2 files changed, 34 insertions(+), 38 deletions(-)

diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index 9f56ec7..d60bb8a 100755
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -2603,21 +2603,6 @@ _git ()
 {
 	local i c=1 command __git_dir
 
-	if [[ -n ${ZSH_VERSION-} ]]; then
-		emulate -L bash
-		setopt KSH_TYPESET
-
-		# workaround zsh's bug that leaves 'words' as a special
-		# variable in versions < 4.3.12
-		typeset -h words
-
-		# workaround zsh's bug that quotes spaces in the COMPREPLY
-		# array if IFS doesn't contain spaces.
-		typeset -h IFS
-	fi
-
-	local cur words cword prev
-	_get_comp_words_by_ref -n =: cur words cword prev
 	while [ $c -lt $cword ]; do
 		i="${words[c]}"
 		case "$i" in
@@ -2667,22 +2652,6 @@ _git ()
 
 _gitk ()
 {
-	if [[ -n ${ZSH_VERSION-} ]]; then
-		emulate -L bash
-		setopt KSH_TYPESET
-
-		# workaround zsh's bug that leaves 'words' as a special
-		# variable in versions < 4.3.12
-		typeset -h words
-
-		# workaround zsh's bug that quotes spaces in the COMPREPLY
-		# array if IFS doesn't contain spaces.
-		typeset -h IFS
-	fi
-
-	local cur words cword prev
-	_get_comp_words_by_ref -n =: cur words cword prev
-
 	__git_has_doubledash && return
 
 	local g="$(__gitdir)"
@@ -2703,16 +2672,43 @@ _gitk ()
 	__git_complete_revlist
 }
 
-complete -o bashdefault -o default -o nospace -F _git git 2>/dev/null \
-	|| complete -o default -o nospace -F _git git
-complete -o bashdefault -o default -o nospace -F _gitk gitk 2>/dev/null \
-	|| complete -o default -o nospace -F _gitk gitk
+__git_func_wrap ()
+{
+	if [[ -n ${ZSH_VERSION-} ]]; then
+		emulate -L bash
+		setopt KSH_TYPESET
+
+		# workaround zsh's bug that leaves 'words' as a special
+		# variable in versions < 4.3.12
+		typeset -h words
+
+		# workaround zsh's bug that quotes spaces in the COMPREPLY
+		# array if IFS doesn't contain spaces.
+		typeset -h IFS
+	fi
+	local cur words cword prev
+	_get_comp_words_by_ref -n =: cur words cword prev
+	$1
+}
+
+# Setup completion for certain functions defined above by setting common
+# variables and workarounds.
+# This is NOT a public function; use at your own risk.
+__git_complete ()
+{
+	local wrapper="__git_wrap${2}"
+	eval "$wrapper () { __git_func_wrap $2 ; }"
+	complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
+		|| complete -o default -o nospace -F $wrapper $1
+}
+
+__git_complete git _git
+__git_complete gitk _gitk
 
 # The following are necessary only for Cygwin, and only are needed
 # when the user has tab-completed the executable name and consequently
 # included the '.exe' suffix.
 #
 if [ Cygwin = "$(uname -o 2>/dev/null)" ]; then
-complete -o bashdefault -o default -o nospace -F _git git.exe 2>/dev/null \
-	|| complete -o default -o nospace -F _git git.exe
+__git_complete git.exe _git
 fi
diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh
index 5bda6b6..0f09fd6 100755
--- a/t/t9902-completion.sh
+++ b/t/t9902-completion.sh
@@ -63,7 +63,7 @@ run_completion ()
 	local _cword
 	_words=( $1 )
 	(( _cword = ${#_words[@]} - 1 ))
-	_git && print_comp
+	__git_wrap_git && print_comp
 }
 
 test_completion ()
-- 
1.7.10.1

Re: [PATCH v5] completion: add new __git_complete helper

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> This simplifies the completions, and would make it easier to define
> aliases in the future.
>
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> ---
>  contrib/completion/git-completion.bash |   70 +++++++++++++++-----------------
>  t/t9902-completion.sh                  |    2 +-
>  2 files changed, 34 insertions(+), 38 deletions(-)
>
> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
> index 9f56ec7..d60bb8a 100755
> --- a/contrib/completion/git-completion.bash
> +++ b/contrib/completion/git-completion.bash
> @@ -2603,21 +2603,6 @@ _git ()
>  {
>  	local i c=1 command __git_dir
>  
> -	if [[ -n ${ZSH_VERSION-} ]]; then
> -		emulate -L bash
> -		setopt KSH_TYPESET
> -
> -		# workaround zsh's bug that leaves 'words' as a special
> -		# variable in versions < 4.3.12
> -		typeset -h words
> -
> -		# workaround zsh's bug that quotes spaces in the COMPREPLY
> -		# array if IFS doesn't contain spaces.
> -		typeset -h IFS
> -	fi
> -
> -	local cur words cword prev
> -	_get_comp_words_by_ref -n =: cur words cword prev
>  	while [ $c -lt $cword ]; do
>  		i="${words[c]}"
>  		case "$i" in
> @@ -2667,22 +2652,6 @@ _git ()
>  
>  _gitk ()
>  {
> -	if [[ -n ${ZSH_VERSION-} ]]; then
> -		emulate -L bash
> -		setopt KSH_TYPESET
> -
> -		# workaround zsh's bug that leaves 'words' as a special
> -		# variable in versions < 4.3.12
> -		typeset -h words
> -
> -		# workaround zsh's bug that quotes spaces in the COMPREPLY
> -		# array if IFS doesn't contain spaces.
> -		typeset -h IFS
> -	fi
> -
> -	local cur words cword prev
> -	_get_comp_words_by_ref -n =: cur words cword prev
> -
> @@ -2703,16 +2672,43 @@ _gitk ()
>  	__git_complete_revlist
>  }
>  
> -complete -o bashdefault -o default -o nospace -F _git git 2>/dev/null \
> -	|| complete -o default -o nospace -F _git git
> -complete -o bashdefault -o default -o nospace -F _gitk gitk 2>/dev/null \
> -	|| complete -o default -o nospace -F _gitk gitk

Nice code reduction by moving the duplicated code into the new helpers ;-)

> +__git_func_wrap ()
> +{
> +	if [[ -n ${ZSH_VERSION-} ]]; then
> +		emulate -L bash
> +		setopt KSH_TYPESET
> +
> +		# workaround zsh's bug that leaves 'words' as a special
> +		# variable in versions < 4.3.12
> +		typeset -h words
> +
> +		# workaround zsh's bug that quotes spaces in the COMPREPLY
> +		# array if IFS doesn't contain spaces.
> +		typeset -h IFS
> +	fi
> +	local cur words cword prev
> +	_get_comp_words_by_ref -n =: cur words cword prev
> +	$1
> +}
> +
> +# Setup completion for certain functions defined above by setting common
> +# variables and workarounds.
> +# This is NOT a public function; use at your own risk.
> +__git_complete ()
> +{
> +	local wrapper="__git_wrap${2}"
> +	eval "$wrapper () { __git_func_wrap $2 ; }"
> +	complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
> +		|| complete -o default -o nospace -F $wrapper $1
> +}
> +
> +__git_complete git _git
> +__git_complete gitk _gitk

It makes my stomach queasy whenever I see $var not in double quotes that
forces me to guess (and trace to verify if the codepath is what I really
care about) if any value with $IFS in it could be used there, so even when
they are known to be safe, I'd prefer to see either explicit quotes or
comment that says what are expected in $1 and $2.

The quoting of all the added lines looks correct, though.

>  # The following are necessary only for Cygwin, and only are needed
>  # when the user has tab-completed the executable name and consequently
>  # included the '.exe' suffix.
>  #
>  if [ Cygwin = "$(uname -o 2>/dev/null)" ]; then
> -complete -o bashdefault -o default -o nospace -F _git git.exe 2>/dev/null \
> -	|| complete -o default -o nospace -F _git git.exe
> +__git_complete git.exe _git
>  fi
> diff --git a/t/t9902-completion.sh b/t/t9902-completion.sh
> index 5bda6b6..0f09fd6 100755
> --- a/t/t9902-completion.sh
> +++ b/t/t9902-completion.sh
> @@ -63,7 +63,7 @@ run_completion ()
>  	local _cword
>  	_words=( $1 )
>  	(( _cword = ${#_words[@]} - 1 ))
> -	_git && print_comp
> +	__git_wrap_git && print_comp
>  }
>  
>  test_completion ()

Re: [PATCH v5] completion: add new __git_complete helper

[Felipe Contreras]

On Mon, May 14, 2012 at 7:43 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> This simplifies the completions, and would make it easier to define
>> aliases in the future.
>>
>> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
>> ---
>>  contrib/completion/git-completion.bash |   70 +++++++++++++++-----------------
>>  t/t9902-completion.sh                  |    2 +-
>>  2 files changed, 34 insertions(+), 38 deletions(-)
>>
>> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
>> index 9f56ec7..d60bb8a 100755
>> --- a/contrib/completion/git-completion.bash
>> +++ b/contrib/completion/git-completion.bash
>> @@ -2603,21 +2603,6 @@ _git ()
>>  {
>>       local i c=1 command __git_dir
>>
>> -     if [[ -n ${ZSH_VERSION-} ]]; then
>> -             emulate -L bash
>> -             setopt KSH_TYPESET
>> -
>> -             # workaround zsh's bug that leaves 'words' as a special
>> -             # variable in versions < 4.3.12
>> -             typeset -h words
>> -
>> -             # workaround zsh's bug that quotes spaces in the COMPREPLY
>> -             # array if IFS doesn't contain spaces.
>> -             typeset -h IFS
>> -     fi
>> -
>> -     local cur words cword prev
>> -     _get_comp_words_by_ref -n =: cur words cword prev
>>       while [ $c -lt $cword ]; do
>>               i="${words[c]}"
>>               case "$i" in
>> @@ -2667,22 +2652,6 @@ _git ()
>>
>>  _gitk ()
>>  {
>> -     if [[ -n ${ZSH_VERSION-} ]]; then
>> -             emulate -L bash
>> -             setopt KSH_TYPESET
>> -
>> -             # workaround zsh's bug that leaves 'words' as a special
>> -             # variable in versions < 4.3.12
>> -             typeset -h words
>> -
>> -             # workaround zsh's bug that quotes spaces in the COMPREPLY
>> -             # array if IFS doesn't contain spaces.
>> -             typeset -h IFS
>> -     fi
>> -
>> -     local cur words cword prev
>> -     _get_comp_words_by_ref -n =: cur words cword prev
>> -
>> @@ -2703,16 +2672,43 @@ _gitk ()
>>       __git_complete_revlist
>>  }
>>
>> -complete -o bashdefault -o default -o nospace -F _git git 2>/dev/null \
>> -     || complete -o default -o nospace -F _git git
>> -complete -o bashdefault -o default -o nospace -F _gitk gitk 2>/dev/null \
>> -     || complete -o default -o nospace -F _gitk gitk
>
> Nice code reduction by moving the duplicated code into the new helpers ;-)
>
>> +__git_func_wrap ()
>> +{
>> +     if [[ -n ${ZSH_VERSION-} ]]; then
>> +             emulate -L bash
>> +             setopt KSH_TYPESET
>> +
>> +             # workaround zsh's bug that leaves 'words' as a special
>> +             # variable in versions < 4.3.12
>> +             typeset -h words
>> +
>> +             # workaround zsh's bug that quotes spaces in the COMPREPLY
>> +             # array if IFS doesn't contain spaces.
>> +             typeset -h IFS
>> +     fi
>> +     local cur words cword prev
>> +     _get_comp_words_by_ref -n =: cur words cword prev
>> +     $1
>> +}
>> +
>> +# Setup completion for certain functions defined above by setting common
>> +# variables and workarounds.
>> +# This is NOT a public function; use at your own risk.
>> +__git_complete ()
>> +{
>> +     local wrapper="__git_wrap${2}"
>> +     eval "$wrapper () { __git_func_wrap $2 ; }"
>> +     complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
>> +             || complete -o default -o nospace -F $wrapper $1
>> +}
>> +
>> +__git_complete git _git
>> +__git_complete gitk _gitk
>
> It makes my stomach queasy whenever I see $var not in double quotes that
> forces me to guess (and trace to verify if the codepath is what I really
> care about) if any value with $IFS in it could be used there, so even when
> they are known to be safe, I'd prefer to see either explicit quotes or
> comment that says what are expected in $1 and $2.

Which ones? These?

>> +     $1
>> +     complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
>> +             || complete -o default -o nospace -F $wrapper $1

So you want:

  "$1"

  complete -o bashdefault -o default -o nospace -F "$wrapper" "$1" 2>/dev/null \
    || complete -o default -o nospace -F "$wrapper" "$1"

I wouldn't object to the arguments of complete, but the function call
seems totally unintuitive to me like that.

-- 
Felipe Contreras

Re: [PATCH v5] completion: add new __git_complete helper

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

>>> +__git_func_wrap ()
>>> +{
>>> +     if [[ -n ${ZSH_VERSION-} ]]; then
>>> +             emulate -L bash
>>> +             setopt KSH_TYPESET
>>> +
>>> +             # workaround zsh's bug that leaves 'words' as a special
>>> +             # variable in versions < 4.3.12
>>> +             typeset -h words
>>> +
>>> +             # workaround zsh's bug that quotes spaces in the COMPREPLY
>>> +             # array if IFS doesn't contain spaces.
>>> +             typeset -h IFS
>>> +     fi
>>> +     local cur words cword prev
>>> +     _get_comp_words_by_ref -n =: cur words cword prev
>>> +     $1
>>> +}
>>> +
>>> +# Setup completion for certain functions defined above by setting common
>>> +# variables and workarounds.
>>> +# This is NOT a public function; use at your own risk.
>>> +__git_complete ()
>>> +{
>>> +     local wrapper="__git_wrap${2}"
>>> +     eval "$wrapper () { __git_func_wrap $2 ; }"
>>> +     complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
>>> +             || complete -o default -o nospace -F $wrapper $1
>>> +}
>>> +
>>> +__git_complete git _git
>>> +__git_complete gitk _gitk
>>
>> It makes my stomach queasy whenever I see $var not in double quotes that
>> forces me to guess (and trace to verify if the codepath is what I really
>> care about) if any value with $IFS in it could be used there, so even when
>> they are known to be safe, I'd prefer to see either explicit quotes or
>> comment that says what are expected in $1 and $2.
>
> Which ones?

All of them ;-)

Here is my attempt to explain why none of them needs to be quoted:

 # Setup completion for certain functions defined above by setting common
 # variables and workarounds.
 # It takes two parameters:
 #  - the first is the command name on the command line to complete its
 #    arguments for the user;
 #  - the second is a name of the completion function
 # This is NOT a public function; use at your own risk.
 #
 # Note that none of the variable reference in the implementation of this
 # function needs dq around it.
 #
 # wrapper: the name of an internal shell function that wraps the
 #          completion function $2, formed by prefixing "__git_wrap"
 #          in front of it.  As it has to be usable as a name of a
 #          shell function, by definition there won't be $IFS characters
 #          in it.
 # $1:      the command name on the command line---ditto.
 # $2:      the shell function name that implements the completion-ditto.

Once there is such an explanation, the answer to the next question would
become...

>>> +     $1
>>> +     complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
>>> +             || complete -o default -o nospace -F $wrapper $1
>
> So you want:
>
>   "$1"

... Not really.

Re: [PATCH v5] completion: add new __git_complete helper

[Felipe Contreras]

On Mon, May 14, 2012 at 8:13 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>>>> +__git_func_wrap ()
>>>> +{
>>>> +     if [[ -n ${ZSH_VERSION-} ]]; then
>>>> +             emulate -L bash
>>>> +             setopt KSH_TYPESET
>>>> +
>>>> +             # workaround zsh's bug that leaves 'words' as a special
>>>> +             # variable in versions < 4.3.12
>>>> +             typeset -h words
>>>> +
>>>> +             # workaround zsh's bug that quotes spaces in the COMPREPLY
>>>> +             # array if IFS doesn't contain spaces.
>>>> +             typeset -h IFS
>>>> +     fi
>>>> +     local cur words cword prev
>>>> +     _get_comp_words_by_ref -n =: cur words cword prev
>>>> +     $1
>>>> +}
>>>> +
>>>> +# Setup completion for certain functions defined above by setting common
>>>> +# variables and workarounds.
>>>> +# This is NOT a public function; use at your own risk.
>>>> +__git_complete ()
>>>> +{
>>>> +     local wrapper="__git_wrap${2}"
>>>> +     eval "$wrapper () { __git_func_wrap $2 ; }"
>>>> +     complete -o bashdefault -o default -o nospace -F $wrapper $1 2>/dev/null \
>>>> +             || complete -o default -o nospace -F $wrapper $1
>>>> +}
>>>> +
>>>> +__git_complete git _git
>>>> +__git_complete gitk _gitk
>>>
>>> It makes my stomach queasy whenever I see $var not in double quotes that
>>> forces me to guess (and trace to verify if the codepath is what I really
>>> care about) if any value with $IFS in it could be used there, so even when
>>> they are known to be safe, I'd prefer to see either explicit quotes or
>>> comment that says what are expected in $1 and $2.
>>
>> Which ones?
>
> All of them ;-)
>
> Here is my attempt to explain why none of them needs to be quoted:
>
>  # Setup completion for certain functions defined above by setting common
>  # variables and workarounds.
>  # It takes two parameters:
>  #  - the first is the command name on the command line to complete its
>  #    arguments for the user;
>  #  - the second is a name of the completion function
>  # This is NOT a public function; use at your own risk.
>  #
>  # Note that none of the variable reference in the implementation of this
>  # function needs dq around it.

I don't understand that.

>  # wrapper: the name of an internal shell function that wraps the
>  #          completion function $2, formed by prefixing "__git_wrap"
>  #          in front of it.  As it has to be usable as a name of a
>  #          shell function, by definition there won't be $IFS characters
>  #          in it.
>  # $1:      the command name on the command line---ditto.
>  # $2:      the shell function name that implements the completion-ditto.

So in short; because the variables are used as function/command names.

Cheers.

-- 
Felipe Contreras

Re: [PATCH v5] completion: add new __git_complete helper

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

>> Here is my attempt to explain why none of them needs to be quoted:
>> ...
> I don't understand that.

That was my attempt to give the readers some context to understand what
comes after that.  If the original patch author does not understand it,
perhaps it is an indication that the function is somewhat underdocumented.

>>  # wrapper: the name of an internal shell function that wraps the
> ...
> So in short; because the variables are used as function/command names.

Yes, and the fact that this is internal and we won't listen to clueless
people who attempt "__git_complete 'foo bar' 'bar boz'" and complain are
what make all of them safe to be used without any quotes around it.

Re: [PATCH v5] completion: add new __git_complete helper

[Felipe Contreras]

On Mon, May 14, 2012 at 9:09 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>>> Here is my attempt to explain why none of them needs to be quoted:
>>> ...
>> I don't understand that.
>
> That was my attempt to give the readers some context to understand what
> comes after that.  If the original patch author does not understand it,
> perhaps it is an indication that the function is somewhat underdocumented.

I mean I don't understand this "Note that none of the variable
reference in the implementation of this function needs dq around it."
I suppose you meant 'references' (as that would make it grammatically
correct AFAICS), but I still don't understand what you are trying so
say. That the way the arguments are used in the __git_complete
function makes it so double quotes are irrelevant?

If so, then yeah, I agree.

Is there something actionable?

-- 
Felipe Contreras

Re: [PATCH v5] completion: add new __git_complete helper

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> On Mon, May 14, 2012 at 9:09 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>
>>>> Here is my attempt to explain why none of them needs to be quoted:
>>>> ...
>>> I don't understand that.
>>
>> That was my attempt to give the readers some context to understand what
>> comes after that....
>
> I mean I don't understand this "Note that none of the variable
> reference in the implementation of this function needs dq around it."

You later say "then yeah, I agree.", so I am interpreting this "I don't
understand" to mean that you do agree that missing dq around $1, $2 and
$wrapper in the function is _not_ a problem, and you do not understand why
it needs to be explained.  See below.

> I suppose you meant 'references' (as that would make it grammatically
> correct AFAICS),...

Correct.

> but I still don't understand what you are trying so
> say. That the way the arguments are used in the __git_complete
> function makes it so double quotes are irrelevant?

Correct.

> If so, then yeah, I agree.
>
> Is there something actionable?

Like adding an explanation, preferrably a better one, there, so that the
next person do not have to wonder and waste time like I did?

Re: [PATCH v5] completion: add new __git_complete helper

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Felipe Contreras <felipe.contreras@gmail.com> writes:
> ...
>> If so, then yeah, I agree.
>>
>> Is there something actionable?
>
> Like adding an explanation, preferrably a better one, there, so that the
> next person do not have to wonder and waste time like I did?

s/a better one/& than my attempt in the message you are replying to/;

Re: [PATCH v5] completion: add new __git_complete helper

[Felipe Contreras]

On Tue, May 15, 2012 at 7:01 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:

>> Is there something actionable?
>
> Like adding an explanation, preferrably a better one, there, so that the
> next person do not have to wonder and waste time like I did?

The next person that does what? Review the code while keeping an eye
on the way the variable arguments are used inside the implementation
of the function? I don't think there will *ever* be such a person
after the code is committed.

Either way, I believe in the notion of self-documenting code, so I
would rather add a few double quotes rather than add an essay on top
of the function just for you.

Not everything in the code needs to be documented, and most
documentation in the code is ignored anyway, and for a good example
take a look at the code in the Linux kernel.

Cheers.

-- 
Felipe Contreras