android/sensors: the example and some whitespace

[nit.git] / lib / json / serialization.nit

diff --git a/lib/json/serialization.nit b/lib/json/serialization.nit
index 19bea9e..3707b19 100644 (file)
--- a/lib/json/serialization.nit
+++ b/lib/json/serialization.nit
@@ -55,11 +55,42 @@
 # assert alice.to_plain_json == """
 # {"name": "Alice", "year_of_birth": 1978, "next_of_kin": {"name": "Bob", "year_of_birth": 1986, "next_of_kin": null}}"""
 # ~~~
+#
+# ## JSON to Nit objects
+#
+# The `JsonDeserializer` support reading JSON code with minimal meta-data
+# to easily create Nit object from client-side code or configuration files.
+# Each JSON object must define the `__class` attribute with the corresponding
+# Nit class and the expected attributes with its name in Nit followed by its value.
+#
+# ### Usage Example
+#
+# ~~~nitish
+# import json::serialization
+#
+# class MeetupConfig
+#     serialize
+#
+#     var description: String
+#     var max_participants: nullable Int
+#     var answers: Array[FlatString]
+# end
+#
+# var json_code = """
+# {"__class": "MeetupConfig", "description": "My Awesome Meetup", "max_participants": null, "answers": ["Pepperoni", "Chicken"]}"""
+# var deserializer = new JsonDeserializer(json_code)
+#
+# var meet = deserializer.deserialize
+# assert meet isa MeetupConfig
+# assert meet.description == "My Awesome Meetup"
+# assert meet.max_participants == null
+# assert meet.answers == ["Pepperoni", "Chicken"]
+# ~~~
 module serialization
 
 import ::serialization::caching
 private import ::serialization::engine_tools
-private import static
+import static
 
 # Serializer of Nit objects to Json string.
 class JsonSerializer
@@ -256,12 +287,17 @@ class JsonDeserializer
                                        end
                                end
 
-                               if not object.keys.has("__class") then
+                               var class_name = object.get_or_null("__class")
+                               if class_name == null then
+                                       # Fallback to custom heuristic
+                                       class_name = class_name_heuristic(object)
+                               end
+
+                               if class_name == null then
                                        errors.add new Error("Serialization Error: JSON object declaration does not declare a `__class`.")
                                        return object
                                end
 
-                               var class_name = object["__class"]
                                if not class_name isa String then
                                        errors.add new Error("Serialization Error: JSON object declaration declares a non-string `__class`.")
                                        return object
@@ -362,6 +398,54 @@ class JsonDeserializer
                errors.clear
                return convert_object(root)
        end
+
+       # User customizable heuristic to get the name of the Nit class to deserialize `json_object`
+       #
+       # This method is called only when deserializing an object without the metadata `__class`.
+       # Return the class name as a `String` when it can be inferred.
+       # Return `null` when the class name cannot be found.
+       #
+       # If a valid class name is returned, `json_object` will then be deserialized normally.
+       # So it must contain the attributes of the corresponding class, as usual.
+       #
+       # ~~~nitish
+       # class MyData
+       #     serialize
+       #
+       #     var data: String
+       # end
+       #
+       # class MyError
+       #     serialize
+       #
+       #     var error: String
+       # end
+       #
+       # class MyJsonDeserializer
+       #     super JsonDeserializer
+       #
+       #     redef fun class_name_heuristic(json_object)
+       #     do
+       #         if json_object.keys.has("error") then return "MyError"
+       #         if json_object.keys.has("data") then return "MyData"
+       #         return null
+       #     end
+       # end
+       #
+       # var json = """{"data": "some other data"}"""
+       # var deserializer = new MyJsonDeserializer(json)
+       # var deserialized = deserializer.deserialize
+       # assert deserialized isa MyData
+       #
+       # json = """{"error": "some error message"}"""
+       # deserializer = new MyJsonDeserializer(json)
+       # deserialized = deserializer.deserialize
+       # assert deserialized isa MyError
+       # ~~~
+       protected fun class_name_heuristic(json_object: JsonObject): nullable String
+       do
+               return null
+       end
 end
 
 redef class Serializable