Add docs and examples

Author: deusaquilus

README.md

@@ -190,7 +190,7 @@ In order to extend pprint, subclass the PPrinter class and override the `treeify
 For example:
 ```kotlin
 class CustomPPrinter1(val config: PPrinterConfig) : PPrinter(config) {
-  override fun treeify(x: Any?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
+  override fun treeify(x: Any?, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
     when (x) {
       is java.time.LocalDate -> Tree.Literal(x.format(DateTimeFormatter.ofPattern("MM/dd/YYYY")))
       else -> super.treeify(x, escapeUnicode, showFieldNames)
@@ -211,9 +211,9 @@ This printer can then be used as the basis of a custom `pprint`-like user define
 > You can extend it like this:
 > ```kotlin
 > class CustomPPrinter1<T>(override val serializer: SerializationStrategy<T>, override val config: PPrinterConfig) : PPrinter<T>(serializer, config) {
->   // Overwrite `treeifyWith` instead of treeify 
->   override fun <R> treeifyWith(treeifyable: PPrinter.Treeifyable<R>, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
->     when (val v = treeifyable.value) {
+>   // Overwrite `treeifyValueOrNull` in order to handle leaf-types. Note that anything handled here will not be treated as a composite value.
+>   override fun <R> treeifyValueOrNull(value: R, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree? =
+>     when (value) {
 >       is LocalDate -> Tree.Literal(v.format(DateTimeFormatter.ofPattern("MM/dd/YYYY")))
 >       else -> super.treeifyWith(treeifyable, escapeUnicode, showFieldNames)
 >     }
@@ -240,11 +240,14 @@ class MyJavaBean(val a: String, val b: Int) {
 
 // Create the custom printer
 class CustomPPrinter2(val config: PPrinterConfig) : PPrinter(config) {
-  override fun treeify(x: Any?, esc: Boolean, names: Boolean): Tree =
+  override fun treeify(x: Any?, elementName: String?, esc: Boolean, names: Boolean): Tree =
     when (x) {
       // List through the properties of 'MyJavaBean' and recursively call treeify on them.
       // (Note that Tree.Apply takes an iterator of properties so that the interface is lazy)
-      is MyJavaBean -> Tree.Apply("MyJavaBean", listOf(x.getValueA(), x.getValueB()).map { treeify(it, esc, names) }.iterator())
+      is MyJavaBean -> 
+        Tree.Apply("MyJavaBean", listOf(x.getValueA() to "A", x.getValueB() to "B")
+          .map { (field, fieldName) -> treeify(field, fieldName, esc, names) }.iterator()
+        )
       else -> super.treeify(x, esc, names)
     }
 }
@@ -258,9 +261,9 @@ println(pp.invoke(bean))
 To print field-names you use Tree.KeyValue:
 ```kotlin
 class CustomPPrinter3(val config: PPrinterConfig) : PPrinter(config) {
-  override fun treeify(x: Any?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree {
+  override fun treeify(x: Any?, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree {
     // function to make recursive calls shorter
-    fun rec(x: Any?) = treeify(x, escapeUnicode, showFieldNames)
+    fun rec(x: Any?) = treeify(x, null, escapeUnicode, showFieldNames)
     return when (x) {
       // Recurse on the values, pass result into Tree.KeyValue.
       is MyJavaBean -> 
@@ -352,6 +355,77 @@ When using sequences, you will need to annotate the
 sequence-field using `@Serializable(with = PPrintSequenceSerializer::class)`.
 See the note in the [Infinite Sequences in Kotlin Multiplatform](#infinite-sequences-in-kotlin-multiplatform) section for more detail.
 
+## Using `elementName` metadata
+
+Note that the `elementName` parameter will contain the name of the field of the data class that is being printed.
+You can use this to exclude particular fields. For example:
+```kotlin
+class CustomPPrinter6(config: PPrinterConfig) : PPrinter(config) {
+  override fun treeify(x: Any?, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
+    when {
+      elementName == "born" -> Tree.Literal("REDACTED", elementName)
+      else -> super.treeify(x, elementName, escapeUnicode, showFieldNames)
+    }
+}
+
+data class Person(val name: String, val born: LocalDate)
+val pp = CustomPPrinter6(PPrinterConfig())
+val joe = Person("Joe", LocalDate.of(1981, 1, 1))
+
+println(pp.invoke(joe))
+//> Person(name = "Joe", born = REDACTED)
+```
+
+You can also filter out fields on the parent-element level like this:
+```kotlin
+data class PersonBorn(val name: String, val born: LocalDate)
+
+class CustomPPrinter5(config: PPrinterConfig) : PPrinter(config) {
+  override fun treeify(x: Any?, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
+    when {
+      x is PersonBorn ->
+        when (val p = super.treeify(x, elementName, escapeUnicode, showFieldNames)) {
+          is Tree.Apply -> p.copy(body = p.body.asSequence().toList().filter { it.elementName != "born" }.iterator())
+          else -> error("Expected Tree.Apply")
+        }
+      else ->
+        super.treeify(x, elementName, escapeUnicode, showFieldNames)
+    }
+}
+
+val p = PersonBorn("Joe", LocalDate.of(1981, 1, 1))
+println(CustomPPrinter5(PPrinterConfig()).invoke(p))
+//> PersonBorn(name = "Joe")
+```
+
+## Using `elementName` metadata - Kotlin Multiplatform
+
+If you want to filter out fields based on `elementName` in Kotlin Multiplatform inside of the PPrinter you need to override
+the `treeifyComposite` method. 
+> Since `treeifyValueOrNull` will always be attempted, trying to do super.treeify (or super.treeifyComposite) inside of it will result in a stack-overflow. 
+
+For example:
+```kotlin
+@Serializable
+data class PersonBorn(val name: String, val born: Long)
+
+class CustomPPrinter6<T>(override val serializer: SerializationStrategy<T>, override val config: PPrinterConfig) : PPrinter<T>(serializer, config) {
+  override fun <E> treeifyComposite(elem: Treeifyable.Elem<E>, elementName: String?, showFieldNames: Boolean): Tree =
+    when(elem.value) {
+      is PersonBorn ->
+        when (val p = super.treeifyComposite(elem, elementName, showFieldNames)) {
+          is Tree.Apply -> p.copy(body = p.body.asSequence().toList().filter { it.elementName != "born" }.iterator())
+          else -> error("Expected Tree.Apply")
+        }
+      else -> super.treeifyComposite(elem, elementName, showFieldNames)
+    }
+}
+
+val p = PersonBorn("Joe", 1234567890)
+println(CustomPPrinter6<PersonBorn>(PersonBorn.serializer(), PPrinterConfig()).invoke(p))
+//> PersonBorn(name = "Joe")
+```
+
 #### Sealed Hierarchies in KMP
 
 According to the `kotlinx-serialization` documentation, every member of a sealed hierarchy must be annotated with `@Serializable`.
@@ -388,20 +462,6 @@ class PPrintSequenceSerializer<T>(val element: KSerializer<T>) : KSerializer<Seq
 ```
 (Note that a real user-defined serialzier for `Sequence` will work as well.)
 
-The actual handling of sequence printing is done in the `treeifyWith` method (roughly) like this:
-```kotlin
-open fun <R> treeifyWith(treeifyable: Treeifyable<R>, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
-  when {
-    treeifyable is Sequence<*> && treeifyable is Treeifyable.Elem && treeifyable.serializer is PPrintSequenceSerializer<*> -> {
-      @Suppress("UNCHECKED_CAST")
-      val elementSerializer = treeifyable.serializer.element as KSerializer<Any?>
-      Tree.Apply("Sequence", value.map { treeifyWith(Treeifyable.Elem(it, elementSerializer), escapeUnicode, showFieldNames) }.iterator())
-    }
-    else -> super.treeifyWith(treeifyable, escapeUnicode, showFieldNames)
-  }
-```
-You can follow this pattern to define PPrintable serializers for other generic types.
-
 #### General Note on Generic ADTs and KMP
 
 Due to issues in kotlinx-serialization like [#1341](https://github.com/Kotlin/kotlinx.serialization/issues/1341) there are cases

pprint-kotlin-kmp/src/jvmTest/kotlin/io/exoquery/pprint/KmpExamples.kt

@@ -19,20 +19,6 @@ data class Stuff(val value: Map<String, String>)
 @Serializable
 data class IterStuff(val value: Iterator<Int>)
 
-@OptIn(ExperimentalSerializationApi::class)
-fun main() {
-//  showMap()
-//  showPerson()
-//  showIteratorInObject()
-//  mutualRecurse()
-//  usingSequence0()
-//    usingSequence1()
-//  customPrinter()
-
-  // GADT1.gadt()
-  GADT2.gadt()
-}
-
 // Problematic Cases with GADTs 1
 object GADT1 {
   @Serializable
@@ -159,3 +145,40 @@ fun showPerson() {
   val str = printer(per)
   println(str)
 }
+
+@Serializable
+data class PersonBorn(val name: String, val born: Long)
+
+class CustomPPrinter6<T>(override val serializer: SerializationStrategy<T>, override val config: PPrinterConfig) : PPrinter<T>(serializer, config) {
+  override fun <E> treeifyComposite(elem: Treeifyable.Elem<E>, elementName: String?, showFieldNames: Boolean): Tree =
+    when(elem.value) {
+      is PersonBorn ->
+        when (val p = super.treeifyComposite(elem, elementName, showFieldNames)) {
+          is Tree.Apply -> p.copy(body = p.body.asSequence().toList().filter { it.elementName != "born" }.iterator())
+          else -> error("Expected Tree.Apply")
+        }
+      else -> super.treeifyComposite(elem, elementName, showFieldNames)
+    }
+}
+
+fun customPrinter6() {
+  val joe = PersonBorn("Joe", 123)
+  val printer = CustomPPrinter6<PersonBorn>(PersonBorn.serializer(), PPrinterConfig())
+  val p = printer(joe)
+  println(p)
+}
+
+@OptIn(ExperimentalSerializationApi::class)
+fun main() {
+//  showMap()
+//  showPerson()
+//  showIteratorInObject()
+//  mutualRecurse()
+//  usingSequence0()
+//    usingSequence1()
+//  customPrinter()
+
+  // GADT1.gadt()
+  //GADT2.gadt()
+  customPrinter6()
+}

pprint-kotlin/src/main/kotlin/io/exoquery/pprint/ProductSupport.kt

@@ -33,7 +33,6 @@ object ProductSupport {
   ): Iterator<Tree>
   {
     val props = cls.dataClassProperties()
-    val productIterator = props.asSequence().map { it.invoke(x) }
     val productElementNames = props.asSequence().map { it.name }
 
     return productElementNames

pprint-kotlin/src/test/kotlin/io/exoquery/pprint/Examples.kt

@@ -140,8 +140,42 @@ fun ex10() = run {
   println(CustomPPrinter4(PPrinterConfig(defaultShowFieldNames = false)).invoke(bean))
 }
 
+data class PersonBorn(val name: String, val born: LocalDate)
+
+class CustomPPrinter5(config: PPrinterConfig) : PPrinter(config) {
+  override fun treeify(x: Any?, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
+    when {
+      x is PersonBorn ->
+        when (val p = super.treeify(x, elementName, escapeUnicode, showFieldNames)) {
+          is Tree.Apply -> p.copy(body = p.body.asSequence().toList().filter { it.elementName != "born" }.iterator())
+          else -> error("Expected Tree.Apply")
+        }
+      else ->
+        super.treeify(x, elementName, escapeUnicode, showFieldNames)
+    }
+}
+
+fun ex11() = run {
+  val p = PersonBorn("Joe", LocalDate.of(1981, 1, 1))
+  println(CustomPPrinter5(PPrinterConfig()).invoke(p))
+}
+
+class CustomPPrinter6(config: PPrinterConfig) : PPrinter(config) {
+  override fun treeify(x: Any?, elementName: String?, escapeUnicode: Boolean, showFieldNames: Boolean): Tree =
+    when {
+      elementName == "born" -> Tree.Literal("REDACTED", elementName)
+      else -> super.treeify(x, elementName, escapeUnicode, showFieldNames)
+    }
+}
+
+fun ex12() = run {
+  val p = PersonBorn("Joe", LocalDate.of(1981, 1, 1))
+  println(CustomPPrinter6(PPrinterConfig()).invoke(p))
+}
+
+
 fun main() {
-  ex10()
+  ex12()
 
 
   //val seq = generateSequence { "foo" }