ObjectCoder is a workaround for circular hierarchy - it is only a placeholder for methods called from State (Coding).
inherits
State supers: Conditions, Constants
methods
void encodeObject State obj usingCoder Encoder coder; |
Undocumented.
void initObject State obj usingCoder Decoder coder; |
Undocumented.
This extension of State defines the functionality for encoding and decoding objects. To be able to encode an object, it must at least properly implement encodeUsingCoder. Similarly, to be decodable, it must implement initWithCoder.
The unit of archiving is a class, not an extension. This means that if an extension adds state information which needs to be archived (or encoded onto a too.PortCoder), the extension must re-implement the coding methods.
variables
Classes that want to be encoded in the obvious way, by writing the values of their variables, set this to TRUE.
methods
int
version;
|
Return the current version of the class cls. This is the version that will be written when coding instances of this class or a subclass thereof. The default version is 0.
A version should only be returned if self is identical to the class containing the method definition, i.e. the method is not inherited. Otherwise, the two are unequal, and the version of a subclass is requested that does not implement this method, and hence should return version 0.
boolean
never-encode-simply-p;
|
Return YES if encode_simply of all classes involved in the receiving object will always return FALSE. Coding is sped up tremendously in that case. The defaultis NO, to not speed up and allow for passive encoding.
boolean
persistent-coding-p;
|
Return YES.
methods
class (State) classForCoder Encoder coder; |
Return the class to be put in the coded stream as the class of this object. The default implementation simply returns isa, which is the receiving object's class.
void encodeUsingCoder Encoder coder; |
Encode the receiving object to the target coder. Every object should first invoke this method of all its direct superclasses before encoding its instance variables, but only if hasBeenCodedFor for the class implementing the method returns FALSE. For classes that set encode_simply to TRUE, this method will use introspection to encode the class variables.
boolean
never-encode-simply-p;
|
Return YES if encode_simply of all classes involved in the receiving object will always return FALSE. Coding is sped up tremendously in that case.
boolean
persistent-coding-p;
|
Return NO.
Any (self) replacementForStreamCoder StreamEncoder coder; |
Return the object to be encoded on the StreamEncoder coder (i.e. archived or wired) instead of the receiving object. The default implementation simply returns self.
void initWithCoder Decoder coder; |
Initialize the receiving object from the coder. After verifying that this method implementation has not yet been invoked (using hasBeenCodedFor), this method should invoke the implementation of this method by the superclasses, followed the fields that were encoded by this class. Decoding must be done in the same order as encoding. Default implementation on State will use introspection to init the objects that requested it by setting encode_simply on their class to TRUE.
Note that this method returns void. An object can change the actual object returned from decoding by implementing awakeAfterUsingCoder.
id (self) awakeAfterUsingCoder Decoder coder; |
Return the object to be the object retrieved from decoding instead of the receiving object. The default implementation returns self.
Objects can use this method to return their administered counterpart, like UniqueString objects do.
Note that if an object is referenced during its decoding (i.e. object A is referenced by an object B which is decoded because B is (indirectly) referenced by A), it must not return a different object from awakeAfterUsingCoder. If it does, a coding-condition is raised.
inherits
State supers: State, Conditions
methods
int
version;
|
The version of the coding scheme used. The current version is 0.
methods
void willCodeVariable String name forObject All object inExtension Extension x; |
Notify the coder object about the variable being coded. This allows primitive form of state versioning control. Note that there are no guarantees that every class will send this notification while encoding itself.
void willCodeExtension Extension x forObject All object; |
Notify the coder of the extension being coded. There are no guarantees that every class will send this notification.
void doneCodingExtension Extension x; |
Notify the coder that the coding of the extension x is finished.
The BinaryCoder classes BinaryEncoder and BinaryDecoder can archive dearchive a graph of objects in a binary form onto/from a stream. The format is rather simple: Every item stored is preceded by a tag byte indicating what the next item is. There are a few secondary tags to introduce classes, etc.
Every instance or class written is internally numbered in the order the objects are written. References to these objects are encoded in the number of bytes necessary for the number of currently known objects. The secondary tags 2 and 4 switch to 2 and 4 byte reference encoding, respectively.
The nil object is denoted by the 0 tag.
Selectors are encoded as a tag S, followed by the assigned selector number (which is an int, starting at 1) and the corresponding Selector object. Selectors already encoded are denoted by a tag s and the int selector number. The invalid selector (the default value of selector typed variables, also available as [Runtime nullSelector]) is identified by the tag s followed by 0 as the selector number.
inherits
State supers: Coder
variables
The number of bytes issued for a reference. This starts with 1 (a byte), and can become 2 (a char) or 4 (an int).
methods
id
init;
|
Undocumented.
inherits
State supers: Coder
variables
Keyed on the objects already encoded, the value is the identifier (which is an IntNumber) used for this object. This dict only contains temporary objects, i.e. objects that can be forgotten about after each encodeRoot.
Similar, the non-temporary objects. This includes class objects and Selector objects.
The set of conditional objects that were skipped.
The classes which, for the current object, have already done their part in the coding.
The most recently issued object identifier.
methods
void encodeRoot State object; |
The main entry Encoder method: encode the object and the whole object graph implied by it. This method is not reentrant.
id
init;
|
Designated initializer.
boolean hasBeenCodedFor class (State) the_class; |
Return NO if the object currently being encoded on this coder has not yet been encoded for the_class. Return YES otherwise. While coding an object, only the first invocation for a certain the_class will return YES; subsequent invocations will return NO.
void encode State object; |
Encode the object, unconditionally.
void encodeConditionally State object; |
Encode the object, but only if it already is part of the output graph. If this is not the case, nil is encoded, and if later on in the coding process the object previously encoded as nil is encountered (unconditionally), a program-condition will be raised to flag the inconsistency.
deferred void encode boolean v; |
Encode the boolean v.
deferred void encode byte v; |
Encode the byte v.
deferred void encode char v; |
Encode the char v.
deferred void encode int v; |
Encode the int v.
deferred void encode long v; |
Encode the long v.
deferred void encode float v; |
Encode the float v.
deferred void encode double v; |
Encode the double v.
deferred void encode selector v; |
Encode the selector v.
deferred void encodeBytes (int, int) (start, length) from ByteArray r pre start >= 0 && length >= -1; |
Encode the bytes in the range (start, length) from the array r.
deferred void encodeBytes (pointer, int) (address, length); |
Encode the length bytes of which the first one resides at the address.
deferred protected State replacementObjectFor State object; |
Return the object to be encoded to this coder instead of the object. This method is implemented by subclasses to retrieve the actual object from the object itself, for instance by asking for it replacementForStreamCoder or replacementForPortCoder.
deferred protected void
encodeNilObject;
|
Encode the nil reference.
deferred protected void encodeReference int v; |
Encode a reference to the object known as v.
protected int identityFor All object; |
Return the identity to be used for the non-class object. This returns the next value of last_object_id.
protected int identityForClass class (State) a_class; |
Return the identity to be used for the class object a_class. This returns the next value of last_object_id.
class (State) startEncoding State object; |
Undocumented.
protected void finishEncoding All object; |
Invoked when the object has been encoded. Default does nothing.
protected void startEncodingRoot All object; |
Invoked when coding starts with the root object. Default does nothing.
protected void finishEncodingRoot All object; |
Invoked when coding the root object has finished. Default does nothing.
inherits
State supers: BinaryCoder, Encoder
variables
methods
id
init;
|
Designated initializer.
class (State) startEncoding State object; |
Undocumented.
protected void finishEncoding All object; |
Invoked when the object has been encoded. Emit a close paren.
protected void
updateReferenceSize;
|
Undocumented.
protected int identityFor All object; |
Undocumented.
protected int identityForClass class (State) a_class; |
Identify this class on the output stream, reporting its coding version.
protected void
encodeNilObject;
|
Undocumented.
protected void encodeReference int v; |
Undocumented.
void encode boolean v; |
Undocumented.
void encode byte v; |
Undocumented.
void encode char v; |
Undocumented.
void encode int v; |
Undocumented.
void encode long v; |
Undocumented.
void encode float v; |
Undocumented.
void encode double v; |
Undocumented.
void encode selector v; |
Undocumented.
void encodeBytes (pointer, int) (address, length); |
Undocumented.
void encodeBytes (int, int) (start, length) from ByteArray r; |
Undocumented.
protected void writeReference int r pre reference_size == 1 || reference_size == 2 || reference_size == 4; |
Undocumented.
deferred protected void writeByte byte b; |
Undocumented.
deferred protected void writeBytes (int, int) (start, length) from ByteArray r; |
Undocumented.
deferred protected void writeBytes (pointer, int) (address, length); |
Undocumented.
protected void writeChar char c; |
Undocumented.
protected void writeInt int i; |
Undocumented.
protected void writeLong long l; |
Undocumented.
The Decoder class defines the interface to all decoder classes, be it binary or textual, stream or port base.
inherits
State supers: Coder
variables
Objects, indexed on their identity, as retrieved from this coder.
The identity of the objects that have been referenced while being decoded.
Mapping from a class to the decoding version of that class.
The classes which, for the current object, have already done their part in the coding.
methods
id
init;
|
Designated initializer.
Any decodeRoot; |
This is the entry point for the user of this decoder. The user invokes decodeRoot to retrieve an object, plus its underlying graph, from this decoder. The object is returned.
boolean hasBeenCodedFor class (State) the_class; |
Return NO if the object currently being decoded on this coder has not yet been decoded for the_class. Return YES otherwise. While coding an object, only the first invocation for a certain the_class will return YES; subsequent invocations will return NO.
int versionOfClass class (State) cls pre class_versions[cls] != nil; |
Return the version of the class cls as encountered by this coder. The version can only be retrieved of classes already encountered curing the decoding process.
deferred Any decode; |
Retrieve an object from this decoder and return it.
deferred boolean
decode;
|
Undocumented.
deferred byte
decode;
|
Undocumented.
deferred char
decode;
|
Undocumented.
deferred int
decode;
|
Undocumented.
deferred long
decode;
|
Undocumented.
deferred float
decode;
|
Undocumented.
deferred double
decode;
|
Undocumented.
deferred selector
decode;
|
Undocumented.
deferred (pointer, int) decodeBytes; |
Decode a sequence of bytes from the coder to newly allocated memory space. Return the address and the length.
deferred void decodeBytes int num to pointer address; |
Decode the num bytes from the coder to the address.
protected Any decodeObject class (State) cls as int ref; |
Undocumented.
protected void finishDecoding All o; |
Invoked by decodeObject as, after having invoked initWithCoder, but before awakeAfterUsingCoder. The default implementation does nothing.
protected Any reference int i; |
Return the object referenced as the number i.
The BinaryDecoder is an abstract decoding class which can decode binary encoded objects. It serves as the decoding engine for the BinaryStreamDecoder and too.PortDecoder.
inherits
State supers: BinaryCoder, Decoder, C
variables
The selectors encountered so far, indexed on their identity.
methods
id
init;
|
Designated initializer.
Any decode; |
Decode and return an object.
Any decode byte b; |
Decode and return an object, announced by the tag b.
boolean
decode;
|
Undocumented.
byte
decode;
|
Undocumented.
char
decode;
|
Undocumented.
int
decode;
|
Undocumented.
long
decode;
|
Undocumented.
float
decode;
|
Undocumented.
double
decode;
|
Undocumented.
selector (result)
decode;
|
Undocumented.
(pointer, int) decodeBytes; |
Undocumented.
void decodeBytes int length to pointer address; |
Undocumented.
protected void finishDecoding All o; |
Invoked when the object o has been decoded. Read a close paren.
protected byte
nextPrimary;
|
Return the next primary tag byte, handling secondary tags such as reference size changes and class declarations.
If an unknown class is encountered, a unknown-class-condition is signaled. A handler may return a replacement class to be used instead. Failure to do so will later on result in a nil-receiver condition or a failed precondition.
protected byte nextPrimary byte expected; |
Return the next primary tag byte, which must match expected. If it doesn't, a program-condition is raised.
protected int
readReference
pre
reference_size == 1 || reference_size == 2 || reference_size == 4;
|
Read an object reference from this decoder. Depending on the reference_size this read 1, 2, or 4 bytes.
protected Any readReference; |
Read an object reference from this decoder and return the object referenced. This raises a coding-condition in case not a proper reference is encountered, or if the referenced object is unknown.
deferred protected byte
readByte;
|
Return the next single byte.
deferred protected void readBytes int num to pointer address; |
Undocumented.
protected char
readChar;
|
Return the next two bytes as a char.
protected int
readInt;
|
Return the next four bytes as an int.
protected long
readLong;
|
Return the next 8 bytes as a long.