From 496bde0f957c89f7392a1cb2111ccc5223c7d4ed Mon Sep 17 00:00:00 2001 From: mccallum Date: Sun, 9 Apr 1995 01:52:11 +0000 Subject: [PATCH] (CommonCoding, Encoding, Decoding): New protocols. (SelfCoding): New category of NSObject, interface only, no implementation. This takes the place of the Coding Protocol. (Coding): Protocol removed. git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@332 72102866-910b-0410-8b05-ffd578937521 --- Headers/gnustep/base/Coding.h | 162 ++++++++++++++++++++++++++++------ Source/objects/Coding.h | 162 ++++++++++++++++++++++++++++------ 2 files changed, 272 insertions(+), 52 deletions(-) diff --git a/Headers/gnustep/base/Coding.h b/Headers/gnustep/base/Coding.h index 867af9122..b02420b1f 100644 --- a/Headers/gnustep/base/Coding.h +++ b/Headers/gnustep/base/Coding.h @@ -1,5 +1,5 @@ /* Protocol for GNU Objective-C objects that can write/read to a coder - Copyright (C) 1993,1994 Free Software Foundation, Inc. + Copyright (C) 1993, 1994, 1995 Free Software Foundation, Inc. Written by: R. Andrew McCallum Date: July 1994 @@ -21,44 +21,154 @@ Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef __Coding_h -#define __Coding_h +#ifndef __Coding_h_OBJECTS_INCLUDE +#define __Coding_h_OBJECTS_INCLUDE #include -@class Coder; +@class Coder; /* xxx remove this eventually */ +@class Stream; /* xxx remove this eventually */ -@protocol Coding +@protocol CommonCoding -- (void) encodeWithCoder: (Coder*)anEncoder; -+ newWithCoder: (Coder*)aDecoder; +- (BOOL) isDecoding; -/* xxx To avoid conflict with OpenStep, change names to: - encodeOnCoder: ? ++ (int) coderFormatVersion; ++ (int) coderConcreteFormatVersion; ++ (const char *) coderSignature; - encodeToCoder: - newFromCoder: -*/ +- doInitOnStream: (Stream *)s isDecoding: (BOOL)f; +/* Internal designated initializer. Override it, but don't call it yourself. + This method name may change. */ -/* NOTE: +@end - This is +newWithCoder: and not -initWithCoder: because many classes - keep track of their instances and only allow one instance of each - configuration. For example, see the designated initializers of - SocketPort, Connection, and Proxy. +@protocol Encoding - Making this +new.. instead of -init.. prevents us from having to - waste the effort of allocating space for an object to be decoded, - then immediately deallocating that space because we're just - returning a pre-existing object. +- initEncodingOnStream: (Stream *)s; +- initEncoding; - I also like it because it makes very clear that this method is - expected to return the decoded object. This requirement would have - also been present in an -init... implementation, but the - requirement may not have been 100 percent clear by the method name. +- (void) encodeValueOfType: (const char*)type + at: (const void*)d + withName: (const char *)name; + +- (void) encodeWithName: (const char *)name + valuesOfTypes: (const char *)types, ...; + +- (void) encodeArrayOfType: (const char *)type + at: (const void *)d + count: (unsigned)c + withName: (const char *)name; + +- (void) encodeObject: anObj + withName: (const char *)name; +- (void) encodeObjectBycopy: anObj + withName: (const char *)name; + +- (void) encodeRootObject: anObj + withName: (const char *)name; +- (void) encodeObjectReference: anObj + withName: (const char *)name; +- (void) startEncodingInterconnectedObjects; +- (void) finishEncodingInterconnectedObjects; + +- (void) encodeAtomicString: (const char*)sp + withName: (const char*)name; + +- (void) encodeClass: aClass; + +/* For inserting a name into a TextCoder stream */ +- (void) encodeName: (const char*)n; + +/* For subclasses that want to keep track of recursion */ +- (void) encodeIndent; +- (void) encodeUnindent; + +/* Implemented by concrete subclasses */ +- (void) encodeValueOfSimpleType: (const char*)type + at: (const void*)d + withName: (const char *)name; +- (void) encodeBytes: (const char *)b + count: (unsigned)c + withName: (const char *)name; + +@end + +@protocol Decoding + +- initDecodingOnStream: (Stream *)s; +- initDecoding; + +- (void) decodeValueOfType: (const char*)type + at: (void*)d + withName: (const char **)namePtr; + +- (void) decodeWithName: (const char **)name + valuesOfTypes: (const char *)types, ...; + +- (void) decodeArrayOfType: (const char *)type + at: (void *)d + count: (unsigned *)c + withName: (const char **)name; + +- (void) decodeObjectAt: (id*)anObjPtr + withName: (const char **)name; + +- (void) startDecodingInterconnectedObjects; +- (void) finishDecodingInterconnectedObjects; + +- (const char *) decodeAtomicStringWithName: (const char **)name; + +- decodeClass; + +/* For inserting a name into a TextCoder stream */ +- (void) decodeName: (const char**)n; + +/* For subclasses that want to keep track of recursion */ +- (void) decodeIndent; +- (void) decodeUnindent; + +/* Implemented by concrete subclasses */ +- (void) decodeValueOfSimpleType: (const char*)type + at: (void*)d + withName: (const char **)namePtr; +- (void) decodeBytes: (char *)b + count: (unsigned*)c + withName: (const char **)name; + +@end + +@interface NSObject (SelfCoding) + +- (void) encodeWithCoder: (id )anEncoder; +- (id) initWithCoder: (id )aDecoder; ++ (id) newWithCoder: (id )aDecoder; + +/* NOTE: + + If the class responds to +newWithCoder Coder will send it for + decoding, otherwise Coder will allocate the object itself and send + initWithCoder instead. + + +newWithCoder is useful because many classes keep track of their + instances and only allow one instance of each configuration. For + example, see the designated initializers of SocketPort, Connection, + and Proxy. + + Using +new.. instead of -init.. prevents us from having to waste + the effort of allocating space for an object to be decoded, then + immediately deallocating that space because we're just returning a + pre-existing object. + + The newWithCoder and initWithCoder methods must return the decoded + object. + + This is not a Protocol, because objects are not required to + implement newWithCoder or initWithCoder. They probably want to + implement one of them, though. -mccallum */ @end -#endif /* __Coding_h */ +#endif /* __Coding_h_OBJECTS_INCLUDE */ diff --git a/Source/objects/Coding.h b/Source/objects/Coding.h index 867af9122..b02420b1f 100644 --- a/Source/objects/Coding.h +++ b/Source/objects/Coding.h @@ -1,5 +1,5 @@ /* Protocol for GNU Objective-C objects that can write/read to a coder - Copyright (C) 1993,1994 Free Software Foundation, Inc. + Copyright (C) 1993, 1994, 1995 Free Software Foundation, Inc. Written by: R. Andrew McCallum Date: July 1994 @@ -21,44 +21,154 @@ Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef __Coding_h -#define __Coding_h +#ifndef __Coding_h_OBJECTS_INCLUDE +#define __Coding_h_OBJECTS_INCLUDE #include -@class Coder; +@class Coder; /* xxx remove this eventually */ +@class Stream; /* xxx remove this eventually */ -@protocol Coding +@protocol CommonCoding -- (void) encodeWithCoder: (Coder*)anEncoder; -+ newWithCoder: (Coder*)aDecoder; +- (BOOL) isDecoding; -/* xxx To avoid conflict with OpenStep, change names to: - encodeOnCoder: ? ++ (int) coderFormatVersion; ++ (int) coderConcreteFormatVersion; ++ (const char *) coderSignature; - encodeToCoder: - newFromCoder: -*/ +- doInitOnStream: (Stream *)s isDecoding: (BOOL)f; +/* Internal designated initializer. Override it, but don't call it yourself. + This method name may change. */ -/* NOTE: +@end - This is +newWithCoder: and not -initWithCoder: because many classes - keep track of their instances and only allow one instance of each - configuration. For example, see the designated initializers of - SocketPort, Connection, and Proxy. +@protocol Encoding - Making this +new.. instead of -init.. prevents us from having to - waste the effort of allocating space for an object to be decoded, - then immediately deallocating that space because we're just - returning a pre-existing object. +- initEncodingOnStream: (Stream *)s; +- initEncoding; - I also like it because it makes very clear that this method is - expected to return the decoded object. This requirement would have - also been present in an -init... implementation, but the - requirement may not have been 100 percent clear by the method name. +- (void) encodeValueOfType: (const char*)type + at: (const void*)d + withName: (const char *)name; + +- (void) encodeWithName: (const char *)name + valuesOfTypes: (const char *)types, ...; + +- (void) encodeArrayOfType: (const char *)type + at: (const void *)d + count: (unsigned)c + withName: (const char *)name; + +- (void) encodeObject: anObj + withName: (const char *)name; +- (void) encodeObjectBycopy: anObj + withName: (const char *)name; + +- (void) encodeRootObject: anObj + withName: (const char *)name; +- (void) encodeObjectReference: anObj + withName: (const char *)name; +- (void) startEncodingInterconnectedObjects; +- (void) finishEncodingInterconnectedObjects; + +- (void) encodeAtomicString: (const char*)sp + withName: (const char*)name; + +- (void) encodeClass: aClass; + +/* For inserting a name into a TextCoder stream */ +- (void) encodeName: (const char*)n; + +/* For subclasses that want to keep track of recursion */ +- (void) encodeIndent; +- (void) encodeUnindent; + +/* Implemented by concrete subclasses */ +- (void) encodeValueOfSimpleType: (const char*)type + at: (const void*)d + withName: (const char *)name; +- (void) encodeBytes: (const char *)b + count: (unsigned)c + withName: (const char *)name; + +@end + +@protocol Decoding + +- initDecodingOnStream: (Stream *)s; +- initDecoding; + +- (void) decodeValueOfType: (const char*)type + at: (void*)d + withName: (const char **)namePtr; + +- (void) decodeWithName: (const char **)name + valuesOfTypes: (const char *)types, ...; + +- (void) decodeArrayOfType: (const char *)type + at: (void *)d + count: (unsigned *)c + withName: (const char **)name; + +- (void) decodeObjectAt: (id*)anObjPtr + withName: (const char **)name; + +- (void) startDecodingInterconnectedObjects; +- (void) finishDecodingInterconnectedObjects; + +- (const char *) decodeAtomicStringWithName: (const char **)name; + +- decodeClass; + +/* For inserting a name into a TextCoder stream */ +- (void) decodeName: (const char**)n; + +/* For subclasses that want to keep track of recursion */ +- (void) decodeIndent; +- (void) decodeUnindent; + +/* Implemented by concrete subclasses */ +- (void) decodeValueOfSimpleType: (const char*)type + at: (void*)d + withName: (const char **)namePtr; +- (void) decodeBytes: (char *)b + count: (unsigned*)c + withName: (const char **)name; + +@end + +@interface NSObject (SelfCoding) + +- (void) encodeWithCoder: (id )anEncoder; +- (id) initWithCoder: (id )aDecoder; ++ (id) newWithCoder: (id )aDecoder; + +/* NOTE: + + If the class responds to +newWithCoder Coder will send it for + decoding, otherwise Coder will allocate the object itself and send + initWithCoder instead. + + +newWithCoder is useful because many classes keep track of their + instances and only allow one instance of each configuration. For + example, see the designated initializers of SocketPort, Connection, + and Proxy. + + Using +new.. instead of -init.. prevents us from having to waste + the effort of allocating space for an object to be decoded, then + immediately deallocating that space because we're just returning a + pre-existing object. + + The newWithCoder and initWithCoder methods must return the decoded + object. + + This is not a Protocol, because objects are not required to + implement newWithCoder or initWithCoder. They probably want to + implement one of them, though. -mccallum */ @end -#endif /* __Coding_h */ +#endif /* __Coding_h_OBJECTS_INCLUDE */