NAME

    Text::Treesitter - Perl binding for tree-sitter

SYNOPSIS

       use Text::Treesitter;
    
       my $ts = Text::Treesitter->new(
          lang_name => "perl",
       );
    
       my $tree = $ts->parse_string( $input );
    
       my $root = $tree->root_node;
    
       ...

DESCRIPTION

    This module provides several classes and utilities that wrap the
    tree-sitter parser library. A toplevel class is provided by this module
    which wraps the functionallity of several other classes, which are also
    available directly in the following modules:

      * Text::Treesitter::Language - represents a tree-sitter language
      grammar

      * Text::Treesitter::Node - an element of a tree-sitter parse result

      * Text::Treesitter::Parser - parse some input text according to a
      tree-sitter grammar

      * Text::Treesitter::Query - represents a set of tree-sitter query
      patterns

      * Text::Treesitter::QueryCursor - stores the result of a tree-sitter
      node query

      * Text::Treesitter::QueryMatch - stores the result of a tree-sitter
      query pattern match

      * Text::Treesitter::Tree - holds the result of a tree-sitter parse
      operation

CONSTRUCTOR

 new

       $ts = Text::Treesitter->new( %params );

    Returns a new Text::Treesitter instance. Takes the following named
    parameters:

    lang => Text::Treesitter::Language

      Optional. An instance of Text::Treesitter::Language to use in the
      parser.

    lang_name => STRING

      Optional. Gives the short name of the tree-sitter language grammar.

      Exactly one of lang or lang_name must be provided.

    lang_lib => STRING

      Gives the path to the compiled object file which contains the
      language grammar. Optional; if not provided it will be presumed to be
      named based on the language name, as tree-sitter-$LANG.so within the
      language directory. If the path does not contain a / character, it
      will have the language directory path prepended onto it.

    lang_dir => STRING

      Gives the directory name in which to find the compiled object file
      which contains the language grammar, or the sources to build it from.

      If not specified, a search will be made for a directory named
      tree-sitter-$LANG among any of the user's configured parser
      directories, as given by the tree-sitter config file.

METHODS

 treesitter_config

       $config = Text::Treesitter->treesitter_config;

    Returns a data structure containing the user's tree-sitter config,
    parsed from $HOME/.config/tree-sitter/config.json if it exists. If
    there is no file then undef is returned.

    This is usable as a class method.

 parser

       $parser = $ts->parser;

    Returns the Text::Treesitter::Parser instance being used. The
    constructor ensures that this will have a language set on it.

 lang

       $lang = $ts->lang;

    Returns the Text::Treesitter::Language instance being used by the
    parser.

 lang_dir

       $dir = $ts->lang_dir;

    Returns the directory path to the language directory. This is either
    the configured path that was set by the lang_dir parameter, or
    discovered by searching if one was not.

 parse_string

       $tree = $ts->parse_string( $str );

    Parses a given input string using the internal parser, returning a node
    tree as an instance of Text::Treesitter::Tree.

 parse_string_range

       $tree = $ts->parse_string_range( $str, %options );

    Since version 0.10.

    Parses a given input string using the internal parser, within the given
    byte range. Returns a node tree as an instance of
    Text::Treesitter::Tree.

    Takes the following named options:

    start_byte

    end_byte

      The start and end position within the string, in byte counts.

 load_query_string

       $query = $ts->load_query_string( $str );

    Creates a Text::Treesitter::Query instance by compiling the match
    patterns given in the source string for the language used by the
    parser.

 query_file_path

       $path = %ts->query_file_path( $name );

    If a file exists of the given path, then it is returned directly.
    Otherwise, returns a path within the language directory given by
    lang_dir; either directly or within a subdirectory called queries/.

 load_query_file

       $query = $ts->load_query_file( $name );

    Creates a Text::Treesitter::Query instance by loading the text from the
    given path, and then compiling it as per "load_query_string". The name
    is resolved into a path by using "query_file_path".

TODO

    The following C library functions are currently unhandled:

       the entire TSTreeCursor API

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>