Inserting a square bracket as part of search and replace

Question

I have the text pattern [2] in a text file. I want to replace it with the text string [1].

Using this command:

:%s/\<[2]\>/[1]/

Vim only replaces the string '2' in the square brackets so the result is [[1]].

I read that when searching:

After an opening [, everything until the next closing ] specifies a /collection source.

So I tried escaping the square brackets:

:%s/\<\[2\]\>/[1]/

But I received this error:

E486: Pattern not found: \<\[2\]\>

Enclosing the entire pattern in the brackets (:%s/\<[[2]]\>/[1]/) also returns the E486: Pattern not found: \<[[2]]\> error

Then removing the special character (or more accurately escape sequence) for the beginning of a word ('<') and the end of a word ('>') i.e. :%s/[[2]]/[1]/ gives the result [[1].

1. When searching with the :s (substitute) command, the collection [[2]] should match any single character '[', '2' or ']', so why does :%s/\<[[2]]\>/[1]/ cause an E486: Pattern not found: \<[[2]]\> error?
2. How do you search for text patterns consisting of an opening bracket ([) and closing bracket (]) e.g. the text pattern [2]?
3. Why is [ ] interpreted as a collection in the search part of the substitute command, but [ ] is not interpreted as a collection in the replace part of the substitute command?
4. Why does :%s/[[2]]/[1]/ only replace the text pattern '2]' i.e. giving the result [[1]?
5. Does enclosing the entire pattern in the brackets (:%s/\<[[2]]\>/[1]/) return an E486: Pattern not found: \<[[2]]\> error because Vim tries looking for the text pattern '[[2]]' but couldn't find it, or is something else causing this error?
6. The command :%s/\<[2]\>/[1]/ only replaces the string 2 in the square brackets (the result is [[1]]), which indicates that the collection [2] matches only the single character 2, but what happened to the beginning-of-a-word escape sequence ('<') and the ending-of-a-word escape sequence ('>')? Why do the escape sequences have no effect or not cause an error?

Answer 1

Before we get to all the questions, the way I'd achieve what you're looking to do is with the following:

:%s/\[2\]/[1]

or the following if you just want to change the text inside the [] without having to specify them again in the replacement part:

:%s/\[\zs2\ze\]/1

I believe the reason you are getting the "Pattern not found" error when you escape the square brackets is because \< is expecting the next character to be a "word character", but square brackets aren't considered to be a word character by default, so it gets a bit confused.

When you remove the \< and \> and search for [[2]], I think vim is trying to be clever about the way it interprets the brackets. The first [ starts the collection and the first ] closes the collection and inside the collection it's trying to match either a literal [ or a 2. Then the second ] is being being interpreted as a literal ] since it would otherwise be a syntax error since there is no opening [ to match it. So, it's basically looking for either a [ or a 2 that is immediately followed by a ]. It matches the 2] and replaces that with [1] so you end up with [[1].

Answers to your other questions:

1. As I tried to explain above (probably confusingly), it's only looking for either a [ or a 2. The first ] is terminating the collection. Then the second ] is being interpreted as a literal ]. I think you may have a typo in the question: :%s/[[2]]/[1]/ should result in [[1] and not the "Pattern not found" error.
2. You had the right idea with escaping the brackets with \. The problem was with the \< and \>. The pattern should be \[2\] to match [2].
3. It wouldn't really make sense to interpret [] as a collection in the replacement part since that construct is intended to match a single character within the collection. As such, it just assumes it's the literal characters in the replacement part.
4. See the explanation above.
5. As stated above, the brackets aren't considered to be a "word character" by default, so I think it's choking on the fact that it's looking for a literal ] followed by the end of word boundary which doesn't really make sense. I'm not 100% sure about this part, though (my experimentation had some odd results).
6. In this case the brackets around the 2 are used to specify a collection of just one character, so it finds the 2 (which is considered a "word character") and then replaces it with the [1].