kPointer

Kotlin Multiplatform libraries for RFC 6901 JSON Pointer support.

Full documentation can be found at the kPointer Web site.

Quick example

import com.commonsware.kpointer.KPointer
import com.commonsware.kpointer.kxs.get
import kotlinx.serialization.json.Json

val doc = Json.parseToJsonElement("""{"a":{"b":"hello"}}""")
val value = doc[KPointer.from("/a/b")] // JsonPrimitive "hello", or null if absent

Modules

Module	Description
kpointer-core	RFC 6901 JSON Pointer parsing, navigation, and manipulation
kpointer-adapter	Generic adapter API for using JSON Pointer with any object-tree representation
kpointer-kxs	Read and mutate kotlinx.serialization JSON structures via JSON Pointers
kpointer-yamlkt	Read and mutate YamlKt YamlMap and YamlList structures via JSON Pointers
kpointer-ksoup	Read KSoup HTML and XML documents (elements and attributes) via JSON Pointers
kpointer-conformance	Conformance-suite runner and result types for testing a kPointer implementation (reference or custom adapter) against the portable fixtures
cli	Command-line tool for running the conformance suite against any implementation and for ad-hoc pointer resolution

See kpointer.commonsware.com/usage/ for dependency coordinates and usage guides, and kpointer.commonsware.com/cli/ for the CLI reference.

Conformance suite

The conformance/ directory holds a language-agnostic conformance suite that any JSON Pointer implementation can test itself against — see kpointer.commonsware.com/porting/. It's also published as a versioned, downloadable ZIP; see kpointer.commonsware.com/porting/distribution/.

Migrating from cw-json

kPointer supersedes the cw-json library. The API surface is mostly the same; the changes below cover everything that requires a code edit.

Dependencies

Replace the two cw-json artifacts with their kPointer equivalents:

Remove	Add
com.commonsware.json:kmp-jsonpointer	com.commonsware.kpointer:kpointer-core
com.commonsware.json:kmp-jsonpointer-kxs	com.commonsware.kpointer:kpointer-kxs

kpointer-kxs pulls in kpointer-adapter and kpointer-core transitively, so if you only use the kotlinx.serialization extensions you need only the one artifact.

Class rename: JsonPointer → KPointer

The pointer class was renamed from JsonPointer to KPointer and moved to a new package.

cw-json	kPointer
import com.commonsware.json.pointer.JsonPointer	import com.commonsware.kpointer.KPointer
JsonPointer.from(path)	KPointer.from(path)
JsonPointer.fromJsonPointer(path)	KPointer.fromKPointer(path)
JsonPointer.fromFragment(fragment)	KPointer.fromFragment(fragment)
JsonPointer.fromDotNotation(path)	KPointer.fromDotNotation(path)
JsonPointer.ROOT	KPointer.ROOT

All other members (isRoot, depth, parent, get(index), +, -, toString, toFragment, toDotNotation, pop) are unchanged.

getSegment(index) was already deprecated in cw-json in favour of get(index); update any remaining call sites now.

kxs package and imports

The kotlinx.serialization extensions moved to a new package. Update the import:

// before
import com.commonsware.json.pointer.kxs.*

// after
import com.commonsware.kpointer.kxs.*

kxs mutation DSL scope types

The DSL scope classes were renamed. This only affects code that references the types explicitly (e.g. a helper function that takes a scope as a parameter):

cw-json	kPointer
JsonObjectMutationScope	KpaStructMutationScope
JsonArrayMutationScope	KpaListMutationScope

Call sites that use the mutate { ... } lambda directly require no change beyond updating the import.

License

This project is licensed under the Apache License, Version 2.0.