vibe.d beta banner
get vibe.d
0.7.30

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. Any BitFlags!T value will be serialized as T[]
  7. 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).
  8. Types satisfying the isCustomSerializable trait will be serialized as the value returned by their toRepresentation method (again subject to these rules).
  9. Types satisfying the isISOExtStringSerializable trait will be serialized as a string, as returned by their toISOExtString method. This causes types such as SysTime to be serialized as strings.
  10. Types satisfying the isStringSerializable trait will be serialized as a string, as returned by their toString method.
  11. 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.
  12. Pointer types will be serialized as either null, or as the value they point to.
  13. 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 beginWriteDocument(TypeTraits)();
	void endWriteDocument(TypeTraits)();
	void beginWriteDictionary(TypeTraits)();
	void endWriteDictionary(TypeTraits)();
	void beginWriteDictionaryEntry(ElementTypeTraits)(string name);
	void endWriteDictionaryEntry(ElementTypeTraits)(string name);
	void beginWriteArray(TypeTraits)(size_t length);
	void endWriteArray(TypeTraits)();
	void beginWriteArrayEntry(ElementTypeTraits)(size_t index);
	void endWriteArrayEntry(ElementTypeTraits)(size_t index);
	void writeValue(TypeTraits, T)(T value);

	// deserialization
	void readDictionary(TypeTraits)(scope void delegate(string) entry_callback);
	void beginReadDictionaryEntry(ElementTypeTraits)(string);
	void endReadDictionaryEntry(ElementTypeTraits)(string);
	void readArray(TypeTraits)(scope void delegate(size_t) size_callback, scope void delegate() entry_callback);
	void beginReadArrayEntry(ElementTypeTraits)(size_t index);
	void endReadArrayEntry(ElementTypeTraits)(size_t index);
	T readValue(TypeTraits, T)();
	bool tryReadNull(TypeTraits)();
}

The TypeTraits type passed to the individual methods has the following members:

  • Type: The original type of the field to serialize
  • Attributes: User defined attributes attached to the field
  • Policy: An alias to the policy used for the serialization process

ElementTypeTraits have the following additional members:

  • ContainerType: The original type of the enclosing container type
  • ContainerAttributes: User defined attributes attached to the enclosing container

Functions

Name Description
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 Deserializes and returns a serialized value.
deserializeWithPolicy Deserializes and returns a serialized value, interpreting values according to Policy when possible.
ignore Attribute for marking non-serialized fields.
name Attribute for overriding the field name during (de-)serialization.
optional Attribute marking a field as optional during deserialization.
serialize Serializes a value with the given serializer.
serializeWithPolicy Serializes a value with the given serializer, representing values according to Policy when possible.

Structs

Name Description
AsArrayAttribute User defined attribute (not intended for direct use)
ByNameAttribute User defined attribute (not intended for direct use)
IgnoreAttribute User defined attribute (not intended for direct use)
NameAttribute User defined attribute (not intended for direct use)
OptionalAttribute User defined attribute (not intended for direct use)

Enums

Name Description
FieldExistence

Templates

Name Description
ChainedPolicy Chains serialization policy.
DefaultPolicy Default policy (performs no customization).

Enum values

Name Type Description
isCustomSerializable Checks if a given type has a custom serialization representation.
isISOExtStringSerializable Checks if a given type has an ISO extended string serialization representation.
isPolicySerializable Checks if a given policy supports custom serialization for a given type.
isStringSerializable Checks if a given type has a string serialization representation.
Authors

Sönke Ludwig

Copyright

© 2013-2016 rejectedsoftware e.K.

License

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