lib/json/serialization_write.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #     http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Services to write Nit objects to JSON strings: `serialize_to_json` and `JsonSerializer`
  16 module serialization_write
  17
  18 import ::serialization::caching
  19 private import ::serialization::engine_tools
  20
  21 # Serializer of Nit objects to Json string.
  22 class JsonSerializer
  23         super CachingSerializer
  24
  25         # Target writing stream
  26         var stream: Writer
  27
  28         # Write plain JSON? Standard JSON without metadata for deserialization
  29         #
  30         # If `false`, the default, serialize to support deserialization:
  31         #
  32         # * Write metadata, including the types of the serialized objects so they can
  33         #   be deserialized to their original form using `JsonDeserializer`.
  34         # * Use references when an object has already been serialized so to not duplicate it.
  35         # * Support cycles in references.
  36         # * Preserve the Nit `Char` type as an object because it does not exist in JSON.
  37         # * The generated JSON is standard and can be read by non-Nit programs.
  38         #   However, some Nit types are not represented by the simplest possible JSON representation.
  39         #   With the added metadata, it can be complex to read.
  40         #
  41         # If `true`, serialize for other programs:
  42         #
  43         # * Nit objects are serialized to pure and standard JSON so they can
  44         #   be easily read by non-Nit programs and humans.
  45         # * Nit objects are serialized for every references, so they can be duplicated.
  46         #   It is easier to read but it creates a larger output.
  47         # * Does not support cycles, will replace the problematic references by `null`.
  48         # * Does not serialize the metadata needed to deserialize the objects
  49         #   back to regular Nit objects.
  50         # * Keys of Nit `HashMap` are converted to their string representation using `to_s`.
  51         var plain_json = false is writable
  52
  53         # Write pretty JSON for human eyes?
  54         #
  55         # Toggles skipping lines between attributes of an object and
  56         # properly indent the written JSON.
  57         var pretty_json = false is writable
  58
  59         # Current indentation level used for writing `pretty_json`
  60         private var indent_level = 0
  61
  62         # List of the current open objects, the first is the main target of the serialization
  63         #
  64         # Used only when `plain_json == true` to detect cycles in serialization.
  65         private var open_objects = new Array[Object]
  66
  67         # Has the first attribute of the current object already been serialized?
  68         #
  69         # Used only when `plain_json == true`.
  70         private var first_attribute = false
  71
  72         redef fun serialize(object)
  73         do
  74                 if object == null then
  75                         stream.write "null"
  76                 else
  77                         if plain_json then
  78                                 for o in open_objects do
  79                                         if object.is_same_serialized(o) then
  80                                                 # Cycle, can't be managed in plain json
  81                                                 warn "Cycle detected in serialized object, replacing reference with 'null'."
  82                                                 stream.write "null"
  83                                                 return
  84                                         end
  85                                 end
  86
  87                                 open_objects.add object
  88                         end
  89
  90                         first_attribute = true
  91                         object.accept_json_serializer self
  92                         first_attribute = false
  93
  94                         if plain_json then open_objects.pop
  95                 end
  96         end
  97
  98         redef fun serialize_attribute(name, value)
  99         do
 100                 if not plain_json or not first_attribute then
 101                         stream.write ","
 102                         first_attribute = false
 103                 end
 104
 105                 new_line_and_indent
 106                 stream.write "\""
 107                 stream.write name
 108                 stream.write "\":"
 109                 if pretty_json then stream.write " "
 110                 super
 111         end
 112
 113         redef fun serialize_reference(object)
 114         do
 115                 if not plain_json and cache.has_object(object) then
 116                         # if already serialized, add local reference
 117                         var id = cache.id_for(object)
 118                         stream.write "\{"
 119                         indent_level += 1
 120                         new_line_and_indent
 121                         stream.write "\"__kind\": \"ref\", \"__id\": "
 122                         stream.write id.to_s
 123                         indent_level -= 1
 124                         new_line_and_indent
 125                         stream.write "\}"
 126                 else
 127                         # serialize here
 128                         serialize object
 129                 end
 130         end
 131
 132         # Write a new line and indent it, only if `pretty_json`
 133         private fun new_line_and_indent
 134         do
 135                 if pretty_json then
 136                         stream.write "\n"
 137                         for i in indent_level.times do stream.write "\t"
 138                 end
 139         end
 140 end
 141
 142 redef class Text
 143
 144         redef fun accept_json_serializer(v)
 145         do
 146                 v.stream.write "\""
 147                 for i in [0 .. self.length[ do
 148                         var char = self[i]
 149                         if char == '\\' then
 150                                 v.stream.write "\\\\"
 151                         else if char == '\"' then
 152                                 v.stream.write "\\\""
 153                         else if char < ' ' then
 154                                 if char == '\n' then
 155                                         v.stream.write "\\n"
 156                                 else if char == '\r' then
 157                                         v.stream.write "\\r"
 158                                 else if char == '\t' then
 159                                         v.stream.write "\\t"
 160                                 else
 161                                         v.stream.write char.escape_to_utf16
 162                                 end
 163                         else
 164                                 v.stream.write char.to_s
 165                         end
 166                 end
 167                 v.stream.write "\""
 168         end
 169 end
 170
 171 redef class Serializable
 172
 173         # Serialize `self` to JSON
 174         #
 175         # Set `plain = true` to generate standard JSON, without deserialization metadata.
 176         # Use this option if the generated JSON will be read by other programs or humans.
 177         # Use the default, `plain = false`, if the JSON is to be deserialized by a Nit program.
 178         #
 179         # Set `pretty = true` to generate pretty JSON for human eyes.
 180         # Use the default, `pretty = false`, to generate minified JSON.
 181         #
 182         # This method should not be refined by subclasses,
 183         # instead `accept_json_serializer` can customize the serialization of an object.
 184         #
 185         # See: `JsonSerializer`
 186         fun serialize_to_json(plain, pretty: nullable Bool): String
 187         do
 188                 var stream = new StringWriter
 189                 var serializer = new JsonSerializer(stream)
 190                 serializer.plain_json = plain or else false
 191                 serializer.pretty_json = pretty or else false
 192                 serializer.serialize self
 193                 stream.close
 194                 return stream.to_s
 195         end
 196
 197         # Serialize `self` to plain JSON
 198         #
 199         # Compatibility alias for `serialize_to_json(plain=true)`.
 200         fun to_json: String do return serialize_to_json(plain=true)
 201
 202         # Serialize `self` to plain pretty JSON
 203         #
 204         # Compatibility alias for `serialize_to_json(plain=true, pretty=true)`.
 205         fun to_pretty_json: String do return serialize_to_json(plain=true, pretty=true)
 206
 207         # Refinable service to customize the serialization of this class to JSON
 208         #
 209         # This method can be refined to customize the serialization by either
 210         # writing pure JSON directly on the stream `v.stream` or
 211         # by using other services of `JsonSerializer`.
 212         #
 213         # Most of the time, it is preferable to refine the method `core_serialize_to`
 214         # which is used by all the serialization engines, not just JSON.
 215         protected fun accept_json_serializer(v: JsonSerializer)
 216         do
 217                 var id = v.cache.new_id_for(self)
 218                 v.stream.write "\{"
 219                 v.indent_level += 1
 220                 if not v.plain_json then
 221                         v.new_line_and_indent
 222                         v.stream.write "\"__kind\": \"obj\", \"__id\": "
 223                         v.stream.write id.to_s
 224                         v.stream.write ", \"__class\": \""
 225                         v.stream.write class_name
 226                         v.stream.write "\""
 227                 end
 228                 core_serialize_to(v)
 229
 230                 v.indent_level -= 1
 231                 v.new_line_and_indent
 232                 v.stream.write "\}"
 233         end
 234 end
 235
 236 redef class Int
 237         redef fun accept_json_serializer(v) do v.stream.write to_s
 238 end
 239
 240 redef class Float
 241         redef fun accept_json_serializer(v) do v.stream.write to_s
 242 end
 243
 244 redef class Bool
 245         redef fun accept_json_serializer(v) do v.stream.write to_s
 246 end
 247
 248 redef class Char
 249         redef fun accept_json_serializer(v)
 250         do
 251                 if v.plain_json then
 252                         to_s.accept_json_serializer v
 253                 else
 254                         v.stream.write "\{\"__kind\": \"char\", \"__val\": "
 255                         to_s.accept_json_serializer v
 256                         v.stream.write "\}"
 257                 end
 258         end
 259 end
 260
 261 redef class NativeString
 262         redef fun accept_json_serializer(v) do to_s.accept_json_serializer(v)
 263 end
 264
 265 redef class Collection[E]
 266         # Utility to serialize a normal Json array
 267         private fun serialize_to_pure_json(v: JsonSerializer)
 268         do
 269                 v.stream.write "["
 270                 var is_first = true
 271                 for e in self do
 272                         if is_first then
 273                                 is_first = false
 274                         else
 275                                 v.stream.write ","
 276                                 if v.pretty_json then v.stream.write " "
 277                         end
 278
 279                         if not v.try_to_serialize(e) then
 280                                 assert e != null # null would have been serialized
 281                                 v.warn("element of type {e.class_name} is not serializable.")
 282                                 v.stream.write "null"
 283                         end
 284                 end
 285                 v.stream.write "]"
 286         end
 287 end
 288
 289 redef class SimpleCollection[E]
 290         redef fun accept_json_serializer(v)
 291         do
 292                 # Register as pseudo object
 293                 if not v.plain_json then
 294                         var id = v.cache.new_id_for(self)
 295                         v.stream.write """{"""
 296                         v.indent_level += 1
 297                         v.new_line_and_indent
 298                         v.stream.write """"__kind": "obj", "__id": """
 299                         v.stream.write id.to_s
 300                         v.stream.write """, "__class": """"
 301                         v.stream.write class_name
 302                         v.stream.write """","""
 303                         v.new_line_and_indent
 304                         v.stream.write """"__items": """
 305
 306                         core_serialize_to v
 307                 end
 308
 309                 serialize_to_pure_json v
 310
 311                 if not v.plain_json then
 312                         v.indent_level -= 1
 313                         v.new_line_and_indent
 314                         v.stream.write "\}"
 315                 end
 316         end
 317 end
 318
 319 redef class Map[K, V]
 320         redef fun accept_json_serializer(v)
 321         do
 322                 # Register as pseudo object
 323                 var id = v.cache.new_id_for(self)
 324
 325                 v.stream.write "\{"
 326                 v.indent_level += 1
 327
 328                 if v.plain_json then
 329                         var first = true
 330                         for key, val in self do
 331                                 if not first then
 332                                         v.stream.write ","
 333                                 else first = false
 334                                 v.new_line_and_indent
 335
 336                                 var k = key or else "null"
 337                                 k.to_s.accept_json_serializer v
 338                                 v.stream.write ":"
 339                                 if v.pretty_json then v.stream.write " "
 340                                 if not v.try_to_serialize(val) then
 341                                         assert val != null # null would have been serialized
 342                                         v.warn("element of type {val.class_name} is not serializable.")
 343                                         v.stream.write "null"
 344                                 end
 345                         end
 346                 else
 347                         v.new_line_and_indent
 348                         v.stream.write """"__kind": "obj", "__id": """
 349                         v.stream.write id.to_s
 350                         v.stream.write """, "__class": """"
 351                         v.stream.write class_name
 352                         v.stream.write """", "__length": """
 353                         v.stream.write length.to_s
 354
 355                         v.stream.write ","
 356                         v.new_line_and_indent
 357                         v.stream.write """"__keys": """
 358                         keys.serialize_to_pure_json v
 359
 360                         v.stream.write ","
 361                         v.new_line_and_indent
 362                         v.stream.write """"__values": """
 363                         values.serialize_to_pure_json v
 364
 365                         core_serialize_to v
 366                 end
 367
 368                 v.indent_level -= 1
 369                 v.new_line_and_indent
 370                 v.stream.write "\}"
 371         end
 372 end