SPDF in Kotlin / JVM

// build.gradle.kts
dependencies {
    implementation("io.github.joseluissaorin:spdf:0.1.0")          // JVM
    // implementation("io.github.joseluissaorin:spdf-android:0.1.0") // Android
}

<dependency>
  <groupId>io.github.joseluissaorin</groupId>
  <artifactId>spdf</artifactId>
  <version>0.1.0</version>
</dependency>

import io.github.joseluissaorin.spdf.*

SpdfFile.open("quijote.spdf").use { f ->          // also legacy .spdf (gzip) files
    for (hit in f.searchLexical("«lugar de la Mancha»", limit = 5)) {
        println("${hit.fragmentId} ${hit.score} ${hit.anchorUri}")
        println(f.cite(hit.anchor!!, hit.anchorEnd, locale = "es"))
        // q4 1.889394 spdf:sha256-fa38…#p=5&pe=6&f=1r&fe=1v&char=101,278
        // (Cervantes Saavedra, 1605, fols. 1r-[1v])
    }
    val query = DoubleArray(8)                     // your own query embedding
    val nearest = f.searchVector(query, space = "toy-embedding@8", limit = 5)
    val fused = f.searchHybrid("hidalgo", query, "toy-embedding@8", limit = 5)
    println(f.exportBibTeX())

    // Resolution of a reference (SPEC §5.4) and structural exports (SPEC §19.4)
    val loc = f.locate("https://example.org/quijote.spdf#p=5&char=101,278")
    println("${loc.units} ${loc.fragments}")          // [p5] [q4]
    val alto: String = f.exportAlto()
    val tei: String = f.exportTei()
    val manifest: String = f.exportIiif(base = "https://example.org/quijote")
    val citeproc = f.exportCslJson(Anchor.page(5, "1r", foliation = "leaf"))   // with "label": "folio", "locator": "1r"
}

// Several documents in one bibliography (keys disambiguated with a, b, c…)
val items = listOf("a.spdf", "b.spdf").map { p -> SpdfFile.open(p).use { it.metadata() } }
println(Export.bibtex(items))
val csl = Json.compact(Export.cslItems(items))

// Validation and canonical dump
val result = Validator.validate("file.spdf")
println("${result.isValid} ${result.errorCodes} ${result.warningCodes}")
SpdfFile.open("file.spdf").use { f ->
    val jcs: String = f.dumpJson()                 // RFC 8785 bytes
    val sum: String = f.contentSha256()            // integrity hash of SPEC §18
}

// Anchors and citations
val a = Anchor.page(29, "21", source = "inferred")
val uri = AnchorUri.format("sha256-3f2a…", a)       // spdf:sha256-3f2a…#p=29&f=21
val parsed = AnchorUri.parse(uri)                    // strict: malformed URIs throw SpdfException
val text = Citation.cite(a, null, mapOf(
    "type" to "book", "title" to "Arte nuevo de hacer comedias",
    "author" to listOf(mapOf("family" to "Vega", "non-dropping-particle" to "de", "given" to "Lope")),
    "issued" to mapOf("date-parts" to listOf(listOf(1609))),
), "es")                                             // (de Vega, 1609, p. [21])

// Writing
// content_sha256 is written by default; a 32-byte Ed25519 seed also signs the file.
SpdfWriter.create(File("out.spdf"), WriterOptions(generator = "my-tool/1.0", signingKey = seed)).use { w ->
    w.setDocument(Document("doc", "pdf", "application/pdf", sha256Hex, mapOf("type" to "book", "title" to "…")))
    w.addUnit(CitableUnit("u1", Anchor.page(1, "1"), "…", reader = "pdf-text-layer"))
    w.addFragment(Fragment("f1", "u1", "…", Anchor.page(1, "1")))
    w.addSpace(Space("embeddinggemma-2@768", "local", "embeddinggemma-2", 768))
    w.addVector("fragment", "f1", "embeddinggemma-2@768", embedding)   // FloatArray or DoubleArray
    w.addBlob("pages/0001.png", "image/png", png)
    w.finish()   // rebuilds FTS, VACUUM, atomic move; closing without finish() discards the file
}

import io.github.joseluissaorin.spdf.*;
import io.github.joseluissaorin.spdf.sql.SqlDriver;
import java.util.List;
import java.util.Map;

try (SpdfFile f = SpdfFile.open("quijote.spdf")) {
    List<Hit> hits = f.searchLexical("lugar de la Mancha", 5);
    for (Hit h : hits) {
        System.out.println(h.getFragmentId() + " " + h.getAnchorUri());
        System.out.println(f.cite(h.getAnchor(), h.getAnchorEnd(), "en"));
    }
}

ValidationResult r = Spdf.validate("quijote.spdf");
System.out.println(r.isValid() + " " + r.getErrorCodes());

try (SpdfWriter w = SpdfWriter.create("out.spdf")) {
    Document d = new Document("lazarillo", "pdf", "application/pdf", sha256Hex,
        Map.of("type", "book", "title", "La vida de Lazarillo de Tormes"));
    d.setTitle("Lazarillo de Tormes");
    w.setDocument(d);
    w.addUnit(new CitableUnit("u1", Anchor.page(3, "A2r", "read", "leaf"), "Pues sepa Vuestra Merced", "pdf-text-layer"));
    Fragment frag = new Fragment("f1", "u1", "Pues sepa Vuestra Merced", Anchor.page(3, "A2r", "read", "leaf"));
    frag.setContext("Prólogo");
    w.addFragment(frag);
    w.finish();
}

AnchorUri.Parsed p = Spdf.parseUri("spdf:sha256-3f2a…#p=29&f=21");
SqlDriver driver = SqlDriver.defaultDriver();      // `default` is a Java keyword
Location where = SpdfFile.open("quijote.spdf").locate("spdf:sha256-fa38…#f=1v");
String cite = Spdf.cite(Anchor.verse(12), null, Json.parseObject("{\"title\":\"Rimas\",\"author\":[{\"family\":\"Bécquer\"}]}"), "es");

val driver = AndroidxSqlDriver()                                   // BundledSQLiteDriver inside
val options = OpenOptions(tempDir = context.cacheDir)              // gunzipped and private copies go here
SpdfFile.open(File(context.filesDir, "book.spdf"), driver, options).use { f ->
    val hits = f.searchLexical("golondrinas")
}

# with an emulator or device attached (ANDROID_HOME pointing at the SDK)
ANDROID_SERIAL=emulator-5584 ./gradlew -Pspdf.androidDevice=true :spdf-android-device:connectedAndroidTest

./gradlew :spdf:installDist
B=spdf/build/install/spdf/bin/spdf
$B validate file.spdf
$B dump file.spdf
$B search file.spdf "lugar de la Mancha" -n 5
$B vsearch file.spdf toy-embedding@8 0,0.5,0.25,0.75,0.25,0,0.25,0 -n 3
$B hybrid file.spdf toy-embedding@8 0,0.5,0.25,0.75,0.25,0,0.25,0 selection -n 3
$B cite file.spdf q4 --locale en
$B export file.spdf bibtex          # also csl, alto, tei, iiif
$B locate file.spdf 'spdf:sha256-…#f=1v'
$B uri parse 'spdf:sha256-…#p=29&f=21'
$B build source.json out.spdf
$B conformance ../conformance -o conformance.json

./gradlew build                      # unit tests; both adapters run the whole suite
./gradlew :spdf:conformance          # runner report in build/conformance.json
./gradlew :spdf:run --args="conformance ../conformance -o conformance.json"