Archive

This interface represents an archive. This is the interface all archive implementations need to implement to be able to be used as an archive with the serializer.

The archive is the backend in the serialization process. It's independent of the serializer and any archive implementation. Although there are a couple of limitations of what archive types can be implemented (see below).

The archive is responsible for archiving primitive types in the format chosen by the archive implementation. The archive ensures that all types are properly archived in a format that can be later unarchived.

The archive can only handle primitive types, like strings, integers, floating point numbers and so on. It can not handle more complex types like objects or arrays; the serializer is responsible for breaking the complex types into primitive types that the archive can handle.

Implementing an Archive Type:

There are a couple of limitations when implementing a new archive, this is due to how the serializer and the archive interface is built. Except for what this interface says explicitly an archive needs to be able to handle the following:

unarchive a value based on a key or id, regardless of where in the archive the value is located
most likely be able to modify already archived data
structured formats like JSON, XML and YAML works best

If a method takes a delegate as one of its parameters that delegate should be considered as a callback to the serializer. The archive need to make sure that any archiving that is performed in the callback be a part of the type that is currently being archived. This is easiest explained by an example:

void archiveArray (Array array, string type, string key, Id id, void delegate () dg)
{
    markBegningOfNewType("array");
    storeMetadata(type, key, id);

    beginNewScope();
    dg();
    endScope();

    markEndOfType();
}

In the above example the archive have to make sure that any values archived by the callback (the delegate) get archived as an element of the array. The same principle applies to objects, structs, associative arrays and other non-primitives that accepts a delegate as a parameter.

An archive implementation needs to be able to handle errors, like missing values in the serialized data, without throwing exceptions. This is because the interface of the serializer and an archive allows the user to set an error callback that is called when an error occurs; and the callback can choose to ignore the exceptions.

In all the examples below "XmlArchive" is used as an example of an archive implementation. "data" is assumed to be the serialized data.

When implementing a new archive type, if any of these methods do not make sense for that particular implementation just implement an empty method and return T.init, if the method returns a value.

interface Archive {

alias Id = size_t;

alias UntypedData = immutable(void)[];

alias ErrorCallback = void delegate(SerializationException exception);

ErrorCallback errorCallback();

ErrorCallback errorCallback(ErrorCallback errorCallback);

void beginArchiving();

void beginUnarchiving(UntypedData data);

UntypedData untypedData();

void reset();

void archiveArray(Array array, string type, string key, Id id, void delegate() dg);

void archiveAssociativeArray(string keyType, string valueType, size_t length, string key, Id id, void delegate() dg);

void archiveAssociativeArrayKey(string key, void delegate() dg);

void archiveAssociativeArrayValue(string key, void delegate() dg);

void archiveEnum(bool value, string baseType, string key, Id id);

void archiveEnum(bool value, string baseType, string key, Id id);

void archiveEnum(byte value, string baseType, string key, Id id);

void archiveEnum(char value, string baseType, string key, Id id);

void archiveEnum(dchar value, string baseType, string key, Id id);

void archiveEnum(int value, string baseType, string key, Id id);

void archiveEnum(long value, string baseType, string key, Id id);

void archiveEnum(short value, string baseType, string key, Id id);

void archiveEnum(ubyte value, string baseType, string key, Id id);

void archiveEnum(uint value, string baseType, string key, Id id);

void archiveEnum(ulong value, string baseType, string key, Id id);

void archiveEnum(ushort value, string baseType, string key, Id id);

void archiveEnum(wchar value, string baseType, string key, Id id);

void archiveBaseClass(string type, string key, Id id);

void archiveNull(string type, string key);

void archiveObject(string runtimeType, string type, string key, Id id, void delegate() dg);

void archivePointer(string key, Id id, void delegate() dg);

void archiveReference(string key, Id id);

void archiveSlice(Slice slice, Id sliceId, Id arrayId);

void archiveStruct(string type, string key, Id id, void delegate() dg);

void archive(string value, string key, Id id);

void archive(wstring value, string key, Id id);

void archive(dstring value, string key, Id id);

void archive(bool value, string key, Id id);

void archive(byte value, string key, Id id);

void archive(char value, string key, Id id);

void archive(dchar value, string key, Id id);

void archive(double value, string key, Id id);

void archive(float value, string key, Id id);

void archive(int value, string key, Id id);

void archive(long value, string key, Id id);

void archive(real value, string key, Id id);

void archive(short value, string key, Id id);

void archive(ubyte value, string key, Id id);

void archive(uint value, string key, Id id);

void archive(ulong value, string key, Id id);

void archive(ushort value, string key, Id id);

void archive(wchar value, string key, Id id);

Id unarchiveArray(string key, void delegate(size_t length) dg);

void unarchiveArray(Id id, void delegate(size_t length) dg);

Id unarchiveAssociativeArray(string key, void delegate(size_t length) dg);

void unarchiveAssociativeArrayKey(string key, void delegate() dg);

void unarchiveAssociativeArrayValue(string key, void delegate() dg);

bool unarchiveEnumBool(string key, Id id);

byte unarchiveEnumByte(string key, Id id);

char unarchiveEnumChar(string key, Id id);

dchar unarchiveEnumDchar(string key, Id id);

int unarchiveEnumInt(string key, Id id);

long unarchiveEnumLong(string key, Id id);

short unarchiveEnumShort(string key, Id id);

ubyte unarchiveEnumUbyte(string key, Id id);

uint unarchiveEnumUint(string key, Id id);

ulong unarchiveEnumUlong(string key, Id id);

ushort unarchiveEnumUshort(string key, Id id);

wchar unarchiveEnumWchar(string key, Id id);

bool unarchiveEnumBool(Id id);

byte unarchiveEnumByte(Id id);

char unarchiveEnumChar(Id id);

dchar unarchiveEnumDchar(Id id);

int unarchiveEnumInt(Id id);

long unarchiveEnumLong(Id id);

short unarchiveEnumShort(Id id);

ubyte unarchiveEnumUbyte(Id id);

uint unarchiveEnumUint(Id id);

ulong unarchiveEnumUlong(Id id);

ushort unarchiveEnumUshort(Id id);

wchar unarchiveEnumWchar(Id id);

void unarchiveBaseClass(string key);

void unarchiveObject(string key, Id id, Object result, void delegate() dg);

Id unarchivePointer(string key, void delegate() dg);

Id unarchiveReference(string key);

Slice unarchiveSlice(string key);

Id unarchiveStruct(string key, void delegate() dg);

void unarchiveStruct(Id id, void delegate() dg);

string unarchiveString(Id id);

wstring unarchiveWstring(Id id);

dstring unarchiveDstring(Id id);

string unarchiveString(string key, Id id);

wstring unarchiveWstring(string key, Id id);

dstring unarchiveDstring(string key, Id id);

bool unarchiveBool(string key, Id id);

byte unarchiveByte(string key, Id id);

char unarchiveChar(string key, Id id);

dchar unarchiveDchar(string key, Id id);

double unarchiveDouble(string key, Id id);

float unarchiveFloat(string key, Id id);

int unarchiveInt(string key, Id id);

long unarchiveLong(string key, Id id);

real unarchiveReal(string key, Id id);

short unarchiveShort(string key, Id id);

ubyte unarchiveUbyte(string key, Id id);

uint unarchiveUint(string key, Id id);

ulong unarchiveUlong(string key, Id id);

ushort unarchiveUshort(string key, Id id);

wchar unarchiveWchar(string key, Id id);

bool unarchiveBool(Id id);

byte unarchiveByte(Id id);

char unarchiveChar(Id id);

dchar unarchiveDchar(Id id);

double unarchiveDouble(Id id);

float unarchiveFloat(Id id);

int unarchiveInt(Id id);

long unarchiveLong(Id id);

real unarchiveReal(Id id);

short unarchiveShort(Id id);

ubyte unarchiveUbyte(Id id);

uint unarchiveUint(Id id);

ulong unarchiveUlong(Id id);

ushort unarchiveUshort(Id id);

wchar unarchiveWchar(Id id);

void postProcessArray(Id id);

}

Members

Aliases

ErrorCallback alias ErrorCallback = void delegate(SerializationException exception): This is the type of an error callback which is called when an unexpected event occurs.
Id alias Id = size_t: The type of an ID.
UntypedData alias UntypedData = immutable(void)[]: The typed used to represent the archived data in an untyped form.

Functions

archive void archive(string value, string key, Id id)
void archive(wstring value, string key, Id id)
void archive(dstring value, string key, Id id)
void archive(bool value, string key, Id id)
void archive(byte value, string key, Id id)
void archive(char value, string key, Id id)
void archive(dchar value, string key, Id id)
void archive(double value, string key, Id id)
void archive(float value, string key, Id id)
void archive(int value, string key, Id id)
void archive(long value, string key, Id id)
void archive(real value, string key, Id id)
void archive(short value, string key, Id id)
void archive(ubyte value, string key, Id id)
void archive(uint value, string key, Id id)
void archive(ulong value, string key, Id id)
void archive(ushort value, string key, Id id)
void archive(wchar value, string key, Id id): Archives the given value.
archiveArray void archiveArray(Array array, string type, string key, Id id, void delegate() dg): Archives an array.
archiveAssociativeArray void archiveAssociativeArray(string keyType, string valueType, size_t length, string key, Id id, void delegate() dg): Archives an associative array.
archiveAssociativeArrayKey void archiveAssociativeArrayKey(string key, void delegate() dg): Archives an associative array key.
archiveAssociativeArrayValue void archiveAssociativeArrayValue(string key, void delegate() dg): Archives an associative array value.
archiveBaseClass void archiveBaseClass(string type, string key, Id id): Archives a base class.
archiveEnum void archiveEnum(bool value, string baseType, string key, Id id)
void archiveEnum(byte value, string baseType, string key, Id id)
void archiveEnum(char value, string baseType, string key, Id id)
void archiveEnum(dchar value, string baseType, string key, Id id)
void archiveEnum(int value, string baseType, string key, Id id)
void archiveEnum(long value, string baseType, string key, Id id)
void archiveEnum(short value, string baseType, string key, Id id)
void archiveEnum(ubyte value, string baseType, string key, Id id)
void archiveEnum(uint value, string baseType, string key, Id id)
void archiveEnum(ulong value, string baseType, string key, Id id)
void archiveEnum(ushort value, string baseType, string key, Id id)
void archiveEnum(wchar value, string baseType, string key, Id id): Archives the given value.
archiveNull void archiveNull(string type, string key): Archives a null pointer or reference.
archiveObject void archiveObject(string runtimeType, string type, string key, Id id, void delegate() dg): Archives an object, either a class or an interface.
archivePointer void archivePointer(string key, Id id, void delegate() dg): Archives a pointer.
archiveReference void archiveReference(string key, Id id): Archives a reference.
archiveSlice void archiveSlice(Slice slice, Id sliceId, Id arrayId): Archives a slice.
archiveStruct void archiveStruct(string type, string key, Id id, void delegate() dg): Archives a struct.
beginArchiving void beginArchiving(): Starts the archiving process. Call this method before archiving any values.
beginUnarchiving void beginUnarchiving(UntypedData data): Begins the unarchiving process. Call this method before unarchiving any values.
errorCallback ErrorCallback errorCallback(): This callback will be called when an unexpected event occurs, i.e. an expected element is missing in the unarchiving process.
errorCallback ErrorCallback errorCallback(ErrorCallback errorCallback): This callback will be called when an unexpected event occurs, i.e. an expected element is missing in the unarchiving process.
postProcessArray void postProcessArray(Id id): Performs post processing of the array associated with the given id.
reset void reset(): Resets the archive. This resets the archive in a state making it ready to start a new archiving process.
unarchiveArray Id unarchiveArray(string key, void delegate(size_t length) dg): Unarchives the value associated with the given key as an array.
unarchiveArray void unarchiveArray(Id id, void delegate(size_t length) dg): Unarchives the value associated with the given id as an array.
unarchiveAssociativeArray Id unarchiveAssociativeArray(string key, void delegate(size_t length) dg): Unarchives the value associated with the given id as an associative array.
unarchiveAssociativeArrayKey void unarchiveAssociativeArrayKey(string key, void delegate() dg): Unarchives an associative array key.
unarchiveAssociativeArrayValue void unarchiveAssociativeArrayValue(string key, void delegate() dg): Unarchives an associative array value.
unarchiveBaseClass void unarchiveBaseClass(string key): Unarchives the base class associated with the given key.
unarchiveBool bool unarchiveBool(string key, Id id): Unarchives the value associated with the given key.
unarchiveBool bool unarchiveBool(Id id): Unarchives the value associated with the given id.
unarchiveByte byte unarchiveByte(string key, Id id): Unarchives the value associated with the given key.
unarchiveByte byte unarchiveByte(Id id): Unarchives the value associated with the given id.
unarchiveChar char unarchiveChar(string key, Id id): Unarchives the value associated with the given key.
unarchiveChar char unarchiveChar(Id id): Unarchives the value associated with the given id.
unarchiveDchar dchar unarchiveDchar(string key, Id id): Unarchives the value associated with the given key.
unarchiveDchar dchar unarchiveDchar(Id id): Unarchives the value associated with the given id.
unarchiveDouble double unarchiveDouble(string key, Id id): Unarchives the value associated with the given key.
unarchiveDouble double unarchiveDouble(Id id): Unarchives the value associated with the given id.
unarchiveDstring dstring unarchiveDstring(Id id): Unarchives the string associated with the given id.
unarchiveDstring dstring unarchiveDstring(string key, Id id): Unarchives the string associated with the given key.
unarchiveEnumBool bool unarchiveEnumBool(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumBool bool unarchiveEnumBool(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumByte byte unarchiveEnumByte(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumByte byte unarchiveEnumByte(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumChar char unarchiveEnumChar(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumChar char unarchiveEnumChar(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumDchar dchar unarchiveEnumDchar(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumDchar dchar unarchiveEnumDchar(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumInt int unarchiveEnumInt(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumInt int unarchiveEnumInt(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumLong long unarchiveEnumLong(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumLong long unarchiveEnumLong(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumShort short unarchiveEnumShort(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumShort short unarchiveEnumShort(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumUbyte ubyte unarchiveEnumUbyte(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumUbyte ubyte unarchiveEnumUbyte(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumUint uint unarchiveEnumUint(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumUint uint unarchiveEnumUint(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumUlong ulong unarchiveEnumUlong(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumUlong ulong unarchiveEnumUlong(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumUshort ushort unarchiveEnumUshort(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumUshort ushort unarchiveEnumUshort(Id id): Unarchives the value associated with the given id as a bool.
unarchiveEnumWchar wchar unarchiveEnumWchar(string key, Id id): Unarchives the value associated with the given key as a bool.
unarchiveEnumWchar wchar unarchiveEnumWchar(Id id): Unarchives the value associated with the given id as a bool.
unarchiveFloat float unarchiveFloat(string key, Id id): Unarchives the value associated with the given key.
unarchiveFloat float unarchiveFloat(Id id): Unarchives the value associated with the given id.
unarchiveInt int unarchiveInt(string key, Id id): Unarchives the value associated with the given key.
unarchiveInt int unarchiveInt(Id id): Unarchives the value associated with the given id.
unarchiveLong long unarchiveLong(string key, Id id): Unarchives the value associated with the given key.
unarchiveLong long unarchiveLong(Id id): Unarchives the value associated with the given id.
unarchiveObject void unarchiveObject(string key, Id id, Object result, void delegate() dg): Unarchives the object associated with the given key.
unarchivePointer Id unarchivePointer(string key, void delegate() dg): Unarchives the pointer associated with the given key.
unarchiveReal real unarchiveReal(string key, Id id): Unarchives the value associated with the given key.
unarchiveReal real unarchiveReal(Id id): Unarchives the value associated with the given id.
unarchiveReference Id unarchiveReference(string key): Unarchives the reference associated with the given key.
unarchiveShort short unarchiveShort(string key, Id id): Unarchives the value associated with the given key.
unarchiveShort short unarchiveShort(Id id): Unarchives the value associated with the given id.
unarchiveSlice Slice unarchiveSlice(string key): Unarchives the slice associated with the given key.
unarchiveString string unarchiveString(Id id): Unarchives the string associated with the given id.
unarchiveString string unarchiveString(string key, Id id): Unarchives the string associated with the given key.
unarchiveStruct Id unarchiveStruct(string key, void delegate() dg): Unarchives the struct associated with the given key.
unarchiveStruct void unarchiveStruct(Id id, void delegate() dg): Unarchives the struct associated with the given id.
unarchiveUbyte ubyte unarchiveUbyte(string key, Id id): Unarchives the value associated with the given key.
unarchiveUbyte ubyte unarchiveUbyte(Id id): Unarchives the value associated with the given id.
unarchiveUint uint unarchiveUint(string key, Id id): Unarchives the value associated with the given key.
unarchiveUint uint unarchiveUint(Id id): Unarchives the value associated with the given id.
unarchiveUlong ulong unarchiveUlong(string key, Id id): Unarchives the value associated with the given key.
unarchiveUlong ulong unarchiveUlong(Id id): Unarchives the value associated with the given id.
unarchiveUshort ushort unarchiveUshort(string key, Id id): Unarchives the value associated with the given key.
unarchiveUshort ushort unarchiveUshort(Id id): Unarchives the value associated with the given id.
unarchiveWchar wchar unarchiveWchar(string key, Id id): Unarchives the value associated with the given key.
unarchiveWchar wchar unarchiveWchar(Id id): Unarchives the value associated with the given id.
unarchiveWstring wstring unarchiveWstring(Id id): Unarchives the string associated with the given id.
unarchiveWstring wstring unarchiveWstring(string key, Id id): Unarchives the string associated with the given key.
untypedData UntypedData untypedData(): Returns the data stored in the archive in an untyped form.

Meta

Source

See Implementation

orange serialization archives Archive classes

ArchiveBase

interfaces

Archive