refactor(bash_completion): refactor { => _comp_}{dequote,quote}

[akinomyoga]

In #735, I'd like to refactor the function names quote and dequote, but another branch that I created two months ago contains an improved version _comp_dequote and improved uses of quote, so I'd like to process this branch before #735 if possible.

[akinomyoga]

Also, it should be noted that, in these commits, I have changed the interface of dequote and quote writing their results to stdout so that the new _comp_dequote and _comp_quote write the result in the variable ret. If you have any suggestions, please feel free to tell me that.

Another thing that needs to be discussed is the annotations like @param in the code documentation. I wanted to describe the variables that are supposed to be referenced/modified so used @var, but this might cause problems if these annotations are processed by some documentation programs that don't support @var. Are these annotations intended to be processed by a certain annotation language? I have used @var inspired by Doxygen, but I found by searching on the internet that the existing documentation seems to follow JavaDoc (which I'm not familiar with)?

[akinomyoga]

With other small fixes bf77c2f 3f49e1b, I have rebased/squashed the related fixup commits.

[scop]

LGTM, thanks! Left a few trivial comments, feel free to merge after addressing.

[akinomyoga]

shellcheck somehow considers the value of the local variable quoted (previously quote) is used in other functions that have the variables of the same name.

In bash_completion line 172:
    local quoted='\\.|'\''[^'\'']*'\''|\$?"([^\"$`!]|'$param'|\\.)*"|\$'\''([^\'\'']|\\.)*'\'''
                       ^-- SC2089: Quotes/backslashes will be treated literally. Use an array.


In bash_completion line 769:
        toks+=($(compgen "${opts[@]}" -- $quoted))
                                         ^-----^ SC2090: Quotes/backslashes in this variable will not be respected.


In bash_completion line 779:
            toks+=($(compgen -f ${plusdirs+"${plusdirs[@]}"} -- $quoted))
                                                                ^-----^ SC2090: Quotes/backslashes in this variable will not be respected.

I have decided to further change the variable names as { => regex_}{param,quoted} (ebf06de...c6bb062). Squashed and rebased.

[scop]

Hmm, in that case I wonder if the syntax we use in the variables' values here throw off shellcheck's parser. That would be unfortunate as we probably wouldn't be able to rely on it much in the file after the position of the definitions.

[akinomyoga]

Hmm, in that case I wonder if the syntax we use in the variables' values here throw off shellcheck's parser.

I think the problem is not that shellcheck fails to parse the right-hand side of the assignment. The shellcheck error can be reproduced even by the following simple script:

$ cat test.sh
#!/usr/bin/env bash
function setv { eval "$1=\$2"; }
function func1 { local var="'"; }
function func2 { local var; setv var 1; echo $var; }
$ shellcheck test.sh

In test.sh line 3:
function func1 { local var="'"; }
                            ^-- SC2089: Quotes/backslashes will be treated literally. Use an array.


In test.sh line 4:
function func2 { local var; setv var 1; echo $var; }
                                             ^--^ SC2090: Quotes/backslashes in this variable will not be respected.

For more information:
  https://www.shellcheck.net/wiki/SC2089 -- Quotes/backslashes will be treate...
  https://www.shellcheck.net/wiki/SC2090 -- Quotes/backslashes in this variab...

[scop]

Ok, sounds like a shellcheck bug anyway, albeit a not that worrying one, and not really introduced or made worse by this PR, so feel free to merge at will.

Would you mind reporting the shellcheck issue upstream?

[akinomyoga]

Maybe this is not really a bug of shellcheck, but shellcheck tries to find the value of uninitialized var in func2 in the above example. For example, if we slightly modify func2 as follows, the errors go away:

function func2 { local var; var=1; echo $var; }

If shellcheck misses something, that's the fact that the local variable var of func1 is not used anywhere else because func1 doesn't call any other shell function. If you are going to report it to the shellcheck upstream, I think we can point it out there.

---

I'll later again check and merge this PR. Thank you!