-
Notifications
You must be signed in to change notification settings - Fork 0
Project Overview
This overview is intended to provide a birds-eye view of the various components of Plancake. For more information on a specific class or function, please read the documentation comments of the linked classes / interfaces.
The ISerializer is an interface that allows for linking other serializers to the Plancake API.
ISerializers must be able to:
- Serialize and deserialize one type of object through the Serialize and Deserialize methods.
- Report the
System.Typeof the serializable type.
Please note that for the purposes of writing your own serializer (rather than linking one to Plancake), usage of the
TypeSafeSerializer<T>is recommended.
The TypeSafeSerializer is an abstract implementation of ISerializer that allows for a type-safe method of serialization.
TypeSafeSerializers are the recommended approach for writing your own serializer, as their type safety allows for build-time type checking.
The InheritanceHash uses name hashing to catalogue data types. It is used behind-the-scenes with the GlobalSerializer, but can also be used on its own.
Please note that the InheritanceHash will generate hashes for any type extending the types passed into its constructor, hence the 'Inheritance'.
The GlobalSerializer represents a collection of ISerializers used to initialize DataConstructors and DataDestructors. When serializing objects, it also serializes their type hash.
The DataConstructor is used as an abstraction layer between the serializer and the raw data stream.
It is passed into serialization methods as a means of writing data to the stream. Note that it supports two types of writing: "raw" data (also known as fixed-width data), and "block" data (also known as variable-width data). Further reading on the differences between the two will be supplied on this wiki eventually.
Note that DataConstructors wrap a GlobalSerializer as the Constructor is considered to be the intended way to interact with the Serializer.
The DataDestructor is used similarly to the DataConstructor, except for deserialization rather than serialization.
Similarly to the Constructor, the Destructor supports "raw" and "block" data formats.
Note that while it will deserialize objects as the proper type, in order for compile-time typing to work properly you must know the structure of the data file.
Headers are small (max 255-byte) blocks of data appended to the beginning of a Constructor. The maximum number of headers that can be applied to one Constructor is 65535.
Their intended purpose is to supply a method of specifying information about the file itself, such as its format or origin.
Headers can be of any data type, as long as it can be converted directly to and from raw byte information via an IHeaderFactory<T>.
They should be constructed via Header.FromData<T>(string, T, IHeaderFactory<T>)
Note that while Headers can be read at any point during deserialization, they can only be written at the beginning of serialization.
Header Factories serve as basic serializers for headers. They are intended to convert the header's data type to and from a target type.
Note that header factories cannot (or rather, should not) be used in place of serializers, and vice versa.