Basics of tree-sitter queries

In the realm of code editing and syntax highlighting, Tree-sitter stands out as a groundbreaking tool that offers a robust solution for understanding the structure of source code in various programming languages. It's a parser generator tool and an incremental parsing library that allows developers to maintain high performance and precise syntax highlighting, code formatting, and more. This post delves into the core aspect of Tree-sitter that makes these features possible: Tree-sitter queries.

Have you not set up tree-sitter on your machine yet? Check this post - Tree-sitter 101.

What are Tree-sitter Queries?

Tree-sitter queries are a powerful mechanism for extracting information and patterns from the syntax tree generated by Tree-sitter. They allow developers to specify patterns in a language-agnostic way, enabling actions like syntax highlighting, code navigation, and other forms of static analysis across many programming languages with minimal effort.

A Tree-sitter query consists of a series of patterns that match nodes in the syntax tree based on their type, content, and relationships to other nodes.
These queries can be written in a S-expression syntax, making them both readable and expressive.

Why Use Tree-sitter Queries?

• Syntax Highlighting: With queries, syntax highlighting can adapt to the structure of the code rather than just the text, providing a more accurate and visually helpful highlighting.
• Code Navigation: Queries enable more sophisticated code navigation features, like jumping to definitions, finding references, and viewing documentation, by understanding the code’s semantics.
• Refactoring Tools: They can be used to build refactoring tools that operate with an understanding of the code’s syntax and semantics, making automated changes safer and more reliable.
• Static Analysis: Tree-sitter queries allow for detailed static analysis by querying the code for patterns that might indicate bugs or code smells.

Writing Your First Tree-sitter Query

To get started with Tree-sitter queries, you first need to have Tree-sitter installed and set up for your target language. Once you have a parsed syntax tree, you can begin writing queries.

Here’s a simple example to highlight function definitions in a JavaScript file:

; Match function declarations
((function_declaration
  name: (identifier) @function.name)
 (highlight @function.name "function.name"))

; Match variable declarations that are initialized with a function
((variable_declaration
  declarators: (variable_declarator
                value: (function) @function.name))
 (highlight @function.name "function.name"))

This query has two patterns: one for matching named function declarations and another for matching variables that are initialized with a function. The @function.name part is a capture name, which is used to refer to the matched nodes in the actions that follow (in this case, highlighting with the tag “function.name”).