{"id":2324,"library":"tree-sitter-java","title":"Tree-sitter Java Grammar","description":"The `tree-sitter-java` library provides the Tree-sitter grammar definition and source files for the Java programming language. It is designed to be used with the `tree-sitter` Python binding (or other language bindings) to parse Java code into a concrete syntax tree (CST) or abstract syntax tree (AST). The current version is `0.23.5`, and it follows the release cadence of the upstream Tree-sitter grammar.","status":"active","version":"0.23.5","language":"en","source_language":"en","source_url":"https://github.com/tree-sitter/tree-sitter-java","tags":["tree-sitter","parser","java","ast","syntax-analysis","grammar"],"install":[{"cmd":"pip install tree-sitter-java tree-sitter","lang":"bash","label":"Install `tree-sitter-java` and the `tree-sitter` Python binding"}],"dependencies":[{"reason":"The `tree-sitter` Python binding is required to load, build, and use the Java grammar provided by `tree-sitter-java`. This package only supplies the grammar's C source files.","package":"tree-sitter","optional":false}],"imports":[{"note":"The core class from the `tree-sitter` binding used to load or build language grammars.","symbol":"Language","correct":"from tree_sitter import Language"},{"note":"The core class from the `tree-sitter` binding used to parse code with a loaded language grammar.","symbol":"Parser","correct":"from tree_sitter import Parser"},{"note":"This module provides access to the Java grammar's source files, which are then used by `tree_sitter.Language.build_library`.","symbol":"tree_sitter_java","correct":"import tree_sitter_java"}],"quickstart":{"code":"import tree_sitter\nimport os\nimport pathlib\nimport tree_sitter_java # This package provides the grammar source files\n\n# Define a path where the shared library for the grammar will be built\n# It's good practice to put this in a temporary directory or a known cache location\ncache_dir = pathlib.Path.home() / \".tree_sitter_cache\"\ncache_dir.mkdir(parents=True, exist_ok=True)\njava_language_so = cache_dir / \"java_language.so\" # .dylib for macOS, .dll for Windows\n\n# Find the directory containing the Java grammar source files within the installed package\ntry:\n    java_grammar_dir = pathlib.Path(tree_sitter_java.__file__).parent / \"grammar\"\nexcept AttributeError:\n    print(\"Error: Could not determine package path for tree_sitter_java. Ensure it's installed correctly.\")\n    exit(1)\n\n# Ensure the grammar directory exists and contains necessary files (e.g., parser.c)\nif not java_grammar_dir.is_dir() or not (java_grammar_dir / \"parser.c\").is_file():\n    print(f\"Warning: Grammar source directory not found at {java_grammar_dir}. \")\n    print(\"You might need to adjust the path or manually download grammar files if the package structure differs.\")\n    exit(1)\n\nprint(f\"Using Java grammar sources from: {java_grammar_dir}\")\n\n# Build the language library (this requires a C compiler like GCC/Clang)\n# This step only needs to be done once per version of the grammar.\nif not java_language_so.exists():\n    try:\n        print(f\"Building Java grammar shared library to: {java_language_so}\")\n        tree_sitter.Language.build_library(\n            str(java_language_so),\n            [str(java_grammar_dir)]\n        )\n        print(\"Java grammar shared library built successfully.\")\n    except Exception as e:\n        print(f\"Error building Java grammar library: {e}\")\n        print(\"Ensure you have a C compiler (e.g., `gcc` or `clang`) installed and configured in your PATH.\")\n        exit(1)\nelse:\n    print(f\"Java grammar shared library already exists at: {java_language_so}\")\n\n# Load the built language\njava_language = tree_sitter.Language(str(java_language_so), 'java')\n\n# Create a parser for Java\nparser = tree_sitter.Parser()\nparser.set_language(java_language)\n\n# Example Java code\njava_code = \"\"\"\nclass MyClass {\n    /* A simple main method */\n    public static void main(String[] args) {\n        String message = \"Hello, Tree-sitter!\";\n        System.out.println(message);\n    }\n}\n\"\"\"\n\n# Parse the code\ntree = parser.parse(java_code.encode('utf-8')) # Tree-sitter expects bytes\n\n# Get the root node of the AST\nroot_node = tree.root_node\n\n# Print a simple representation of the AST\nprint(\"\\nParsed Java AST (first few children):\")\nfor child in root_node.children:\n    print(f\"- Type: {child.type}, Text: {child.text.decode('utf-8')[:70].strip()}...\")\n\n# Don't forget to close the parser and tree to release resources\nparser.close()\ntree.close()","lang":"python","description":"This quickstart demonstrates how to install `tree-sitter-java` and the `tree-sitter` binding, then build and load the Java grammar to parse a simple Java code snippet. It highlights the one-time build process for the shared library and basic AST traversal."},"warnings":[{"fix":"Install a C compiler (e.g., `sudo apt-get install build-essential` on Debian/Ubuntu, `xcode-select --install` on macOS, or Visual Studio Build Tools on Windows).","message":"Building the grammar's shared library requires a C compiler (like GCC or Clang) to be installed and accessible in your system's PATH. Without it, `tree_sitter.Language.build_library` will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always include `Language.build_library` in your setup script or ensure the shared library is built once and cached before loading the language.","message":"The `tree-sitter-java` PyPI package provides only the grammar's C source files, not a pre-compiled shared library. You must explicitly call `tree_sitter.Language.build_library` to compile these sources into a `.so`, `.dylib`, or `.dll` file before you can load and use the grammar.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the exact path to `parser.c` and `scanner.c` within the installed `tree-sitter-java` package. For more robust applications, consider using `importlib.resources.files` (Python 3.9+) to locate package data.","message":"The method to locate the grammar source files (e.g., `pathlib.Path(tree_sitter_java.__file__).parent / \"grammar\"`) relies on the internal packaging structure. While common, this path might change in future `tree-sitter-java` versions or vary based on installation methods.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly call `.close()` on `Parser` and `Tree` objects, or use them within a `with` statement if available for those objects (check `tree_sitter` documentation for context manager support).","message":"Tree-sitter objects like `Parser` and `Tree` manage external C resources. Failing to call `parser.close()` and `tree.close()` (or using them as context managers `with Parser() as parser:`) can lead to resource leaks, especially in long-running applications or when parsing many files.","severity":"gotcha","affected_versions":"All versions of `tree-sitter` binding"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}