From e5e703ea0b36015727551acc6dc63f94269c112c Mon Sep 17 00:00:00 2001
From: xiaozhikang <xiaozhikang0916@gmail.com>
Date: Sat, 20 Jan 2024 16:14:10 +0800
Subject: [PATCH] docs for protobuf oneof

---
 docs/formats.md                     |  80 ++++++++++++++---
 docs/serialization-guide.md         |   1 +
 guide/example/example-formats-08.kt |  23 +++--
 guide/example/example-formats-09.kt |  20 ++---
 guide/example/example-formats-10.kt |  32 ++-----
 guide/example/example-formats-11.kt |  28 +-----
 guide/example/example-formats-12.kt |   6 +-
 guide/example/example-formats-13.kt |  24 ++---
 guide/example/example-formats-14.kt |  12 +--
 guide/example/example-formats-15.kt |  78 +++++++---------
 guide/example/example-formats-16.kt |  47 +---------
 guide/example/example-formats-17.kt | 135 ++++++++++++++++++++++++++++
 guide/test/FormatsTest.kt           |  44 +++++----
 13 files changed, 313 insertions(+), 217 deletions(-)
 create mode 100644 guide/example/example-formats-17.kt

diff --git a/docs/formats.md b/docs/formats.md
index 3fcbf9c82d..6f49510c57 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -18,6 +18,7 @@ stable, these are currently experimental features of Kotlin Serialization.
   * [Integer types](#integer-types)
   * [Lists as repeated fields](#lists-as-repeated-fields)
   * [Packed fields](#packed-fields)
+  * [Oneof field (experimental)](#oneof-field-experimental)
   * [ProtoBuf schema generator (experimental)](#protobuf-schema-generator-experimental)
 * [Properties (experimental)](#properties-experimental)
 * [Custom formats (experimental)](#custom-formats-experimental)
@@ -435,6 +436,65 @@ Per the standard packed fields can only be used on primitive numeric types. The
 Per the [format description](https://developers.google.com/protocol-buffers/docs/encoding#packed) the parser ignores
 the annotation, but rather reads list in either packed or repeated format.
 
+### Oneof field (experimental)
+
+Kotlin Serialization `ProtoBuf` format supports [oneof](https://protobuf.dev/programming-guides/proto2/#oneof) fields
+base on the [Polymorphism](polymorphism.md).
+
+You can declare a property of your class to be `oneof` by following the contracts:
+
+* Declare an interface, or abstract class, in represent of the `oneof` group.
+* Declare the property with the type added above, annotated with `@ProtoOneOf(ids)`
+  with all possible proto numbers, not `@ProtoNumber`.
+* Declare subclasses from the type with **only one property** each per the oneof group elements.
+* Annotated the subclasses with `@ProtoNumber` on the class declaration, not the property, 
+  per the oneof group elements and `@ProtoOneOf(ids)` above.
+
+<!--- INCLUDE
+import kotlinx.serialization.*
+import kotlinx.serialization.protobuf.*
+-->
+
+```kotlin
+@Serializable
+data class Data(
+    @ProtoNumber(1) val name: String,
+    @ProtoOneOf(2, 3) val phone: IPhoneType,
+)
+@Serializable sealed interface IPhoneType
+@Serializable @ProtoNumber(2) @JvmInline value class HomePhone(val number: String): IPhoneType
+@Serializable @ProtoNumber(3) data class WorkPhone(val number: String): IPhoneType
+
+fun main() {
+  val dataTom = Data("Tom", HomePhone("123"))
+  val stringTom = ProtoBuf.encodeToHexString(dataTom)
+  val dataJerry = Data("Jerry", WorkPhone("789"))
+  val stringJerry = ProtoBuf.encodeToHexString(dataJerry)
+  println(stringTom)
+  println(stringJerry)
+  println(ProtoBuf.decodeFromHexString<Data>(stringTom))
+  println(ProtoBuf.decodeFromHexString<Data>(stringJerry))
+}
+```
+
+> You can get the full code [here](../guide/example/example-formats-08.kt).
+
+```text
+0a03546f6d1203313233
+0a054a657272791a03373839
+Data(name=Tom, phone=HomePhone(number=123))
+Data(name=Jerry, phone=WorkPhone(number=789))
+```
+
+<!--- TEST -->
+
+In [ProtoBuf diagnostic mode](https://protogen.marcgravell.com/decode) the first 2 lines on output is equivalent to
+
+```
+Field #1: 0A String Length = 3, Hex = 03, UTF8 = "Tom" Field #2: 12 String Length = 3, Hex = 03, UTF8 = "123"
+Field #1: 0A String Length = 5, Hex = 05, UTF8 = "Jerry" Field #3: 1A String Length = 3, Hex = 03, UTF8 = "789"
+```
+
 ### ProtoBuf schema generator (experimental)
 
 As mentioned above, when working with protocol buffers you usually use a ".proto" file and a code generator for your
@@ -467,7 +527,7 @@ fun main() {
   println(schemas)
 }
 ```
-> You can get the full code [here](../guide/example/example-formats-08.kt).
+> You can get the full code [here](../guide/example/example-formats-09.kt).
 
 Which would output as follows.
 
@@ -475,7 +535,7 @@ Which would output as follows.
 syntax = "proto2";
 
 
-// serial name 'example.exampleFormats08.SampleData'
+// serial name 'example.exampleFormats09.SampleData'
 message SampleData {
   required int64 amount = 1;
   optional string description = 2;
@@ -519,7 +579,7 @@ fun main() {
 }
 ```      
 
-> You can get the full code [here](../guide/example/example-formats-09.kt).
+> You can get the full code [here](../guide/example/example-formats-10.kt).
 
 The resulting map has dot-separated keys representing keys of the nested objects.
 
@@ -599,7 +659,7 @@ fun main() {
 }
 ```                                    
 
-> You can get the full code [here](../guide/example/example-formats-10.kt).
+> You can get the full code [here](../guide/example/example-formats-11.kt).
 
 As a result, we got all the primitive values in our object graph visited and put into a list
 in _serial_ order.
@@ -701,7 +761,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-formats-11.kt).
+> You can get the full code [here](../guide/example/example-formats-12.kt).
 
 Now we can convert a list of primitives back to an object tree.
 
@@ -792,7 +852,7 @@ fun main() {
 }
 -->
 
-> You can get the full code [here](../guide/example/example-formats-12.kt).
+> You can get the full code [here](../guide/example/example-formats-13.kt).
 
 <!--- TEST 
 [kotlinx.serialization, kotlin, 9000]
@@ -899,7 +959,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-formats-13.kt).
+> You can get the full code [here](../guide/example/example-formats-14.kt).
 
 We see the size of the list added to the result, letting the decoder know where to stop. 
 
@@ -1011,7 +1071,7 @@ fun main() {
 
 ```
 
-> You can get the full code [here](../guide/example/example-formats-14.kt).
+> You can get the full code [here](../guide/example/example-formats-15.kt).
 
 In the output we see how not-null`!!` and `NULL` marks are used.
 
@@ -1139,7 +1199,7 @@ fun main() {
 }
 ```
               
-> You can get the full code [here](../guide/example/example-formats-15.kt).
+> You can get the full code [here](../guide/example/example-formats-16.kt).
 
 As we can see, the result is a dense binary format that only contains the data that is being serialized. 
 It can be easily tweaked for any kind of domain-specific compact encoding.
@@ -1333,7 +1393,7 @@ fun main() {
 }
 ```
               
-> You can get the full code [here](../guide/example/example-formats-16.kt).
+> You can get the full code [here](../guide/example/example-formats-17.kt).
 
 As we can see, our custom byte array format is being used, with the compact encoding of its size in one byte. 
 
diff --git a/docs/serialization-guide.md b/docs/serialization-guide.md
index 50cb1306ae..c9fe583a09 100644
--- a/docs/serialization-guide.md
+++ b/docs/serialization-guide.md
@@ -151,6 +151,7 @@ Once the project is set up, we can start serializing some classes.
   * <a name='integer-types'></a>[Integer types](formats.md#integer-types)
   * <a name='lists-as-repeated-fields'></a>[Lists as repeated fields](formats.md#lists-as-repeated-fields)
   * <a name='packed-fields'></a>[Packed fields](formats.md#packed-fields)
+  * <a name='oneof-field-experimental'></a>[Oneof field (experimental)](formats.md#oneof-field-experimental)
   * <a name='protobuf-schema-generator-experimental'></a>[ProtoBuf schema generator (experimental)](formats.md#protobuf-schema-generator-experimental)
 * <a name='properties-experimental'></a>[Properties (experimental)](formats.md#properties-experimental)
 * <a name='custom-formats-experimental'></a>[Custom formats (experimental)](formats.md#custom-formats-experimental)
diff --git a/guide/example/example-formats-08.kt b/guide/example/example-formats-08.kt
index 61d4aeb81a..45bf94a965 100644
--- a/guide/example/example-formats-08.kt
+++ b/guide/example/example-formats-08.kt
@@ -3,16 +3,23 @@ package example.exampleFormats08
 
 import kotlinx.serialization.*
 import kotlinx.serialization.protobuf.*
-import kotlinx.serialization.protobuf.schema.ProtoBufSchemaGenerator
 
 @Serializable
-data class SampleData(
-    val amount: Long,
-    val description: String?,
-    val department: String = "QA"
+data class Data(
+    @ProtoNumber(1) val name: String,
+    @ProtoOneOf(2, 3) val phone: IPhoneType,
 )
+@Serializable sealed interface IPhoneType
+@Serializable @ProtoNumber(2) @JvmInline value class HomePhone(val number: String): IPhoneType
+@Serializable @ProtoNumber(3) data class WorkPhone(val number: String): IPhoneType
+
 fun main() {
-  val descriptors = listOf(SampleData.serializer().descriptor)
-  val schemas = ProtoBufSchemaGenerator.generateSchemaText(descriptors)
-  println(schemas)
+  val dataTom = Data("Tom", HomePhone("123"))
+  val stringTom = ProtoBuf.encodeToHexString(dataTom)
+  val dataJerry = Data("Jerry", WorkPhone("789"))
+  val stringJerry = ProtoBuf.encodeToHexString(dataJerry)
+  println(stringTom)
+  println(stringJerry)
+  println(ProtoBuf.decodeFromHexString<Data>(stringTom))
+  println(ProtoBuf.decodeFromHexString<Data>(stringJerry))
 }
diff --git a/guide/example/example-formats-09.kt b/guide/example/example-formats-09.kt
index 99ed45d2e2..387061f084 100644
--- a/guide/example/example-formats-09.kt
+++ b/guide/example/example-formats-09.kt
@@ -2,17 +2,17 @@
 package example.exampleFormats09
 
 import kotlinx.serialization.*
-import kotlinx.serialization.properties.Properties // todo: remove when no longer needed
-import kotlinx.serialization.properties.*
+import kotlinx.serialization.protobuf.*
+import kotlinx.serialization.protobuf.schema.ProtoBufSchemaGenerator
 
 @Serializable
-class Project(val name: String, val owner: User)
-
-@Serializable
-class User(val name: String)
-
+data class SampleData(
+    val amount: Long,
+    val description: String?,
+    val department: String = "QA"
+)
 fun main() {
-    val data = Project("kotlinx.serialization",  User("kotlin"))
-    val map = Properties.encodeToMap(data)
-    map.forEach { (k, v) -> println("$k = $v") }
+  val descriptors = listOf(SampleData.serializer().descriptor)
+  val schemas = ProtoBufSchemaGenerator.generateSchemaText(descriptors)
+  println(schemas)
 }
diff --git a/guide/example/example-formats-10.kt b/guide/example/example-formats-10.kt
index 0fc318bd4d..020f175da9 100644
--- a/guide/example/example-formats-10.kt
+++ b/guide/example/example-formats-10.kt
@@ -2,35 +2,17 @@
 package example.exampleFormats10
 
 import kotlinx.serialization.*
-import kotlinx.serialization.descriptors.*
-import kotlinx.serialization.encoding.*
-import kotlinx.serialization.modules.*
-
-class ListEncoder : AbstractEncoder() {
-    val list = mutableListOf<Any>()
-
-    override val serializersModule: SerializersModule = EmptySerializersModule()
-
-    override fun encodeValue(value: Any) {
-        list.add(value)
-    }
-}
-
-fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
-    val encoder = ListEncoder()
-    encoder.encodeSerializableValue(serializer, value)
-    return encoder.list
-}
-
-inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
+import kotlinx.serialization.properties.Properties // todo: remove when no longer needed
+import kotlinx.serialization.properties.*
 
 @Serializable
-data class Project(val name: String, val owner: User, val votes: Int)
+class Project(val name: String, val owner: User)
 
 @Serializable
-data class User(val name: String)
+class User(val name: String)
 
 fun main() {
-    val data = Project("kotlinx.serialization",  User("kotlin"), 9000)
-    println(encodeToList(data))
+    val data = Project("kotlinx.serialization",  User("kotlin"))
+    val map = Properties.encodeToMap(data)
+    map.forEach { (k, v) -> println("$k = $v") }
 }
diff --git a/guide/example/example-formats-11.kt b/guide/example/example-formats-11.kt
index 942febb103..9fa4180d8e 100644
--- a/guide/example/example-formats-11.kt
+++ b/guide/example/example-formats-11.kt
@@ -24,29 +24,6 @@ fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any>
 
 inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
 
-class ListDecoder(val list: ArrayDeque<Any>) : AbstractDecoder() {
-    private var elementIndex = 0
-
-    override val serializersModule: SerializersModule = EmptySerializersModule()
-
-    override fun decodeValue(): Any = list.removeFirst()
-    
-    override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
-        if (elementIndex == descriptor.elementsCount) return CompositeDecoder.DECODE_DONE
-        return elementIndex++
-    }
-
-    override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
-        ListDecoder(list)
-}
-
-fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
-    val decoder = ListDecoder(ArrayDeque(list))
-    return decoder.decodeSerializableValue(deserializer)
-}
-
-inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
-
 @Serializable
 data class Project(val name: String, val owner: User, val votes: Int)
 
@@ -55,8 +32,5 @@ data class User(val name: String)
 
 fun main() {
     val data = Project("kotlinx.serialization",  User("kotlin"), 9000)
-    val list = encodeToList(data)
-    println(list)
-    val obj = decodeFromList<Project>(list)
-    println(obj)
+    println(encodeToList(data))
 }
diff --git a/guide/example/example-formats-12.kt b/guide/example/example-formats-12.kt
index 1e83b9bf5f..803f331e6c 100644
--- a/guide/example/example-formats-12.kt
+++ b/guide/example/example-formats-12.kt
@@ -37,10 +37,8 @@ class ListDecoder(val list: ArrayDeque<Any>) : AbstractDecoder() {
     }
 
     override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
-        ListDecoder(list) 
-
-    override fun decodeSequentially(): Boolean = true
-}        
+        ListDecoder(list)
+}
 
 fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
     val decoder = ListDecoder(ArrayDeque(list))
diff --git a/guide/example/example-formats-13.kt b/guide/example/example-formats-13.kt
index 62ecdc66de..568017765c 100644
--- a/guide/example/example-formats-13.kt
+++ b/guide/example/example-formats-13.kt
@@ -13,12 +13,7 @@ class ListEncoder : AbstractEncoder() {
 
     override fun encodeValue(value: Any) {
         list.add(value)
-    }                               
-
-    override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder {
-        encodeInt(collectionSize)
-        return this
-    }                                                
+    }
 }
 
 fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
@@ -29,26 +24,23 @@ fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any>
 
 inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
 
-class ListDecoder(val list: ArrayDeque<Any>, var elementsCount: Int = 0) : AbstractDecoder() {
+class ListDecoder(val list: ArrayDeque<Any>) : AbstractDecoder() {
     private var elementIndex = 0
 
     override val serializersModule: SerializersModule = EmptySerializersModule()
 
     override fun decodeValue(): Any = list.removeFirst()
-
+    
     override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
-        if (elementIndex == elementsCount) return CompositeDecoder.DECODE_DONE
+        if (elementIndex == descriptor.elementsCount) return CompositeDecoder.DECODE_DONE
         return elementIndex++
     }
 
     override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
-        ListDecoder(list, descriptor.elementsCount)
+        ListDecoder(list) 
 
     override fun decodeSequentially(): Boolean = true
-
-    override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
-        decodeInt().also { elementsCount = it }
-}
+}        
 
 fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
     val decoder = ListDecoder(ArrayDeque(list))
@@ -58,13 +50,13 @@ fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>
 inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
 
 @Serializable
-data class Project(val name: String, val owners: List<User>, val votes: Int)
+data class Project(val name: String, val owner: User, val votes: Int)
 
 @Serializable
 data class User(val name: String)
 
 fun main() {
-    val data = Project("kotlinx.serialization",  listOf(User("kotlin"), User("jetbrains")), 9000)
+    val data = Project("kotlinx.serialization",  User("kotlin"), 9000)
     val list = encodeToList(data)
     println(list)
     val obj = decodeFromList<Project>(list)
diff --git a/guide/example/example-formats-14.kt b/guide/example/example-formats-14.kt
index cd823e8d90..3f88d51caf 100644
--- a/guide/example/example-formats-14.kt
+++ b/guide/example/example-formats-14.kt
@@ -19,9 +19,6 @@ class ListEncoder : AbstractEncoder() {
         encodeInt(collectionSize)
         return this
     }                                                
-
-    override fun encodeNull() = encodeValue("NULL")
-    override fun encodeNotNullMark() = encodeValue("!!")
 }
 
 fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
@@ -34,7 +31,7 @@ inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value
 
 class ListDecoder(val list: ArrayDeque<Any>, var elementsCount: Int = 0) : AbstractDecoder() {
     private var elementIndex = 0
-    
+
     override val serializersModule: SerializersModule = EmptySerializersModule()
 
     override fun decodeValue(): Any = list.removeFirst()
@@ -51,8 +48,6 @@ class ListDecoder(val list: ArrayDeque<Any>, var elementsCount: Int = 0) : Abstr
 
     override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
         decodeInt().also { elementsCount = it }
-
-    override fun decodeNotNullMark(): Boolean = decodeString() != "NULL"
 }
 
 fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
@@ -63,16 +58,15 @@ fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>
 inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
 
 @Serializable
-data class Project(val name: String, val owner: User?, val votes: Int?)
+data class Project(val name: String, val owners: List<User>, val votes: Int)
 
 @Serializable
 data class User(val name: String)
 
 fun main() {
-    val data = Project("kotlinx.serialization",  User("kotlin") , null)
+    val data = Project("kotlinx.serialization",  listOf(User("kotlin"), User("jetbrains")), 9000)
     val list = encodeToList(data)
     println(list)
     val obj = decodeFromList<Project>(list)
     println(obj)
 }
-
diff --git a/guide/example/example-formats-15.kt b/guide/example/example-formats-15.kt
index 81928d49b7..c48c18e4f1 100644
--- a/guide/example/example-formats-15.kt
+++ b/guide/example/example-formats-15.kt
@@ -2,54 +2,42 @@
 package example.exampleFormats15
 
 import kotlinx.serialization.*
-import kotlinx.serialization.Serializable
 import kotlinx.serialization.descriptors.*
 import kotlinx.serialization.encoding.*
 import kotlinx.serialization.modules.*
-import java.io.*
 
-class DataOutputEncoder(val output: DataOutput) : AbstractEncoder() {
+class ListEncoder : AbstractEncoder() {
+    val list = mutableListOf<Any>()
+
     override val serializersModule: SerializersModule = EmptySerializersModule()
-    override fun encodeBoolean(value: Boolean) = output.writeByte(if (value) 1 else 0)
-    override fun encodeByte(value: Byte) = output.writeByte(value.toInt())
-    override fun encodeShort(value: Short) = output.writeShort(value.toInt())
-    override fun encodeInt(value: Int) = output.writeInt(value)
-    override fun encodeLong(value: Long) = output.writeLong(value)
-    override fun encodeFloat(value: Float) = output.writeFloat(value)
-    override fun encodeDouble(value: Double) = output.writeDouble(value)
-    override fun encodeChar(value: Char) = output.writeChar(value.code)
-    override fun encodeString(value: String) = output.writeUTF(value)
-    override fun encodeEnum(enumDescriptor: SerialDescriptor, index: Int) = output.writeInt(index)
+
+    override fun encodeValue(value: Any) {
+        list.add(value)
+    }                               
 
     override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder {
         encodeInt(collectionSize)
         return this
-    }
+    }                                                
 
-    override fun encodeNull() = encodeBoolean(false)
-    override fun encodeNotNullMark() = encodeBoolean(true)
+    override fun encodeNull() = encodeValue("NULL")
+    override fun encodeNotNullMark() = encodeValue("!!")
 }
 
-fun <T> encodeTo(output: DataOutput, serializer: SerializationStrategy<T>, value: T) {
-    val encoder = DataOutputEncoder(output)
+fun <T> encodeToList(serializer: SerializationStrategy<T>, value: T): List<Any> {
+    val encoder = ListEncoder()
     encoder.encodeSerializableValue(serializer, value)
+    return encoder.list
 }
 
-inline fun <reified T> encodeTo(output: DataOutput, value: T) = encodeTo(output, serializer(), value)
+inline fun <reified T> encodeToList(value: T) = encodeToList(serializer(), value)
 
-class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : AbstractDecoder() {
+class ListDecoder(val list: ArrayDeque<Any>, var elementsCount: Int = 0) : AbstractDecoder() {
     private var elementIndex = 0
+    
     override val serializersModule: SerializersModule = EmptySerializersModule()
-    override fun decodeBoolean(): Boolean = input.readByte().toInt() != 0
-    override fun decodeByte(): Byte = input.readByte()
-    override fun decodeShort(): Short = input.readShort()
-    override fun decodeInt(): Int = input.readInt()
-    override fun decodeLong(): Long = input.readLong()
-    override fun decodeFloat(): Float = input.readFloat()
-    override fun decodeDouble(): Double = input.readDouble()
-    override fun decodeChar(): Char = input.readChar()
-    override fun decodeString(): String = input.readUTF()
-    override fun decodeEnum(enumDescriptor: SerialDescriptor): Int = input.readInt()
+
+    override fun decodeValue(): Any = list.removeFirst()
 
     override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
         if (elementIndex == elementsCount) return CompositeDecoder.DECODE_DONE
@@ -57,38 +45,34 @@ class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : Abstr
     }
 
     override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
-        DataInputDecoder(input, descriptor.elementsCount)
+        ListDecoder(list, descriptor.elementsCount)
 
     override fun decodeSequentially(): Boolean = true
 
     override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
         decodeInt().also { elementsCount = it }
 
-    override fun decodeNotNullMark(): Boolean = decodeBoolean()
+    override fun decodeNotNullMark(): Boolean = decodeString() != "NULL"
 }
 
-fun <T> decodeFrom(input: DataInput, deserializer: DeserializationStrategy<T>): T {
-    val decoder = DataInputDecoder(input)
+fun <T> decodeFromList(list: List<Any>, deserializer: DeserializationStrategy<T>): T {
+    val decoder = ListDecoder(ArrayDeque(list))
     return decoder.decodeSerializableValue(deserializer)
 }
 
-inline fun <reified T> decodeFrom(input: DataInput): T = decodeFrom(input, serializer())
+inline fun <reified T> decodeFromList(list: List<Any>): T = decodeFromList(list, serializer())
 
-fun ByteArray.toAsciiHexString() = joinToString("") {
-    if (it in 32..127) it.toInt().toChar().toString() else
-        "{${it.toUByte().toString(16).padStart(2, '0').uppercase()}}"
-}
+@Serializable
+data class Project(val name: String, val owner: User?, val votes: Int?)
 
 @Serializable
-data class Project(val name: String, val language: String)
+data class User(val name: String)
 
 fun main() {
-    val data = Project("kotlinx.serialization", "Kotlin")
-    val output = ByteArrayOutputStream()
-    encodeTo(DataOutputStream(output), data)
-    val bytes = output.toByteArray()
-    println(bytes.toAsciiHexString())
-    val input = ByteArrayInputStream(bytes)
-    val obj = decodeFrom<Project>(DataInputStream(input))
+    val data = Project("kotlinx.serialization",  User("kotlin") , null)
+    val list = encodeToList(data)
+    println(list)
+    val obj = decodeFromList<Project>(list)
     println(obj)
 }
+
diff --git a/guide/example/example-formats-16.kt b/guide/example/example-formats-16.kt
index 24604902d3..5bf0e44516 100644
--- a/guide/example/example-formats-16.kt
+++ b/guide/example/example-formats-16.kt
@@ -4,11 +4,10 @@ package example.exampleFormats16
 import kotlinx.serialization.*
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.descriptors.*
-import kotlinx.serialization.modules.*
 import kotlinx.serialization.encoding.*
+import kotlinx.serialization.modules.*
 import java.io.*
 
-private val byteArraySerializer = serializer<ByteArray>()
 class DataOutputEncoder(val output: DataOutput) : AbstractEncoder() {
     override val serializersModule: SerializersModule = EmptySerializersModule()
     override fun encodeBoolean(value: Boolean) = output.writeByte(if (value) 1 else 0)
@@ -29,27 +28,6 @@ class DataOutputEncoder(val output: DataOutput) : AbstractEncoder() {
 
     override fun encodeNull() = encodeBoolean(false)
     override fun encodeNotNullMark() = encodeBoolean(true)
-
-    override fun <T> encodeSerializableValue(serializer: SerializationStrategy<T>, value: T) {
-        if (serializer.descriptor == byteArraySerializer.descriptor)
-            encodeByteArray(value as ByteArray)
-        else
-            super.encodeSerializableValue(serializer, value)
-    }
-
-    private fun encodeByteArray(bytes: ByteArray) {
-        encodeCompactSize(bytes.size)
-        output.write(bytes)
-    }
-    
-    private fun encodeCompactSize(value: Int) {
-        if (value < 0xff) {
-            output.writeByte(value)
-        } else {
-            output.writeByte(0xff)
-            output.writeInt(value)
-        }
-    }            
 }
 
 fun <T> encodeTo(output: DataOutput, serializer: SerializationStrategy<T>, value: T) {
@@ -87,25 +65,6 @@ class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : Abstr
         decodeInt().also { elementsCount = it }
 
     override fun decodeNotNullMark(): Boolean = decodeBoolean()
-
-    @Suppress("UNCHECKED_CAST")
-    override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?): T =
-        if (deserializer.descriptor == byteArraySerializer.descriptor)
-            decodeByteArray() as T
-        else
-            super.decodeSerializableValue(deserializer, previousValue)
-
-    private fun decodeByteArray(): ByteArray {
-        val bytes = ByteArray(decodeCompactSize())
-        input.readFully(bytes)
-        return bytes
-    }
-
-    private fun decodeCompactSize(): Int {
-        val byte = input.readByte().toInt() and 0xff
-        if (byte < 0xff) return byte
-        return input.readInt()
-    }
 }
 
 fun <T> decodeFrom(input: DataInput, deserializer: DeserializationStrategy<T>): T {
@@ -121,10 +80,10 @@ fun ByteArray.toAsciiHexString() = joinToString("") {
 }
 
 @Serializable
-data class Project(val name: String, val attachment: ByteArray)
+data class Project(val name: String, val language: String)
 
 fun main() {
-    val data = Project("kotlinx.serialization", byteArrayOf(0x0A, 0x0B, 0x0C, 0x0D))
+    val data = Project("kotlinx.serialization", "Kotlin")
     val output = ByteArrayOutputStream()
     encodeTo(DataOutputStream(output), data)
     val bytes = output.toByteArray()
diff --git a/guide/example/example-formats-17.kt b/guide/example/example-formats-17.kt
new file mode 100644
index 0000000000..9a1c5a21d3
--- /dev/null
+++ b/guide/example/example-formats-17.kt
@@ -0,0 +1,135 @@
+// This file was automatically generated from formats.md by Knit tool. Do not edit.
+package example.exampleFormats17
+
+import kotlinx.serialization.*
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.descriptors.*
+import kotlinx.serialization.modules.*
+import kotlinx.serialization.encoding.*
+import java.io.*
+
+private val byteArraySerializer = serializer<ByteArray>()
+class DataOutputEncoder(val output: DataOutput) : AbstractEncoder() {
+    override val serializersModule: SerializersModule = EmptySerializersModule()
+    override fun encodeBoolean(value: Boolean) = output.writeByte(if (value) 1 else 0)
+    override fun encodeByte(value: Byte) = output.writeByte(value.toInt())
+    override fun encodeShort(value: Short) = output.writeShort(value.toInt())
+    override fun encodeInt(value: Int) = output.writeInt(value)
+    override fun encodeLong(value: Long) = output.writeLong(value)
+    override fun encodeFloat(value: Float) = output.writeFloat(value)
+    override fun encodeDouble(value: Double) = output.writeDouble(value)
+    override fun encodeChar(value: Char) = output.writeChar(value.code)
+    override fun encodeString(value: String) = output.writeUTF(value)
+    override fun encodeEnum(enumDescriptor: SerialDescriptor, index: Int) = output.writeInt(index)
+
+    override fun beginCollection(descriptor: SerialDescriptor, collectionSize: Int): CompositeEncoder {
+        encodeInt(collectionSize)
+        return this
+    }
+
+    override fun encodeNull() = encodeBoolean(false)
+    override fun encodeNotNullMark() = encodeBoolean(true)
+
+    override fun <T> encodeSerializableValue(serializer: SerializationStrategy<T>, value: T) {
+        if (serializer.descriptor == byteArraySerializer.descriptor)
+            encodeByteArray(value as ByteArray)
+        else
+            super.encodeSerializableValue(serializer, value)
+    }
+
+    private fun encodeByteArray(bytes: ByteArray) {
+        encodeCompactSize(bytes.size)
+        output.write(bytes)
+    }
+    
+    private fun encodeCompactSize(value: Int) {
+        if (value < 0xff) {
+            output.writeByte(value)
+        } else {
+            output.writeByte(0xff)
+            output.writeInt(value)
+        }
+    }            
+}
+
+fun <T> encodeTo(output: DataOutput, serializer: SerializationStrategy<T>, value: T) {
+    val encoder = DataOutputEncoder(output)
+    encoder.encodeSerializableValue(serializer, value)
+}
+
+inline fun <reified T> encodeTo(output: DataOutput, value: T) = encodeTo(output, serializer(), value)
+
+class DataInputDecoder(val input: DataInput, var elementsCount: Int = 0) : AbstractDecoder() {
+    private var elementIndex = 0
+    override val serializersModule: SerializersModule = EmptySerializersModule()
+    override fun decodeBoolean(): Boolean = input.readByte().toInt() != 0
+    override fun decodeByte(): Byte = input.readByte()
+    override fun decodeShort(): Short = input.readShort()
+    override fun decodeInt(): Int = input.readInt()
+    override fun decodeLong(): Long = input.readLong()
+    override fun decodeFloat(): Float = input.readFloat()
+    override fun decodeDouble(): Double = input.readDouble()
+    override fun decodeChar(): Char = input.readChar()
+    override fun decodeString(): String = input.readUTF()
+    override fun decodeEnum(enumDescriptor: SerialDescriptor): Int = input.readInt()
+
+    override fun decodeElementIndex(descriptor: SerialDescriptor): Int {
+        if (elementIndex == elementsCount) return CompositeDecoder.DECODE_DONE
+        return elementIndex++
+    }
+
+    override fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder =
+        DataInputDecoder(input, descriptor.elementsCount)
+
+    override fun decodeSequentially(): Boolean = true
+
+    override fun decodeCollectionSize(descriptor: SerialDescriptor): Int =
+        decodeInt().also { elementsCount = it }
+
+    override fun decodeNotNullMark(): Boolean = decodeBoolean()
+
+    @Suppress("UNCHECKED_CAST")
+    override fun <T> decodeSerializableValue(deserializer: DeserializationStrategy<T>, previousValue: T?): T =
+        if (deserializer.descriptor == byteArraySerializer.descriptor)
+            decodeByteArray() as T
+        else
+            super.decodeSerializableValue(deserializer, previousValue)
+
+    private fun decodeByteArray(): ByteArray {
+        val bytes = ByteArray(decodeCompactSize())
+        input.readFully(bytes)
+        return bytes
+    }
+
+    private fun decodeCompactSize(): Int {
+        val byte = input.readByte().toInt() and 0xff
+        if (byte < 0xff) return byte
+        return input.readInt()
+    }
+}
+
+fun <T> decodeFrom(input: DataInput, deserializer: DeserializationStrategy<T>): T {
+    val decoder = DataInputDecoder(input)
+    return decoder.decodeSerializableValue(deserializer)
+}
+
+inline fun <reified T> decodeFrom(input: DataInput): T = decodeFrom(input, serializer())
+
+fun ByteArray.toAsciiHexString() = joinToString("") {
+    if (it in 32..127) it.toInt().toChar().toString() else
+        "{${it.toUByte().toString(16).padStart(2, '0').uppercase()}}"
+}
+
+@Serializable
+data class Project(val name: String, val attachment: ByteArray)
+
+fun main() {
+    val data = Project("kotlinx.serialization", byteArrayOf(0x0A, 0x0B, 0x0C, 0x0D))
+    val output = ByteArrayOutputStream()
+    encodeTo(DataOutputStream(output), data)
+    val bytes = output.toByteArray()
+    println(bytes.toAsciiHexString())
+    val input = ByteArrayInputStream(bytes)
+    val obj = decodeFrom<Project>(DataInputStream(input))
+    println(obj)
+}
diff --git a/guide/test/FormatsTest.kt b/guide/test/FormatsTest.kt
index c20a9f2afd..f305a59bf2 100644
--- a/guide/test/FormatsTest.kt
+++ b/guide/test/FormatsTest.kt
@@ -62,10 +62,20 @@ class FormatsTest {
     @Test
     fun testExampleFormats08() {
         captureOutput("ExampleFormats08") { example.exampleFormats08.main() }.verifyOutputLines(
+            "0a03546f6d1203313233",
+            "0a054a657272791a03373839",
+            "Data(name=Tom, phone=HomePhone(number=123))",
+            "Data(name=Jerry, phone=WorkPhone(number=789))"
+        )
+    }
+
+    @Test
+    fun testExampleFormats09() {
+        captureOutput("ExampleFormats09") { example.exampleFormats09.main() }.verifyOutputLines(
             "syntax = \"proto2\";",
             "",
             "",
-            "// serial name 'example.exampleFormats08.SampleData'",
+            "// serial name 'example.exampleFormats09.SampleData'",
             "message SampleData {",
             "  required int64 amount = 1;",
             "  optional string description = 2;",
@@ -77,63 +87,63 @@ class FormatsTest {
     }
 
     @Test
-    fun testExampleFormats09() {
-        captureOutput("ExampleFormats09") { example.exampleFormats09.main() }.verifyOutputLines(
+    fun testExampleFormats10() {
+        captureOutput("ExampleFormats10") { example.exampleFormats10.main() }.verifyOutputLines(
             "name = kotlinx.serialization",
             "owner.name = kotlin"
         )
     }
 
     @Test
-    fun testExampleFormats10() {
-        captureOutput("ExampleFormats10") { example.exampleFormats10.main() }.verifyOutputLines(
+    fun testExampleFormats11() {
+        captureOutput("ExampleFormats11") { example.exampleFormats11.main() }.verifyOutputLines(
             "[kotlinx.serialization, kotlin, 9000]"
         )
     }
 
     @Test
-    fun testExampleFormats11() {
-        captureOutput("ExampleFormats11") { example.exampleFormats11.main() }.verifyOutputLines(
+    fun testExampleFormats12() {
+        captureOutput("ExampleFormats12") { example.exampleFormats12.main() }.verifyOutputLines(
             "[kotlinx.serialization, kotlin, 9000]",
             "Project(name=kotlinx.serialization, owner=User(name=kotlin), votes=9000)"
         )
     }
 
     @Test
-    fun testExampleFormats12() {
-        captureOutput("ExampleFormats12") { example.exampleFormats12.main() }.verifyOutputLines(
+    fun testExampleFormats13() {
+        captureOutput("ExampleFormats13") { example.exampleFormats13.main() }.verifyOutputLines(
             "[kotlinx.serialization, kotlin, 9000]",
             "Project(name=kotlinx.serialization, owner=User(name=kotlin), votes=9000)"
         )
     }
 
     @Test
-    fun testExampleFormats13() {
-        captureOutput("ExampleFormats13") { example.exampleFormats13.main() }.verifyOutputLines(
+    fun testExampleFormats14() {
+        captureOutput("ExampleFormats14") { example.exampleFormats14.main() }.verifyOutputLines(
             "[kotlinx.serialization, 2, kotlin, jetbrains, 9000]",
             "Project(name=kotlinx.serialization, owners=[User(name=kotlin), User(name=jetbrains)], votes=9000)"
         )
     }
 
     @Test
-    fun testExampleFormats14() {
-        captureOutput("ExampleFormats14") { example.exampleFormats14.main() }.verifyOutputLines(
+    fun testExampleFormats15() {
+        captureOutput("ExampleFormats15") { example.exampleFormats15.main() }.verifyOutputLines(
             "[kotlinx.serialization, !!, kotlin, NULL]",
             "Project(name=kotlinx.serialization, owner=User(name=kotlin), votes=null)"
         )
     }
 
     @Test
-    fun testExampleFormats15() {
-        captureOutput("ExampleFormats15") { example.exampleFormats15.main() }.verifyOutputLines(
+    fun testExampleFormats16() {
+        captureOutput("ExampleFormats16") { example.exampleFormats16.main() }.verifyOutputLines(
             "{00}{15}kotlinx.serialization{00}{06}Kotlin",
             "Project(name=kotlinx.serialization, language=Kotlin)"
         )
     }
 
     @Test
-    fun testExampleFormats16() {
-        captureOutput("ExampleFormats16") { example.exampleFormats16.main() }.verifyOutputLines(
+    fun testExampleFormats17() {
+        captureOutput("ExampleFormats17") { example.exampleFormats17.main() }.verifyOutputLines(
             "{00}{15}kotlinx.serialization{04}{0A}{0B}{0C}{0D}",
             "Project(name=kotlinx.serialization, attachment=[10, 11, 12, 13])"
         )