## The Eight Bit Algorithmic Language for Apple II, Commodore 64 and VIC 20
### What is EightBall?
EightBall is an interpreter for a novel structured programming language. It runs on a number of 6502-based vintage systems and may also be compiled as a 32 bit Linux executable.
### Design Philosophy
EightBall tries to form a balance of the following qualities, in 20K or so of 6502 code:
* Statically typed
* Provides facilities which encourage structured programming ...
* ... Yet makes it easy to fiddle with hardware (PEEK and POKE and bit twiddling)
* Keep the language as simple and small as possible ...
* ... While providing powerful language primitives and encapsulation in subroutines, allowing the language to be extended by writing EightBall routines
* When in doubt, do it in a similar way to C!
EightBall resembles an interpreted C.
### Supported Systems
The following 6502-based systems are currently supported:
* Apple II - EightBall runs under ProDOS and uses upper/lowercase text. It should run on 64K Apple IIe, IIc or IIgs. It can probably run on Apple II/II+ with an 80 column code, but this has not been tested.
* Commodore 64 - EightBall should run on any C64.
* Commodore VIC-20 - EightBall runs on a VIC-20 with 32K of additional RAM.
### Getting Started
There are executables and disk images available to download for Apple II, Commodore 64 and VIC-20. These may be run on real hardware or one of the many emulators that are available.
The language itself is documented in these wiki pages. The best way to learn is to study example programs.
### Build Toolchain
I am building EightBall using cc65 v2.15 on Ubuntu Linux. Please let me know if you need help with compilation.
The Linux version of EightBall is currently being built using gcc 6.3.0.
EightBall allows named subroutines to be defined, for example:
sub myFirstSubroutine()
pr.msg "Hello"; pr.nl
endsub
All subroutines must end with `endsub` statement.
A subroutine may have more than one `return` statement returning a numeric value:
sub mySecondSubroutine()
return 2
endsub
If the flow of execution hits the `endsub` then 0 is returned to the caller.
### Simple Subroutine Invocation
The subroutine above can be called as follows:
call myFirstSubroutine()
When `myFirstSubroutine` hits a `return` statement, the flow of execution will return to the statement immediately following the `call`.
### Local Variables
Each subroutine has its own local variable scope. If a local variable is declared with the same name as a global variable, the global will not be available within the scope of the subroutine. When the subroutine returns, the local variables are destroyed.
sub myThirdSubroutine()
word w[10] = 0; ' Local array
endsub
### Argument Passing
Subroutines may take `byte` or `word` arguments, using the following syntax:
sub withArgs(byte flag, word val1, word val2)
' Do stuff
return 0
endsub
This could be called as follows:
word ww = 0; byte b = 0;
call withArgs(b, ww, ww+10)
When `withArgs` runs, the expression passed as the first argument (`b`) will be evaluated and the value assigned to the first formal argument `flag`, which will be created in the subroutine's local scope. Similarly, the second argument (`ww`) will be evaluated and the result assigned to `val1`. Finally, `ww+10` will be evaluated and assigned to `val2`.
Argument passing is by value, which means that `withArgs` can modify `flag`, `val1` or `val2` freely without the changes being visible to the caller.
### Function Invocation
Subroutines may be invoked within an expression. For example, the following subroutine:
sub adder(word a, word b)
return a+b
endsub
Could be used in an expression like this:
pr.dec adder(10, 5); ' Prints 15
Functions may invoke themselves recursively (but you will run out of stack quite fast!)
### Passing by Reference
Passing by reference allows a subroutine to modify a value passed to it. EightBall does this using pointers, in a manner that will be familiar to C programmers. Here is `adder` implemented using this pattern:
sub adder(word a, word b, word resptr)
*resptr = a+b
endsub
Then to call it:
word result
call adder(10, 20, &result)
This code takes the address of variable `result` using the ampersand operator and passes it to subroutine `adder` as `resptr`. The subroutine then uses the star operator to write the result of the addition of the first two arguments (10 + 20 in this example) to the word pointed to by `resptr`.
Unlike C, there are no special pointer types. Pointers must be stored in a `word` variable, since they do not fit in a `byte`.
### Passing an Array by Reference
**Warning: This is currently not implemented in the compiler, only the interpreter.**
It is frequently useful to pass an array into a subroutine. It is not very useful to use pass by value for arrays, since this may mean copying a large object onto the stack. For these reasons, EightBall implements a special pass by reference mode for array variables, which operates in a manner similar to C.
Here is an example of a function which takes a regular variable and an array:
sub clearArray(byte arr[], word sz)
word i = 0
for i = 0 : sz-1
arr[i] = 0
endfor
endsub
This may be invoked like this:
word n = 10
byte A[n] = 99
call clearArray(A, n)
Note that the size of the array is not specified in the subroutine definition - any size array may be passed. Note also that the corresponding argument in the `call` is simply the array name (no [] or other annotation is permitted.)
This mechanism effectively passes a pointer to the array contents 'behind the scenes'.
### End Statement
The `end` statement marks the normal end of execution. This is often used to stop the flow of execution running off the end of the main program and into the subroutines (which causes an error):
