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.

    start_row

    start_column

      Since version 0.11.

      Optionally, the logical position within the original source that
      corresponds to the start byte. These values don't affect parsing as
      such, but will be reflected in the position offsets of the nodes in
      the returned tree.

    node

      Since version 0.11.

      Alternative to specifying the four values given above, where they are
      all taken from the given Text::Treesitter::Node instance directly.

 parse_file

       $tree = $ts->parse_file( $path );

    Since version 0.13.

    Reads the file content as a string, then applies "parse_string" on it.

 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>