Escaping closing brackets in snippet choices results in backslashes being inserted

[DanTup]

In the docs here it says:

Below is the EBNF (extended Backus-Naur form) for snippets. With \ (backslash), you can escape $, }, and \. Within choice elements, the backslash also escapes comma and pipe characters.

My understanding of this is that } can be escaped with a \ for all kinds of snippets.

However, if I create a snippet that uses choices and escapes a bracket, the backslash appears as-is in the choice:

const doc = await vscode.workspace.openTextDocument({ content: '' });
const editor = await vscode.window.showTextDocument(doc);
const snippet = new vscode.SnippetString("a(${1|{optionA\\})>,optionB|}");
await editor.insertSnippet(snippet, new vscode.Range(new vscode.Position(0, 0), new vscode.Position(0, 0)));

If it is not allowed to escape } for choices, then I think it should be clearer from the docs (and the same docs in LSP).

Note: I can't use the appendChoice() API because these snippets are being returned over LSP from a language server (and such, it's important the docs are accurate and specific, to ensure servers and clients have the same understandings).

[DanTup]

This actually repros without the backslashes when using appendChoice:

const doc = await vscode.workspace.openTextDocument({ content: '' });
const editor = await vscode.window.showTextDocument(doc);
const snippet = new vscode.SnippetString("a(");
snippet.appendChoice(["{optionA})>", "optionB"]);
await editor.insertSnippet(snippet, new vscode.Range(new vscode.Position(0, 0), new vscode.Position(0, 0)));

Although it's possible that bit will be fixed by #180132

[RedCMD]

related: #200424

[jrieken]

My understanding of this is that } can be escaped with a \ for all kinds of snippets.

I see how the docs make you believe so but it is a misunderstanding. Generally, only things that have a "syntax-meaning" need to be escaped.

[RedCMD]

only things that have a "syntax-meaning" need to be escaped

@jrieken then how come when I escape snippet syntax in #200424 the escape char goes through
but if I don't escape it, the snippet syntax goes through

[jrieken]

@RedCMD I don't see how #200424 is related to this issue

[DanTup]

@jrieken

I see how the docs make you believe so but it is a misunderstanding. Generally, only things that have a "syntax-meaning" need to be escaped.

Gotcha - so the only thing to escape in a choice is the pipe | and comma ,? It would be good if the docs could list exactly which characters can be escaped (it sounds like there's no difference between need and can here) for each of the contexts to avoid any ambiguity?

I'm happy to send a PR with my guess at what that is if you'd review it - I'd like to ensure our server (and the LSP spec) are correct
and explicit for the actual behaviour here. Thanks!

[DanTup]

microsoft/vscode-docs#6928 was merged with doc updates for VS Code. The same change in LSP is open at microsoft/language-server-protocol#1868.

[DanTup]

Both the PRs above have been merged.