.\" @(#)preprocessor	1.4 12/8/92
.H1 "The Ptolemy Processor Language"
.pp
.IE ptlang
The Ptolemy preprocessor exists to make it easier to write and
document star
and galaxy class definitions to run under Ptolemy.  Instead of
writing all the initialization code required for a Ptolemy star,
the user can concentrate on writing the action code for a star
and let the preprocessor generate the standard initialization code
for portholes, states, etc.
The preprocessor also generates standardized documentation
to be included in the manual.
.pp
The Ptolemy preprocessor reads class definitions from an input file,
and generates one
.c .cc,
one
.c .h
and one
.c .t
file for each class defined.  By convention, only one class is defined
per file, and the filename is of the form
.c MyClass.pl
where
.c MyClass
is the name of the class to be defined (the dynamic linking code
in Pigi searches for filenames of this form, so you might as well consider it
mandatory to use this naming convention).
The
.c .t
file is troff source for documentation.
.pp
The preprocessor is written in Yacc and C.  It does not attempt to
parse the parts of the language that consist of C++ code (for example,
.c go()
methods); for these it simply counts curly braces to find the ends
of the items in question.  It outputs
.c #line
directives so the C++ compiler will print error messages, if any, with
respect to the original source file.
It also makes no attempt to parse information in the
.c explanation
directive, so arbitrary troff formatting commands can be inserted.
.pp
To make things clearer, let's
start with an example, a rectangular pulse star in the file
.c SDFRect.pl :
.(d
ident {
/*  Anything put here will appear verbatim in the .cc and .h files
    so please note that comments must be delimited, as done here.
    This feature is no longer used by the Ptolemy group; its use
    is deprecated.
*/
}
defstar {
	name { Rect }
	domain { SDF }
	desc {
Generates a rectangular pulse of height "height" (default 1.0).
with width "width" (default 8).
	}
	version {%\&W\&% %\&G\&%}
	author { J. T. Buck }
	copyright { 1991 The Regents of the University of California }
	location { SDF main library }
	explanation {
If needed, a longer explanation would go here.
	}
	defstate {
		name { height }
		type { float }
		default { 1.0 }
		desc { Height of the rectangular pulse. }
	}
	defstate {
		name { width }
		type { int }
		default { 8 }
		desc { Width of the rectangular pulse. }
	}
	defstate {
		name { count }
		type { int }
		default { 0 }
		desc { Internal counting state. }
		attributes { A_NONSETTABLE|A_NONCONSTANT }
	}
	output {		// the output port
		name { output }
		type { float }
		desc { The output pulse. }
	}
	go {			// the run-time function
		double t = 0.0;
		if (count < width) t = height;
		count = int(count) + 1;
		output%0 << t;
	}
}
.)d
.pp
Running the preprocessor on the above file produces the three files
.c SDFRect.h,
.c SDFRect.cc
and
.c SDFRect.t ;
the names are determined
.i not
by the input filename but by concatenating the domain and name
fields.
.pp
Three types of declarations may appear at the "top level" of a Ptolemy
language file: an
.c ident
section, a
.c defstar
section, or a
.c defgalaxy
section.  Any number of these may appear in the file,
although normally, it is preferable to separate each star
or galaxy definition into its own file.  For each
.c defstar
or
.c defgalaxy
section, three files are created, a
.c .h
file declaring the class, a
.c .cc
file implementing its methods, and a
.c .t
file documenting it.
The most recently seen
.IE ident
.c ident
section is inserted, uninterpreted, at the beginning of the
.c .h
and
.c .cc
files (the naming is
historical; this section was originally used to generate identifying
information in the output files, but it is no longer needed for
this purpose).
If it contains comments, they
should be valid C++ comments.  The
.IE defstar
.IE defgalaxy
.c defstar
and
.c defgalaxy
sections are themselves composed of subitems that define various
attributes of the star or galaxy.  All subitems are of the form
.sp
.i keyword " {"
.i stuff " }"
.sp
where the
.i stuff
may itself be composed of sub-sub-items, or may be C++ code (in which
case the Ptolemy language processor checks it only for balanced curly
braces).  Note that the keywords are
.i not
reserved words; they may also be used as identifiers.
