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.

  • Constructor Details

    • Parser

      public Parser()
      Creates a new instance with a null language.
      See Also:
      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

      @Deprecated(since="0.25.0") @Unsigned public long getTimeoutMicros()
      Deprecated.
      Use Parser.Options instead.
      Get the maximum duration in microseconds that parsing should be allowed to take before halting.

    • setTimeoutMicros

      @Deprecated(since="0.25.0") public Parser setTimeoutMicros(@Unsigned long timeoutMicros)
      Deprecated.
      Use Parser.Options instead.
      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

      @Deprecated(since="0.25.0") public Parser setCancellationFlag(Parser.CancellationFlag cancellationFlag)
      Deprecated.
      Use Parser.Options instead.
      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(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(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 parseCallback, 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 parseCallback, InputEncoding encoding, Parser.Options options) 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 parseCallback, InputEncoding encoding, @Nullable Tree oldTree, @Nullable Parser.Options options) 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(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 parsing was previously halted, the parser 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