tinkoff / phobos   0.18.0

Apache License 2.0 GitHub

Efficient and expressive XML data-binding library for Scala

Scala versions: 2.12 2.13 3.x

phobos

Maven Central Build Scala Steward Discord

Phobos is an XML data-binding library based on stream parsing. It depends only on aalto-xml for parsing.

Scala 2.12, 2.13 and 3.1 are supported. Scala 3.0 is supported in core-3-0 module. See Supported Scala versions for more details.

QuickStart

Add phobos-core to your dependencies:

libraryDependencies += "ru.tinkoff" %% "phobos-core" % "0.18.0"

Then try this code out in sbt console or in a separate source file:

import ru.tinkoff.phobos.decoding._
import ru.tinkoff.phobos.encoding._
import ru.tinkoff.phobos.syntax._
import ru.tinkoff.phobos.derivation.semiauto._

case class TravelPoint(country: String, city: String)
object TravelPoint {
  implicit val travelPointElementEncoder: ElementEncoder[TravelPoint] = deriveElementEncoder
  implicit val travelPointElementDecoder: ElementDecoder[TravelPoint] = deriveElementDecoder
}

case class Price(@attr currency: String, @text value: Double)
object Price {
  implicit val priceElementEncoder: ElementEncoder[Price] = deriveElementEncoder
  implicit val priceElementDecoder: ElementDecoder[Price] = deriveElementDecoder
}

case class Journey(price: Price, departure: TravelPoint, arrival: TravelPoint)
object Journey {
  implicit val journeyXmlEncoder: XmlEncoder[Journey] = deriveXmlEncoder("journey")
  implicit val journeyXmlDecoder: XmlDecoder[Journey] = deriveXmlDecoder("journey")
}


val journey =
  Journey(
    price = Price("EUR", 1000.0),
    departure = TravelPoint("France", "Marcelle"),
    arrival = TravelPoint("Germany", "Munich")
  )

val xml: String = XmlEncoder[Journey].encode(journey)
println(xml)

val decodedJourney = XmlDecoder[Journey].decode(xml)
println(decodedJourney)

assert(Right(journey) == decodedJourney)

Please see phobos wiki for explanation of the syntax and more details.

Performance

Performance details can be found out in phobos-benchmark repository.

Modules

There are several additional modules for some specific cases. These modules could be added with command below:

libraryDependencies += "ru.tinkoff" %% "phobos-<module>" % "0.18.0"

Where <module> is module name.

Module name Functionality
core-3-0 Core module compiled for Scala 3.0.
ast Support for parsing XML into AST
akka-http Marshallers and unmarshallers for akka-http
akka-stream Streaming decoding support for akka-stream
cats Cats instances
derevo Separate derivation of encoders and decoders separately using derevo annotations (e.g. @derive(xmlEncoder("foo")))
enumeratum Support for enumeratum enums
fs2 Streaming decoding support (Stream[F, Array[Byte]] => G[A]). Latest fs2 version (fs2 3.x, cats effect 3.x)
fs2-ce2 Streaming decoding support (Stream[F, Array[Byte]] => G[A]). Same as fs2 module, but for fs2 version 2.x using cats effect 2.x
monix Streaming decoding support (Observable[Array[Byte]] => Task[A])
refined Support for refined

Supported Scala versions

Most modules support Scala 2.12, 2.13 and 3.1. Dependencies for some modules don't support Scala 3, thus these modules support only Scala 2.x. Most module dependencies are compiled for Scala 3.1, and they can not be used with Scala 3.0, because Scala 3 TASTy files are not forward compatible. Module core is also compiled for Scala 3.1, but core features may be used via core-3-0 module.

Detailed information about supported Scala versions is in the table. Available versions for modules are marked with ✓.

Module name 2.12 2.13 3.0 3.1
core
core-3-0
akka-http
akka-stream
ast
cats
derevo
enumeratum
fs2
fs2-ce2
monix
refined

XSD and WSDL code-generation support

Classes from XSD could be generated using deimos library.