Package ch.usi.si.seart.treesitter

Class Parser

java.lang.Object

ch.usi.si.seart.treesitter.Parser

All Implemented Interfaces:

AutoCloseable

public class Parser
extends Object

Parsers are stateful objects used to produce a Tree from some source code, based on the rules outlined by the used Language.

Since:

1.0.0

Author:

Tommy MacWilliam, Ozren Dabić

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Parser.Builder	Facilitates the construction of Parser instances.

Method Summary

Modifier and Type	Method	Description
static Parser.Builder	builder()	Obtain a new Builder for constructing a parser instance.
void	close()	Delete the external resource, freeing all the memory that it used.
boolean	equals(Object obj)
static Parser	getFor(@NotNull Language language)	Static factory for obtaining new parser instances.
List<Range>	getIncludedRanges()	Get an ordered, immutable Range sequence that corresponds to segments of source code included by the parser during parsing.
static int	getLanguageVersion()	Deprecated, for removal: This API element is subject to removal in a future version. Use TreeSitter.getCurrentABIVersion()
org.slf4j.Logger	getLogger()	Get the Logger instance used by the parser for writing debugging information during parsing.
static int	getMinimumCompatibleLanguageVersion()	Deprecated, for removal: This API element is subject to removal in a future version. Use TreeSitter.getMinimumABIVersion()
long	getTimeout()	Get the duration in microseconds that parsing is allowed to take.
int	hashCode()
boolean	isNull()	Checks whether the memory address associated with this external resource is nullptr.
Tree	parse(@NotNull String source)	Use the parser to parse some source code and create a syntax Tree.
Tree	parse(@NotNull String source, @NotNull Tree oldTree)	Use the parser to incrementally reparse a changed source code string, re-using unchanged parts of the Tree to expedite the process.
Tree	parse(@NotNull Path path)	Use the parser to parse source code from a file.
Tree	parse(@NotNull Path path, @NotNull Tree oldTree)	Use the parser to reparse source code from a file, re-using unchanged parts of the Tree to expedite the process.
void	setIncludedRanges(@NotNull Range... ranges)	Specify an arbitrary number of Range text segments that the parser should include when parsing source code.
void	setIncludedRanges(@NotNull List<@NotNull Range> ranges)	Specify a list of Range text segments that the parser should include when parsing source code.
void	setLanguage(@NotNull Language language)	Set the language that the parser should use for parsing.
void	setLogger(org.slf4j.Logger logger)	Set the Logger that a parser should use for writing debugging information during parsing.
void	setTimeout(long timeout)	Set the maximum duration in microseconds that parsing should be allowed to take.
void	setTimeout(long timeout, @NotNull TimeUnit timeUnit)	Set the maximum duration that parsing should be allowed to take.
void	setTimeout(@NotNull Duration duration)	Set the maximum duration that parsing should be allowed to take.
Parser.Builder	toBuilder()	Obtain a new Builder initialized with the current parser settings.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFor

public static Parser getFor(@NotNull
                            @NotNull Language language)

Static factory for obtaining new parser instances.

Parameters:

language - The language used for parsing

Returns:

A new parser instance

Since:

1.7.0

builder

public static Parser.Builder builder()

Obtain a new Builder for constructing a parser instance.

Returns:

a new parser builder

Since:

1.7.0

toBuilder

public Parser.Builder toBuilder()

Obtain a new Builder initialized with the current parser settings.

Returns:

a new parser builder

Since:

1.8.0

getLanguageVersion

@Deprecated(since="1.12.0",
            forRemoval=true)
public static int getLanguageVersion()

Deprecated, for removal: This API element is subject to removal in a future version.

Use TreeSitter.getCurrentABIVersion()

getMinimumCompatibleLanguageVersion

@Deprecated(since="1.12.0",
            forRemoval=true)
public static int getMinimumCompatibleLanguageVersion()

Deprecated, for removal: This API element is subject to removal in a future version.

Use TreeSitter.getMinimumABIVersion()

setLanguage

public void setLanguage(@NotNull
                        @NotNull Language language)

Set the language that the parser should use for parsing.

Parameters:

language - the language used for parsing

Throws:

NullPointerException - if the language is null

UnsatisfiedLinkError - if the language was not linked to native code

ABIVersionError - if the language ABI version is outdated

IncompatibleLanguageException - if the language can not be set

getLogger

public org.slf4j.Logger getLogger()

Get the Logger instance used by the parser for writing debugging information during parsing.

Returns:

the logger used by the parser

Since:

1.12.0

setLogger

public void setLogger(org.slf4j.Logger logger)

Set the Logger that a parser should use for writing debugging information during parsing. To disable logging, pass null as an argument.

By default, the parser will use the DEBUG level with a dedicated Marker for either the PARSE or LEX events.

Parameters:

logger - the logger used by the parser

Since:

1.12.0

getIncludedRanges

public List<Range> getIncludedRanges()

Get an ordered, immutable Range sequence that corresponds to segments of source code included by the parser during parsing. Returns an empty list when the included ranges were not set, i.e. when the parser is configured to include the entire source code.

Returns:

the included text ranges

Since:

1.12.0

setIncludedRanges

public void setIncludedRanges(@NotNull
                              @NotNull List<@NotNull Range> ranges)

Specify a list of Range text segments that the parser should include when parsing source code. This function allows you to parse only a portion of a document, while yielding a syntax tree whose ranges match up with the document as a whole. Although ranges can be disjoint, they must be ordered from earliest to latest in the source, and they must not overlap. In other words, the following must hold for each Range at index i:

 ranges[i].end_byte <= ranges[i + 1].start_byte
 

Passing an empty list will clear any previously set ranges, causing the parser to include the entire source code.

Parameters:

ranges - the included text ranges

Throws:

NullPointerException - if the list is null or contains null values

IllegalArgumentException - if the range overlap invariant is violated

Since:

1.12.0

setIncludedRanges

public void setIncludedRanges(@NotNull
                              @NotNull Range... ranges)

Specify an arbitrary number of Range text segments that the parser should include when parsing source code. This function allows you to parse only a portion of a document, while yielding a syntax tree whose ranges match up with the document as a whole. Although ranges can be disjoint, they must be ordered from earliest to latest in the source, and they must not overlap. In other words, the following must hold for each Range at index i:

 ranges[i].end_byte <= ranges[i + 1].start_byte
 

Passing no arguments will clear any previously set ranges, causing the parser to include the entire source code.

Parameters:

ranges - the included text ranges

Throws:

NullPointerException - if any value is null

IllegalArgumentException - if the range overlap invariant is violated

Since:

1.12.0

getTimeout

public long getTimeout()

Get the duration in microseconds that parsing is allowed to take.

Returns:

the timeout duration set for parsing, 0 if it was not set

Since:

1.1.0

setTimeout

public void setTimeout(@NotNull
                       @NotNull Duration duration)

Set the maximum duration that parsing should be allowed to take. If parsing time exceeds this value, an exception is thrown. The duration is rounded down to zero if it does not exceed one microsecond. Timeouts are considered disabled when the value is zero.

Parameters:

duration - the timeout duration

Throws:

NullPointerException - if the duration is null

Since:

1.1.0

setTimeout

public void setTimeout(long timeout,
                       @NotNull
                       @NotNull TimeUnit timeUnit)

Set the maximum duration that parsing should be allowed to take. If parsing time exceeds this value, an exception is thrown. The duration is rounded down to zero if it does not exceed one microsecond. Timeouts are considered disabled when the value is zero.

Parameters:

timeout - the timeout duration amount

timeUnit - the duration time unit

Throws:

NullPointerException - if the time unit is null

IllegalArgumentException - if the timeout value is negative

Since:

1.1.0

setTimeout

public void setTimeout(long timeout)

Set the maximum duration in microseconds that parsing should be allowed to take. If parsing time exceeds this value, an exception is thrown. Timeouts are considered disabled when the value is zero.

Parameters:

timeout - the timeout in microseconds

Throws:

IllegalArgumentException - if the timeout value is negative

Since:

1.1.0

parse

public Tree parse(@NotNull
                  @NotNull String source)
           throws ParsingException

Use the parser to parse some source code and create a syntax Tree.

Parameters:

source - the source code string to be parsed

Returns:

a syntax tree matching the provided source

Throws:

ParsingException - if a parsing failure occurs

Since:

1.3.0

parse

public Tree parse(@NotNull
                  @NotNull String source,
                  @NotNull
                  @NotNull Tree oldTree)
           throws ParsingException

Use the parser to incrementally reparse a changed source code string, re-using unchanged parts of the Tree to expedite the process.

Parameters:

source - the source code string to be parsed

oldTree - the syntax tree before changes were made

Returns:

a syntax tree matching the provided source

Throws:

ParsingException - if a parsing failure occurs

Since:

1.3.0

parse

public Tree parse(@NotNull
                  @NotNull Path path)
           throws ParsingException

Use the parser to parse source code from a file.

Parameters:

path - the path of the file to be parsed

Returns:

a syntax tree matching the provided source

Throws:

ParsingException - if a parsing failure occurs

Since:

1.3.0

parse

public Tree parse(@NotNull
                  @NotNull Path path,
                  @NotNull
                  @NotNull Tree oldTree)
           throws ParsingException

Use the parser to reparse source code from a file, re-using unchanged parts of the Tree to expedite the process.

Parameters:

path - the path of the file to be parsed

oldTree - the syntax tree before changes were made

Returns:

a syntax tree matching the provided source

Throws:

ParsingException - if a parsing failure occurs

Since:

1.3.0

isNull

public final boolean isNull()

Checks whether the memory address associated with this external resource is nullptr.

Returns:

true if the memory address is 0, otherwise false

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

close

public void close()

Delete the external resource, freeing all the memory that it used.

Specified by:

close in interface AutoCloseable