X-Git-Url: http://nitlanguage.org diff --git a/lib/serialization/serialization.nit b/lib/serialization/serialization.nit index 3bc086a..cdbaed4 100644 --- a/lib/serialization/serialization.nit +++ b/lib/serialization/serialization.nit @@ -14,140 +14,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Abstract services to serialize Nit objects to different formats -# -# This module declares the `auto_serializable` annotation to mark Nit classes as serializable. -# For an introduction to this service, refer to the documentation of the `serialization` group. -# This documentation provides more technical information on interesting entitie of this module. -# -# Interesting entities for end users of serializable classes: -# -# * Serialize an instance subclass of `Serializable` with either -# `Serializer::serializable` and `Serializable::serialize`. -# * Deserialize an object using `Deserializer::deserialize`. -# The object type must the be checked with an `assert` or otherwise. -# -# Interesting entities to create custom serializable classes: -# -# * Subclass `Serializable` to declare a class as serializable and to customize -# the serialization and deserialization behavior. -# * Redefine `Serializable::core_serialize_to` to customize the serialization -# of the receiver class. -# * Redefine `Deserializer::deserialize_class` to customize the deserialization -# of a specific class by name. -# -# Interesting entities for serialization format: -# -# * Subclass `Serializer` and `Deserializer` with custom serices. -# * In `Serializer`, `serialize` and `serialize_reference` must be redefined. -# * In `Deserializer`; `deserialize`, `deserialize_attribute and -# `notify_of_creation` must be redefined. -module serialization is - new_annotation auto_serializable -end - -# Abstract serialization service to be sub-classed by specialized services. -interface Serializer - # Entry point method of this service, serialize the `object` - # - # This method, and refinements, should handle `null` and probably - # use double dispatch to customize the bahavior per serializable objects. - fun serialize(object: nullable Serializable) is abstract - - fun serialize_reference(object: Serializable) is abstract - # Serialize an object, with full serialization or a simple reference - - # Serialize an attribute to compose a serializable object - # - # This method should be called from `Serializable::core_serialize_to`. - fun serialize_attribute(name: String, value: nullable Object) - do - if not try_to_serialize(value) then - warn("argument {value.class_name}::{name} is not serializable.") - end - end - - # Serialize `value` is possie, i.e. it is `Serializable` or `null` - fun try_to_serialize(value: nullable Object): Bool - do - if value isa Serializable then - value.serialize_to_or_delay(self) - else if value == null then - serialize value - else return false - return true - end - - # Warn of problems and potential errors (such as if an attribute - # is not serializable) - fun warn(msg: String) do print "Serialization warning: {msg}" -end - -# Abstract deserialization service -# -# After initialization of one of its sub-classes, call `deserialize` -interface Deserializer - # Main method of this class, returns a Nit object - fun deserialize: nullable Object is abstract - - # Internal method to be implemented by sub-classes - fun deserialize_attribute(name: String): nullable Object is abstract - - # Internal method called by objects in creation, - # to be implemented by sub-classes - fun notify_of_creation(new_object: Object) is abstract - - # Deserialize the next available object as an instance of `class_name` - # - # Returns the deserialized object on success, aborts on error. - # - # This method should be redefined for each custom subclass of `Serializable`. - # All refinement should look for a precise `class_name` and call super - # on unsupported classes. - fun deserialize_class(class_name: String): Object do - print "Error: doesn't know how to deserialize class \"{class_name}\"" - abort - end -end - -# Instances of this class can be passed to `Serializer::serialize` -interface Serializable - # Serialize `self` to `serializer` - # - # This is a shortcut to `Serializer::serialize`. - fun serialize_to(serializer: Serializer) do serializer.serialize(self) - - # Actual serialization of `self` to `serializer` - # - # This writes the full data of `self` to `serializer`. - # - # This method can be redefined in sub classes and refinements. - # It should use `Serializer::serialize_attribute` to to register real or - # logical attributes. - # - # Any refinement should have its equivalent refinement of - # `Deserializer::deserialize_class` to support this custom deserialization. - fun core_serialize_to(serializer: Serializer) do end - - # Accept references or force direct serialization (using `serialize_to`) - # - # The subclass change the default behavior, which will accept references, - # to force to always serialize copies of `self`. - private fun serialize_to_or_delay(v: Serializer) do v.serialize_reference(self) -end - -# Instances of this class are not delayed and instead serialized immediately -# This applies mainly to `universal` types -interface DirectSerializable - super Serializable - - redef fun serialize_to_or_delay(v) do serialize_to(v) -end +# General serialization services +module serialization -redef class Bool super DirectSerializable end -redef class Char super DirectSerializable end -redef class Int super DirectSerializable end -redef class Float super DirectSerializable end -redef class NativeString super DirectSerializable end -redef class String super DirectSerializable end -redef class Array[E] super Serializable end +import serialization_core +import inspect