Using Parsers - Overview

Learn how to use Tree-sitter parsers in your applications

Introduction

This guide covers the fundamental concepts of using Tree-sitter, which is applicable across all programming languages. Although we’ll explore some C-specific details that are valuable for direct C API usage or creating new language bindings, the core concepts remain the same.

Tree-sitter’s parsing functionality is implemented through its C API, with all functions documented in the tree_sitter/api.h header file. If you’re working in another language, you can use one of the official language bindings:

Language Bindings

• Go - Idiomatic Go API
• Java - Java bindings with full API support
• JavaScript (Node.js) - Native Node.js addon
• Kotlin - Kotlin/JVM bindings
• Python - Python bindings with comprehensive API
• Rust - Safe Rust API with zero-cost abstractions
• Zig - Zig language bindings

Each binding provides idiomatic access to Tree-sitter’s functionality in that language.

The Basic Objects

There are four main types of objects involved when using Tree-sitter:

TSLanguage

An opaque object that defines how to parse a particular programming language. The code for each language is generated by Tree-sitter.

TSParser

A stateful object that can be assigned a language and used to produce syntax trees based on source code.

TSTree

Represents the syntax tree of an entire source code file. It contains nodes that indicate the structure of the source code.

TSNode

Represents a single node in the syntax tree. It tracks its start and end positions in the source code, as well as its relation to other nodes.

Building the Library

To build the library on a POSIX system, just run make in the Tree-sitter directory. This will create both static and dynamic libraries:

cd tree-sitter
make

This creates:

• libtree-sitter.a - Static library
• libtree-sitter.so / libtree-sitter.dylib - Dynamic library

Embedding in Your Project

Alternatively, you can incorporate the library in a larger project’s build system by adding one source file:

Source file:

• tree-sitter/lib/src/lib.c

Include directories:

• tree-sitter/lib/src
• tree-sitter/lib/include

Getting Started

Here’s a minimal example of using Tree-sitter to parse JSON:

C

#include <assert.h>
#include <string.h>
#include <stdio.h>
#include <tree_sitter/api.h>

const TSLanguage *tree_sitter_json(void);

int main() {
  // Create a parser
  TSParser *parser = ts_parser_new();
  
  // Set the parser's language
  ts_parser_set_language(parser, tree_sitter_json());
  
  // Parse source code
  const char *source_code = "[1, null]";
  TSTree *tree = ts_parser_parse_string(
    parser,
    NULL,
    source_code,
    strlen(source_code)
  );
  
  // Get the root node
  TSNode root_node = ts_tree_root_node(tree);
  
  // Print the syntax tree
  char *string = ts_node_string(root_node);
  printf("Syntax tree: %s\n", string);
  
  // Free memory
  free(string);
  ts_tree_delete(tree);
  ts_parser_delete(parser);
  return 0;
}

What’s Next?

Basic Parsing

Learn how to parse source code and work with syntax nodes

Advanced Parsing

Explore incremental parsing, editing, and multi-language documents

Walking Trees

Use tree cursors for efficient tree traversal

Pattern Matching

Query syntax trees with powerful pattern matching

Many languages are already available in the Tree-sitter GitHub organization and the Tree-sitter grammars organization.