From d9e81649f6e7a9ddac8d4eaf9763f1caa32b8c8b Mon Sep 17 00:00:00 2001 From: mccallum Date: Thu, 6 Apr 1995 20:11:43 +0000 Subject: [PATCH] Initial revision git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@305 72102866-910b-0410-8b05-ffd578937521 --- Documentation/objective-c.texi | 567 +++++++++++++++++++++++++++++++++ 1 file changed, 567 insertions(+) create mode 100644 Documentation/objective-c.texi diff --git a/Documentation/objective-c.texi b/Documentation/objective-c.texi new file mode 100644 index 000000000..f2e776bff --- /dev/null +++ b/Documentation/objective-c.texi @@ -0,0 +1,567 @@ +\input texinfo @c -*-texinfo-*- +@c @setfilename objective-c.info + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Objective-C: (objective-c). The GNU Objective-C Language Manual +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @copyright{} 1994 R. Andrew McCallum and Free Software +Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@setchapternewpage odd +@settitle Objective-C Language Manual +@titlepage +@finalout +@title The GNU Objective-C Language Manual +@author R. Andrew McCallum +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1994 R. Andrew McCallum and Free Software +Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage + +@node Top, Introduction, (dir), (dir) +@top Main Menu + +This is the manual for the GNU Objective-C language. + +@menu +* Introduction:: +* Objects Messages and Classes:: +* Techniques:: +* Advanced Features:: +* Builtin Classes:: + +Appendices + +* History and Comparisons:: +* Runtime Internals:: +* Hacking for Efficiency:: +* Debugging ObjC:: +* Language Summary:: A summary of ObjC syntax and semantics. + +Indeces + +* Concept Index:: +* Function Index:: +@end menu + +@c ****************************************************************** +@node Introduction, Objects Messages and Classes, Top, Top +@chapter Introduction + +This manual describes the GNU Objective-C language. It is assumed that +the reader is already familiar with ANSI C. + +@section Overview + +Objective-C is an object-oriented computer programming language. It is +a superset of ANSI C and provides classes and message passing similar to +Smalltalk. (xxx Lifted from FAQ. General question: Should I lift from +the Objc FAQ? Is there a problem with this? If in doubt, I'll write it +all myself.) + +@menu +* Caveats:: Flaws and requests for help. +* Conventions:: How this manual is formatted. +* Acknowledgements:: The authors and editors of this manual. +@end menu + +@node Caveats, Conventions, Introduction, Introduction +@section Caveats + +This manual is pre-alpha. I am now trying to determine the organization +of manual. Afterward, sections will be filled in with text. + +If you have suggestions for additional topics or organizational changes, +please email them to @samp{mccallum@@cs.rochester.edu}. + + +@node Conventions, Acknowledgements, Caveats, Introduction +@section Conventions + +@node Acknowledgements, , Conventions, Introduction +@section Acknowledgements + + +@c ****************************************************************** +@node Objects Messages and Classes, Techniques, Introduction, Top +@chapter Objects, Messages and Classes + +Object-oriented programming made up of objects, the messages they can +receive and the classes that specify how objects are related. + +@menu +* Objects:: +* Messages:: +* Classes and Instances:: +* Inheritance of Subclasses:: +@end menu + +@node Objects, Messages, Objects Messages and Classes, Objects Messages and Classes +@section Objects Encapsulate Data and Operations + + + +Procedures and data in a bundle. Abstraction. + +@node Messages, Classes and Instances, Objects, Objects Messages and Classes +@section Messages Request Operations +@c @section Sending a Message to an Object + +@smallexample +[@var{receiver} @var{message}]; +@end smallexample + +Messages with arguments. +Return types. +Argument types. +Messages to @samp{nil}. + +@node Classes and Instances, Inheritance of Subclasses, Messages, Objects Messages and Classes +@section Classes Define Objects +@c @section Classes and Instances +@c @section Classes Define their Instances + +Inheritance of methods and instance variables. +Overriding methods. +Syntax of @@interface, @@implementation. +Messages to super. +Creating and freeing instances. + +@node Inheritance of Subclasses, , Classes and Instances, Objects Messages and Classes +@section Inheritance of Subclasses +@c @section Classes are Defined in an Inheritance Heirarchy +@c @section Subclasses and Inheritance + +@node Techniques, Advanced Features, Objects Messages and Classes, Top +@chapter Programming Techniques and Conventions + +@section Overriding Methods +@section Abstract Superclasses +@section Returning @samp{self} +@section ...more here... + + +@c ****************************************************************** +@node Advanced Features, Builtin Classes, Techniques, Top +@chapter Advanced Features + +@menu +* Runtime Message Variation:: +* Forwarding a Message:: Using @samp{-forward::} and @samp{-performv::}. +* Adding Methods to a Class:: Defining categories. +* Posing as a Superclass:: +* Protocols of Messages:: +* Class initialization:: Defining @samp{+initialize}. +* Encoding Types:: +* Structure of an Object:: Using @@defs(). +* Archiving:: Using @samp{-write:} and @samp{-read:}. +@end menu + +@node Runtime Message Variation, Forwarding a Message, Advanced Features, Advanced Features +@section Runtime Message Variation + +Describe @samp{-perform:} and friends. + +@node Forwarding a Message, Adding Methods to a Class, Runtime Message Variation, Advanced Features +@section Forwarding a Message +@cindex Forwarding a Message + +Describe @samp{-forward::} and @samp{-performv::}. + +@node Adding Methods to a Class, Posing as a Superclass, Forwarding a Message, Advanced Features +@section Adding Methods to a Class +@cindex Categories + +Categories. +You can use this feature to add new methods to a class, but not to +change methods that have already been defined in the class implementation. +You can't add new instance variables (although I should include a +footnote that shows the hack for getting around this). + +@node Posing as a Superclass, Protocols of Messages, Adding Methods to a Class, Advanced Features +@section Posing as a Superclass +@cindex Posing + +Describe @samp{poseAs:}. +Changing Behavior of Inherited Methods. +Substituting a your new class for some old class. +You can use this to override methods that have already been defined in +the implementation of the old class. + +Use subclassing to override method behavior in new classes you write. +Use posing to override method behavior in preexisting subclasses of the +posed class. + +@node Protocols of Messages, Class initialization, Posing as a Superclass, Advanced Features +@section Defining a Message Protocol +@cindex Protocols +@cindex @@protocol + +@node Class initialization, Encoding Types, Protocols of Messages, Advanced Features +@section Class Initialization +@cindex @samp{+initialize} method + +Describe the @samp{+initialize} method. + +@node Encoding Types, Structure of an Object, Class initialization, Advanced Features +@section Encoding Types +@cindex @@encode + +@node Structure of an Object, Archiving, Encoding Types, Advanced Features +@section Obtaining the Structure of an Object +@cindex @@defs + +@node Archiving, , Structure of an Object, Advanced Features +@section Archiving Objects to a Stream +@cindex Archiving +@cindex Typed Stream + +@section ...potential for more here... + +@c ****************************************************************** +@node Builtin Classes, History and Comparisons, Advanced Features, Top +@chapter Builtin Classes + +@menu +* The Object Class:: +* The Protocol Class:: +@end menu + +@node The Object Class, The Protocol Class, Builtin Classes, Builtin Classes +@section The @samp{Object} Class + +@subsection Creating, Copying and Freeing + +@deftypemethod Object {} @keyword{+alloc} +@end deftypemethod + +@deftypemethod Object {} @keyword{+new} +@end deftypemethod + +@deftypemethod Object {} @keyword{-init} +@end deftypemethod + +@deftypemethod Object {} @keyword{-shallowCopy} +@end deftypemethod + +@deftypemethod Object {} @keyword{-deepCopy} +@end deftypemethod + +@deftypemethod Object {} @keyword{-deepen} +@end deftypemethod + +@deftypemethod Object {} @keyword{-copy} +@end deftypemethod + +@deftypemethod Object {} @keyword{-free} +@end deftypemethod + + +@subsection Identifying the Class + +@deftypemethod Object {(Class*)} @keyword{-class} +@end deftypemethod + +@deftypemethod Object {(const char *)} @keyword{-name} +@end deftypemethod + + +@subsection Identifying and Comparing the Instance + +@deftypemethod Object {} @keyword{-self} +@end deftypemethod + +@deftypemethod Object {(int)} @keyword{-hash} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-isEqual:} @var{anObject} +@end deftypemethod + +@deftypemethod Object {(int)} @keyword{-compare} @var{anObject} +@end deftypemethod + +@subsection Determining Object Type + +@deftypemethod Object {(BOOL)} @keyword{-isMetaClass} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-isClass} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-isInstance} +@end deftypemethod + +@subsection Determining Inheritance Relations + +@deftypemethod Object {(BOOL)} @keyword{-isKindOf:} (Class*)@var{aClassObj} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-isKindOfClassNamed:} (const char *)@var{aClassName} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-isMemberOf:} (Class*)@var{aClassObj} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-isMemberOfClassNamed:} (const char *)@var{aClassName} +@end deftypemethod + +@subsection Determining Messages Understood + +@deftypemethod Object {(BOOL)} @keyword{-instancesRespondTo:} (SEL)@var{aSel} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-respondsTo:} (SEL)@var{aSel} +@end deftypemethod + +@deftypemethod Object {(BOOL)} @keyword{-conformsTo:} (Protocol*)@var{aProtocolObj} +@end deftypemethod + +@subsection Method Lookup + +@subsection Sending Messages Determined at Runtime + +@subsection Forwarding + +@subsection Posing + +@subsection Enforcing Intentions + +@subsection Announcing Errors + +@subsection Archiving + +@deftypemethod Object {(int)} @keyword{+version} +<> +@end deftypemethod + +@deftypemethod Object {} @keyword{+setVersion:} (int)@var{aVersion} +<> +@end deftypemethod + +@deftypemethod Object {(int)} @keyword{+streamVersion:} (TypedStream*)@var{aStream} +<> +@end deftypemethod + +@deftypemethod Object {} @keyword{-write:} (TypedStream*)@var{aStream} +<> Returns self. +@end deftypemethod + +@deftypemethod Object {} @keyword{-read:} (TypedStream*)@var{aStream} +<> Returns self. +@end deftypemethod + + + +@c ****************************************************************** +@node The Protocol Class, , The Object Class, Builtin Classes +@section The @samp{Protocol} Class + +@deftypemethod Protocol {(const char *)} @keyword{-name} +@end deftypemethod + +@deftypemethod Protocol {(BOOL)} @keyword{-conformsTo:} (Protocol*)@var{aProtocolObj} +@end deftypemethod + +@deftypemethod Protocol {(struct objc_method_description *)} @keyword{-descriptionForInstanceMethod:} (SEL)@var{aSel} +@end deftypemethod + +@deftypemethod Protocol {(struct objc_method_description *)} @keyword{-descriptionForClassMethod:} (SEL)@var{aSel} +@end deftypemethod + + +@c ****************************************************************** +@node History and Comparisons, Runtime Internals, Builtin Classes, Top +@appendix Objective-C History and Comparisons + +@menu +* History of ObjC:: +* Smalltalk and ObjC:: +* C++ vs ObjC:: +* Other ObjC's:: +@end menu + +@node History of ObjC, Smalltalk and ObjC, History and Comparisons, History and Comparisons +@section History of Objective-C + +@node Smalltalk and ObjC, C++ vs ObjC, History of ObjC, History and Comparisons +@section Smalltalk and Objective-C + +@node C++ vs ObjC, Other ObjC's, Smalltalk and ObjC, History and Comparisons +@section Difference between Objective-C and C++ + +@node Other ObjC's, , C++ vs ObjC, History and Comparisons +@section Difference between GNU Objective-C and others + +@c ****************************************************************** +@node Runtime Internals, Hacking for Efficiency, History and Comparisons, Top +@appendix Runtime Internals + +Some notes on topics to be covered: +Data structures: Symtab, Module, IvarList, MethodList, Category. +Info bits. +Runtime class lookup. +Ivar lookup. +Method lookup. +version number. +IMP. +objc_class. +arglist_t. +sarray. + +@menu +* Method Lookup and Selectors:: +* Runtime Initialization:: +* Memory Management:: +* Metaclasses:: +* Archiving and Typed Streams:: +* Internal Hash Tables:: +@end menu + +@node Method Lookup and Selectors, Runtime Initialization, Runtime Internals, Runtime Internals +@section Method Lookup and Selectors +@cindex Method lookup +@cindex Selector + +objc_msg_lookup. message to self and super. + +@deftp {Data Type} IMP +The @code{IMP} data type is a pointer to the function implementing an +Objective-C method. +@end deftp + +@node Runtime Initialization, Memory Management, Method Lookup and Selectors, Runtime Internals +@section Runtime Initialization + +@node Memory Management, Metaclasses, Runtime Initialization, Runtime Internals +@section Memory Management + +class_create_instance, object_dispose, object_copy... + +For instance, @samp{Object}'s @samp{-alloc} method is implemented like +this: +@smallexample ++ alloc +@{ + return class_create_instance(self); +@} +@end smallexample + +@node Metaclasses, Archiving and Typed Streams, Memory Management, Runtime Internals +@section Metaclasses + +Move this to "Advanced Features"? I'm not sure we want to talk about it +as an implementation detail. + +@node Archiving and Typed Streams, Internal Hash Tables, Metaclasses, Runtime Internals +@section Archiving and Typed Streams +@cindex Archiving an object to a stream + +@node Internal Hash Tables, , Archiving and Typed Streams, Runtime Internals +@section Internal Hash Tables + + +@c ****************************************************************** +@node Hacking for Efficiency, Debugging ObjC, Runtime Internals, Top +@appendix Hacking for Efficiency + +@menu +* Address of a Method:: +* Address of an Ivar:: +@end menu + +@node Address of a Method, Address of an Ivar, Hacking for Efficiency, Hacking for Efficiency +@section Getting the Address of a Method + +@node Address of an Ivar, , Address of a Method, Hacking for Efficiency +@section Getting the Address of an Instance Variable + +@c ****************************************************************** +@node Debugging ObjC, Language Summary, Hacking for Efficiency, Top +@appendix Debugging Objective-C + +@c ****************************************************************** +@node Language Summary, Concept Index, Debugging ObjC, Top +@appendix Language Summary + +@menu +* Directives:: +* Declaring Methods:: +* Types and Keywords:: +* Formal Grammar:: +@end menu + +@node Directives, Declaring Methods, Language Summary, Language Summary +@section Directives + +@itemize +@item @@defs +@item @@encode +@item @@end +@item @@implementation +@item @@interface +@item @@protocol +@item @@public +@item @@selector +@end itemize + +@node Declaring Methods, Types and Keywords, Directives, Language Summary +@section Declaring Methods + +Difference between -,+. Return types of methods. Argument types of +methods. + +@node Types and Keywords, Formal Grammar, Declaring Methods, Language Summary +@section Types and Keywords + +BOOL, Class, id, IMP, SEL, STR. + +nil, Nil. + +@node Formal Grammar, , Types and Keywords, Language Summary +@section Formal Grammar of Objective-C + +@c ****************************************************************** +@node Concept Index, Function Index, Language Summary, Top +@unnumbered Concept Index +@printindex cp + +@c ****************************************************************** +@node Function Index, , Concept Index, Top +@unnumbered Function Index +@printindex fn + + +@bye