diff --git a/buildSrc/src/main/kotlin/publishing-conventions.gradle.kts b/buildSrc/src/main/kotlin/publishing-conventions.gradle.kts index 7f2a72a627..6d0d3bfe26 100644 --- a/buildSrc/src/main/kotlin/publishing-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/publishing-conventions.gradle.kts @@ -145,13 +145,6 @@ tasks.withType() { mustRunAfter(tasks.withType().named { it == "sign${targetName}Publication" }) } -// Compatibility with old TeamCity configurations that perform :kotlinx-coroutines-core:bintrayUpload -tasks.register("bintrayUpload") { - dependsOn(tasks.publish) - // This is required for K/N publishing - dependsOn(tasks.publishToMavenLocal) -} - fun MavenPom.configureMavenCentralMetadata() { name = project.name description = "Kotlin multiplatform serialization runtime library" diff --git a/core/commonMain/src/kotlinx/serialization/Annotations.kt b/core/commonMain/src/kotlinx/serialization/Annotations.kt index c1a0835c6d..ec1bf14f92 100644 --- a/core/commonMain/src/kotlinx/serialization/Annotations.kt +++ b/core/commonMain/src/kotlinx/serialization/Annotations.kt @@ -42,9 +42,9 @@ import kotlin.reflect.* * * @Serializable * class RgbExample( - * @Serializable(with = RgbAsHexString::class) p1: RgpPixel, // Serialize as HEX string, e.g. #FFFF00 - * @Serializable(with = RgbAsSingleInt::class) p2: RgpPixel, // Serialize as single integer, e.g. 16711680 - * p3: RgpPixel // Serialize as 3 short components, e.g. { "red": 255, "green": 255, "blue": 0 } + * @Serializable(with = RgbAsHexString::class) p1: RgbPixel, // Serialize as HEX string, e.g. #FFFF00 + * @Serializable(with = RgbAsSingleInt::class) p2: RgbPixel, // Serialize as single integer, e.g. 16711680 + * p3: RgbPixel // Serialize as 3 short components, e.g. { "red": 255, "green": 255, "blue": 0 } * ) * ``` * In this example, each pixel will be serialized using different data representation. diff --git a/core/commonMain/src/kotlinx/serialization/encoding/Decoding.kt b/core/commonMain/src/kotlinx/serialization/encoding/Decoding.kt index dc4aa2ab9e..75bf37f2c2 100644 --- a/core/commonMain/src/kotlinx/serialization/encoding/Decoding.kt +++ b/core/commonMain/src/kotlinx/serialization/encoding/Decoding.kt @@ -250,8 +250,8 @@ public interface Decoder { /** * Decodes the value of type [T] by delegating the decoding process to the given [deserializer]. - * For example, `decodeInt` call us equivalent to delegating integer decoding to [Int.serializer][Int.Companion.serializer]: - * `decodeSerializableValue(IntSerializer)` + * For example, `decodeInt` call is equivalent to delegating integer decoding to [Int.serializer][Int.Companion.serializer]: + * `decodeSerializableValue(Int.serializer())` */ public fun decodeSerializableValue(deserializer: DeserializationStrategy): T = deserializer.deserialize(this) diff --git a/core/commonMain/src/kotlinx/serialization/encoding/Encoding.kt b/core/commonMain/src/kotlinx/serialization/encoding/Encoding.kt index 2b1dd09cc8..76acbf9081 100644 --- a/core/commonMain/src/kotlinx/serialization/encoding/Encoding.kt +++ b/core/commonMain/src/kotlinx/serialization/encoding/Encoding.kt @@ -272,7 +272,7 @@ public interface Encoder { /** * Encodes the [value] of type [T] by delegating the encoding process to the given [serializer]. - * For example, `encodeInt` call us equivalent to delegating integer encoding to [Int.serializer][Int.Companion.serializer]: + * For example, `encodeInt` call is equivalent to delegating integer encoding to [Int.serializer][Int.Companion.serializer]: * `encodeSerializableValue(Int.serializer())` */ public fun encodeSerializableValue(serializer: SerializationStrategy, value: T) { diff --git a/docs/builtin-classes.md b/docs/builtin-classes.md index 0a6a8c1649..f36b8d6df1 100644 --- a/docs/builtin-classes.md +++ b/docs/builtin-classes.md @@ -351,8 +351,8 @@ even if they are numbers in Kotlin, as we can see below. ### Unit and singleton objects -The Kotlin builtin `Unit` type is also serializable. -`Unit` is a Kotlin [singleton object](https://kotlinlang.org/docs/tutorials/kotlin-for-py/objects-and-companion-objects.html), +The Kotlin builtin [Unit](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/) type is also serializable. +`Unit` is a Kotlin [singleton object](https://kotlinlang.org/docs/object-declarations.html#object-declarations-overview), and is handled equally with other Kotlin objects. Conceptually, a singleton is a class with only one instance, meaning that state does not define the object, diff --git a/docs/serialization-guide.md b/docs/serialization-guide.md index 3749909237..01ada5fa9b 100644 --- a/docs/serialization-guide.md +++ b/docs/serialization-guide.md @@ -66,14 +66,14 @@ Once the project is set up, we can start serializing some classes. * [Primitive serializer](serializers.md#primitive-serializer) * [Delegating serializers](serializers.md#delegating-serializers) * [Composite serializer via surrogate](serializers.md#composite-serializer-via-surrogate) - * [Hand-written composite serializer](serializers.md#hand-written-composite-serializer) + * [Handwritten composite serializer](serializers.md#handwritten-composite-serializer) * [Sequential decoding protocol (experimental)](serializers.md#sequential-decoding-protocol-experimental) * [Serializing 3rd party classes](serializers.md#serializing-3rd-party-classes) * [Passing a serializer manually](serializers.md#passing-a-serializer-manually) - * [Specifying serializer on a property](serializers.md#specifying-serializer-on-a-property) - * [Specifying serializer for a particular type](serializers.md#specifying-serializer-for-a-particular-type) + * [Specifying a serializer on a property](serializers.md#specifying-a-serializer-on-a-property) + * [Specifying a serializer for a particular type](serializers.md#specifying-a-serializer-for-a-particular-type) * [Specifying serializers for a file](serializers.md#specifying-serializers-for-a-file) - * [Specifying serializer globally using typealias](serializers.md#specifying-serializer-globally-using-typealias) + * [Specifying a serializer globally using a typealias](serializers.md#specifying-a-serializer-globally-using-a-typealias) * [Custom serializers for a generic type](serializers.md#custom-serializers-for-a-generic-type) * [Format-specific serializers](serializers.md#format-specific-serializers) * [Simultaneous use of plugin-generated and custom serializers](serializers.md#simultaneous-use-of-plugin-generated-and-custom-serializers) diff --git a/docs/serializers.md b/docs/serializers.md index df40863ac7..19542cc686 100644 --- a/docs/serializers.md +++ b/docs/serializers.md @@ -19,14 +19,14 @@ In this chapter we'll take a look at serializers in more detail, and we'll see h * [Primitive serializer](#primitive-serializer) * [Delegating serializers](#delegating-serializers) * [Composite serializer via surrogate](#composite-serializer-via-surrogate) - * [Hand-written composite serializer](#hand-written-composite-serializer) + * [Handwritten composite serializer](#handwritten-composite-serializer) * [Sequential decoding protocol (experimental)](#sequential-decoding-protocol-experimental) * [Serializing 3rd party classes](#serializing-3rd-party-classes) * [Passing a serializer manually](#passing-a-serializer-manually) - * [Specifying serializer on a property](#specifying-serializer-on-a-property) - * [Specifying serializer for a particular type](#specifying-serializer-for-a-particular-type) + * [Specifying a serializer on a property](#specifying-a-serializer-on-a-property) + * [Specifying a serializer for a particular type](#specifying-a-serializer-for-a-particular-type) * [Specifying serializers for a file](#specifying-serializers-for-a-file) - * [Specifying serializer globally using typealias](#specifying-serializer-globally-using-typealias) + * [Specifying a serializer globally using a typealias](#specifying-a-serializer-globally-using-a-typealias) * [Custom serializers for a generic type](#custom-serializers-for-a-generic-type) * [Format-specific serializers](#format-specific-serializers) * [Simultaneous use of plugin-generated and custom serializers](#simultaneous-use-of-plugin-generated-and-custom-serializers) @@ -165,9 +165,11 @@ fun main() { > You can get the full code [here](../guide/example/example-serializer-04.kt). - +``` + + ### Constructing collection serializers @@ -191,9 +193,11 @@ fun main() { > You can get the full code [here](../guide/example/example-serializer-05.kt). - +``` + + ### Using top-level serializer function @@ -217,14 +221,17 @@ fun main() { > You can get the full code [here](../guide/example/example-serializer-06.kt). - +``` + + ## Custom serializers A plugin-generated serializer is convenient, but it may not produce the JSON we want -for such a class as `Color`. Let's study alternatives. +for such a class as `Color`. +Let's study the alternatives. ### Primitive serializer @@ -254,7 +261,7 @@ object ColorAsStringSerializer : KSerializer { } ``` -Serializer has three required pieces. +A serializer has three required pieces. * The [serialize][SerializationStrategy.serialize] function implements [SerializationStrategy]. It receives an instance of [Encoder] and a value to serialize. @@ -419,10 +426,10 @@ class ColorIntArraySerializer : KSerializer { Note that we can't use default `Color.serializer().descriptor` here because formats that rely on the schema may think that we would call `encodeInt` instead of `encodeSerializableValue`. Neither we can use `IntArraySerializer().descriptor` directly — otherwise, formats that handle int arrays specially -can't tell if `value` is really a `IntArray` or a `Color`. Don't worry, this optimization would still kick in -when serializing actual underlying int array. +can't tell if `value` is really an `IntArray` or a `Color`. +Don't worry, this optimization would still kick in when serializing the actual underlying int array. -> Example of how format can treat arrays specially is shown in the [formats guide](formats.md#format-specific-types). +> An example of how a format can treat arrays specially is shown in the [formats guide](formats.md#format-specific-types). Now we can use the serializer: @@ -518,7 +525,7 @@ fun main() { -### Hand-written composite serializer +### Handwritten composite serializer There are some cases where a surrogate solution does not fit. Perhaps we want to avoid the performance implications of additional allocation, or we want a configurable/dynamic set of properties for the @@ -617,10 +624,10 @@ As before, we got the `Color` class represented as a JSON object with three keys ### Sequential decoding protocol (experimental) The implementation of the `deserialize` function from the previous section works with any format. However, -some formats either always store all the complex data in order, or only do so sometimes (JSON always stores -collections in order). With these formats the complex protocol of calling `decodeElementIndex` in the loop is -not needed, and a faster implementation can be used if the [CompositeDecoder.decodeSequentially] function returns `true`. -The plugin-generated serializers are actually conceptually similar to the below code. +some formats either always store all the complex data in order or only do so sometimes (JSON always stores +collections in order). With these formats the complex protocol of calling `decodeElementIndex` in a loop is +unnecessary, and a faster implementation can be used if the [CompositeDecoder.decodeSequentially] function returns `true`. +The plugin-generated serializers are actually conceptually similar to the code below. -### Specifying serializer on a property +### Specifying a serializer on a property When a property of a non-serializable class, like `Date`, is serialized as part of a serializable class we must supply its serializer or the code will not compile. This is accomplished using the [`@Serializable`][Serializable] annotation on the property. @@ -774,7 +787,7 @@ The `stableReleaseDate` property is serialized with the serialization strategy t -### Specifying serializer for a particular type +### Specifying a serializer for a particular type [`@Serializable`][Serializable] annotation can also be applied directly to the types. This is handy when a class that requires a custom serializer, such as `Date`, happens to be a generic type argument. @@ -854,7 +867,7 @@ fun main() { -### Specifying serializer globally using typealias +### Specifying a serializer globally using a typealias kotlinx.serialization tends to be the always-explicit framework when it comes to serialization strategies: normally, they should be explicitly mentioned in `@Serializable` annotation. Therefore, we do not provide any kind of global serializer @@ -1103,7 +1116,7 @@ class ProgrammingLanguage( To provide a context, we define a [SerializersModule] instance that describes which serializers shall be used at run-time to serialize which contextually-serializable classes. This is done using the [SerializersModule {}][SerializersModule()] builder function, which provides the [SerializersModuleBuilder] DSL to -register serializers. In the below example we use the [contextual][_contextual] function with the serializer. The corresponding +register serializers. In the example below we use the [contextual][_contextual] function with the serializer. The corresponding class this serializer is defined for is fetched automatically via the `reified` type parameter. ```kotlin @@ -1201,7 +1214,7 @@ This gets all the `Project` properties serialized: -### External serialization uses properties +### External serialization uses properties As we saw earlier, the regular `@Serializable` annotation creates a serializer so that [Backing fields are serialized](basic-serialization.md#backing-fields-are-serialized). _External_ serialization using diff --git a/formats/README.md b/formats/README.md index 327c2d78ff..62d59c41bc 100644 --- a/formats/README.md +++ b/formats/README.md @@ -26,9 +26,9 @@ For convenience, they have same `groupId`, versioning and release cycle as core | MsgPack | [esensar/kotlinx-serialization-msgpack](https://github.com/esensar/kotlinx-serialization-msgpack)
`com.ensarsarajcic.kotlinx:serialization-msgpack` | all supported platforms | Allows serialization and deserialization of objects to and from [MsgPack](https://msgpack.org/). | | SharedPreferences | [EdwarDDay/serialization.kprefs](https://github.com/EdwarDDay/serialization.kprefs)
`net.edwardday.serialization:kprefs` | Android only | This library allows serialization and deserialization of objects into and from Android [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences). | | XML | [pdvrieze/xmlutil](https://github.com/pdvrieze/xmlutil)
`io.github.pdvrieze.xmlutil:serialization` | all supported platforms | This library allows for reading and writing of XML documents with the serialization library. It is multiplatform, providing both a shared parser/writer for xml as well as platform-specific parsers where available. The library is designed to handle existing xml formats that use features that would not be available in other formats such as JSON. | -| YAML | [charleskorn/kaml](https://github.com/charleskorn/kaml)
`com.charleskorn.kaml:kaml` | JVM only | Allows serialization and deserialization of objects to and from [YAML](http://yaml.org). | +| YAML | [charleskorn/kaml](https://github.com/charleskorn/kaml)
`com.charleskorn.kaml:kaml` | all supported platforms | Allows serialization and deserialization of objects to and from [YAML](http://yaml.org). | | YAML | [him188/yamlkt](https://github.com/him188/yamlkt)
`net.mamoe.yamlkt:yamlkt` | all supported platforms | Allows serialization and deserialization of objects to and from [YAML](http://yaml.org). Basic serial operations have been implemented, but some features such as compound keys and polymorphism are still work in progress. | -| CBOR | [L-Briand/obor](https://github.com/L-Briand/obor)
`net.orandja.obor:obor` | JVM, Android | Allow serialization and deserialization of objects to and from [CBOR](https://cbor.io/). This codec can be used to read and write from Java InputStream and OutputStream. | +| CBOR | [L-Briand/obor](https://github.com/L-Briand/obor)
`net.orandja.obor:obor` | all supported platforms | Allow serialization and deserialization of objects to and from [CBOR](https://cbor.io/). The serializer supports major type 2 byte string and custom tags. | | Amazon Ion (binary only) | [dimitark/kotlinx-serialization-ion](https://github.com/dimitark/kotlinx-serialization-ion)
`com.github.dimitark:kotlinx-serialization-ion` | JVM only | Allow serialization and deserialization of objects to and from [Amazon Ion](https://amzn.github.io/ion-docs/). It stores the data in a flat binary format. Upon destialization, it retains the references between the objects. | | android.os.Bundle | [AhmedMourad0/bundlizer](https://github.com/AhmedMourad0/bundlizer)
`dev.ahmedmourad.bundlizer:bundlizer-core` | Android | Allow serialization and deserialization of objects to and from [android.os.Bundle](https://developer.android.com/reference/android/os/Bundle). | | CSV | [hfhbd/kotlinx-serialization-csv](https://github.com/hfhbd/kotlinx-serialization-csv)
`app.softwork:kotlinx-serialization-csv` | all supported platforms | Allows serialization and deserialization of CSV files. There are still some limitations (ordered properties). |