Why not a compiler? by Y [05-04-00] or later
Version 0.06 alpha, built [23-06-00]
Copyright (c) 1997-2000 YALLIE, Inc. All Rights Reserved.

Dedicated to Diana ;)



Opening words
-------------
Hello everybody interested in compilers, syntax analysis and code
generation. Look at this project - why not a compiler? ;)


What is Why?
------------
Why is a general purpose programming language, similar to Forth. I just
took the base concepts, throw out all the stuff that didn't seem to be
nice (on my opinion), added some extensions and tried to implement the
ideas with the syntax closest to Forth.
The Why compiler produces fast and stable (I hope) 32-bit code for
extended DOS (DOW4GW, PMODEW, DOS32A, etc). It can also be moved to
YaOS, Linux, Win32 and (virtually) any other 32-bit environment. I don't
have time to do it, but you may help me ;)
The Why compiler is available for free with the complete TPascal source
code.  Why didn't I wrote it in C++? Hmm... I don't know really. Another
compiler of mine (it's not ready at the moment) is written in pretty
portable C++, but Why is written in Pascal. At last, why not?


Legal
-----
The Why compiler, its source code and run-time libraries is NOT a public
domain software. It is copyrighted freeware distributed under the terms of
GNU General Public License. The Why compiler run-time libraries are
distributed under the terms of GNU Library General Public License rather
than GNU GPL. See copying and copying.lib for details.
The Why compiler is distributed in the hope it will be useful, but with
no warranty or whatsoever. In no event will the author be liable of any
damage resulted from the using or misusing of it.
The entire risk is on your own.


Basic concepts
--------------
Like Forth, Why language is stack-oriented. Why program can work with two
stacks: arithmetic stack (astack for short) and return stack (rstack).
All data to work with can be put to or taken from the astack top. Rstack
can also be used for such operations, but this is not a recommended style.

Example:
123 PutNumber

In the example above, 123 is integer constant and PutNumber is a pro-
cedure call. 123 pushed onto the astack, then PutNumber is called.
PutNumber takes the top element from astack and displays it. After those
operations astack will remain the same.
PutNumber is a procedure because it does not return any value. Functions
are called and declared in exactly the same way as a procedures, and the
only difference is that the function puts it returns value (or values)
to the astack top. Function can return any number of values of any type
supported by Why language.
Like Forth, Why procedure/function definitions start with ":" and end
with ";" characters.
Here is the simple example of a function declaration and usage:

: Sum ( a b -> a+b )
  +
;

: Main
  2 3 Sum PutNumber
;

The above example will display 5. 2 and 3 are pushed, then Sum is called.
Sum performs + operation which takes two integer values from astack and
puts their sum instead.
The Why program is a number of definitions. Every definition describes a
procedure or a function. Program begins its execution by calling function
Main, like in C or C++. Unlike C, Why language is case insensitive, so
Main is equal to main, MAIN and so on.
Here is "Hello, World!" program example.

( hello.why by Y [11-05-00] )

: Main
  "Hello, World!" Puts
;

Why compiler cannot perform any type checking and so on, and the whole
process is controlled by a programmer. This is because of the language
itself: the astack cannot be controlled at compile time.
Many odd-looking things can be written according to Why concepts. The
example below just displays "Hello there again":

"again\r\n" "there " "Hello " Put Put Put

You can also write, for example, "Hello" PutNumber, and the compiler will
not warn you because it can't check type of parameters accepted by
PutNumber procedure. The program will just display an address of "Hello"
string constant.


Why language grammar
--------------------

Program ::= [ Imports ] { GlobalVariableDefinition | Definition }

Imports ::= "imports" { Identifier }

GlobalVariableDefinition ::= TypeName { Identifier [ "["
  IntegerConstant "]" ] } ";"

TypeName ::= "int" | "string";

Definition ::= ":" Identifier Sequence ";"

Sequence ::= { Element }

Element ::= Constant | Operation | ProcedureCall | VariableDefinition |
  Variable | BeginStatement | DoLoopStatement | DowntoLoopStatement |
  IfStatement | InlineStatement | SimpleStatement | ToLoopStatement |
  Pragma

Operation ::= "+" | "-" | "*" | "/" | "%" | ">" | "<" | ">=" | "<=" |
  "<>" | "!=" | "==" | "||" | "&&" | "!" | "|" | "&" | "~" | "<-" |
  "->" | "<." | ".>" | "[]" | "++" | "--" | "<<" | ">>" | <+> | <-> |
  <*> | </> | <%> | <++> | <-->

ProcedureCall ::= Identifier;

VariableDefinition ::= TypeName { Identifier [ "["
  IntegerConstant "]" ] } ";"

BeginStatement ::= "begin" Sequence ( "until" | "while" Sequence "repeat" )

DoLoopStatement ::= "do" Sequence "loop"

DowntoLoopStatement ::= "downto" Sequence "loop"

IfStatement ::= "if" Sequence [ "else" Sequence ] "then"

InlineStatement ::= "inline" { IntegerConstant } ";"

SimpleStatement ::= "drop" | "dup" | "rot" | "swap"

ToLoopStatement ::= "to" Sequence "loop"

Pragma ::= "pragma" { Setting } ";"

Setting ::= Identifier StringConstant


Why compiler accepts four different types of commens:

block:  (Forth-like)
block:  /* C-like */
line:   \ Forth-like
line:   // C++-like


Why run-time library
--------------------
The Why RTL is not finished at the moment. It uses Tran's PMC library,
pmc.lib, which is not directly called from why programs because of C
calling conventions. Why startup code included in this release,
w0d32f.asm, is for extended DOS only. It contains some portions from
Tran's PMC startup code.
Here is a list of all routines in the Why run-time library:

Standard procedures: nDup, nDrop, nRot, nSwap, xStacks, AtoR, RtoA,
  Extract, nExtract, Abs, Sign, UpCase, LoCase, Random, Str, StrHex, Val

Standard I/O routines: Put, Puts, PutChar, NewLine, PutNumber, PutHexNumber,
  Gets, GetNumber

PMC thunks: Malloc, Realloc, Free


Why compiler optimization features
----------------------------------
This version of Why compiler tries to perform simple machine code
optimization. Some astack top values can be stored in certain CPU registers
and so accessed much faster. I call this stuff "cache".
Cache can contain 0 to 5 registers (eax, ebx, ecx, edx, edi) in any order.
Drop, rot and swap statements may be executed at compile time: they will
just swap registers in the cache. Cache is flushed before any routine is
called (when cache if flushed, all registers are written to astack), so
the routine works with astack as usual.
Another optimization level is a constant optimization. Look at the example
below:

1 2 + 4 * PutNumber

When operations are performed on integer constants, it is possible to
calculate the result at compile time. For this example, the current version
of Why compiler will produce the same machine code as for

12 PutNumber

This optimization can also speed up some conditional and loop statements.
For example, "0 if ... then" will never execute "if" part, so the compiler
can produce unconditional JMP to the statement after "then" (and it does
actually ;). The same goes for loops like "1 5 to ... loop" (1 > 5, so the
loop body will never be executed).


Why language samples
--------------------
Go to Samples directory and learn all *.why files. This should be enough
for anybody who uses at least one programming language... Those who
can't figure out something may contact me (see addresses below).


Why compiler usage
------------------
The compiler itself is called why.exe. The only command line parameter
accepted is a Why source file name:

why.exe <source.why>

The default extension for the source file is "why".
The compiler produces two assembly files with the same name as a source
plus "asm" and "inc" extensions.
Warning! Any of those files (if exist) will be silently overwritten without
an alarm.
You can also use whymake utility (whymak32.exe) to build Why programs.
Whymake is a simple compile and link driver for Why programs. For example,
to build hello.why, just type: "whymak32 hello.why" - and you will get an
exe file, "hello.exe". To make demo19.why (which imports graph.why and
keyboard.why), type "whymak32 demo19 graph keyboard".
If you don't want to rebuild graph and keyboard modules, specify ".obj"
extensions for them. Whymake will only compile demo19.why, and all other
modules will not be rebuilt: "whymak32 demo19.why graph.obj keyboard.obj".


System requirements
-------------------
Why compiler and the software created with it will run on any IBM PC/AT
compatible machine with 386 or better CPU with at least 1 MB of RAM,
VGA video adapter and 1MB or more free hard disk space. Pentium (tm) with
8MB and SVGA board is recommended. Note that I didn't tested anything with
such configuration, I just think it should be enough. I wrote the stuff on
Celeron 466 MHz, 64MB RAM, with 10G Quantum Fireball, so the compilation
speed was not the first goal of mine.
To compile, run and debug Why programs you will also need:

o TASM (I tested versions 4.1 and 5.2)
o Tran's PMC library (version 1.01)
o WLINK (WATCOM Linker, version 11.0).
o DOS4G/W or compatible extender (DOS4G/W 1.97, PMODE/W 1.33 etc)
o WD (WATCOM Debugger, version 11.0)

To get started and to test whether the compiler works correctly, unpack all
archives to the new directory and run demo.bat. This will compile and run
a demo program (needs VGA or SVGA board).


Rebuilding the compiler
-----------------------
To rebuild the Why compiler you need Turbo Pascal 7.0 or compatible
compiler. Learn build.bat for more information. It's the shortest source
file in the current directory ;)


Notes, ideas, todo items, etc
-----------------------------
See todo.txt for todo items. See done.txt to learn what todo items
are already done.


Closing words
-------------
I would like to thank all people who didn't disturb me during my work on
this project. The Why compiler is [almost] complete now, so you can
contact me to receive all additional info you need. Send me e-mail to the
one of the following addresses:


Contact info
------------
e-mail:                 yallie@yandex.ru        (preferred)
                        yallie@mail.ru
icq:                    67654811


Related Web sites
-----------------
http://yallie.narod.ru  My homepage


Y [05-04-00] or later