feat!: update API to 0.25

Author: ObserverOfTime

ktreesitter/src/androidInstrumentedTest/kotlin/io/github/treesitter/ktreesitter/LanguageTest.kt

@@ -2,9 +2,9 @@ package io.github.treesitter.ktreesitter
 
 import br.com.colman.kotest.KotestRunnerAndroid
 import io.github.treesitter.ktreesitter.java.TreeSitterJava
-import io.kotest.assertions.throwables.shouldNotThrowAny
 import io.kotest.core.spec.style.FunSpec
 import io.kotest.matchers.*
+import io.kotest.matchers.collections.shouldBeEmpty
 import io.kotest.matchers.comparables.*
 import io.kotest.matchers.nulls.*
 import io.kotest.matchers.string.*
@@ -15,8 +15,8 @@ import org.junit.runner.RunWith
 class LanguageTest : FunSpec({
     val language = Language(TreeSitterJava.language())
 
-    test("version") {
-        language.version shouldBe 14U
+    test("abiVersion") {
+        language.abiVersion shouldBe 14U
     }
 
     test("symbolCount") {
@@ -31,6 +31,19 @@ class LanguageTest : FunSpec({
         language.fieldCount shouldBeGreaterThan 1U
     }
 
+    test("name") {
+        language.name.shouldBeNull()
+    }
+
+    test("metadata") {
+        language.metadata.shouldBeNull()
+    }
+
+    @OptIn(ExperimentalUnsignedTypes::class)
+    test("supertypes") {
+        language.supertypes.shouldBeEmpty()
+    }
+
     test("symbolName()") {
         language.symbolName(1U) shouldBe "identifier"
     }
@@ -40,6 +53,11 @@ class LanguageTest : FunSpec({
         language.symbolForName("program", true) shouldBeGreaterThan 0U
     }
 
+    @OptIn(ExperimentalUnsignedTypes::class)
+    test("subtypes") {
+        language.subtypes(1U).shouldBeEmpty()
+    }
+
     test("isNamed()") {
         language.isNamed(1U) shouldBe true
     }
@@ -72,10 +90,6 @@ class LanguageTest : FunSpec({
         lookahead.language shouldBe language
     }
 
-    test("query()") {
-        shouldNotThrowAny { language.query("(program) @root") }
-    }
-
     test("equals()") {
         Language(TreeSitterJava.language()) shouldBe language.copy()
     }
@@ -85,6 +99,6 @@ class LanguageTest : FunSpec({
     }
 
     test("toString()") {
-        language.toString() shouldMatch Regex("""Language\(id=0x[0-9a-f]+, version=14\)""")
+        language.toString() shouldMatch Regex("""Language\(id=0x[0-9a-f]+, abiVersion=14\)""")
     }
 })

ktreesitter/src/androidInstrumentedTest/kotlin/io/github/treesitter/ktreesitter/NodeTest.kt

@@ -149,6 +149,14 @@ class NodeTest : FunSpec({
         shouldThrow<IndexOutOfBoundsException> { rootNode.namedChild(1U) }
     }
 
+    test("firstChildForByte()") {
+        rootNode.firstChildForByte(10U)!!.type shouldBe "class_declaration"
+    }
+
+    test("firstNamedChildForByte()") {
+        rootNode.firstNamedChildForByte(10U)!!.type shouldBe "class_declaration"
+    }
+
     test("childByFieldId()") {
         rootNode.childByFieldId(0U).shouldBeNull()
     }
@@ -177,13 +185,6 @@ class NodeTest : FunSpec({
         rootNode.child(0U)!!.fieldNameForNamedChild(2U).shouldBeNull()
     }
 
-    @Suppress("DEPRECATION")
-    test("childContainingDescendant()") {
-        val descendant = rootNode.child(0U)!!.child(0U)!!
-        val child = rootNode.childContainingDescendant(descendant)
-        child?.type shouldBe "class_declaration"
-    }
-
     test("childWithDescendant()") {
         val descendant = rootNode.child(0U)!!
         val child = rootNode.childWithDescendant(descendant)

ktreesitter/src/androidInstrumentedTest/kotlin/io/github/treesitter/ktreesitter/ParserTest.kt

@@ -30,12 +30,6 @@ class ParserTest : FunSpec({
         parser.includedRanges shouldHaveSingleElement range
     }
 
-    test("timeoutMicros") {
-        parser.timeoutMicros shouldBe 0UL
-        parser.timeoutMicros = 10000UL
-        parser.timeoutMicros shouldBe 10000UL
-    }
-
     test("logger") {
         shouldNotThrowAnyUnit {
             parser.logger = { _, _ ->
@@ -61,12 +55,12 @@ class ParserTest : FunSpec({
         }
 
         // UTF-16
-        source = "var java = \"💩\""
-        tree = parser.parse(source)
-        tree.text()?.subSequence(12, 14) shouldBe "\uD83D\uDCA9"
+        source = "\uFEFFvar java = \"💩\""
+        tree = parser.parse(source, encoding = InputEncoding.UTF_16BE)
+        tree.text()?.subSequence(13, 15) shouldBe "\uD83D\uDCA9"
     }
 
-    test("parse(callback)") {
+    test("parse(readCallback)") {
         val source = "class Foo {}"
         val tree = parser.parse { byte, _ ->
             val end = minOf(byte.toInt() * 2, source.length)
@@ -79,7 +73,6 @@ class ParserTest : FunSpec({
     afterTest { (test, _) ->
         when (test.name.testName) {
             "includedRanges" -> parser.includedRanges = emptyList()
-            "timeoutMicros" -> parser.timeoutMicros = 0UL
             "logger" -> parser.logger = null
         }
     }

ktreesitter/src/androidMain/kotlin/io/github/treesitter/ktreesitter/InputEncoding.kt

@@ -0,0 +1,14 @@
+package io.github.treesitter.ktreesitter
+
+import java.nio.charset.Charset
+
+/**
+ * The encoding of the input text.
+ *
+ * @since 0.25.0
+ */
+actual enum class InputEncoding(val charset: Charset) {
+    UTF_8(Charsets.UTF_8),
+    UTF_16LE(Charsets.UTF_16LE),
+    UTF_16BE(Charsets.UTF_16BE)
+}

ktreesitter/src/androidMain/kotlin/io/github/treesitter/ktreesitter/Language.kt

@@ -6,12 +6,13 @@ import dalvik.annotation.optimization.FastNative
 /**
  * A class that defines how to parse a particular language.
  *
- * When a [Language] is generated by the Tree-sitter CLI, it is assigned
- * an ABI [version] number that corresponds to the current CLI version.
+ * When a [Language] is generated by the Tree-sitter CLI, it is assigned an
+ * [ABI version][abiVersion] number that corresponds to the current CLI version.
  *
  * @constructor Create a new instance from the given language pointer.
  * @param language A pointer to a `TSLanguage` cast to [Long].
- * @throws [IllegalArgumentException] If the pointer is invalid or the [version] is incompatible.
+ * @throws [IllegalArgumentException]
+ *  If the pointer is invalid or the [version][abiVersion] is incompatible.
  */
 actual class Language @Throws(IllegalArgumentException::class) actual constructor(language: Any) {
     @JvmField
@@ -22,7 +23,17 @@ actual class Language @Throws(IllegalArgumentException::class) actual constructo
         checkVersion()
     }
 
+    /**
+     * The ABI version number for this language.
+     *
+     * @since 0.25.0
+     */
+    @get:JvmName("getAbiVersion")
+    actual val abiVersion: UInt
+        @FastNative external get
+
     /** The ABI version number for this language. */
+    @Deprecated("version is deprecated", ReplaceWith("abiVersion"), DeprecationLevel.ERROR)
     @get:JvmName("getVersion")
     actual val version: UInt
         @FastNative external get
@@ -42,6 +53,32 @@ actual class Language @Throws(IllegalArgumentException::class) actual constructo
     actual val fieldCount: UInt
         @FastNative external get
 
+    /**
+     * The name of the language, if available.
+     *
+     * @since 0.25.0
+     */
+    actual val name: String?
+        @FastNative external get
+
+    /**
+     * The metadata of the language, if available.
+     *
+     * @since 0.25.0
+     */
+    actual val metadata: Metadata?
+        @FastNative external get
+
+    /**
+     * The supertype symbols of the language.
+     *
+     * @since 0.25.0
+     */
+    @OptIn(ExperimentalUnsignedTypes::class)
+    @get:JvmName("getSupertypes")
+    actual val supertypes: UShortArray
+        @FastNative external get
+
     /**
      * Get another reference to the language.
      *
@@ -59,6 +96,17 @@ actual class Language @Throws(IllegalArgumentException::class) actual constructo
     @JvmName("symbolForName")
     actual external fun symbolForName(name: String, isNamed: Boolean): UShort
 
+    /**
+     * Get the subtype symbols for the given supertype symbol
+     *
+     * @since 0.25.0
+     * @see supertypes
+     */
+    @FastNative
+    @JvmName("subtypes")
+    @OptIn(ExperimentalUnsignedTypes::class)
+    actual external fun subtypes(supertype: UShort): UShortArray
+
     /**
      * Check if the node for the given numerical ID is named
      *
@@ -119,24 +167,46 @@ actual class Language @Throws(IllegalArgumentException::class) actual constructo
 
     /**
      * Create a new [Query] from a string containing one or more S-expression
-     * [patterns](https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax).
+     * [patterns](https://tree-sitter.github.io/tree-sitter/using-parsers/queries/1-syntax.html).
      *
      * @throws [QueryError] If any error occurred while creating the query.
      */
     @Throws(QueryError::class)
+    @Deprecated("Use the Query constructor instead")
     actual fun query(source: String) = Query(this, source)
 
     actual override fun equals(other: Any?) =
         this === other || (other is Language && self == other.self)
 
     actual override fun hashCode() = self.hashCode()
 
-    override fun toString() = "Language(id=0x${self.toString(16)}, version=$version)"
+    override fun toString() = "Language(id=0x${self.toString(16)}, abiVersion=$abiVersion)"
 
     @FastNative
     @Throws(IllegalArgumentException::class)
     private external fun checkVersion()
 
+    /**
+     * A class containing the [Language] metadata.
+     *
+     * @property semanticVersion The [Semantic Version](https://semver.org/) of the [Language].
+     */
+    @ConsistentCopyVisibility
+    actual data class Metadata internal actual constructor(
+        @get:JvmName("getSemanticVersion")
+        actual val semanticVersion: Triple<UShort, UShort, UShort>
+    ) {
+        actual override fun toString() = buildString {
+            append("Metadata(semanticVersion=\"")
+            append(semanticVersion.first)
+            append('.')
+            append(semanticVersion.second)
+            append('.')
+            append(semanticVersion.third)
+            append("\")")
+        }
+    }
+
     private companion object {
         @JvmStatic
         @CriticalNative

ktreesitter/src/androidMain/kotlin/io/github/treesitter/ktreesitter/Node.kt

@@ -207,6 +207,26 @@ actual class Node internal constructor(
     @Throws(IndexOutOfBoundsException::class)
     actual external fun namedChild(index: UInt): Node?
 
+    /**
+     * Get the node's first child that contains
+     * or starts after the given byte offset.
+     *
+     * @since 0.25.0
+     */
+    @FastNative
+    @JvmName("firstChildForByte")
+    actual external fun firstChildForByte(byte: UInt): Node?
+
+    /**
+     * Get the node's first _named_ child that contains
+     * or starts after the given byte offset.
+     *
+     * @since 0.25.0
+     */
+    @FastNative
+    @JvmName("firstNamedChildForByte")
+    actual external fun firstNamedChildForByte(byte: UInt): Node?
+
     /**
      * Get the node's child with the given field ID, if any.
      *
@@ -249,14 +269,6 @@ actual class Node internal constructor(
     @Throws(IndexOutOfBoundsException::class)
     actual external fun fieldNameForNamedChild(index: UInt): String?
 
-    /** Get the child of the node that contains the given descendant, if any. */
-    @FastNative
-    @Deprecated(
-        "This method will not return a direct descendant",
-        ReplaceWith("childWithDescendant(descendant)", "io.github.treesitter.ktreesitter.Node")
-    )
-    actual external fun childContainingDescendant(descendant: Node): Node?
-
     /**
      * Get the node that contains the given descendant, if any.
      *

ktreesitter/src/androidMain/kotlin/io/github/treesitter/ktreesitter/Parser.kt

@@ -50,6 +50,7 @@ actual class Parser actual constructor() : AutoCloseable {
      */
     @get:JvmName("getTimeoutMicros")
     @set:JvmName("setTimeoutMicros")
+    @Deprecated("Use the progressCallback in parse()")
     actual var timeoutMicros: ULong
         @FastNative external get
 
@@ -82,11 +83,10 @@ actual class Parser actual constructor() : AutoCloseable {
      * [Tree.edit] method in a way that exactly matches the source code changes.
      *
      * @throws [IllegalStateException]
-     *  If the parser does not have a [language] assigned or
-     *  if parsing was cancelled due to a [timeout][timeoutMicros].
+     *  If the parser does not have a [language] assigned or if parsing was halted.
      */
     @Throws(IllegalStateException::class)
-    actual external fun parse(source: String, oldTree: Tree?): Tree
+    actual external fun parse(source: String, encoding: InputEncoding, oldTree: Tree?): Tree
 
     /**
      * Parse source code from a callback and create a syntax tree.
@@ -98,19 +98,22 @@ actual class Parser actual constructor() : AutoCloseable {
      * [Tree.edit] method in a way that exactly matches the source code changes.
      *
      * @throws [IllegalStateException]
-     *  If the parser does not have a [language] assigned or
-     *  if parsing was cancelled due to a [timeout][timeoutMicros].
+     *  If the parser does not have a [language] assigned or if parsing was halted.
      */
     @Throws(IllegalStateException::class)
-    actual external fun parse(oldTree: Tree?, callback: ParseCallback): Tree
+    actual external fun parse(
+        encoding: InputEncoding,
+        oldTree: Tree?,
+        progressCallback: ParseProgressCallback?,
+        readCallback: ParseReadCallback
+    ): Tree
 
     /**
      * Instruct the parser to start the next [parse] from the beginning.
      *
-     * If the parser previously failed because of a [timeout][timeoutMicros],
-     * then by default, it will resume where it left off. If you don't
-     * want to resume, and instead intend to use this parser to parse
-     * some other document, you must call this method first.
+     * If parsing was previously halted, then by default, it will resume where
+     * it left off. If you don't want to resume, and instead intend to use this
+     * parser to parse some other document, you must call this method first.
      */
     @FastNative
     actual external fun reset()

ktreesitter/src/commonMain/kotlin/io/github/treesitter/ktreesitter/InputEncoding.kt

@@ -0,0 +1,8 @@
+package io.github.treesitter.ktreesitter
+
+/**
+ * The encoding of the input text.
+ *
+ * @since 0.25.0
+ */
+expect enum class InputEncoding { UTF_8, UTF_16LE, UTF_16BE }