File tom/coding

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.


class tom.State (Coding)

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.

methods

int
  version;
Undocumented.

boolean
  persistent-coding-p;
Return YES.

Encoding methods

instance tom.State (Coding)

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.

boolean
  persistent-coding-p;
Return NO.

_builtin_.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.

Decoding methods

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.

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.


class tom.Coder

Inherits

State supers
State, Conditions

methods

int
  version;
The version of the coding scheme used. The current version is 0.

instance tom.Coder


class tom.BinaryCoder

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

instance tom.BinaryCoder

variables

int reference_size;
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.


class tom.Encoder

Inherits

State supers
Coder

instance tom.Encoder

variables

MutableEqDictionary tmp_objects_done;
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.
MutableEqDictionary perm_objects_done;
Similar, the non-temporary objects. This includes class objects and Selector objects.
MutableEqSet objects_skipped;
The set of conditional objects that were skipped.
MutableEqSet coded_classes;
The classes which, for the current object, have already done their part in the coding.
int last_object_id;
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.

Encoding methods

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.

Internal methods

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.


class tom.BinaryEncoder

Inherits

State supers
BinaryCoder, Encoder

instance tom.BinaryEncoder

variables

MutableDictionary selectors;
The selector dictionary, from Selector to IntNumber.

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.


class tom.Decoder

The Decoder class defines the interface to all decoder classes, be it binary or textual, stream or port base.

Inherits

State supers
Coder

instance tom.Decoder

variables

MutableIntDictionary tmp_objects_done;
Objects, indexed on their identity, as retrieved from this coder.
MutableIntDictionary perm_objects_done;
IntegerRangeSet objects_referenced;
The identity of the objects that have been referenced while being decoded.
MutableEqDictionary class_versions;
Mapping from a class to the decoding version of that class.
MutableEqSet coded_classes;
The classes which, for the current object, have already done their part in the coding.

methods

id
  init;
Designated initializer.

_builtin_.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.

Decoding methods

deferred _builtin_.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 _builtin_.Any
  decodeObject class (State) cls
            as int ref;

Private methods

protected void
  finishDecoding All o;
Invoked by decodeObject as, after having invoked initWithCoder, but before awakeAfterUsingCoder. The default implementation does nothing.

protected _builtin_.Any
  reference int i;
Return the object referenced as the number i.


class tom.BinaryDecoder

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

instance tom.BinaryDecoder

variables

MutableArray selectors;
The selectors encountered so far, indexed on their identity.

methods

id
  init;
Designated initializer.

_builtin_.Any
  decode;
Decode and return an object.

_builtin_.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.

Internal methods

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 _builtin_.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.


Generated by tm 1.01.