Luau.YAML-tmLanguage

---
information_for_contributors:
  - "The source of this file is https://github.com/JohnnyMorganz/Luau.tmLanguage/blob/main/Luau.YAML-tmLanguage"
  - "If you want to provide a fix or improvement, please create a pull request against the original repository."
  - "Once accepted there, we are happy to receive an update request."

name: Luau
scopeName: source.luau
fileTypes: [luau]

# TODO: check if we really need to assign 'keyword.operator.type.luau' for ':'

variables:
  matchingParentheses: (\(([^\(\)]|(\(([^\(\)]|\([^\(\)]*\))*\)))*\))
  lookAheadEndOfType: '[;),}\]:?\-\+\>](?!\s*[&\|])|$|\b(break|do|else|for|if|elseif|return|then|repeat|while|until|end|in|continue)\b'
  identifier: "[a-zA-Z_][a-zA-Z0-9_]*"

patterns:
  - include: "#function-definition"
  - include: "#number"
  - include: "#string"
  - include: "#shebang"
  - include: "#comment"
  - include: "#local-declaration"
  - include: "#for-loop"
  - include: "#type-alias-declaration"
  - include: "#keyword"
  - include: "#language_constant"
  - include: "#standard_library"
  - include: "#identifier"
  - include: "#operator"
  - include: "#parentheses"
  - include: "#table"
  - include: "#type_cast"
  - include: "#type_annotation"
  - include: "#attribute"

repository:
  function-definition:
    begin: "\\b(?:(local)\\s+)?(function)\\b(?![,:])"
    beginCaptures:
      "1": { name: storage.modifier.local.luau } # OLD: keyword.local.luau
      "2": { name: keyword.control.luau }
    end: "(?<=[\\)\\-{}\\[\\]\"'])"
    name: meta.function.luau
    patterns:
      - include: "#comment"
      - include: "#generics-declaration"
      - begin: "(\\()"
        beginCaptures:
          "1": { name: punctuation.definition.parameters.begin.luau }
        end: "(\\))"
        endCaptures:
          "1": { name: punctuation.definition.parameters.end.luau }
        name: meta.parameter.luau
        patterns:
          - include: "#comment"
          - match: "\\.\\.\\."
            name: variable.parameter.function.varargs.luau
          - match: "{{identifier}}"
            name: variable.parameter.function.luau
          - match: ","
            name: punctuation.separator.arguments.luau
          - begin: ":"
            beginCaptures:
              "0": { name: keyword.operator.type.luau }
            end: "(?=[\\),])"
            patterns:
              - include: "#type_literal"
      - match: "\\b(__add|__call|__concat|__div|__eq|__index|__le|__len|__lt|__metatable|__mod|__mode|__mul|__newindex|__pow|__sub|__tostring|__unm|__iter|__idiv)\\b"
        name: variable.language.metamethod.luau
      - match: "\\b({{identifier}})\\b"
        name: entity.name.function.luau

  local-declaration:
    begin: "\\b(local)\\b"
    end: "(?=\\s*do\\b|\\s*[=;]|\\s*$)"
    beginCaptures:
      "1": { name: storage.modifier.local.luau }
    patterns:
      - include: "#comment"
      - include: "#attribute"
      - begin: "(:)"
        beginCaptures:
          "1": { name: keyword.operator.type.luau }
        end: "(?=\\s*do\\b|\\s*[=;,]|\\s*$)"
        patterns:
          - include: "#type_literal"
      - name: variable.other.constant.luau
        match: "\\b([A-Z_][A-Z0-9_]*)\\b"
      - name: variable.other.readwrite.luau # TODO: should this be something different? old was just variable.other.luau
        match: "\\b({{identifier}})\\b"

  for-loop:
    begin: "\\b(for)\\b"
    beginCaptures:
      "1": { name: keyword.control.luau }
    end: "\\b(in)\\b|(=)"
    endCaptures:
      "1": { name: keyword.control.luau }
      "2": { name: keyword.operator.assignment.luau }
    patterns:
      - begin: "(:)"
        beginCaptures:
          "1": { name: keyword.operator.type.luau }
        end: "(?=\\s*in\\b|\\s*[=,]|\\s*$)"
        patterns:
          - include: "#type_literal"
      - name: variable.parameter.luau
        match: "\\b({{identifier}})\\b"

  shebang:
    captures:
      "1": { name: punctuation.definition.comment.luau }
    match: "\\A(#!).*$\\n?"
    name: comment.line.shebang.luau

  string_escape:
    patterns:
      # As it turns out, because backslashes have to be escaped in both JSON and Regex, a single backslash is represented as 4 here
      - name: constant.character.escape.luau
        match: "\\\\[abfnrtvz'\"`{\\\\]"
      - name: constant.character.escape.luau
        match: "\\\\\\d{1,3}"
      - name: constant.character.escape.luau
        match: "\\\\x[0-9a-fA-F]{2}"
      - name: constant.character.escape.luau
        match: "\\\\u\\{[0-9a-fA-F]*\\}"
      - name: constant.character.escape.luau
        match: "\\\\$"
  number:
    patterns:
      - name: constant.numeric.hex.luau
        match: "\\b0_*[xX]_*[\\da-fA-F_]*(?:[eE][\\+\\-]?_*\\d[\\d_]*(?:\\.[\\d_]*)?)?"
      - name: constant.numeric.binary.luau
        match: "\\b0_*[bB][01_]+(?:[eE][\\+\\-]?_*\\d[\\d_]*(?:\\.[\\d_]*)?)?"
      - name: constant.numeric.decimal.luau
        match: "(?:\\d[\\d_]*(?:\\.[\\d_]*)?|\\.\\d[\\d_]*)(?:[eE][\\+\\-]?_*\\d[\\d_]*(?:\\.[\\d_]*)?)?"

  string:
    patterns:
      - name: string.quoted.double.luau
        begin: '"'
        end: '"'
        patterns:
          - include: "#string_escape"
      - name: string.quoted.single.luau
        begin: "'"
        end: "'"
        patterns:
          - include: "#string_escape"
      - name: string.other.multiline.luau
        begin: "\\[(=*)\\["
        end: "\\]\\1\\]"
      - name: string.interpolated.luau
        begin: "`"
        end: "`"
        patterns:
          - include: "#interpolated_string_expression"
          - include: "#string_escape"

  interpolated_string_expression:
    name: meta.template.expression.luau
    contentName: meta.embedded.line.luau
    begin: "\\{"
    end: "\\}"
    beginCaptures:
      "0":
        {
          name: punctuation.definition.interpolated-string-expression.begin.luau,
        }
    endCaptures:
      "0":
        { name: punctuation.definition.interpolated-string-expression.end.luau }
    patterns:
      - include: "source.luau"

  standard_library:
    patterns:
      - name: support.function.luau
        match: "(?<![^.]\\.|:)\\b(assert|collectgarbage|error|gcinfo|getfenv|getmetatable|ipairs|loadstring|newproxy|next|pairs|pcall|print|rawequal|rawset|require|select|setfenv|setmetatable|tonumber|tostring|type|typeof|unpack|xpcall)\\b"
      - name: constant.language.luau
        match: "(?<![^.]\\.|:)\\b(_G|_VERSION)\\b"
      - name: support.function.luau
        match: "(?<![^.]\\.|:)\\b(bit32\\.(?:arshift|band|bnot|bor|btest|bxor|extract|lrotate|lshift|replace|rrotate|rshift|countlz|countrz|byteswap)|coroutine\\.(?:create|isyieldable|resume|running|status|wrap|yield|close)|debug\\.(?:info|loadmodule|profilebegin|profileend|traceback)|math\\.(?:abs|acos|asin|atan|atan2|ceil|clamp|cos|cosh|deg|exp|floor|fmod|frexp|ldexp|log|log10|max|min|modf|noise|pow|rad|random|randomseed|round|sign|sin|sinh|sqrt|tan|tanh)|os\\.(?:clock|date|difftime|time)|string\\.(?:byte|char|find|format|gmatch|gsub|len|lower|match|pack|packsize|rep|reverse|split|sub|unpack|upper)|table\\.(?:concat|create|find|foreach|foreachi|getn|insert|maxn|move|pack|remove|sort|unpack|clear|freeze|isfrozen|clone)|task\\.(?:spawn|synchronize|desynchronize|wait|defer|delay)|utf8\\.(?:char|codepoint|codes|graphemes|len|nfcnormalize|nfdnormalize|offset)|buffer\\.(?:create|fromstring|tostring|len|readi8|readu8|readi16|readu16|readi32|readu32|readf32|readf64|writei8|writeu8|writei16|writeu16|writei32|writeu32|writef32|writef64|readstring|writestring|copy|fill))\\b"
      - name: support.constant.luau
        match: "(?<![^.]\\.|:)\\b(bit32|buffer|coroutine|debug|math(\\.(huge|pi))?|os|string|table|task|utf8(\\.charpattern)?)\\b"
      # TODO: These are Roblox-specific patterns. Maybe they should not be part of the Luau syntax
      - name: support.function.luau
        match: "(?<![^.]\\.|:)\\b(delay|DebuggerManager|elapsedTime|PluginManager|printidentity|settings|spawn|stats|tick|time|UserSettings|version|wait|warn)\\b"
      - name: constant.language.luau
        match: "(?<![^.]\\.|:)\\b(game|plugin|shared|script|workspace|Enum(?:\\.\\w+){0,2})\\b"

  keyword:
    patterns:
      - match: "\\b(break|do|else|for|if|elseif|return|then|repeat|while|until|end|in|continue)\\b"
        name: keyword.control.luau
      - match: "\\b(local)\\b"
        name: storage.modifier.local.luau
      - match: "\\b(function)\\b(?![,:])"
        name: keyword.control.luau
      - match: "(?<![^.]\\.|:)\\b(self)\\b"
        name: variable.language.self.luau
      - match: "\\b(and|or|not)\\b"
        name: keyword.operator.logical.luau keyword.operator.wordlike.luau
      - name: variable.language.metamethod.luau
        match: "(?<=[^.]\\.|:)\\b(__add|__call|__concat|__div|__eq|__index|__le|__len|__lt|__metatable|__mod|__mode|__mul|__newindex|__pow|__sub|__tostring|__unm)\\b"
      - name: keyword.other.unit.luau
        match: "(?<![.])\\.{3}(?!\\.)"

  identifier:
    patterns:
      - match: "\\b({{identifier}})\\b(?=\\s*(?:[({\"']|\\[\\[))"
        name: entity.name.function.luau # OLD: support.function.any-method.luau
      - match: "(?<=[^.]\\.|:)\\b({{identifier}})\\b"
        name: variable.other.property.luau # OLD: entity.other.attribute.luau
      - match: "\\b([A-Z_][A-Z0-9_]*)\\b"
        name: variable.other.constant.luau
      - match: "\\b({{identifier}})\\b"
        name: variable.other.readwrite.luau # OLD: variable.other.luau

  operator:
    patterns:
      - match: "==|~=|!=|<=?|>=?"
        name: keyword.operator.comparison.luau
      - match: "\\+=|-=|/=|//=|\\*=|%=|\\^=|\\.\\.=|="
        name: keyword.operator.assignment.luau
      - match: "\\+|-|%|\\*|\\/\\/|\\/|\\^"
        name: "keyword.operator.arithmetic.luau"
      - match: "#|(?<!\\.)\\.{2}(?!\\.)"
        name: keyword.operator.other.luau

  parentheses:
    begin: "(\\()"
    beginCaptures:
      "1": { name: punctuation.arguments.begin.luau }
    end: "(\\))"
    endCaptures:
      "1": { name: punctuation.arguments.end.luau }
    patterns:
      - match: ","
        name: punctuation.separator.arguments.luau
      - include: "source.luau"

  table:
    begin: "(\\{)"
    beginCaptures:
      "1": { name: punctuation.table.begin.luau }
    end: "(\\})"
    endCaptures:
      "1": { name: punctuation.table.end.luau }
    patterns:
      - match: "[,;]"
        name: punctuation.separator.fields.luau
      - include: "source.luau"

  language_constant:
    patterns:
      - match: "(?<![^.]\\.|:)\\b(false)\\b"
        name: constant.language.boolean.false.luau
      - match: "(?<![^.]\\.|:)\\b(true)\\b"
        name: constant.language.boolean.true.luau
      - match: "(?<![^.]\\.|:)\\b(nil(?!:))\\b"
        name: constant.language.nil.luau

  comment:
    patterns:
      - name: comment.block.luau
        begin: "--\\[(=*)\\["
        end: "\\]\\1\\]"
        patterns:
          - name: keyword.operator.other.luau
            begin: "(```luau?)\\s+"
            end: "(```)"
            beginCaptures:
              "1": { name: comment.luau }
            endCaptures:
              "1": { name: comment.luau }
            patterns:
              - include: "source.luau"
          - include: "#doc_comment_tags"
      - name: comment.line.double-dash.documentation.luau
        begin: "---"
        end: "\\n"
        patterns:
          - include: "#doc_comment_tags"
      - name: comment.line.double-dash.luau
        begin: "--"
        end: "\\n"

  doc_comment_tags:
    patterns:
      - name: storage.type.class.luadoc.luau
        match: "@\\w+"
      - match: "((?<=[\\s*!\\/])[\\\\@]param)(?:\\s)+(\\b\\w+\\b)"
        captures:
          "1": { name: storage.type.class.luadoc.luau }
          "2": { name: variable.parameter.luau }

  generics-declaration:
    begin: "(<)"
    # TODO:
    # beginCaptures:
    #  "1": { name: punctuation.definition.generics.begin.luau }
    end: "(>)"
    # endCaptures:
    #  "1": { name: punctuation.definition.generics.end.luau }
    # name: meta.generic.luau
    patterns:
      - match: "{{identifier}}"
        name: entity.name.type.luau
      - match: "="
        name: keyword.operator.assignment.luau
      - include: "#type_literal"
      # - match: ","
      # name: punctuation.separator.generics.luau

  type-alias-declaration:
    # TODO: don't match start of line, it's not really correct. but we need to make sure we handle appropraitely if we remove ^
    begin: "^\\b(?:(export)\\s+)?(type)\\b"
    end: "(?=\\s*$)|(?=\\s*;)"
    beginCaptures:
      "1": { name: storage.modifier.visibility.luau }
      "2": { name: storage.type.luau }
    patterns:
      - include: "#type_literal" # handles generics declaration
      - match: "="
        name: keyword.operator.assignment.luau

  type_annotation: # Type annotations not matched by other rules (i.e., function return type)
    begin: ":(?!\\b({{identifier}})\\b(?=\\s*(?:[({\"']|\\[\\[)))" # negative lookahead: the syntax should not be of a method-call form `:name(`
    end: "(?<=\\))(?!\\s*->)|=|;|$|(?=\\breturn\\b)|(?=\\bend\\b)"
    patterns:
      - include: "#comment"
      - include: "#type_literal"

  type_cast:
    begin: "(::)"
    beginCaptures:
      "1": { name: keyword.operator.typecast.luau }
    end: (?=^|{{lookAheadEndOfType}})
    patterns:
      - include: "#type_literal"

  type_literal:
    patterns:
      - include: "#comment"
      - include: "#string"
      - match: "\\?|\\&|\\|"
        name: keyword.operator.type.luau
      - match: "->"
        name: keyword.operator.type.function.luau
      - match: "\\b(false)\\b"
        name: constant.language.boolean.false.luau
      - match: "\\b(true)\\b"
        name: constant.language.boolean.true.luau
      - name: support.type.primitive.luau
        match: "\\b(nil|string|number|boolean|thread|userdata|symbol|any)\\b"
      - begin: "\\b(typeof)\\b(\\()" # TODO: assign scope to punctuation?
        beginCaptures:
          "1": { name: support.function.luau }
          "2": { name: punctuation.arguments.begin.typeof.luau }
        end: "(\\))"
        endCaptures:
          "1": { name: punctuation.arguments.end.typeof.luau }
        patterns:
          - include: "source.luau"
      - begin: "(<)"
        end: "(>)"
        beginCaptures:
          "1": { name: punctuation.definition.typeparameters.begin.luau }
        endCaptures:
          "1": { name: punctuation.definition.typeparameters.end.luau }
        patterns:
          - match: "=" # for generics declarations
            name: keyword.operator.assignment.luau
          - include: "#type_literal"
      - match: "\\b({{identifier}})\\b"
        name: entity.name.type.luau
      - begin: "\\{"
        end: "\\}"
        patterns:
          - begin: "\\["
            end: "\\]" # TODO: do we need to match the ':' afterwards?
            patterns:
              - include: "#type_literal"
          - match: "\\b({{identifier}})\\b(:)"
            captures:
              "1": { name: variable.property.luau }
              "2": { name: keyword.operator.type.luau }
          - include: "#type_literal"
          - match: "[,;]"
            name: punctuation.separator.fields.type.luau
      - begin: "\\("
        end: "\\)"
        patterns:
          - name: variable.parameter.luau
            match: "\\b({{identifier}})\\b(:)"
            captures:
              "1": { name: variable.parameter.luau }
              "2": { name: keyword.operator.type.luau }
          - include: "#type_literal"

  attribute:
    patterns:
      # TODO: support parameters for attributes as defined in the RFC
      - name: meta.attribute.luau
        match: "(@)({{identifier}})"
        captures:
          "1": { name: keyword.operator.attribute.luau }
          "2": { name: storage.type.attribute.luau }