Merge: nitunit: Use markdown2

[nit.git] / lib / msgpack / serialization_write.nit

# This file is part of NIT ( http://www.nitlanguage.org ).
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Serialize full Nit objects to MessagePack format
#
# There are 3 main entrypoint services:
# * `Writer::serialize_msgpack` adds an object to any stream writer.
# * `Serializable::serialize_msgpack` serializes the object to bytes.
# * `MsgPackSerializer` gives full control over the serialization of
#   Nit objets to the MessagePack format.
module serialization_write

import serialization::caching
private import serialization::engine_tools

import serialization_common
private import write
import ext

# MessagePack deserialization engine
class MsgPackSerializer
        super CachingSerializer
        super MsgPackEngine

        # Target writing stream
        var stream: Writer

        # Write plain MessagePack without metadata for deserialization?
        #
        # If `false`, the default, serialize to support deserialization:
        #
        # * Each object is encapsulated in an array that contains metadata and
        #   the actual object attributes in a map. The metadata includes the type
        #   name and references to already serialized object. This information
        #   supports deserializing the message, including cycles.
        # * Preserve the Nit `Char` and `Byte` types as an object.
        # * The generated MessagePack is standard and can be read by non-Nit programs.
        #   However, it contains some complexity that may make it harder to use.
        #
        # If `true`, serialize only the real data or non-Nit programs:
        #
        # * Nit objects are serialized to pure and standard MessagePack so they can
        #   be easily read by non-Nit programs.
        # * Nit objects are serialized at every reference, so they may be duplicated.
        #   It is easier to read but it creates a larger output and it does not support
        #   cycles. Cyclic references are replaced by `null`.
        # * The serialized data can only be deserialized to their expected static
        #   types, losing the knowledge of their dynamic type.
        var plain_msgpack = false is writable

        # Should strings declaring the objects type and attributes name be cached?
        #
        # If `true` metadata strings are cached using `cache`.
        # The first occurrence is written as an object declaration,
        # successive occurrences are written as an object reference.
        #
        # If `false`, the default, metadata strings are written as pure MessagePack
        # strings, without their own metadata.
        #
        # Using the cache may save some space by avoiding the repetition of
        # names used by many types or attributes.
        # However, it adds complexity to the generated message and may be less
        # safe for versioning.
        var cache_metadata_strings = false is writable

        # List of the current open objects, the first is the main target of the serialization
        #
        # Used only when `plain_msgpack == true` to detect cycles in serialization.
        private var open_objects = new Array[Object]

        redef var current_object = null

        redef fun serialize(object)
        do
                if object == null then
                        stream.write_msgpack_null
                else
                        if plain_msgpack then
                                for o in open_objects do
                                        if object.is_same_serialized(o) then
                                                # Cycle, can't be managed in plain_msgpack mode
                                                warn "Cycle detected in serialized object, replacing reference with 'null'."
                                                stream.write_msgpack_null
                                                return
                                        end
                                end

                                open_objects.add object
                        end

                        var last_object = current_object
                        current_object = object
                        object.accept_msgpack_serializer self
                        current_object = last_object

                        if plain_msgpack then open_objects.pop
                end
        end

        redef fun serialize_attribute(name, value)
        do
                serialize_meta_string name
                super
        end

        redef fun serialize_reference(object)
        do
                if not plain_msgpack and cache.has_object(object) then
                        # if already serialized, add local reference
                        var id = cache.id_for(object)
                        stream.write_msgpack_ext(ext_typ_ref, id.to_bytes)
                else
                        # serialize
                        serialize object
                end
        end

        private fun serialize_meta_string(type_name: String)
        do
                if plain_msgpack or not cache_metadata_strings then
                        # String only version
                        stream.write_msgpack_str type_name
                        return
                end

                if cache.has_object(type_name) then
                        # if already serialized, add reference
                        var id = cache.id_for(type_name)
                        stream.write_msgpack_ext(ext_typ_ref, id.to_bytes)
                else
                        # serialize
                        var id = cache.new_id_for(type_name)
                        stream.write_msgpack_array 2 # obj+id, type_name
                        stream.write_msgpack_ext(ext_typ_obj, id.to_bytes)
                        stream.write_msgpack_str type_name
                end
        end
end

# Serialization visitor to count attribute in `Serializable` objects
class AttributeCounter
        super Serializer

        # Number of attributes counted
        var count = 0

        redef fun serialize_attribute(name, object) do count += 1
end

# ---
# Services and serializables

redef class Writer
        # Serialize `value` in MessagePack format
        fun serialize_msgpack(value: nullable Serializable, plain: nullable Bool)
        do
                var serializer = new MsgPackSerializer(self)
                serializer.plain_msgpack = plain or else false
                serializer.serialize value
        end
end

redef class Serializable

        # Serialize `self` to MessagePack bytes
        #
        # Set `plain = true` to generate standard MessagePack, without deserialization metadata.
        # Use this option if the generated MessagePack will be read by non-Nit programs.
        # Use the default, `plain = false`, if the MessagePack bytes are to be deserialized by a Nit program.
        fun serialize_msgpack(plain: nullable Bool): Bytes
        do
                var stream = new BytesWriter
                stream.serialize_msgpack(self, plain)
                stream.close
                return stream.bytes
        end

        # Hook to customize the serialization of this class to MessagePack
        #
        # This method can be refined to customize the serialization by either
        # writing pure JSON directly on the stream `v.stream` or
        # by using other services of `MsgPackSerializer`.
        #
        # Most of the time, it is better to refine the method `core_serialize_to`
        # which is used by all the serialization engines, not just MessagePack.
        protected fun accept_msgpack_serializer(v: MsgPackSerializer)
        do

                # Count the number of attributes
                var attribute_counter = new AttributeCounter
                accept_msgpack_attribute_counter attribute_counter
                var n_attributes = attribute_counter.count

                if not v.plain_msgpack then

                        var n_meta_items = 2
                        if n_attributes > 0 then n_meta_items += 1
                        n_meta_items += msgpack_extra_array_items # obj+id, class_name, attributes

                        # Metadata
                        var id = v.cache.new_id_for(self)
                        v.stream.write_msgpack_array n_meta_items
                        v.stream.write_msgpack_ext(v.ext_typ_obj, id.to_bytes)
                        v.serialize_meta_string class_name

                        if n_attributes > 0 then v.stream.write_msgpack_map n_attributes
                else
                        v.stream.write_msgpack_map n_attributes
                end

                v.serialize_core self
        end

        # Hook to customize the behavior of the `AttributeCounter`
        #
        # By default, this method makes `v` visits all serializable attributes.
        protected fun accept_msgpack_attribute_counter(v: AttributeCounter)
        do
                v.serialize_core self
        end

        # Hook to request a larger than usual metadata array
        #
        # Use by `SimpleCollection` and `Map` to append the items after
        # the metadata and attributes.
        protected fun msgpack_extra_array_items: Int do return 0
end

redef class MsgPackExt
        redef fun accept_msgpack_serializer(v) do v.stream.write_msgpack_ext(typ, data)
end

redef class Text
        redef fun accept_msgpack_serializer(v) do v.stream.write_msgpack_str self
end

redef class Int
        redef fun accept_msgpack_serializer(v) do v.stream.write_msgpack_int self
end

redef class Float
        redef fun accept_msgpack_serializer(v) do v.stream.write_msgpack_double self
end

redef class Bool
        redef fun accept_msgpack_serializer(v) do v.stream.write_msgpack_bool self
end

redef class Byte
        redef fun accept_msgpack_serializer(v)
        do
                if v.plain_msgpack then
                        # Write as a string
                        v.stream.write_msgpack_int to_i
                else
                        # Write as ext
                        var bytes = new Bytes.with_capacity(1)
                        bytes.add self.to_i
                        v.stream.write_msgpack_ext(v.ext_typ_byte, bytes)
                end
        end
end

redef class Char
        redef fun accept_msgpack_serializer(v)
        do
                if v.plain_msgpack then
                        # Write as a string
                        v.stream.write_msgpack_fixstr to_s
                else
                        # Write as ext
                        var bytes = to_s.to_bytes
                        v.stream.write_msgpack_ext(v.ext_typ_char, bytes)
                end
        end
end

redef class Bytes
        redef fun accept_msgpack_serializer(v) do v.stream.write_msgpack_bin self
end

redef class CString
        redef fun accept_msgpack_serializer(v) do to_s.accept_msgpack_serializer(v)
end

redef class SimpleCollection[E]
        redef fun accept_msgpack_serializer(v)
        do
                if not v.plain_msgpack then
                        # Add metadata and other attributes
                        super
                end

                # Header
                v.stream.write_msgpack_array length

                # Items
                for e in self do
                        if not v.try_to_serialize(e) then
                                assert e != null # null would have been serialized
                                v.warn "element of type {e.class_name} is not serializable."
                                v.stream.write_msgpack_null
                        end
                end
        end

        redef fun msgpack_extra_array_items do return 1
end

redef class Map[K, V]
        redef fun accept_msgpack_serializer(v)
        do
                if not v.plain_msgpack then
                        # Add metadata and other attributes
                        super
                end

                # Header
                v.stream.write_msgpack_map keys.length

                # Key / values, alternating
                for key, val in self do
                        if not v.try_to_serialize(key) then
                                assert val != null # null would have been serialized
                                v.warn "element of type {val.class_name} is not serializable."
                                v.stream.write_msgpack_null
                        end

                        if not v.try_to_serialize(val) then
                                assert val != null # null would have been serialized
                                v.warn "element of type {val.class_name} is not serializable."
                                v.stream.write_msgpack_null
                        end
                end
        end

        redef fun msgpack_extra_array_items do return 1
end