.TH HEADERS 1 "29 September 1992" "Demeter" "Demeter Software"
.SH NAME
headers \- header file generator for Demeter/C++
.SH SYNOPSIS
.I headers

.SH DESCRIPTION 
.I headers 
generates header files for those classes with methods defined
by users.  The file "cd-param-exp" is supposed to be notmod/cds.
The header files will be generated in the directory
called "notmod/headers".

.SH EXAMPLE

Its intended use is the
generation of header files containing method prototypes for
user-written code in Demeter environments.  All prototypes
for a given class are written to a single header file for
that class, named <classname>.h.  For example, the method:

.RS 5.0
int Foo::Pinch(char *a, int b) { 

.RS 5.0
cout << a[b] << \&"\en\&"; 
.br
cout << \&"Ouch!\en\&";
.RE

}
.RE

results in an appropriate prototype, such as:		

.RS 5.0
int Pinch(char a, int b);
.RE

to be written to
.I notmod/headers/Foo.h.

.I headers
checks time stamps to see whether it is necessary to scan all the C++
source files. You can force 
.I headers
to scan C++ source files by touching any C++ file. If there are no
updates to the existing header files, 
.I headers
will not touch them. All the updated header files will be printed on
the screen. If no file is printed, that means all header
files are up to date. 

.SH VIRTUAL FUNCTIONS AND CD-PARAM-EXP

If the method is attached to an Alternation class, the function
prototype will indicate that the method is 
.I virtual, 
unless
otherwise specified (see below).  Construction and Repetition class
methods have non-virtual methods, again, unless otherwise specified.
In order to determine whether a class is an Alternation, Construction,
or Repetition, 
.I headers 
must have access to the file 
.I notmod/cds/cd-param-exp 
in the upper directory.  This file is automatically
generated by
.I sem-check
of Demeter/C++ from a user-written class dictionary.  If a
method appears which is not in
.I notmod/cds/cd-param-exp, 
.I headers 
issues a warning, but generates a header file.

.SH OVERRIDING CLASS SCOPE, VIRTUAL DEFAULTS

By default, all methods are declared 
.I public
in the generated header file.  The user can override this default by 
indicating the class scope of a method in a special comment just 
preceding the method definition.  These override comments have the 
syntax:

.RS 5.0
//++ <keyword1> <keyword2> ...
.RE

where <keyword> may be any of the class scopes
.I public, private,
or
.I protected.
If more than one class scope appears in an override comment, a 
diagnostic is printed, and 
.I headers
aborts.

Similarly, the user may override the defaults for which methods 
become virtual, and which not.  In an override comment, the user
may use the keywords
.I virtual
or
.I non-virtual.
Use of more than one of these keywords in a given override comment
results in an error diagnostic.

Override comment keywords may be distributed over an arbitrary number
of lines:

.RS 5.0
//++ <keyword1> 
.br
//++ <keyword2>
.br
//++ ...
.RE

.SH PURE VIRTUAL FUNCTIONS

AT&T C++ version 2.0 or later supports the notion of uninstantiable
abstract classes.  Methods attached to abstract classes are deemed
"pure virtual", that is, without any code.  The code for such methods
is given in classes which inherit from the abstract.  Demeter users
can  indicate that a method is pure virtual by supplying an override
comment  with the keywords
.I pure
and 
.I virtual.
(Actually, 
.I pure
alone is sufficient.)  These keywords may be used in conjunction with 
class scope keywords, as described above.  

Since a pure virtual function has no body, the user must supply the 
prototype in an immediately following override comment.  Here is 
an example:

.RS 5.0
//++ pure protected virtual
.br
//++ Myclass *Bar::myMethod(int i)
.RE

which generates a prototype in
.I Bar.h:

.RS 5.0
Myclass *myMethod(int i) = 0;
.RE

.SH C++ DEFAULT ARGUMENTS

C++ allows users to specify default arguments for method arguments.
For an argument in a given position, a default may be specified only
if all arguments to the right have specified defaults.  
.I headers 
allows Demeter users to specify defaults by using the override comment
keyword
.I defaults,
followed by a list of arguments in parentheses:

.RS 5.0
//++ defaults  ( , , 0, init() )
.br
int Foo::yow(int a,int b, int c, Myclass *x ) {
.br
   ...
.br
}
.RE

Note that in this example, two of the arguments lack default values.
Defaults need not be constants, as shown for the rightmost argument.

.I headers

allows the user to indicate the types of parameters, as an option:

.RS 5.0
//++ defaults  ( , , int c = 0, Myclass *x = init() )
.br
int Foo::yow(int a,int b, int c    , Myclass *x ) {
.br
   ...
.br
}
.RE

The types are not checked, and so are provided solely as a 
notational convenience.

.SH STATIC FUNCTIONS

C++ allows users to specify static memeber functions. Demeter users
can  indicate that a method is static by supplying an override comment
with the keyword 
.I static.

.RS 5.0
//++ static
.br
int Foo::foo( ) {
.br
   ...
.br
}
.RE

.SH FRIEND FUNCTIONS

C++ allows users to specify friend functions for a class. Demeter users
can  indicate that a function is a friend of a class by supplying an
override comment with the keyword 
.I friend.

.RS 5.0
//++ friend Foo int foo( );
.RE

The example shows function
.I foo
is a friend of class
.I Foo.
You have to write then all in one line. This line is like a
declaration. You define the function
.I foo
somewhere else.


.SH INLINE FUNCTIONS

C++ allows users to specify inline memeber functions. Demeter users
can  indicate that a method is inline by supplying an override comment
with the keyword 
.I inline.

.RS 5.0
//++ inline
.br
//++ int Foo::foo1( ) {
.br
//++   ...
.br
//++ }
.br

.br
//++ inline
.br
//++ int Foo::foo2( ) {
.br
//++   ...
.br
//++ }
.RE

Notice that every line of a inline function should start with
.I //++.
Different inline function declaration blocks should be seperated by an
empty line.

.SH BUGS

Source code lines are limited to 1024 characters.
If a member function has no return type, you can not write,
for example,
.RS 5.0
#define One 1
.br
Victim::Victim()
.br
{
.br
}
.RE
.I headers
will generate "1 Victim(void);" in Victim.h.
You have to write
.RS 5.0
#define One 1
.br
//for the bug. This comment will drive it away.
.br
Victim::Victim()
.br
{
.br
}
.RE