vson.serialization

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();
}