mcfunction.tmLanguage.yaml

name: Syntax Mcfunction

scopeName: source.mcfunction
uuid: 8918dadd-8ebe-42d9-b1e9-0489ab228d9d

fileTypes:
  - mcfunction
  - bolt

patterns:
  - include: "#root"

repository:
  root:
    patterns:
      - include: "#literals"
      - include: "#comments"
      - include: "#say"
      - include: "#names" # we do names before inline since inline comments can eat
      - include: "#comments_inline"
      - include: "#subcommands"
      - include: "#property"
      - include: "#operators" # ideally not so low but this eats into fakeplayers
      - include: "#selectors"

  # Comments have two styles
  # 1. Basic `# comment`, single line
  # 2. `#>`, etc. block comments
  #
  # We provide a subset of command highlighting within comments to enable
  #  docstring-esque type highlighting
  comments:
    patterns:
      - applyEndPatternLast: 1
        begin: ^\s*(#[>!#])(.+)$
        beginCaptures:
          "1":
            name: comment.block.mcfunction
          "2":
            name: markup.bold.mcfunction
        captures:
          "0":
            name: comment.block.mcfunction
        end: ^(?!#)
        name: meta.comments
        patterns:
          - include: "#comments_block"
      - captures:
          "0":
            name: comment.line.mcfunction
        match: '^\s*#.*$'
        name: meta.comments

  # `execute if entity @a run tellraw "hello"  # cool command here`
  #                                            ^^^^^^^^^^^^^^^^^^^
  comments_inline:
    patterns:
      - captures:
          "0":
            name: comment.line.mcfunction
        match: "#.*$"
        name: meta.comments

  comments_block:
    patterns:
      - applyEndPatternLast: 1
        begin: ^\s*#[>!]
        captures:
          "0":
            name: comment.block.mcfunction
        end: $
        name: meta.comments_block
        patterns:
          - include: "#comments_block_emphasized"
      - applyEndPatternLast: 1
        begin: ^\s*#
        captures:
          "0":
            name: comment.block.mcfunction
        end: $
        name: meta.comments_block
        patterns:
          - include: "#comments_block_normal"

  # Header comments (just bolded)
  # `#> This function does cool things`
  #     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  comments_block_emphasized:
    patterns:
      - include: "#comments_block_special"
      - captures:
          "0":
            name: markup.bold.mcfunction
        match: \S+
        name: meta.comments_block_emphasized

  #> Normal comments within a comment block
  comments_block_normal:
    patterns:
      - include: "#comments_block_special"
      - captures:
          "0":
            name: comment.block.mcfunction
        match: \S+
        name: meta.comments_block_normal
      - include: "#whitespace"

  # Special highlighting for resource locations and params
  # `# Taco Bell @rx97`
  #              ^^^^^
  # `# Caching handled by storage:location/over/here`
  #                       ^^^^^^^^^^^^^^^^^^^^^^^^^^
  # `# $mypack.raycast.result return`
  #    ^^^^^^^^^^^^^^^^^^^^^^
  comments_block_special:
    patterns:
      - captures:
          "0":
            name: markup.heading.mcfunction
        match: '@\S+'
        name: meta.comments_block_special
      - include: "#resource-name"
      - captures:
          "0":
            name: variable.other.mcfunction
        match: "[#%$][A-Za-z0-9_.#%$]+"
        name: meta.comments_block_special

  # Literals encompasses numbers, booleans, UUIDs, and strings
  literals:
    patterns:
      - captures:
          "0":
            name: constant.numeric.boolean.mcfunction
        match: \b(true|false|True|False)\b
        name: meta.literals
      - captures:
          "0":
            name: variable.uuid.mcfunction
        match: \b[0-9a-fA-F]+(?:-[0-9a-fA-F]+){4}\b
        name: meta.names
      - captures:
          "0":
            name: constant.numeric.float.mcfunction
        match: '[+-]?\d*\.?\d+([eE]?[+-]?\d+)?[df]?\b'
        name: meta.literals
      - captures:
          "0":
            name: constant.numeric.integer.mcfunction
        match: '[+-]?\d+(b|B|L|l|s|S)?\b'
        name: meta.literals

      # yea this should be operator, but i need this to exist before #names
      # otherwise `..0.5` will be a valid name
      - captures:
          "0":
            name: variable.other.mcfunction
        match: \.\.
        name: meta.ellipse.literals

      # Strings will encompass multiple lines meaning an unclosed quote will
      #  eat extra tokens.
      - applyEndPatternLast: 1
        begin: '"'
        beginCaptures:
          "0":
            name: punctuation.definition.string.begin.mcfunction
        end: '"'
        endCaptures:
          "0":
            name: punctuation.definition.string.end.mcfunction
        name: string.quoted.double.mcfunction
        patterns:
          - include: "#literals_string-double"
      - applyEndPatternLast: 1
        begin: "'"
        beginCaptures:
          "0":
            name: punctuation.definition.string.begin.mcfunction
        end: "'"
        endCaptures:
          "0":
            name: punctuation.definition.string.begin.mcfunction
        name: string.quoted.single.mcfunction
        patterns:
          - include: "#literals_string-single"

  # Simplistic highlighting for basic subcommands.
  subcommands:
    patterns:
      - captures:
          "0":
            name: entity.name.class.mcfunction
        match: "[a-z_]+" # "[A-Za-z_]+"
        name: meta.literals

  # Strings also have to account for `\`s esp, solo at the end of a line
  literals_string-double:
    patterns:
      - captures:
          "0":
            name: constant.character.escape.mcfunction
        match: \\.
        name: meta.literals_string-double
      - captures:
          "0":
            name: constant.character.escape.mcfunction
        match: \\
        name: meta.literals_string-double
      - include: "#macro-name"
      - captures:
          "0":
            name: string.quoted.double.mcfunction
        match: '[^\\"]'
        name: meta.literals_string-double

  literals_string-single:
    patterns:
      - captures:
          "0":
            name: constant.character.escape.mcfunction
        match: \\.
        name: meta.literals_string-single
      - captures:
          "0":
            name: constant.character.escape.mcfunction
        match: \\
        name: meta.literals_string-double
      - include: "#macro-name"
      - captures:
          "0":
            name: string.quoted.single.mcfunction
        match: '[^\\'']'
        name: meta.literals_string-single

  # We need to hardcode `say` to avoid greedy `'`s to break formatting
  # ex: `say Bob's uncle was pretty cool`, this would break commands that follow
  say:
    patterns:
      - begin: ^(\s*)(say)
        beginCaptures:
          "1":
            name: whitespace.mcfunction
          "2":
            name: keyword.control.flow.mcfunction
        end: \n
        name: meta.say.mcfunction
        patterns:
          - captures:
              "0":
                name: constant.character.escape.mcfunction
            match: \\\s*\n
            meta: meta.say.backslash.mcfunction
          - include: "#literals_string-double"
          - include: "#literals_string-single"
      - begin: (run)(\s+)(say)
        beginCaptures:
          "1":
            name: entity.name.mcfunction
          "2":
            name: whitespace.mcfunction
          "3":
            name: keyword.control.flow.mcfunction
        end: \n
        name: meta.say.mcfunction
        patterns:
          - captures:
              "0":
                name: constant.character.escape.mcfunction
            match: \\\s*\n
            meta: meta.say.backslash.mcfunction
          - include: "#literals_string-double"
          - include: "#literals_string-single"

  # Names are a very generic term in this grammar. They specially highlight the
  #  beginning of a line (and a word after `run`), handle macro commands, and
  #  fakeplayers.
  names:
    patterns:
      - captures:
          "1":
            name: whitespace.mcfunction
          "2":
            name: keyword.control.flow.mcfunction
        match: ^(\s*)([a-z_]+)(?=\s)
        name: meta.names
      - captures:
          "1":
            name: whitespace.mcfunction
          "2":
            name: markup.italic.mcfunction
          "3":
            name: whitespace.mcfunction
          "4":
            name: keyword.control.flow.mcfunction
        match: ^(\s*)(\$)( ?)([a-z_]*)
        name: meta.names
      - captures:
          "1":
            name: entity.name.mcfunction
          "2":
            name: whitespace.mcfunction
          "3":
            name: keyword.control.flow.mcfunction
        match: (run)(\s+)([a-z_]+)
        name: meta.names
      - include: "#resource-name"
      - captures:
          "0":
            name: entity.name.mcfunction
        match: '[A-Za-z]+(?=\W)'
        name: meta.names
      - captures:
          "0":
            name: string.unquoted.mcfunction
        match: "[A-Za-z_][A-Za-z0-9_.#%$]*"
        name: meta.names
      - include: "#macro-name"
      - captures:
          "0":
            name: variable.other.mcfunction
        match: '([#%$]|((?<=\s)\.))[A-Za-z0-9_.#%$\-]+'
        name: meta.names

  # These are for macro-names defined within a macro-line (including strings).
  # TODO: only activate this if the beginning of the line starts with `$`
  macro-name:
    patterns:
      - captures:
          "1":
            name: punctuation.definition.template-expression.begin.mcfunction
          "2":
            name: variable.other.mcfunction
          "3":
            name: punctuation.definition.template-expression.end.mcfunction
        match: '(\$\()([A-Za-z0-9_]*)(\))'
        name: meta.macro-name

  # General operators (including beyond mcfunction)
  operators:
    patterns:
      - captures:
          "0":
            name: constant.numeric.mcfunction
        match: "[~^]"
        name: meta.operators
      - captures:
          "0":
            name: keyword.operator.mcfunction
        match: '[\-%?!+*<>\\/|&=.:,;]'
        name: meta.operators

  # Properties are a subset of definitions that exist within `{}`, `[]`, or `()`s. They are a
  #  generic formula for highlighting key-value pairs, but are also capable of doing a good job
  #  for generic scoping (such as in mcbuild), JSON, or even python/js esque expressions. They
  #  can be nested as many times as needed as long as the brackets match!
  #
  # Unfortuntely, there's a bit of limitations based on how strict it is with mcfunction
  #  vs how accepting it is of foreign syntax. For example `[key:val]` and `[key: val]`
  #  highlight very differently as either a resource-name or a key/value.
  #
  # In the future, we could attempt a stricter property key-value scheme and then fall-back
  #  to a generic, more forgiving highlighting if the strict one fails. This would be complex
  #  though maybe needing some lookaheads, etc which could be not worth.
  property:
    patterns:
      - applyEndPatternLast: 1
        begin: \{
        captures:
          "0":
            name: punctuation.mcfunction
        end: \}
        name: meta.property.curly
        patterns:
          - include: "#resource-name"
          - include: "#literals"
          - include: "#property_key"
          - include: "#operators"
          - include: "#property_value"
          - include: $self
      - applyEndPatternLast: 1
        begin: \[
        captures:
          "0":
            name: variable.other.mcfunction
        end: \]
        name: meta.property.square
        patterns:
          - include: "#resource-name"
          - include: "#literals"
          - include: "#property_key"
          - include: "#operators"
          - include: "#property_value"
          - include: $self
      - applyEndPatternLast: 1
        begin: \(
        captures:
          "0":
            name: punctuation.mcfunction
        end: \)
        name: meta.property.paren
        patterns:
          - include: "#resource-name"
          - include: "#literals"
          - include: "#property_key"
          - include: "#operators"
          - include: "#property_value"
          - include: $self

  property_key:
    patterns:
      - captures:
          "0":
            name: variable.other.mcfunction
        match: '#?[a-z_][a-z_\.\-]*\:[a-z0-9_\.\-/]+(?=\s*\=:)'
        name: meta.property_key
      - captures:
          "0":
            name: variable.other.mcfunction
        match: '#?[a-z_][a-z0-9_\.\-/]+'
        name: meta.property_key
      - captures:
          "0":
            name: variable.other.mcfunction
        match: '[A-Za-z_]+[A-Za-z_\-\+]*'
        name: meta.property_key

  property_value:
    patterns:
      - captures:
          "0":
            name: string.unquoted.mcfunction
        match: '#?[a-z_][a-z_\.\-]*\:[a-z0-9_\.\-/]+'
        name: meta.property_value
      - captures:
          "0":
            name: string.unquoted.mcfunction
        match: '#?[a-z_][a-z0-9_\.\-/]+'
        name: meta.property_value

  resource-name:
    patterns:
      - captures:
          "0":
            name: entity.name.function.mcfunction
        match: "#?[a-z_][a-z0-9_.-]*:[a-z0-9_./-]+"
        name: meta.resource-name
      - captures:
          "0":
            name: entity.name.function.mcfunction
        match: '#?[a-z0-9_\.\-]+\/[a-z0-9_\.\-\/]+'
        name: meta.resource-name

  # Selectors consume more than 1 char after an `@` symbol to allow for fancier
  #  `@param` style highlighting like python decorators or even modded selectors.
  selectors:
    patterns:
      - captures:
          "0":
            name: support.class.mcfunction
        match: "@[a-z]+"
        name: meta.selectors