TMLanguage, what does captures do?

Question

I am working on a tm language project for vscode and I'm wondering what the captures property on a pattern does exactly.

I can't seem to figure out what the indexes of the captures object stand for and I can't find any information on it online.

Example:

{
    "match": "(group 1)(group2)"
    "captures": {
        "0": {
             "name": "Name of first capture group? What does 0 mean here?"
         }
    }
}

Answer 1

The "captures" key is documented here, in the "Rule Keys" section (12.3):

https://macromates.com/manual/en/language_grammars

The name is not the name of the first capture group. It is just a string that specifies the name of the style to apply to the characters that were matched by that capture group. When I say "capture group", I am referring to a matching left paren and right paren in your regular expression.

Using the "captures" key is a relatively complex way to assign style names to characters in the document. It allows you to specify different styles to different portions of the text matched by the regular expression. A simpler way is to just use the "name" key, which will apply the style to all of the matched text.