uPickle is a lightweight JSON and binary MessagePack serialization library for Scala. It is simple to use, flexible and easily customizable and has zero dependencies.
1 Introduction
To use uPickle, import it in Mill ivy"com.lihaoyi::upickle:1.1.0". Then use it:
|
|
1.1 Supported Types
Use write, read, writeBinary, readBinary. The indent parameter formats the output in indented format.
The data types include:
BooleanInt,Short,Byte,Float, andDouble. LargeLongvalues too large for Javascript and are written as a string. Speical values includeInfinity,-Infinity.CharandStringare serialzed as strings.- Immutable
Array,Seq,Vector,List,SortedSet,Mapetc. are serialized as JSON lists. Options are serialized as JSON lists with 0 or 1 element.Tuples from 1 to 22 are serialized as heterogenous JSON lists.case classandcase object, stand-alone.sealed traitorsealed classhierarchy.nulls seraialize into JSON nulls.UUIDDuraionEither
uPickle only throws exceptions on unpickling. Readability and writability is recursive: a class is only serializable if all its fields are serializable. Case classes are serialized using the apply and unapply methos on their companion objects.
If a field is missing upon deserialization, uPickle uses the ddefault value for the type if one exists.
1.2 Case Classes
Case classes of sizes 1-22 are serialized as JSON dictionaries. A serializer should be defined in the case class’s companion object as: implicit val rw: ReadWriter[MyCaseClass] = macroRW.
Sealed hierarchies are serialized as tagged values, the serialized object tagged with the full name of the instance’s class.
1.3 Read/Writing Other Things
Other than strings, uPickle can read/write form other sources such as CharSequence, Array[Byte], java.io.File and java.nio.file.path.
1.4 Common Operations
Use readwriter[T].bimap[V](toT, toV) function to create a pickler that reads/writes a type V, using the pickler for type T, by providing a conversion function between them.
More control can be done using readwriter[ujson.Value].bimap[V](toujson, toV) and raw JSON AST.
Use @upickle.implicits.key("name") to custom the key of a field. It can also be used to custom the tagged class name.
Use a custom pickler to change project-wide configuration.
1.5 Limitations
uPickle doesn’t support:
- circular object graphs
- reflective reading and writing
- read/write of untyped values such as
Any - read/write arbitrarily shaped objects
- read/write case classes with multiple parameter lists
Due to a Scala bug, automatic sealed trait pickling can fail unpredictably. This can be fixed by using the macroRW and merge methods.
|
|
2 uJson
uJson is uPickle’s JSON lib. It is used to manipulate JSON source and data structures without converting them into Scala case-classes.
2.1 uJson Values
You can use ujson to construct JSON blobs, either programmatically or parsing from strings, byte arrays or files.
ujson.Js AST (ujson.Value) is mutable. A ujson.Value can be one of the following types:
|
|
You can use str, bool, num, arr, and obj etc to casts a ujson.Value to the specific sub-type and corresponding value. Each type has a Opt postfix method for optional values.
You can construct JSON data using the above types or primitive types:
|
|
Use ujson.write to serialize a uJson value into string.
2.2 Converting To/From Scala Data Types
Scala case classes or other data structures can be converted to ujson.Js AST using upickle.default.writeJs and upickle.default.readJs or plian upickle.default.read, upickle.default.write.
uJson allows you convert between any of the following forms:
- case class and Scala data types
ujson.JsASTString,CharSequence,Array[Byte]- Third party JSON ASTs such as
Argonaut,Circe,Json4s, andPlay-Json
The case class can be sested. ujson.Value can be stroed as a case class field.