ooce.html

Appendix C
Manual

This appendix contains UNIX manual pages describing the final version of ooc and some classes developed in this book.

C.1 Commands
munch — produce class list
nm p object... archive... | munch
munch reads a Berkeley-style nm(1) listing from standard input and produces as standard output a C source file defining a null-terminated array classes[] with pointers to the class functions found in each object and archive. The array is sorted by class function names.
A class function is any name that appears with type T and, preceded with an under- score, with type b, d, or s.
This is a hack to simplify retrieval programs. The compatible effect of option p in Berkeley and System V nm is quite a surprise.
Because HP/UX nm does not output static symbols, munch is not very useful on this system.

ooc — preprocessor for object-oriented coding in ANSI C
ooc [option ...] [report ...] description target ...
ooc is an awk program which reads class descriptions and performs the routine coding tasks necessary to do object-oriented coding in ANSI C. Code generated by ooc is controlled by reports which may be changed. This manual page describes the effects of the standard reports.
description is a class name. ooc loads a class description file with the name description.d and recursively class description files for all superclasses back to the root class. If h or r is specified as a target, a C header file for the public interface or the private representation of description is written to standard output. If source.dc or  is specified as a target, #include statements for the description header files are written to standard output and source.dc or standard input is read, preprocessed, and copied to standard output. If dc is specified as a target, a source skeleton for description is written to standard output, which contains all pos- sible methods.
The output is produced by report generation from standard report files. If file.rep is specified as a report, the standard files are not loaded.
There are some global options to control ooc:
Dname[=value]
defines value or an empty string as replacement for `name. The name
should be a single word. ooc predefines GNUC with value 0.
d
arranges for debugging to follow normal processing. Debugging com- mands are read from standard input: class.d loads a class description file; report.rep loads a report file; a description, report, class, or method name produces a dump of the appropriate information; and all, classes, descrip- tions, or reports dump all information in the respective category.
l
produces #line stamps as directed by the reports.
M
produces a makefile dependency line between each description and its superclass description files.
R
must be specified if the root class is processed. Other standard reports are loaded in this case.
Lexical Conventions
All input lines are processed as follows: first, a comment is removed; next, lines are glued together as long as they end with a backslash; finally, trailing white space is removed.
A comment extends from // to the end of a line. It is removed together with preceding white space before glueing takes place.
In glueing, the backslash marks the contact point and is removed. All white space around the contact point is replaced with a single space.
Identifiers significant to ooc follow the conventions of C, except that they may not use underscore characters. The underscore is used to avoid clashes between ooc’s and the user’s code.
Declarators significant to ooc are simplified relative to C. They may start with const and the type information must precede the name. The type information may use * but no parentheses. In general, an arbitrary declarator can be adapted for ooc by introducing a type name with typedef.
A line starting with %% acts as end of file.
Class Description File
The class description file has the following format:
header
% meta class {
components
%
methods with static linkage
%
methods with dynamic linkage
%+
class methods
%}
...
header is arbitrary information which is copied to standard output if the interface file is produced. Information following %prot is copied to standard output if the representation file is produced.
components are C structure component declarations with one declarator per line. They are copied into the struct generated in the representation file for the class. They also determine the order of the construction parameters for the root meta- class.
The first set of methods has static linkage, i.e., they are functions with at least one object as a parameter; the second set has dynamic linkage and has an object as a parameter for which the method is selected; the third set are class methods, i.e., they have a class as a parameter for which the method is selected. The selection object is always called self. The method declarations define C function headers, selectors, and information for the metaclass constructor.
The class header line % meta class { has one of three forms. The first form is used to introduce the root class only:
% meta class {
class is the root class, indicated by the fact that it has no superclass. The superclass is then defined to be the root class itself. meta should be intro- duced later as the root metaclass, indicated by the fact that it has itself as metaclass.
% meta class: super {
class is a new class with meta as its metaclass and super as its superclass. This would also be used to introduce the root metaclass, which has itself as metaclass and the root class as superclass. If super is undefined, ooc will recursively (but only once) load the class description file super.d and then super and meta must have been defined so that class can be defined. If this form of the class header is used, only methods with static linkage can be introduced.
% meta: supermeta class: super {
This additionally defines meta as a new metaclass with supermeta as its superclass. If super is undefined, ooc will recursively (but only once) load the class description file super.d and then super and supermeta must have been defined so that meta and class can be defined.
A method declaration line has the following form, where braces indicate zero or more occurrences and brackets indicate an optional item:
[ tag : ] declarator ( declarator { , declarator }[ , ... ] );
The optional tag is an identifier involved in locating a method with respondsTo(). The first declarator introduces the method name and result type, the remaining declarators introduce parameter names and types. Exactly one parameter name must be self to indicate the receiver of the method call.
A declarator is a simplified C declarator as described above, but there are two spe- cial cases:
_name
introduces name as the declarator name. The type is a pointer to an instance of the current class or to the class for which a dynamically linked method is overwritten. Such a pointer will be dereferenced by %casts as name within a method. Therefore, self must be introduced as _self, where self is the dereferenced object or class for class methods and _self is the raw pointer.
class @ name
introduces name as a pointer to an instance of class. Such a pointer will not be dereferenced but it will be checked by %casts.
The result type of a method can employ class @. In this case, the result type is generated as a pointer to a struct class which is useful when implementing methods, and which cannot be used other than for assignments to void * in appli- cation code. The result type should be void * for constructors and similar methods to emphasize the generic aspects of construction.
Preprocessing
Subject to the lexical conventions described above, an implementation file source.dc is copied to standard output. Lines starting with % are preprocessed as follows:
% class method {
This is replaced by a C function header for method; the header is declared static with the name class_method, unless method has static linkage. In the latter case, class is optional. ooc checks in all cases that the method can be specified for class. Function names are remembered as necessary for initialization of the description of class and the corresponding metaclass if any. There can be an optional tag preceding class unless method has static linkage.
%casts
This is replaced by definitions of local variables to securely dereference parameter pointers to objects in the current class. For statically linked methods this is followed by checks to verify the parameters pointing to objects of other classes. %casts should be used where local variables can be defined; for statically linked methods it must be the last definition. Note that null pointers flunk the checks and terminate the calling program.
%init
This should be near the end of the implementation file. If the description introduced a new metaclass, a constructor for the metaclass, selectors for the class, and initializations for the metaclass are generated. In either case, an initialization for the class is generated.
If a method m does not have static linkage, there are two selectors: m with the same parameters as the method selecting the method defined for self, and super_m with an explicit class description as an additional first parameter. The second selector is used to pass a method call to the superclass of the class where the method is defined.
If a dynamically linked or class method has a variable argument list, the selector passes va_list * app to the actual method.
If a selector recognizes that it cannot be applied to its object, it calls forward and passes its object, a pointer to a result area, or a null pointer, its own address, its name as a string, and its entire argument list. forward should be a dynamically linked method in the root class; it can be used to forward a message from one object to another.
Tags
respondsTo() is a method in the root class which takes an object and a tag, i.e., a C string containing an identifier, and returns either a null pointer or a selector which will accept the object and other parameters and call the method corresponding to the tag.
The tag under which a class or dynamically linked method can be found is defined as follows. The default is either the method name or tag in the method header in the class description file:
[ tag : ] declarator ( declarator { , declarator }[ , ... ] );
The method header in the implementation may overwrite the tag:
% mtag: class method {
The effective tag is mtag if specified, or tag if not. If mtag or tag is empty but the colon is specified, respondsTo() cannot find the method.
Report File
ooc uses report files containing all code fragments which ooc will generate. Names such as app for an argument list pointer can be changed in the report file. Only self is built into ooc itself.
A report file contains one or more reports. The usual lexical conventions apply. Each report is preceded by a line starting with % and containing the report name which may be enclosed by white space. The report name is arbitrary text but it must be unique.
A report consists of lines of words separated by single blanks or tabs, called spaces. An empty word results between any two adjacent spaces or if a space starts or ends a line.
An empty word, not at the beginning of an output line, is printed as a blank. In par- ticular, this means that two successive spaces in a report represent a single blank to be printed. Any word not starting with a back quote ` is printed as is.
A word starting with `% causes a report to be printed. The report name is the remainder of the word.
`#line followed by a word causes a line stamp to be printed if option l is specified; the phrase is ignored otherwise. If the word is a class, method, or class com- ponent name, the line stamp refers to its position in a class description file. Other- wise, and in particular for empty words, the line stamp refers to the current input file position.
A word starting with `{ starts a group. The group is terminated with a word starting with `}. All other words starting with a back quote ` are replaced during printing. Some replacements are globally defined, others are set up by certain groups. A table of replacements follows at the end of this section.
Groups are either loops over parts of the database collected by ooc or they are con- ditionals based on a comparison. Words inside a group are printed under control of the loop or the comparison. Afterwards, printing continues with the word following the group. Groups can be nested, but that may not make sense for some parts of the database. Here is a table of words starting a loop:
`{%	static methods for the current `class
`{%	dynamic methods for the current `class
`{%+	class methods for the current `class
`{()	parameters for the current `method
`{dcl	class headers in the `desc description file
`{pub	public lines in the `desc description file
`{prot	protected lines in the `desc description file
`{links class	dynamic and class methods defined for class
`{struct class	components for class
`{super	`desc and all its superclasses back to `root
A loop is terminated with a word starting with `}. If the terminating word is `}, in the loop over parameters, and if the loop will continue for more parameters, a comma followed by a blank is printed for this word. If the terminating word is `}n and if the group has produced any output, a newline is printed for this word. Otherwise, nothing is printed for termination.
A conditional group starts with `{if or `{ifnot followed by two words. The words are replaced if necessary and compared. If they are equal, the group starting with `{if is executed; if they are not equal, the group starting with `{ifnot is executed. If either group is not executed and if it is followed by a group starting with `{else, this group is executed. Otherwise the `{else group is skipped.
In general it is best if the `} terminating the `{if group immediately precedes `{else
on the same line of the report.
Here is a table of replaced words together with the events that set up the replace- ments:
set up globally
`	no text (empty string)
``	` (back quote)
`t	tab
`n	newline (limited to one blank line)
set up once class descriptions are loaded
`desc	last description from command line
`root	root class’ name
`metaroot	root’s metaclass name
set up for a class	% % %+ `{dcl `{prot `{pub `{super
`class	class’ name
`super	class’ superclass name
`meta	class’ metaclass name
`supermeta	metaclass’ superclass name
set up for a method                                   `{% `{% `{%+ `{links class
`method	method’s name
`result	method’s result type
`linkage	method’s linkage: %, %, or %+
`tag	method’s tag
`,...                                       , ... if variable arguments are declared, 
empty if not
`_last	last parameter’s name if variable arguments, 
undefined if not
set up for a declarator	`{() `{struct class
`name	name in declarator
`const	const followed by a blank, if so declared
`type	void * for objects, declared type otherwise
`_	_ if used in declaration, empty otherwise
`cast	object’s class name, empty otherwise
set up for lines from the description file	`{dcl `{prot `{pub
`class                             set up for a class description, empty otherwise
`line                                   line’s text if not class description, undefined otherwise
`newmeta                      1 if new metaclass is defined, 0 if not
A description on the command line of ooc sets up for a class. Requesting a method header in a source file sets up for a class and a method. The loops `{dcl, `{prot, and `{pub set up for lines from a class description file. The loops `{%, `{%, `{%+, and `{links class set up for a method. The loop `{() sets up for a parameter declara- tor. The loop `{struct class sets up for the declarator of a component of a class. The loop `{super runs from description through all its superclasses.
Environment
OOCPATH is a colon-separated list of paths. If a file name does not contain path delimiters, ooc looks for the file (class descriptions, sources, and report files) by prefixing each entry of OOCPATH to the required file name. By default, OOCPATH consists of the working directory and a standard place.
FILES              class.d	description for class 
class.dc	implementation for class
report.rep	report file
AWKPATH/ *.awk	modules
AWKPATH/ *.dbg	debugger modules
OOCPATH/ c.rep	implementation file reports OOCPATH/ dc.rep	implementation thunks report OOCPATH/ etc.rep	common reports
OOCPATH/ h.rep	interface file report
OOCPATH/ header.rep	common reports
OOCPATH/ m.rep	makefile dependency report OOCPATH/ r.rep	representation file reports OOCPATH/ va.rep	common reports
OOCPATH/ [chr]-R.rep	root class versions
The C preprocessor is applied to the output of ooc, not to the input, i.e., conditional compilation should not be applied to ooc controls.

C.2 Functions

retrieve — get object from file
void * retrieve (FILE * fp)
retrieve() returns an object read in from the input stream represented by fp. At end of file or in case of an error, retrieve() returns a null pointer.
retrieve() requires a sorted table of class function pointers that can be produced with munch(1). Once the class description has been located, retrieve() applies the method geto to an area obtained with allocate.
SEE ALSO	munch(1), Object(3)

C.3 Root Classes

intro — introduction to the root classes
Object	Class
Exception
Object(3) is the root class; Class(3) is the root metaclass. Most of the methods defined for Object are used in the standard reports for ooc(1), i.e., they cannot be changed without changing the reports.
Exception(3) manages a stack of exception handlers. This class is not mandatory for working with ooc.
Class Class: Object - root metaclass
Object
Class
new(Class(), name, superclass, size, selector, tag, method, ... , 0); 
Object @ allocate (const self)
const Class @ super (const self) 
const char * nameOf (const self)
A metaclass object describes a class, i.e., it contains the class name, a pointer to the class’ super class description, the size of an object in the class, and information about all dynamically linked methods which can be applied to objects of the class. This information consists of a pointer to the selector function, a tag string for the respondsTo method (which may be empty), and a pointer to the actual method function for objects of the class.
A metaclass is a collection of metaclass objects which all contain the same variety of method informations, where, of course, each metaclass object may point to dif- ferent methods. A metaclass description describes a metaclass.
Class is the root metaclass. There is a metaclass object Class which describes the metaclass Class. Every other metaclass X is described by some other metaclass object X which is a member of Class.
The metaclass Class contains a metaclass object Object which describes the root class Object. A new class Y, which has the same dynamically bound methods as the class Object, is described by a metaclass object Y, which is a member of Class.
A new class Z, which has more dynamically bound methods than Object, requires a metaclass object Z, which is a member of a new metaclass M. This new metaclass has a metaclass description M, which is a member of Class.
The Class constructor is used to build new class description objects like Y and metaclass description objects like M. The M constructor is used to build new class description objects like Z. The Y constructor builds objects which are members of class Y, and the Z constructor builds objects in class Z.
allocate reserves memory for an object of its argument class and installs this class as the class description pointer. Unless overwritten, new calls allocate and applies ctor to the result. retrieve calls allocate and applies geto to the result.
super returns the superclass from a class description.
nameOf returns the name from a class description.
The Class constructor ctor handles method inheritance. Only information about overwritten methods needs to be passed to new. The information consists of the address of the selector to locate the method, a tag string which may be empty, and the address of the new method. The method information tuples may appear in any order of methods; zero in place of a selector terminates the list.
delete, dtor, and geto are inoperative for class descriptions.
Class descriptions are only accessed by means of functions which initialize the description during the first call.
SEE ALSO	ooc(1), retrieve(2)

Class Exception: Object — manage a stack of exception handlers
Object
Exception 
new(Exception());
int catch (self)
void cause (int number)
Exception is a class for managing a stack of exception handlers. After it is armed with catch, the newest Exception object can receive a nonzero exception number sent with cause().
ctor pushes the new Exception object onto the global exception stack, dtor
removes it. These calls must be balanced.
catch arms its object for receiving an exception number. Once the number is sent, catch will return it. This function is implemented as a macro with setjmp(3) and is subject to the same restrictions; in particular, the function containing the call to catch must still be active when the exception number is sent.
Other methods should generally not be applied to an Exception object.
SEE ALSO	setjmp(3)

Class Object — root class
Object
Class
new(Object());
typedef void (* Method) ();
const void * classOf (const self) 
size_t sizeOf (const self)
int isA (const self, const Class @ class) 
int isOf (const self, const Class @ class)
void * cast (const Class @ class, const self) 
Method respondsTo (const self, const char * tag)
%
void * ctor (self, va_list * app) void delete (self)
void * dtor (self)
int puto (const self, FILE * fp) 
void * geto (self, FILE * fp)
void forward (self, void * result, Method selector, const char * name, ...)
%+
Object @ new (const self, ...)

Object is the root class; all classes and metaclasses have Object as their ultimate superclass. Metaclasses have Class as their penultimate superclass.
classOf returns the class description of an object; sizeOf returns the size in bytes.
isA returns true if an object is described by a specific class description, i.e., if it belongs to that class. isA is false for null pointers. isOf returns true, if an object belongs to a specific class or has it as a superclass. isOf is false for null pointers and true for any object and the class Object.
cast checks if its second argument is described, directly or ultimately, by the first. If not, and in particular for null pointers, the calling program is terminated. cast nor- mally returns its second argument unchanged; for efficiency, cast could be replaced by a macro.
respondsTo returns zero or a method selector corresponding to a tag for some object. If the result is not null, the object with other arguments as appropriate can be passed to this selector.
ctor is the constructor. It receives the additional arguments from new. It should first call super_ctor, which may use up part of the argument list, and then handle its own initialization from the rest of the argument list.
Unless overwritten, delete destroys an object by calling dtor and sending the result to free(3). Null pointers may not be passed to delete.
dtor is responsible for reclaiming resources acquired by the object. It will normally call super_dtor and let it determine its result. If a null pointer is returned, delete will effectively not reclaim the space for the object.
puto writes an ASCII representation of an object to a stream. It will normally call puto for the superclass so that the output starts with the class name. The representation must be designed so that geto can retrieve all but the class name from the stream and place the information into the area passed as first argument. geto works just like ctor and will normally let the superclass geto handle the part written by the superclass puto.
forward is called by a selector if it cannot be applied to an object. The method can be overwritten to forward messages.
Unless overwritten, new calls allocate and passes the result to ctor together with its remaining arguments.
SEE ALSO	ooc(1), retrieve(2), Class(3)









intro — introduction to the calculator application
Objct	Class
Event
Ic	IcClass
Button Calc Crt
CButton CLineOut
LineOut Mux
List	ListClass
Xt
XawBox 
XawCommand
XButton 
XawForm 
XawLabel
XLineOut 
XtApplicationShell
Object(3) is the root class. Object needs to be renamed as Objct because the ori- ginal name is used by X11.
Event(4) is a class to represent input data such as key presses or mouse clicks.
Ic(4) is the base class to represent objects that can receive, process, and send events. Button converts incoming events to events with definite text values. Calc processes texts and sends a result on. LineOut displays an incoming text. Mux tries to send an incoming event to one of several objects.
Crt(4) is a class to work with the curses terminal screen function package. It sends position events for a cursor and text events for other key presses. CButton imple- ments Button on a curses screen. CLineOut implements LineOut.
List manages a list of objects and is taken from chapter 7.
Xt(4) is a class to work with the X Toolkit. The subclasses wrap toolkit and Athena widgets. XButton implements a Button with a Command widget. XLineOut implements a LineOut with a Label widget.
SEE ALSO                       curses(3), X(1)


IcClass Crt: Ic — input/output objects for curses
Objct 
Ic
Crt
CButton 
CLineout
new(Crt());
new(CButton(), "text", y, x);
new(CLineOut(), y, x, len);
void makeWindow (self, int rows, int cols, int x, int y) 
void addStr (self, int y, int x, const char * s)
void crtBox (self)
A Crt object wraps a curses(3) window. curses is initialized when the first Crt
object is created.
Crt_gate() is the event loop: it monitors the keyboard; it implements a vi-style cur- sor move for the keys hjkl, and possibly, for the arrow keys; if return is pressed, it sends an Event object with kind 1 and an array with column and row position; if control-D is pressed, gate returns reject; any other key is sent on as an Event object with a string containing the key character.
A CLineOut object implements a LineOut object on a curses screen. Incoming strings should not exceed len bytes.
A CButton object implements a Button object on a curses screen. If it receives a matching text, it sends it. Additionally, if it receives a position event, e.g., from a Crt object, and if the coordinates are within its window, it sends its text on.
SEE ALSO	Event(4)

Class Event: Objct — input item
Objct
Event
new(Event(), kind, data); 
int kind (self)
void * data (self)
An Event object represents an input item such as a piece of text, a mouse click, etc.
kind is zero if data is a static string. kind is not zero if data is a pointer. In particu- lar, a mouse click can be represented with kind 1 and data pointing to an array with two integer coordinates.
SEE ALSO	Ic(4)
IcClass: Class Ic: Objct — basic input/output/transput objects
Objct
Ic
Button 
Calc 
LineOut 
Mux
new(Ic()); new(Button(), "text"); 
new(Calc());
new(LineOut());
new(Mux());
%
void wire (Objct @ to, self)
enum { reject, accept } gate (self, const void * item)
An Ic object has an output pin and an input action. wire() connects the output to some other object. If an Ic object is sent a data item with gate(), it will perform some action and send some result to its output pin; some Ic objects only create output and others only consume input. gate() returns accept if the receiver accepts the data.
Ic is a base class. Subclasses overwrite gate() to implement their own processing. Ic_gate() takes item and uses gate() to send it on to the output pin, i.e., a subclass will use super_gate() to send something to its output pin.
A Button object contains a text which is sent out in response to certain inputs. It expects an Event object as input. If the Event contains a matching text or a null pointer or other data, the Button accepts the input and sends its own text on. A non-matching text is rejected.
Button is designed as a base class. Subclasses should match mouse positions, etc., and use super_gate() to send out the appropriate text.
A Calc object receives a string, computes a result, and sends the current result on as a string. The first character of the input string is processed: digits are assem- bled into a non-negative decimal number; +, , *, and / perform arithmetic opera- tions on two operands; = completes an arithmetic operation; C resets the calculator; and Q quits the application. The calculator is a simple, precedence-free, finite state machine: the first set of digits defines a first operand; the first operator is saved; more digits define another operand; if another operator is received, the saved operator is executed and the new operator is saved. Invalid inputs are accepted and silently ignored.
A LineOut object accepts a string and displays it.
A Mux object can be wired to a list of outputs. It sends its input to each of these outputs until one of them accepts the input. The list is built and searched in order of the wire() calls.
SEE ALSO	Crt(4), Event(4), Xt(4)
Class Xt: Object — input/output objects for X11
Objct
Xt
XawBox 
XawCommand
XButton 
XawForm 
XawLabel
XLineOut 
XtApplicationShell
new(Xt());
new(XtApplicationShell(), & argc, argv);
 new(XawBox(), parent, "name"); 
new(XawCommand(), parent, "name"); 
new(XawForm(), parent, "name"); 
new(XawLabel(), parent, "name"); 
new(XButton(), parent, "name", "label");
new(XLineOut(), parent, "name", "label");
void * makeWidget (self, WidgetClass wc, va_list * app) 
void addAllAccelerators (self)
void setLabel (self, const char * label)
void addCallback (self, XtCallbackProc fun, XtPointer data) 
void mainLoop (self)
An Xt object wraps a widget from the X toolkit. makeWidget() is used to create
and install the widget in the hierarchy; it takes a parent Xt object and a widget name from the argument list pointer to which app points. addAllAccelerators() is used to install the accelerators below the Xt object. setLabel() sets the label resource. addCallback() adds a callback function to the callback list.
An XtApplicationShell object wraps an application shell widget from the X toolkit. When it is created, the shell widget is also created and X toolkit options are removed from the main program argument list passed to new(). The application main loop is mainLoop().
XawBox, XawCommand, XawForm, and XawLabel objects wrap the correspond- ing Athena widgets. When they are created, the widgets are also created. setLa- bel() is accepted by XawCommand and XawLabel. A callback function can be registered with an XawCommand object by addCallback().
An XButton object is a Button object implemented with an XawCommand object. It forwards wire() to its internal Button object and it sets a callback to gate() to this button so that it sends its text on if notify() is executed, i.e., if the button is clicked. Accelerators can be used to arrange for other calls to notify().
An XLineOut object is a LineOut object implemented with an XawLabel object. It forwards gate() to itself to receive and display a string. If permitted by the parent widget, its widget will change its size according to the string.
SEE ALSO	Event(4)