From d8fbf88acf394529f7f53e0f0b34702886da849f Mon Sep 17 00:00:00 2001 From: Alexander Ioffe Date: Wed, 31 Jan 2024 00:41:17 -0500 Subject: [PATCH] Move namespaces. Begin adding some more docs. --- README.md | 32 ++++++++++++++++--- build.gradle.kts | 2 +- .../kotlin/io/exoquery/{ => kmp}/Base.kt | 4 +-- .../io/exoquery/{ => kmp}/pprint/PPrinter.kt | 10 ++++-- .../{ => kmp}/pprint/PPrinterHelper.kt | 4 ++- .../{ => kmp}/pprint/TreeElementEncoder.kt | 4 ++- .../kotlin/io/exoquery/pprint/Check.kt | 1 + .../io/exoquery/pprint/VerticalTests.kt | 2 ++ .../kotlin/io/exoquery/pprint/Example2.kt | 4 ++- 9 files changed, 50 insertions(+), 13 deletions(-) rename pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/{ => kmp}/Base.kt (91%) rename pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/{ => kmp}/pprint/PPrinter.kt (92%) rename pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/{ => kmp}/pprint/PPrinterHelper.kt (95%) rename pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/{ => kmp}/pprint/TreeElementEncoder.kt (98%) diff --git a/README.md b/README.md index e48529e..3438fc2 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,15 @@ Add the following to your build.gradle.kts: ```kotlin implementation("io.exoquery:pprint-kotlin:1.1.0") + +// For Kotlin Multiplatform use: +implementation("io.exoquery:pprint-kotlin-kmp:1.1.0") ``` Then use the library like this: ```kotlin import io.exoquery.pprint +// For kotlin multiplatform use: import io.exoquery.kmp.pprint data class Name(val first: String, val last: String) data class Person(val name: Name, val age: Int) @@ -164,7 +168,7 @@ println(pprint(parent, defaultHeight = 10)) The output of the pprint function is not actually a java.lang.String, but a fansi.Str. This means you can control how it is printed. For example, to print it in black and white simple do: ```kotlin -import io.exoquery.pprint.PPrinter +import io.exoquery.pprint val p = Person(Name("Joe", "Bloggs"), 42) @@ -177,7 +181,7 @@ println(pprint(p).plainText) In order to extend pprint, subclass the PPrinter class and override the `treeify` function. For example: ```kotlin -class CustomPPrinter1(config: PPrinterConfig) : PPrinter(config) { +class CustomPPrinter1(val config: PPrinterConfig) : PPrinter(config) { override fun treeify(x: Any?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree = when (x) { is java.time.LocalDate -> Tree.Literal(x.format(DateTimeFormatter.ofPattern("MM/dd/YYYY"))) @@ -192,6 +196,24 @@ val joe = Person("Joe", LocalDate.of(1981, 1, 1)) println(pp.invoke(joe)) //> Person(name = "Joe", born = 01/01/1981) ``` +This printer can then be used as the basis of a custom `pprint`-like user defined function. + +> ### Note for Kotlin Multiplatform +> In Kotlin Multiplatform, the PPrinter is parametrized and takes an additional `SerializationStrategy` parameter. +> You can extend it like this: +> ```kotlin +> class CustomPPrinter1(val serializer: SerializationStrategy, val config: PPrinterConfig) : PPrinter(config) { +> ... +> } +> +> // You can then use this class like so: +> @Serializeable data class Person(val name: String, val born: LocalDate) +> val pp = CustomPPrinter1(Person.serializer(), PPrinterConfig()) +> val joe = Person("Joe", LocalDate.of(1981, 1, 1)) +> println(pp.invoke(joe)) +> ``` +> TODO finish this example and write docs for how to write a custom pprint function that uses serializer instead of requring passing it in +> You can then use this () For nested objects use Tree.Apply and recursively call the treeify method. ```kotlin @@ -202,7 +224,7 @@ class MyJavaBean(val a: String, val b: Int) { } // Create the custom printer -class CustomPPrinter2(config: PPrinterConfig) : PPrinter(config) { +class CustomPPrinter2(val config: PPrinterConfig) : PPrinter(config) { override fun treeify(x: Any?, esc: Boolean, names: Boolean): Tree = when (x) { // List through the properties of 'MyJavaBean' and recursively call treeify on them. @@ -220,7 +242,7 @@ println(pp.invoke(bean)) To print field-names you use Tree.KeyValue: ```kotlin -class CustomPPrinter3(config: PPrinterConfig) : PPrinter(config) { +class CustomPPrinter3(val config: PPrinterConfig) : PPrinter(config) { override fun treeify(x: Any?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree { // function to make recursive calls shorter fun rec(x: Any?) = treeify(x, escapeUnicode, showFieldNames) @@ -245,7 +267,7 @@ println(pp.invoke(bean)) Often it is a good idea to honor the `showFieldNames` parameter only display key-values if it is enabled: ```kotlin -class CustomPPrinter4(config: PPrinterConfig) : PPrinter(config) { +class CustomPPrinter4(val config: PPrinterConfig) : PPrinter(config) { override fun treeify(x: Any?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree { // function to make recursive calls shorter fun rec(x: Any?) = treeify(x, escapeUnicode, showFieldNames) diff --git a/build.gradle.kts b/build.gradle.kts index d03779e..0849687 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -28,7 +28,7 @@ nexusPublishing { } allprojects { - group = "io.exoquery.pprint" + group = "io.exoquery" version = "1.2.0" } diff --git a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/Base.kt b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/Base.kt similarity index 91% rename from pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/Base.kt rename to pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/Base.kt index 1d271ab..6cac038 100644 --- a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/Base.kt +++ b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/Base.kt @@ -1,8 +1,8 @@ -package io.exoquery +package io.exoquery.kmp import io.exoquery.fansi.Attrs import io.exoquery.fansi.Color -import io.exoquery.pprint.PPrinter +import io.exoquery.kmp.pprint.PPrinter import io.exoquery.pprint.PPrinterConfig inline fun pprint( diff --git a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/PPrinter.kt b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/PPrinter.kt similarity index 92% rename from pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/PPrinter.kt rename to pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/PPrinter.kt index 58d12bb..6076be7 100644 --- a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/PPrinter.kt +++ b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/PPrinter.kt @@ -1,6 +1,9 @@ -package io.exoquery.pprint +package io.exoquery.kmp.pprint import io.exoquery.fansi.Attrs +import io.exoquery.pprint.PPrinterBase +import io.exoquery.pprint.PPrinterConfig +import io.exoquery.pprint.Tree import kotlinx.serialization.KSerializer import kotlinx.serialization.SerializationStrategy import kotlinx.serialization.descriptors.SerialDescriptor @@ -54,7 +57,10 @@ open class PPrinter(val serializer: SerializationStrategy, override val co value is Sequence<*> && treeifyable is Treeifyable.Elem && treeifyable.serializer is PPrintSequenceSerializer<*> -> { @Suppress("UNCHECKED_CAST") val elementSerializer = treeifyable.serializer.element as KSerializer - Tree.Apply("Sequence", value.map { treeifyWithSerializer(Treeifyable.Elem(it, elementSerializer), escapeUnicode, showFieldNames) }.iterator()) + Tree.Apply("Sequence", + value.map { treeifyWithSerializer(Treeifyable.Elem(it, elementSerializer), escapeUnicode, showFieldNames) } + .iterator() + ) } treeifyable is Treeifyable.Elem -> { val encoder = TreeElementEncoder(this) diff --git a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/PPrinterHelper.kt b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/PPrinterHelper.kt similarity index 95% rename from pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/PPrinterHelper.kt rename to pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/PPrinterHelper.kt index 0d65fed..dd81522 100644 --- a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/PPrinterHelper.kt +++ b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/PPrinterHelper.kt @@ -1,5 +1,7 @@ -package io.exoquery.pprint +package io.exoquery.kmp.pprint +import io.exoquery.pprint.PPrinterConfig +import io.exoquery.pprint.Tree import kotlinx.serialization.ExperimentalSerializationApi import kotlinx.serialization.descriptors.SerialDescriptor import kotlinx.serialization.descriptors.StructureKind diff --git a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/TreeElementEncoder.kt b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/TreeElementEncoder.kt similarity index 98% rename from pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/TreeElementEncoder.kt rename to pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/TreeElementEncoder.kt index 3182f34..4db1f00 100644 --- a/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/pprint/TreeElementEncoder.kt +++ b/pprint-kotlin-kmp/src/commonMain/kotlin/io/exoquery/kmp/pprint/TreeElementEncoder.kt @@ -1,5 +1,7 @@ -package io.exoquery.pprint +package io.exoquery.kmp.pprint +import io.exoquery.pprint.EncodeHelper +import io.exoquery.pprint.Tree import kotlinx.serialization.ExperimentalSerializationApi import kotlinx.serialization.SerializationException import kotlinx.serialization.SerializationStrategy diff --git a/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/Check.kt b/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/Check.kt index c788d88..9182761 100644 --- a/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/Check.kt +++ b/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/Check.kt @@ -1,6 +1,7 @@ package io.exoquery.pprint import io.exoquery.fansi.Str +import io.exoquery.kmp.pprint.PPrinter import io.kotest.assertions.fail import kotlinx.serialization.KSerializer import kotlinx.serialization.SerializationStrategy diff --git a/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/VerticalTests.kt b/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/VerticalTests.kt index 1ee7966..a994b49 100644 --- a/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/VerticalTests.kt +++ b/pprint-kotlin-kmp/src/commonTest/kotlin/io/exoquery/pprint/VerticalTests.kt @@ -4,6 +4,8 @@ import io.exoquery.fansi.Color import io.exoquery.fansi.Console.GREEN import io.exoquery.fansi.Console.YELLOW import io.exoquery.fansi.Str +import io.exoquery.kmp.pprint.PPrintSequenceSerializer +import io.exoquery.kmp.pprint.PPrinter import io.kotest.core.spec.style.FunSpec import io.kotest.matchers.shouldBe import kotlinx.serialization.Serializable diff --git a/pprint-kotlin-kmp/src/jvmTest/kotlin/io/exoquery/pprint/Example2.kt b/pprint-kotlin-kmp/src/jvmTest/kotlin/io/exoquery/pprint/Example2.kt index 3ea6f7a..79f32ad 100644 --- a/pprint-kotlin-kmp/src/jvmTest/kotlin/io/exoquery/pprint/Example2.kt +++ b/pprint-kotlin-kmp/src/jvmTest/kotlin/io/exoquery/pprint/Example2.kt @@ -1,6 +1,8 @@ package io.exoquery.pprint -import io.exoquery.pprint +import io.exoquery.kmp.pprint.PPrintSequenceSerializer +import io.exoquery.kmp.pprint.PPrinter +import io.exoquery.kmp.pprint import kotlinx.serialization.ExperimentalSerializationApi import kotlinx.serialization.Serializable