\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 Andrew Kachites 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 Andrew Kachites McCallum
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1994 Andrew Kachites 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}
<<Undocumented>>  
@end deftypemethod

@deftypemethod Object {} @keyword{+setVersion:} (int)@var{aVersion}
<<Undocumented>>  
@end deftypemethod

@deftypemethod Object {(int)} @keyword{+streamVersion:} (TypedStream*)@var{aStream}
<<Undocumented>>  
@end deftypemethod

@deftypemethod Object {} @keyword{-write:} (TypedStream*)@var{aStream}
<<Undocumented>>  Returns self.
@end deftypemethod

@deftypemethod Object {} @keyword{-read:} (TypedStream*)@var{aStream}
<<Undocumented>>  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 @bullet
@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