Wednesday, September 5, 2012

Easily implementing Json serialization for Play using macro. Function by symbol (lisp-like)l

I liked the idea of using fields macro in scala so much so I created a dedicated project for this macro to start reusing it in the different projects I did. Here it is.

Few words about implementation of this macro

The code has been reworked and now it is possible to transform field value using a supplied function. It means that Field and Fields types, and fields macro signatures are changed. In addition, there is a new convenient macro called allFields. I.e.:
    case class Field[-I <: AnyRef, +R, +A <: Product](name: String, get: I => R, args: A)
    type Fields[-I <: AnyRef, +R, +A <: Product] = List[Field[I, R, A]]
    def fields[Ann, I <: AnyRef, R, Args <: Product](apply: Symbol) = macro fieldsImpl[Ann, I, R, Args]
    def allFields[I <: AnyRef, R](apply: Symbol) = macro fieldsImpl[Any, I, R, None.type]
allFields is the new function that lists all public value members enclosed in the given type regardless of annotations. R in a Field(s) type stands for RETURN and represents type of a value returned by the field getter transformed using the supplied function. Value transformer function is passed into the macro using its symbol. You might wonder why aren't we just using something like f : T => R forSome { type T } ? That's because you can't pass the following function that way:
    def trans[T : TypeClass](x : T) : Int = ???
(which is just a sweet way of saving some keystrokes by not writing this:)
    def trans[T](x : T)(implicit tc : TypeClass[T]) : Int = ???
i.e. you can't pass function with TWO parameters (one of which is implicit parameter) where a ONE parameter function is expected. That is quite obvious but anyway.. So we use Symbol (in the spirit of Lisp). As you might guess by looking at the snippet below, it is expected that the symbol is constructed directly and not passed by reference:
        val applyFunName =
            apply.tree match {
                case Apply(_, List(Literal(Constant(s)))) => s.toString
                case _ =>
                    c.abort(apply.tree.pos,
                        "fields macro is expected to be used with symbol literal like 'nothing or 'myFunction")
            }
Almost everything in the macro implementation remains more-less same, except part that constructs expression for getting field value out of object. Now it looks like this:
                val applyFunTree = c.parse(applyFunName)
                val getFunArgTree = ValDef(Modifiers(), newTermName("x"), TypeTree(instanceT), EmptyTree)
                
                val getFunBodyTree =
                    treeBuild.mkMethodCall(applyFunTree,
                        List(Select(Ident(newTermName("x")), newTermName(name)),
                             argsTree))
getFunBodyTree illustrates what signature is really expected for the transformer function: in addition to field value, all arguments of the annotation are passed into the function (or None if no annotation used or annotation has no arguments). For example, you can't use Predef.identity function, instead, you should use valueIdentity which is (already) defined like this:
def valueIdentity[X] (value : X, annotationArgs : Any) : X = value
Having annotation arguments provided for the currently processing field gives you possibility for further customization of how the value is transformed. Now lets do an example.

Real-world example

Suppose you want to serialize your custom classes into JSON with no boilerplate code what so ever. That is how you can do it with this only (general-purpose) macro. Lets define some generic Writes typeclase provider:
    implicit def writesForFields[T <: AnyRef](implicit fields: clazz.Fields[T, JsValue, _]): Writes[T] = {
        new Writes[T] {
            def writes(t: T): JsValue = {
                JsObject(fields map {
                    (field: clazz.Field[T, JsValue, _]) =>
                        field.name -> field.get(t: T)
                })
            }
        }
    }
The function shown above implicitly creates Writes for any type T which has an implicit instance of type Fields[T, JsValue, _] (read it like "List of fields of class T along with function to get value of type JsValue for each field"). Now lets define the transformer function, it will be used for serialization of field values:
def asJsValue[T : Writes](v : T, annArgs : Any) : JsValue = Json.toJson(v)
That was the only code needed to bootstrap your mini-serialization framework. Now you can use it. Lets assume you have declarations:
    case class JquerySocketEvent[T](id: Int, data: T, `type`: String = "message", reply: Boolean = false)
    case class ChatMessage(user: String, text: String)
    
    implicit def jquerySocketEventJsFields[T: Writes] = clazz.allFields[JquerySocketEvent[T], JsValue]('asJsValue)
    implicit val chatMessageJsFields = clazz.allFields[ChatMessage, JsValue]('asJsValue)
That's it. ... some fun:
        val event = JquerySocketEvent(id = 1, data = ChatMessage("Fluttershy", "Yay!"))
        println (Json.toJson(event))
... prints:
    {"id":1,"data":{"user":"Fluttershy","text":"Yay!"},"type":"message","reply":false}
That was easy enough. Feel free to use it, re-implement it or implement a more powerful stuff. Macros FTW!

7 comments: