fc.doc						Last modified: 1986-12-15


			The FOOGOL-IV compiler
		   relese notes and documentation
			   Per Lindberg, QZ
                  The mad programmer strikes again!

NAME
	fc - foogol compiler

SYNOPSIS
	fc [ -d ] infile [ outfile ]

DESCRIPTION
	fc compiles a foogol program into VAX/UNIX assembly language.
	Default extentions are ".foo" for the source file and ".s"
	for the compiled file. In other words, the resulting outfile
	is is VAX/UNIX assembly language, and can be assebled and
	linked with the vanilla UNIX as and ld programs.

	Options: (There is only one switch so far...)

	-d	Sets the debug option, which makes the compiler print
		out internal diagnostics. Useful for debugging and
		understanding the compiler.

	The foogol object code has to be linked with the RTS (Run-Time
	system) and the C library in order to be able to do I/O.
	Example:
		fc foo
		as foo.s -o foo.o
		ld /lib/crt0.o rts.o foo.o -o foo -lc
	Or (shorter):
		fc foo
		cc rts.o foo.s -o foo

	The RTS (Run-Time System) should be compiled before it is
	linked with the foogol object code. It consists of just three
	output functions written in C:

	PRS(s) char *s; { printf("%s",s); }

	PRN(i) int i;   { printf("%d",i); }

	PR()            { putchar('\n');  }

	The foogol language is basically a very small ALGOL. The
	current syntactic elements are:

	PROGRAM ::=		begin
				[ DECLARATION ; ]
				STATEMENT [ ; STATEMENT ]...
				end

	DECLARATION	::=	integer ID_SEQUENCE

	ID_SEQUENCE	::=	IDENTIFIER [ , IDENTIFIER ]

	STATEMENT	::=	IO_STATEMENT
			!	WHILE_STATEMENT
			!	COND_STATEMENT
			!	BLOCK
			!	ASSIGN_STATEMENT

	BLOCK	    ::=		begin
				[ DECLARATION ]
				[ ; STATEMENT ]...
				end

	IO_STATEMENT	::=	prints ( STRING )
			!	printn ( EXPRESSION )
			!	print

	COND_STATEMENT	::=	if EXPRESSION then STATEMENT
				[ else STATEMENT ]

	WHILE_STATEMENT	::=	while EXPRESSION do STATEMENT

	ASSIGN_STATEMENT::=	IDENTIFIER := EXPRESSION

	EXPRESSION	::=	EXPR1 [ RHS ]

	RHS		::=	= EXPR1
			!	# EXPR1

	SIGNED_TERM	::=	+ TERM
			!	- TERM

	TERM		::=	PRIMARY [ * PRIMARY ]...

	PRIMARY		::=	IDENTIFIER
			!	NUMBER
			!	( EXPRESSION )

	EXPR1		::=	TERM [ SIGNED_TERM ]...

	IDENTIFIER	::=	<the usual thing, and no word reserved>

	NUMBER		::=	<the usual thing, unsigned integers>

	STRING		::=	<the usual thing>

	Example program:

	begin
	  integer n, div, sub, test, testcopy, found, max;
	  test := 2; max := 10; /* number of primes wanted */
	  while n # max do begin
	    div:= test-1; found:= 0;
	    while div-1 do begin
	      testcopy:= test; sub:= 0;
	      while testcopy do begin
	        sub:= sub+1; if sub = div then sub:= 0;
	        testcopy:= testcopy-1
	      end;
	      if sub = 0 then found:= 1;
	      div:= div-1
	    end;
	    if found = 0 then begin
	      n:= n+1;
	      printn(test); prints(" is prime number "); printn(n); print
	    end;
	    test:= test+1
	  end
	end

	The syntax is highly flexible, which means it might easily be
	changed due to some whim. The source code should be checked
	for details and changes before bugs are reported.

	The compiler is written by Per Lindberg, and placed in the
	public domain. The Hacker's Ethic applies. It is based on the
	VALGOL I compiler published by G.A. Edgar in Dr. Dobb's
	Journal May 1985. It was implemented for the purpouse of
	demonstrating how a simple compiler works. Therefore, there
	are no optimizations or other frills. You might want to add
	things to it; go right ahead. Happy hacking!

FILES
	fc.c	Source code for the foogol compiler
	fc	The foogol compiler
	rts.c	Source code for the Run-Time system
	rts.o	The Run-Time system
	fc.doc	This file
	bar.foo	Your program...

SEE ALSO
	as, ld, cc

BUGS
	There are no scoping rules, all declared variables can be used
	throughout the entire program. And although you can have local
	declarations in blocks, these declarations are in fact global.
	So you can't redeclare a variable.

	Because parsing is by simple recursive-descent and backtracking,
	there is only one cheerful error message: "Syntax error". No
	hints on missing or superflous semicolons or such hand-holding.
	You're supposed to write correct programs in foogol, Buster!

	The output code is extremely naive, and very suitable for
	code optimization exercises.

	Finally, please remember that this is just a 500-line toy
	compiler, so don't expect too much of it.