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:
- An
enum
type is serialized as its raw value, except if@byName
is used, in which case thename
of the enum value is serialized. - Any type that is specifically supported by the serializer
is directly serialized. For example, the BSON serializer
supports
BsonObjectID
directly. - Arrays and tuples (
std.typecons.Tuple
) are serialized using the array serialization functions where each element is serialized again according to these rules. - 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. - Any
Nullable!T
will be serialized as eithernull
, or as the contained value (subject to these rules again). - Any
BitFlags!T
value will be serialized asT[]
- Types satisfying the
isPolicySerializable
trait for the suppliedPolicy
will be serialized as the value returned by the policytoRepresentation
function (again subject to these rules). - Types satisfying the
isCustomSerializable
trait will be serialized as the value returned by theirtoRepresentation
method (again subject to these rules). - Types satisfying the
isISOExtStringSerializable
trait will be serialized as a string, as returned by theirtoISOExtString
method. This causes types such asSysTime
to be serialized as strings. - Types satisfying the
isStringSerializable
trait will be serialized as a string, as returned by theirtoString
method. - 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 asnull
. - Pointer types will be serialized as either
null
, or as the value they point to. - 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
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. |
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-2014 rejectedsoftware e.K.
License
Subject to the terms of the MIT license, as written in the included LICENSE.txt file.