docs for protobuf oneof

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,15 +527,15 @@ 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.
 
 ```text
 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. 
 

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)

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))
 }

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)
 }

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") }
 }

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))
 }

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))

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)