YAML Grammar for Tree-sitter

Warnings

• breaking Tree-sitter grammars are compiled against a specific ABI version of the core Tree-sitter library. Updating the `tree-sitter` Python package (or underlying C library) without a corresponding `tree-sitter-yaml` update can lead to 'Incompatible language version' errors.
  Fix: Ensure `tree-sitter-yaml` and the core `tree-sitter` library are compatible. If you encounter this error, try updating both packages to their latest versions or consult release notes for compatibility information.
• gotcha Directly using the `tree-sitter` library often involves compiling grammars. However, `tree-sitter-yaml` (and `tree-sitter-languages`) provides pre-compiled binary wheels. Attempting manual compilation (`Language.build_library()`) for these packages is usually unnecessary and can lead to errors or confusion if the package already supplies a pre-built grammar.
  Fix: For `tree-sitter-yaml`, simply load the `language()` function directly. If using `tree-sitter-languages`, use `get_language()` and `get_parser()`. Only manually compile if you are working with a grammar that does not provide pre-built Python wheels.
• gotcha Some users have reported memory leaks or unexpected highlighting issues when reusing Tree-sitter YAML parsers, especially with very large files or specific text editing patterns in integrated environments (e.g., Neovim). This can manifest as broken highlighting or increased memory consumption.
  Fix: If experiencing memory issues with reused parsers or large YAML files, consider re-initializing the parser for new files, ensuring the correct language name is passed, or investigating if the issue lies within the integrating application (e.g., editor plugin). Consult the `tree-sitter` core library issues for potential upstream fixes or workarounds.
• breaking Downstream tools relying on Tree-sitter grammars (e.g., `nvim-treesitter` for syntax highlighting) may experience breaking changes if Tree-sitter's internal capture group naming conventions are updated. This requires corresponding updates in client applications' configurations, queries, or color schemes.
  Fix: Update the consuming application or its configuration (e.g., Neovim plugins, color schemes, custom queries) to align with the new Tree-sitter capture group names. Refer to the specific application's documentation or migration guides for details on affected groups (e.g., `@parameter` to `@variable.parameter`).

Install

• pip install tree-sitter-yaml Install stable version

Imports

• language

  import tree_sitter_yaml
  from tree_sitter import Language, Parser
  
  YAML_LANGUAGE = Language(tree_sitter_yaml.language())

  Imports the pre-compiled YAML grammar and initializes it with the core Tree-sitter Language object.
• get_language, get_parser

  from tree_sitter_languages import get_language, get_parser
  
  # Or, for YAML specifically if available via this package
  language = get_language('yaml')
  parser = get_parser('yaml')

  If using the 'tree-sitter-languages' package, grammars (including YAML) can be loaded conveniently by name. Requires 'tree-sitter-languages' to be installed.

Quickstart

This quickstart demonstrates how to initialize the Tree-sitter parser with the `tree-sitter-yaml` grammar, parse a YAML byte string, traverse the resulting syntax tree, and execute a basic Tree-sitter query to extract key-value pairs.

import tree_sitter_yaml
from tree_sitter import Language, Parser

# Load the YAML language grammar
YAML_LANGUAGE = Language(tree_sitter_yaml.language())

# Initialize the parser with the YAML language
parser = Parser()
parser.set_language(YAML_LANGUAGE)

# Example YAML content
yaml_code = b"""
name: John Doe
age: 30
cities:
  - New York
  - London
"""

# Parse the YAML code
tree = parser.parse(yaml_code)

# Get the root node of the syntax tree
root_node = tree.root_node

# Print the tree structure (simplified for quickstart)
def print_node(node, indent=0):
    print('  ' * indent + f"Type: {node.type}, Text: {node.text.decode('utf8')}")
    for child in node.children:
        print_node(child, indent + 1)

print_node(root_node)

# Example: Find a specific node type (e.g., 'pair')
query = YAML_LANGUAGE.query("""
(pair (key) @key (value) @value)
""")
captures = query.captures(root_node)

print("\nKey-Value Pairs:")
for node, name in captures:
    if name == 'key':
        key_text = node.text.decode('utf8')
    elif name == 'value':
        value_text = node.text.decode('utf8')
        print(f"  Key: {key_text}, Value: {value_text}")