VS code snippets - what is the required number in front of a choice list?

Question

https://code.visualstudio.com/docs/editor/userdefinedsnippets#_choice

${1|one,two,three|}

So I'm new to snippets, and I noticed the number in front of a list of completion choices is required to show the choice menu correctly (if omitted, it will populate the choice list as a literal string - https://github.com/infosec-intern/textmate-yara/pull/29).

What does this number do, and why is it needed ? (the documentation doesn't explain it)

is it for the default selection ?

Thanks,

Answer 1

In ${1|one,two,three|} the 1 is a tabstop. When you trigger the snippet that is the first place your cursor will go. See https://code.visualstudio.com/docs/editor/userdefinedsnippets#_tabstops

Tabstops

With tabstops, you can make the editor cursor move inside a snippet. Use $1, $2 to specify cursor locations. The number is the order in which tabstops will be visited, whereas $0 denotes the final cursor position. Multiple occurrences of the same tabstop are linked and updated in sync.

Accorsing to the snippet grammar the tabstop number is required before a choice element.

choice ::= '${' int '|' text (',' text)* '|}'

Since it is a choice element it makes sense that you want the cursor to go there at some time just by cycling through the tabstops with the tab key. You can select the order of the tabstops, they don't have to be in any certain order within your snippet. Tabstop $2 could appear before $1 for example.

And the tabstop has nothing to do with the default selection/option. The default will always be the first option listed in the snippet.