doc: add rules for quoting

[akinomyoga]

Resolve #932

Note: shfmt tries to remove the quoting of [[ "$*" ]], which is needed to avoid the behavior change in bash 4.2 => 4.3. There is a similar problem with [[ "${arr[*]}" ]]. Actually, the current codebase doesn't have cases of [[ "$*" ]] or [[ "${arr[*]}" ]] where shfmt tries to remove the necessary quoting. But this could conflict in the future.

[scop]

Good stuff, pre-approved with some trivial changes/comments to address.

[scop]

What is "the word" here, could we rephrase/clarify this some, perhaps through an example?

[akinomyoga]

Hmm. The "word" here means the range of characters in the shell code that the user wants to treat as a single shell WORD. WORD is defined in POSIX XCU 2.3 Token Recognition and in XCU 2.10.2 Shell Grammar Rules. So, if the text range contains unquoted shell special characters, that is actually no longer a shell word. In that sense, the word cannot contain these characters without quoting.

[scop]

Sorry, I was probably unclear, let me try to elaborate. The bullet point examples above contain uses of $var (which are not "word"s AFAIU), but this bullet talks about exceptions, and I read them being exceptions to the above points. But because the above points do not contain any "word" uses -> confusion ensues exactly to which are these exceptions for.

So reading this I'm left wondering if quoting is necessary e.g. (using the slash as an example) for literal foo/bar so we'd need to do v="foo/bar", or uses of variables whose values might contain the slash (in which case we might not know, and it would arguably to be better to just always quote).

[akinomyoga]

Thank you for your clarification! I still planned to update the corresponding part, but I was thinking about how I should fix it. Now I understand the problems.

In my mind, I was talking about "the words that contain shell expansions" in the entire section as in the section title, and $var was the simplest case of such a word. However, as you pointed out, the examples seem to just talk about the shell expansions so are confusing. Then, I guess adding examples would be fine to avoid the confusion.

So reading this I'm left wondering if quoting is necessary e.g. (using the slash as an example) for literal foo/bar so we'd need to do v="foo/bar",

Sorry for confusing you, but the slash is not a part of the set of special characters. The enclosing [ and ] are also not a part of the special characters. I have a habit of indicating a regular expression by /.../. (Actually, I initially wrote \t\n;|&()<>\\$`'"#!~{ without /[ and ]/, but the pre-commit hook (probably PyMarkdown) has complained that a whitespace character cannot be included at the beginning of the code span.) I'll try to fix it.

---

edit: Also, I noticed that the right-hand sides are not words.

[akinomyoga]

ca0fde0, 740fc7e (squashed into the first commit)

• I changed the section title to Quoting of words to extend the target to the general words.
• I made it explicit that we avoid unnecessary quoting.
• I explained the exception of shell special characters in more detail.
• I added the case of an empty word as an exception.
• I also added our preferences in the type of quoting as suggested in #932 (comment).
• I updated examples, for example, from "v=$var" to "v=WORD (e.g. v=$var)".

[scop]

Looks great to me 👍

[scop]

shfmt tries to remove the quoting of [[ "$*" ]]

Is this something that should be reported as a bug against shfmt?

[akinomyoga]

shfmt tries to remove the quoting of [[ "$*" ]]

Is this something that should be reported as a bug against shfmt?

I think it should be reported to shfmt if it hasn't been reported so far, though I'm not sure we could claim that is a bug. The behavior of bash <= 4.2 may be considered as a bug of Bash, and it's possible that shfmt intentionally excludes workarounds of bash bugs. Anyway, it's worth reporting.

[scop]

Would you like to have a go at reporting the shfmt issue discussed above? I can do it as well, but I guess you know the details better by heart.

[akinomyoga]

Would you like to have a go at reporting the shfmt issue discussed above? I can do it as well, but I guess you know the details better by heart.

I'll think about it. Before reporting, I'd like to think about whether it is technically reasonable to implement it in the current codebase of mvdan/sh. I guess we need to add some codes in this case branch, but if the implementation would be too complicated, the suggestion might be just left untouched just like mvdan/sh#996.

[scop]

FWIW I'm not that surprised if upstream would feel reluctant to touch mvdan/sh#996, as there are a bunch of bugs related bugs even just with bash in the area, let alone other shells. I've contemplated closing the issue, or narrowing it down to the cases "known" not to be problematic anywhere, perhaps taking a look at implementing that myself.