Package io.github.treesitter.jtreesitter

Class Parser

java.lang.Object

io.github.treesitter.jtreesitter.Parser

All Implemented Interfaces:

AutoCloseable

@NullMarked
public final class Parser
extends Object
implements AutoCloseable

A class that is used to produce a syntax tree from source code.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Parser.CancellationFlag	A class representing a cancellation flag.

Constructor Summary

Constructors

Constructor	Description
Parser()	Creates a new instance with a null language.
Parser(Language language)	Creates a new instance with the given language.

Method Summary

Modifier and Type	Method	Description
void	close()
List<Range>	getIncludedRanges()	Get the ranges of text that the parser should include when parsing.
@Nullable Language	getLanguage()	Get the language that the parser will use for parsing.
long	getTimeoutMicros()	Get the maximum duration in microseconds that parsing should be allowed to take before halting.
Optional<Tree>	parse(ParseCallback callback, InputEncoding encoding)	Parse source code from a callback and create a syntax tree.
Optional<Tree>	parse(ParseCallback callback, InputEncoding encoding, @Nullable Tree oldTree)	Parse source code from a callback and create a syntax tree.
Optional<Tree>	parse(String source)	Parse source code from a string and create a syntax tree.
Optional<Tree>	parse(String source, InputEncoding encoding)	Parse source code from a string and create a syntax tree.
Optional<Tree>	parse(String source, InputEncoding encoding, @Nullable Tree oldTree)	Parse source code from a string and create a syntax tree.
Optional<Tree>	parse(String source, Tree oldTree)	Parse source code from a string and create a syntax tree.
void	reset()	Instruct the parser to start the next parse from the beginning.
Parser	setCancellationFlag(Parser.CancellationFlag cancellationFlag)	Set the parser's current cancellation flag.
Parser	setIncludedRanges(List<Range> includedRanges)	Set the ranges of text that the parser should include when parsing.
Parser	setLanguage(Language language)	Set the language that the parser will use for parsing.
Parser	setLogger(@Nullable Logger logger)	Set the logger that the parser will use during parsing.
Parser	setTimeoutMicros(long timeoutMicros)	Set the maximum duration in microseconds that parsing should be allowed to take before halting.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

Parser

public Parser()

Creates a new instance with a null language.

API Note:

Parsing cannot be performed while the language is null.

Parser

public Parser(Language language)

Creates a new instance with the given language.

Method Details

getLanguage

public @Nullable Language getLanguage()

Get the language that the parser will use for parsing.

setLanguage

public Parser setLanguage(Language language)

Set the language that the parser will use for parsing.

getTimeoutMicros

@Unsigned
public long getTimeoutMicros()

Get the maximum duration in microseconds that parsing should be allowed to take before halting.

setTimeoutMicros

public Parser setTimeoutMicros(@Unsigned
 long timeoutMicros)

Set the maximum duration in microseconds that parsing should be allowed to take before halting.

setLogger

public Parser setLogger(@Nullable Logger logger)

Set the logger that the parser will use during parsing.

Example

import java.util.logging.Logger;

Logger logger = Logger.getLogger("tree-sitter");
Parser parser = new Parser().setLogger(
   (type, message) -> logger.info("%s - %s".formatted(type.name(), message)));

setCancellationFlag

public Parser setCancellationFlag(Parser.CancellationFlag cancellationFlag)

Set the parser's current cancellation flag.

The parser will periodically read from this flag during parsing. If it reads a non-zero value, it will halt early.

getIncludedRanges

public List<Range> getIncludedRanges()

Get the ranges of text that the parser should include when parsing.

API Note:

By default, the parser will always include entire documents.

setIncludedRanges

public Parser setIncludedRanges(List<Range> includedRanges)

Set the ranges of text that the parser should include when parsing.

This allows you to parse only a portion of a document but still return a syntax tree whose ranges match up with the document as a whole. You can also pass multiple disjoint ranges.

Throws:

IllegalArgumentException - If the ranges overlap or are not in ascending order.

parse

public Optional<Tree> parse(String source)
                     throws IllegalStateException

Parse source code from a string and create a syntax tree.

Returns:

An optional Tree which is empty if parsing was halted.

Throws:

IllegalStateException - If the parser does not have a language assigned.

parse

public Optional<Tree> parse(String source,
 InputEncoding encoding)
                     throws IllegalStateException

Parse source code from a string and create a syntax tree.

Returns:

An optional Tree which is empty if parsing was halted.

Throws:

IllegalStateException - If the parser does not have a language assigned.

parse

public Optional<Tree> parse(String source,
 Tree oldTree)
                     throws IllegalStateException

Parse source code from a string and create a syntax tree.

If you have already parsed an earlier version of this document and the document has since been edited, pass the previous syntax tree to oldTree so that the unchanged parts of it can be reused. This will save time and memory.
For this to work correctly, you must have already edited the old syntax tree using the Tree.edit(io.github.treesitter.jtreesitter.InputEdit) method in a way that exactly matches the source code changes.

Returns:

An optional Tree which is empty if parsing was halted.

Throws:

IllegalStateException - If the parser does not have a language assigned.

parse

public Optional<Tree> parse(String source,
 InputEncoding encoding,
 @Nullable Tree oldTree)
                     throws IllegalStateException

Parse source code from a string and create a syntax tree.

If you have already parsed an earlier version of this document and the document has since been edited, pass the previous syntax tree to oldTree so that the unchanged parts of it can be reused. This will save time and memory.
For this to work correctly, you must have already edited the old syntax tree using the Tree.edit(io.github.treesitter.jtreesitter.InputEdit) method in a way that exactly matches the source code changes.

Returns:

An optional Tree which is empty if parsing was halted.

Throws:

IllegalStateException - If the parser does not have a language assigned.

parse

public Optional<Tree> parse(ParseCallback callback,
 InputEncoding encoding)
                     throws IllegalStateException

Parse source code from a callback and create a syntax tree.

Returns:

An optional Tree which is empty if parsing was halted.

Throws:

IllegalStateException - If the parser does not have a language assigned.

parse

public Optional<Tree> parse(ParseCallback callback,
 InputEncoding encoding,
 @Nullable Tree oldTree)
                     throws IllegalStateException

Parse source code from a callback and create a syntax tree.

If you have already parsed an earlier version of this document and the document has since been edited, pass the previous syntax tree to oldTree so that the unchanged parts of it can be reused. This will save time and memory.
For this to work correctly, you must have already edited the old syntax tree using the Tree.edit(io.github.treesitter.jtreesitter.InputEdit) method in a way that exactly matches the source code changes.

Returns:

An optional Tree which is empty if parsing was halted.

Throws:

IllegalStateException - If the parser does not have a language assigned.

reset

public void reset()

Instruct the parser to start the next parse from the beginning.

API Note:

If the parser previously stopped because of a timeout or cancellation, it will resume where it left off.
If you intend to parse another document instead, you must call this method first.

close

public void close()
           throws RuntimeException

Specified by:

close in interface AutoCloseable

Throws:

RuntimeException

toString

public String toString()

Overrides:

toString in class Object