diff --git a/README.md b/README.md index c24ffe4..050f037 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Contents * [Changelog](#changelog) Getting started ------------------------------------------- +---------------------------------------------- The library is published to the Maven central, so you can just add the following line to your `build.sbt` file in order to use the core library: @@ -99,7 +99,7 @@ available later. [Jawn]: https://github.com/non/jawn Serialization mechanism ----------------------------------------------------------- +-------------------------------------------------------------- picopickle uses the pretty standard typeclass approach where the way the type is serialized or deserialized is defined through implicit objects (called `Reader[T]` and `Writer[T]` in picopickle) @@ -136,7 +136,7 @@ picopickle also supports default values and variable arguments in case classes a or sealed trait descendants with a bit of custom macros. Usage ------ +-------------------------- ### Basic usage @@ -546,7 +546,7 @@ val s: backend.BString = backend.makeString("hello world") These implicit methods are somewhat more convenient than `make*` functions. Converters --------------------------------- +------------------------------------ Low-level conversions, however, may be overly verbose to write. picopickle provides a declarative way of defining how the backend representation should be translated to the desired Scala objects and vice versa. @@ -677,7 +677,7 @@ val optionStringConv: Converter.Id[Option[String]] = value[Option[String]] You can find more on converters in their Scaladoc section (**TODO**). Supported types ------------------------------------------- +---------------------------------------------- By default picopickle provides a lot of serializers for various types which do their best to represent their respective types in the serialized form as close as possible. @@ -1141,7 +1141,7 @@ as a `BNumber` if it can be represented precisely in `Double` as a `BString` oth This trait is useful e.g. when writing a JSON-based backend. Official backends ----------------------------------------------- +-------------------------------------------------- ### Collections pickler @@ -1295,7 +1295,7 @@ it serializes `BValue` as `BValue`, `BString` as `BString`, `BInt64` as `BInt64` [bson]: http://mongodb.github.io/mongo-java-driver/3.0/bson/ Error handling ----------------------------------------- +-------------------------------------------- While serialization is straightforward and should never fail (if it does, it is most likely a bug in the library or in some `Writer` implementation), deserialization is prone to errors because the serialized representation usually @@ -1384,7 +1384,7 @@ serialization methods, like Jawn's `tryReadString()`. Limitations ----------------------------------- +-------------------------------------- picopickle does not support serializing `Any` in any form because it relies on the static knowledge of types being serialized. However, its design, as far as I can tell, in principle does not disallow writing @@ -1434,16 +1434,17 @@ object Serializers { Plans ----------------------- +-------------------------- * Consider adding support for more types * Consider adding more converters (e.g. for tuples) +* Add proper support for error handling in conversions * Add more tests * Add more documentation Changelog ------------------------------- +---------------------------------- ### 0.2.0 diff --git a/notes/0.2.0.markdown b/notes/0.2.0.markdown index a1be6c4..6ae9d98 100644 --- a/notes/0.2.0.markdown +++ b/notes/0.2.0.markdown @@ -1,55 +1,53 @@ This release contains a lot of changes and new features. -* Updated shapeless to 2.3.3, jawn to 0.8.8, scala to 2.11.7. +### Updated shapeless to 2.3.3, jawn to 0.8.8, scala to 2.11.7. - In particular, updating shapeless allowed using picopickle with case classes with variable arguments. +In particular, updating shapeless allowed using picopickle with case classes with variable arguments. -* Improved reader interface - added `readOrElse` method and changed existing code to depend on it. +### Improved reader interface - added `readOrElse` method and changed existing code to depend on it. - `readOrElse` is borrowed from `PartialFunction` trait where it is called `applyOrElse`. It is an - important method for optimization because it allows checking whether a function (reader) can be - applied to a value and apply it to this value at the same time. Now `Reader` trait has this method - and it is defined and used correctly by the built-in `Reader` combinators, in particular, - for error checks. +`readOrElse` is borrowed from `PartialFunction` trait where it is called `applyOrElse`. It is an +important method for optimization because it allows checking whether a function (reader) can be +applied to a value and apply it to this value at the same time. Now `Reader` trait has this method +and it is defined and used correctly by the built-in `Reader` combinators, in particular, +for error checks. -* Added proper error handling. +### Added proper error handling. - While writing data to backend representation is usually an error-free operation (if there is a writer - for some type, it should handle all values of this type), reading data from the backend representation - is a source of errors. This happens because the backend representation has much weaker typing guarantees - than Scala code and can't correspond directly to Scala types. - - Previously picopickle didn't provide any special error handling. If the backend value couldn't be - deserialized, picopickle would throw some obscure `MatchError` or `IllegalArgumentException`. Since - 0.2.0 picopickle has a proper exception system, and if a read error occurs, the exception would contain - much more information about what was expected and what was actually found. You can find more on it - in [Readme][readme-error-handling]. - -* Added new BSON-based backend. +While writing data to backend representation is usually an error-free operation (if there is a writer +for some type, it should handle all values of this type), reading data from the backend representation +is a source of errors. This happens because the backend representation has much weaker typing guarantees +than Scala code and can't correspond directly to Scala types. - A new officially supported backend has been added. It uses [MongoDB BSON][mongodb-bson] data types - as the backend representation. - - With this backend it is possible to use picopickle for serialization using the official Mongo drivers. +Previously picopickle didn't provide any special error handling. If the backend value couldn't be +deserialized, picopickle would throw some obscure `MatchError` or `IllegalArgumentException`. Since +0.2.0 picopickle has a proper exception system, and if a read error occurs, the exception would contain +much more information about what was expected and what was actually found. You can find more on it +in [Readme][readme-error-handling]. - It also serves as an example extended backend implementation with more types than the basic backend - supports. +### Added new BSON-based backend. -* Added support for changing STH discriminator key on per-STH basis. +A new officially supported backend has been added. It uses [MongoDB BSON][mongodb-bson] data types +as the backend representation. - It is now possible to change sealed trait hierarchy discriminator key for each sealed trait separately: - - ```scala - @discriminator("status") sealed trait Root - case object Stopped extends Root - case class Running(name: String) extends Root - - writeString[Root](Stopped) shouldEqual """{"status":"Stopped"}""" - writeString[Root](Running("me")) shouldEqual """{"status":"Running","name":"me"}""" - ``` - - This allows even more flexibility in defining serialization formats, especially when matching some - existing interface. +With this backend it is possible to use picopickle for serialization using the official Mongo drivers. + +It also serves as an example extended backend implementation with more types than the basic backend +supports. + +### Added support for changing STH discriminator key on per-STH basis. + +It is now possible to change sealed trait hierarchy discriminator key for each sealed trait separately: + + @discriminator("status") sealed trait Root + case object Stopped extends Root + case class Running(name: String) extends Root + + writeString[Root](Stopped) shouldEqual """{"status":"Stopped"}""" + writeString[Root](Running("me")) shouldEqual """{"status":"Running","name":"me"}""" + +This allows even more flexibility in defining serialization formats, especially when matching some +existing interface. More information can be found in the [readme](https://github.com/netvl/picopickle#readme).