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 that can be assigned a language and used to produce a Tree based on some source code. Instances of this class can not be created without an initially set language.

Since:

1.0.0

Author:

Tommy MacWilliam, Ozren Dabić

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Parser.Builder

Constructor Summary

Constructors

Constructor	Description
Parser(@NotNull Language language)	Deprecated, for removal: This API element is subject to removal in a future version. Use getFor(Language) or builder() instead

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.
static int	getLanguageVersion()	The latest ABI version that is supported by the current version of the library.
static int	getMinimumCompatibleLanguageVersion()	The earliest ABI version that is supported by the current version of the library.
long	getTimeout()	Get the duration in microseconds that parsing is allowed to take.
int	hashCode()
boolean	isNull()
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 parse a changed source code string, reusing unchanged parts of the tree to speed up the process.
Tree	parse(@NotNull Path path)	Use the parser to parse some source code found in a file at the specified path.
Tree	parse(@NotNull Path path, @NotNull Tree oldTree)	Use the parser to parse some source code found in a file at the specified path, reusing unchanged parts of the tree to speed up the process.
void	setLanguage(@NotNull Language language)	Set the language that the parser should use for parsing.
void	setTimeout(long timeout)	Set the maximum duration in microseconds that parsing should be allowed to take before halting.
void	setTimeout(long timeout, @NotNull TimeUnit timeUnit)	Set the maximum duration that parsing should be allowed to take before halting.
void	setTimeout(@NotNull Duration duration)	Set the maximum duration that parsing should be allowed to take before halting.
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Parser

@Deprecated(since="1.7.0",
            forRemoval=true)
public Parser(@NotNull
              @NotNull Language language)

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

Use getFor(Language) or builder() instead

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

getLanguageVersion

public static int getLanguageVersion()

The latest ABI version that is supported by the current version of the library. When languages are generated by the tree-sitter CLI, they are assigned an ABI version number that corresponds to the current CLI version.

The tree-sitter library is generally backwards-compatible with languages generated using older CLI versions, but is not forwards-compatible.

Returns:

latest ABI version number

Since:

1.6.0

getMinimumCompatibleLanguageVersion

public static int getMinimumCompatibleLanguageVersion()

The earliest ABI version that is supported by the current version of the library.

Returns:

earliest supported ABI version number

Since:

1.6.0

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

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 before halting. If parsing takes longer than this, an exception is thrown. Note that the supplied duration will be rounded down to 0 if the duration is expressed in nanoseconds.

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 before halting. If parsing takes longer than this, an exception is thrown. Note that the supplied duration will be rounded down to 0 if the duration is expressed in nanoseconds.

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 before halting. If parsing takes longer than this, an exception is thrown.

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 parse a changed source code string, reusing unchanged parts of the tree to speed up 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 some source code found in a file at the specified path.

Parameters:

path - The path of the file to be parsed

Returns:

A tree-sitter 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 parse some source code found in a file at the specified path, reusing unchanged parts of the tree to speed up the process.

Parameters:

path - The path of the file to be parsed

oldTree - The syntax tree before changes were made

Returns:

A tree-sitter Tree matching the provided source

Throws:

ParsingException - if a parsing failure occurs

Since:

1.3.0

toString

public String toString()

Overrides:

toString in class Object

isNull

public final boolean isNull()

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