Class Recorder
- Namespace
- Dec
- Assembly
- dec.dll
Main class for the serialization/deserialization system.
public abstract class Recorder- Inheritance
-
objectRecorder
Remarks
Recorder is used to call the main functions for serialization/deserialization. This includes both the static initiation functions (Read, Write) and the per-element status functions.
To start serializing or deserializing an object, see Recorder.Read and Recorder.Write.
Properties
Context
Provide the Context for this serialization step, which can be used to get diagnostic information about "where" it is.
public abstract Context Context { get; }Property Value
Mode
Indicates whether this Recorder is being used for reading or writing.
public abstract Recorder.Direction Mode { get; }Property Value
UserSettings
public abstract Recorder.IUserSettings UserSettings { get; }Property Value
Methods
Bespoke_KeyTypeDict()
Informs the recorder system that the next parameter will be a Dictionary<Type, V> where the key should be interpreted as the type of the V.
public Recorder.Parameters Bespoke_KeyTypeDict()Returns
Remarks
This is a specialty hack added for one specific user and may vanish with little warning, though if it does, it'll be replaced by something at least as capable.
Clone<T>(T, IUserSettings)
Makes a copy of an object.
public static T Clone<T>(T obj, Recorder.IUserSettings userSettings = null)Parameters
objTuserSettingsRecorder.IUserSettings
Returns
- T
Type Parameters
T
Remarks
This is logically equivalent to Write(Read(obj)), but much faster (approx 200x in one real-world testcase.)
Clone() is guaranteed to accept everything that Write(Read(obj)) does, but the reverse is not true; Clone is sometimes more permissive than the disk serialization system. Don't expect to use this as complete validation for Write.
This is a new feature and should be considered experimental. It is currently undertested, and I cannot stress this enough, Dec is a library full of weird edge cases and extremely carefully chosen behaviors, I guarantee many of those are handled wrong with Clone. If performance is not critical I currently strongly recommend using Write(Read(obj)).
Err(string)
Post a proper Context-decorated message to the error log.
public void Err(string message)Parameters
messagestring
Ignore(string)
Indicates that a field is intentionally unused and should be ignored.
public virtual void Ignore(string label)Parameters
labelstring
Remarks
Dec will output warnings if a field isn't being used, on the assumption that it's probably a mistake.
Sometimes a field is ignored intentionally, usually for backwards compatibility reasons, and this function can be used to suppress that warning.
Inf(string)
Post a proper Context-decorated message to the info log.
public void Inf(string message)Parameters
messagestring
ReadSimple<T>(string, string, string, IUserSettings)
Parses the output of WriteSimple, generating an object and all its related serialized data.
public static T ReadSimple<T>(string input, string rootTag, string stringName = "input", Recorder.IUserSettings userSettings = null)Parameters
inputstringrootTagstringstringNamestringuserSettingsRecorder.IUserSettings
Returns
- T
Type Parameters
T
Read<T>(string, string, IUserSettings)
Parses the output of Write, generating an object and all its related serialized data.
public static T Read<T>(string input, string stringName = "input", Recorder.IUserSettings userSettings = null)Parameters
inputstringstringNamestringuserSettingsRecorder.IUserSettings
Returns
- T
Type Parameters
T
RecordAsThis<T>(ref T)
Serialize or deserialize a member of a class as if it were this class.
public void RecordAsThis<T>(ref T value)Parameters
valueT
Type Parameters
T
Remarks
This function serializes or deserializes a class member as if it were this entire class. Call it with a reference to the member.
This is intended for cases where a class's contents are a single method and where an extra level of indirection in XML files isn't desired.
In most cases, you don't need to do anything different for read vs. write; this function will figure out the details and do the right thing.
This does not work, at all, if any of the classes in the this chain are inherited; it needs to be able to fall back on default types.
Record<T>(ref T, string)
Serialize or deserialize a member of a class.
public void Record<T>(ref T value, string label)Parameters
valueTlabelstring
Type Parameters
T
Remarks
This function serializes or deserializes a class member. Call it with a reference to the member and a label for the member (usually the member's name.)
In most cases, you don't need to do anything different for read vs. write; this function will figure out the details and do the right thing.
Be aware that if you're reading an object that was serialized as .Shared(), the object may not be fully deserialized by the time this function returns. If you aren't completely certain that the object was unshared when serialized, do not access members of the recorded object - they may be in an unknown state. If you need to do something after all objects are fully deserialized, wait until Recorder.Read() is finished and do a post-processing pass.
Shared()
Allow sharing for class objects referenced during this call.
public Recorder.Parameters Shared()Returns
Remarks
Shared objects can be referenced from multiple classes. During serialization, these links will be stored; during deserialization, these links will be recreated. This is handy if (for example) your entities need to refer to each other for AI or targeting reasons.
However, when reading, shared Recorder fields must be initially set to null.
Dec objects are essentially treated as value types, and will be referenced appropriately even without this.
This is incompatible with WithFactory().
WithFactory(Dictionary<Type, Func<Type, object>>)
Add a factory layer to objects created during this call.
public Recorder.Parameters WithFactory(Dictionary<Type, Func<Type, object>> factories)Parameters
factoriesDictionary<Type, Func<Type, object>>
Returns
Remarks
This allows you to create your own object initializer for things deserialized during this call. Standard Recorder functionality will apply on the object returned. This is sometimes a convenient way to set per-object defaults when deserializing.
The initializer layout takes the form of a dictionary from Type to Func<Type, object>.
When creating a new object, Dec will first look for a dictionary key of that type, then continue checking base types iteratively until it either finds a callback or passes object.
That callback will be given a desired type and must return either an object of that type, an object of a type derived from that type, or null.
On null, Dec will fall back to its default behavior. In each other case, it will then be deserialized as usual.
The factory callback will persist until the next Recorder is called; recursive calls past that will be reset to default behavior.
This means that it will effectively tunnel through supported containers such as List<> and Dictionary<>, allowing you to control the constructor of CustomType in List<CustomType>.
Be aware that any classes created with a factory callback added cannot be referenced from multiple places in Record hierarchy - the normal ref structure does not function with them.
Also, be aware that excessively deep hierarchies full of factory callbacks may result in performance issues when writing pretty-print XML; this is not likely to be a problem in normal code, however.
For performance's sake, this function does not duplicate factories and may modify it for efficiency reasons.
It can be reused, but should not be modified by the user once passed into a function once.
This is incompatible with Shared().
WriteSimple<T>(T, string, IUserSettings)
Returns a fully-formed XML document starting at an object. Supports tree layouts only; no shared objects, no loops, no self-referencing objects.
public static string WriteSimple<T>(T target, string rootTag, Recorder.IUserSettings userSettings = null)Parameters
targetTrootTagstringuserSettingsRecorder.IUserSettings
Returns
Type Parameters
T
WriteValidation<T>(T, IUserSettings)
Returns C# validation code starting at an option.
public static string WriteValidation<T>(T target, Recorder.IUserSettings userSettings = null)Parameters
targetTuserSettingsRecorder.IUserSettings
Returns
Type Parameters
T
Write<T>(T, bool, IUserSettings)
Returns a fully-formed XML document starting at an object. Supports non-tree layouts with shared objects, including loops and self-referencing objects.
public static string Write<T>(T target, bool pretty = false, Recorder.IUserSettings userSettings = null)Parameters
targetTprettybooluserSettingsRecorder.IUserSettings
Returns
Type Parameters
T
Wrn(string)
Post a proper Context-decorated message to the warning log.
public void Wrn(string message)Parameters
messagestring