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.

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>

cpanm Text::Treesitter

perl -MCPAN -e shell
install Text::Treesitter