A tiny micro-library for encoding scala-xml with zero dependencies (outside of scala-xml itself)
See blog post //TODO BEFORE PUBLISHING ARTIFACTS
Import it
import codes.mostly.xml.XmlSugar._
Define your encoders:
case class Employee(name: String, hasProvidedTaxCode: Boolean)
case class TerribleAccountingSoftware(employees: Option[List[Set[Seq[Option[List[Employee]]]]]]) // Hopefully a contrived example
implicit val developerEncoder: XmlEncoder[Employee] = employee =>
<emp>
<name>{employee.name}</name>
<isPayingTax>{employee.hasProvidedTaxCode.toString}</isPayingTax>
</emp>
implicit val accountingSoftwareEncoder: XmlEncoder[TerribleAccountingSoftware] = software =>
<accountingSofware3000>
<employees>{software.employees.asXml}</employees>
</accountingSofware3000>
And produce XML:
myAccountingSoftware.asTopLevelXml match {
Left(error: String) => ??? // in case you goofed and didn't produce EXACTLY one xml element
Right(elem: scala.xml.Elem) => ??? // here's your valid XML element
}
(here's this example written as a unit test)
That's it!
- Encode a basic case class
- Encode a more complex case class (with nested case classes and collections)
- Encode an AST / a type hierarchy
- Encode Collections (List, Set, Seq, Option)
- Encode Option
- Encode Scala Primitives (String, Int, Long and such)
- Encode the same type in multiple different ways
- Encode while having to omit an XML element
- Adding an optional attribute to an XML Element
To make writing XML more fun and less annoying by using implicit encoders which
is inspired by circe
, but a little simpler and a lot less grand in scope.
The general concepts are:
- Put implicit XML encoders for your models into scope
- Once you have that, define your XML using standard scala-xml syntax
.asXml
to encode the child types. - Empty collections means no XML elements are produced
I like cats too, but I didn't want to add more dependencies to this micro library.
In general, if you need to add encoders for any structural types, the easiest
thing is to convert them to a list and call .asXml
on them. If you for instance wanted
NonEmptyList and NonEmptySet encoders, you could do:
import codes.mostly.xml.XmlSugar._
implicit def encodeNEL[A](implicit aEnc: XmlEncoder[A]): XmlEncoder[NonEmptyList[A]] = nel => nel.toList.toXml
implicit def encodeNES[A](implicit aEnc: XmlEncoder[A]): XmlEncoder[NonEmptySet[A]] = nes => nes.toNonEmptyList.toXml
And now you can encode to your heart's content:
case class Person(name: String, hobbies: NonEmptySet[Hobby], jobs: NonEmptyList[Job])
implicit val personEncoder: XmlEncoder[Person] = p =>
<person name={p.name}>
{p.hobbies.asXml} <!-- assuming an XmlEncoder[Hobby] exists in scope -->
{p.jobs.asXml} <!-- assuming an XmlEncoder[Job] exists in scope -->
</person>
- No de-coding of XML
- Automatically deriving XML based on your case classes is out of scope for this project.
- It's assumed your encoders are always deterministic - this won't catch any errors thrown or raised during encoding. So don't do that.