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.
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.
int version;
boolean persistent-coding-p;
YES
.
class (State) classForCoder Encoder coder;
isa
, which is the
receiving object's class.
void encodeUsingCoder Encoder coder;
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;
NO
.
_builtin_.Any (self) replacementForStreamCoder StreamEncoder coder;
StreamEncoder
coder
(i.e. archived or wired) instead of the receiving object. The default
implementation simply returns self
.
void initWithCoder Decoder coder;
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;
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.
int version;
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.
int reference_size;
id init;
MutableEqDictionary tmp_objects_done;
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;
Selector
objects.
MutableEqSet objects_skipped;
MutableEqSet coded_classes;
int last_object_id;
void encodeRoot State object;
Encoder
method: encode the object
and the whole
object graph implied by it. This method is not reentrant.
id init;
boolean hasBeenCodedFor class (State) the_class;
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;
object
, unconditionally.
void encodeConditionally State object;
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;
boolean
v
.
deferred void encode byte v;
byte
v
.
deferred void encode char v;
char
v
.
deferred void encode int v;
int
v
.
deferred void encode long v;
long
v
.
deferred void encode float v;
float
v
.
deferred void encode double v;
double
v
.
deferred void encode selector v;
selector
v.
deferred void encodeBytes (int, int) (start, length) from ByteArray r pre start >= 0 && length >= -1;
(start, length)
from the array r
.
deferred void encodeBytes (pointer, int) (address, length);
length
bytes of which the first one resides at the
address
.
deferred protected State replacementObjectFor State object;
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;
nil
reference.
deferred protected void encodeReference int v;
v
.
protected int identityFor All object;
object
. This
returns the next value of last_object_id
.
protected int identityForClass class (State) a_class;
a_class
. This
returns the next value of last_object_id
.
class (State) startEncoding State object;
protected void finishEncoding All object;
object
has been encoded. Default does nothing.
protected void startEncodingRoot All object;
object
. Default does
nothing.
protected void finishEncodingRoot All object;
object
has finished. Default does
nothing.
MutableDictionary selectors;
Selector
to IntNumber
.
id init;
class (State) startEncoding State object;
protected void finishEncoding All object;
object
has been encoded. Emit a close paren.
protected void updateReferenceSize;
protected int identityFor All object;
protected int identityForClass class (State) a_class;
stream
, reporting its coding
version.
protected void encodeNilObject;
protected void encodeReference int v;
void encode boolean v;
void encode byte v;
void encode char v;
void encode int v;
void encode long v;
void encode float v;
void encode double v;
void encode selector v;
void encodeBytes (pointer, int) (address, length);
void encodeBytes (int, int) (start, length) from ByteArray r;
protected void writeReference int r pre reference_size == 1 || reference_size == 2 || reference_size == 4;
deferred protected void writeByte byte b;
deferred protected void writeBytes (int, int) (start, length) from ByteArray r;
deferred protected void writeBytes (pointer, int) (address, length);
protected void writeChar char c;
protected void writeInt int i;
protected void writeLong long l;
Decoder
class defines the interface to all decoder classes, be
it binary or textual, stream or port base.
MutableIntDictionary tmp_objects_done;
MutableIntDictionary perm_objects_done;
IntegerRangeSet objects_referenced;
MutableEqDictionary class_versions;
MutableEqSet coded_classes;
id init;
_builtin_.Any decodeRoot;
decodeRoot
to retrieve an object, plus its underlying graph,
from this decoder. The object is returned.
boolean hasBeenCodedFor class (State) the_class;
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;
cls
as encountered by this coder.
The version can only be retrieved of classes already encountered
curing the decoding process.
deferred _builtin_.Any decode;
deferred boolean decode;
deferred byte decode;
deferred char decode;
deferred int decode;
deferred long decode;
deferred float decode;
deferred double decode;
deferred selector decode;
deferred (pointer, int) decodeBytes;
deferred void decodeBytes int num to pointer address;
num
bytes from the coder to the address
.
protected _builtin_.Any decodeObject class (State) cls as int ref;
protected void finishDecoding All o;
decodeObject as
, after having invoked initWithCoder
,
but before awakeAfterUsingCoder
. The default implementation does
nothing.
protected _builtin_.Any reference int i;
i
.
BinaryDecoder
is an abstract decoding class which can decode
binary encoded objects. It serves as the decoding engine for the
BinaryStreamDecoder
and too.PortDecoder
.
MutableArray selectors;
id init;
_builtin_.Any decode;
_builtin_.Any decode byte b;
b
.
boolean decode;
byte decode;
char decode;
int decode;
long decode;
float decode;
double decode;
selector (result) decode;
(pointer, int) decodeBytes;
void decodeBytes int length to pointer address;
protected void finishDecoding All o;
o
has been decoded. Read a close paren.
protected byte nextPrimary;
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;
expected
. If
it doesn't, a program-condition
is raised.
protected int readReference pre reference_size == 1 || reference_size == 2 || reference_size == 4;
reference_size
this read 1, 2, or 4 bytes.
protected _builtin_.Any readReference;
coding-condition
in case not a proper
reference is encountered, or if the referenced object is unknown.
deferred protected byte readByte;
byte
.
deferred protected void readBytes int num to pointer address;
protected char readChar;
char
.
protected int readInt;
int
.
protected long readLong;
long
.