vibe.d beta banner
get vibe.d
0.8.1

Asynchronous I/O that doesn’t get in your way, written in D

Module vibe.data.serialization

Generic serialization framework.

This module provides general means for implementing (de-)serialization with a standardized behavior.

Supported types

The following rules are applied in order when serializing or deserializing a certain type:

  1. An enum type is serialized as its raw value, except if @byName is used, in which case the name of the enum value is serialized.
  2. Any type that is specifically supported by the serializer is directly serialized. For example, the BSON serializer supports BsonObjectID directly.
  3. Arrays and tuples (std.typecons.Tuple) are serialized using the array serialization functions where each element is serialized again according to these rules.
  4. Associative arrays are serialized similar to arrays. The key type of the AA must satisfy the isStringSerializable trait and will always be serialized as a string.
  5. Any Nullable!T will be serialized as either null, or as the contained value (subject to these rules again).
  6. Types satisfying the isPolicySerializable trait for the supplied Policy will be serialized as the value returned by the policy toRepresentation function (again subject to these rules).
  7. Types satisfying the isCustomSerializable trait will be serialized as the value returned by their toRepresentation method (again subject to these rules).
  8. Types satisfying the isISOExtSerializable trait will be serialized as a string, as returned by their toISOExtString method. This causes types such as SysTime to be serialized as strings.
  9. Types satisfying the isStringSerializable trait will be serialized as a string, as returned by their toString method.
  10. Struct and class types by default will be serialized as associative arrays, where the key is the name of the corresponding field (can be overridden using the @name attribute). If the struct/class is annotated with @asArray, it will instead be serialized as a flat array of values in the order of declaration. Null class references will be serialized as null.
  11. Pointer types will be serialized as either null, or as the value they point to.
  12. Built-in integers and floating point values, as well as boolean values will be converted to strings, if the serializer doesn't support them directly.

Note that no aliasing detection is performed, so that pointers, class references and arrays referencing the same memory will be serialized as multiple copies. When in turn deserializing the data, they will also end up as separate copies in memory.

Serializer implementation

Serializers are implemented in terms of a struct with template methods that get called by the serialization framework:

struct ExampleSerializer {
	enum isSupportedValueType(T) = is(T == string) || is(T == typeof(null));

	// serialization
	auto getSerializedResult();
	void beginWriteDictionary(T)();
	void endWriteDictionary(T)();
	void beginWriteDictionaryEntry(T)(string name);
	void endWriteDictionaryEntry(T)(string name);
	void beginWriteArray(T)(size_t length);
	void endWriteArray(T)();
	void beginWriteArrayEntry(T)(size_t index);
	void endWriteArrayEntry(T)(size_t index);
	void writeValue(T)(T value);

	// deserialization
	void readDictionary(T)(scope void delegate(string) entry_callback);
	void readArray(T)(scope void delegate(size_t) size_callback, scope void delegate() entry_callback);
	T readValue(T)();
	bool tryReadNull();
}

Functions

NameDescription
asArray()Attribute for representing a struct/class as an array instead of an object.
byName()Attribute for forcing serialization of enum fields by name instead of by value.
deserialize(args)Deserializes and returns a serialized value.
deserializeWithPolicy(args)Deserializes and returns a serialized value, interpreting values according to Policy when possible.
ignore()Attribute for marking non-serialized fields.
name(name)Attribute for overriding the field name during (de-)serialization.
optional()Attribute marking a field as optional during deserialization.
serialize(value, args)Serializes a value with the given serializer.
serializeWithPolicy(value, args)Serializes a value with the given serializer, representing values according to Policy when possible.

Structs

NameDescription
AsArrayAttributeUser defined attribute (not intended for direct use)
ByNameAttributeUser defined attribute (not intended for direct use)
IgnoreAttributeUser defined attribute (not intended for direct use)
NameAttributeUser defined attribute (not intended for direct use)
OptionalAttributeUser defined attribute (not intended for direct use)

Enums

NameDescription
FieldExistence

Templates

NameDescription
ChainedPolicyChains serialization policy.

Manifest constants

NameTypeDescription
isCustomSerializableChecks if a given type has a custom serialization representation.
isISOExtStringSerializableChecks if a given type has an ISO extended string serialization representation.
isPolicySerializableChecks if a given policy supports custom serialization for a given type.
isStringSerializableChecks if a given type has a string serialization representation.
Authors

Sönke Ludwig

Copyright

© 2013-2014 rejectedsoftware e.K.

License

Subject to the terms of the MIT license, as written in the included LICENSE.txt file.