---- B.A.L.L Language Specifications ----
* Version 2.1 (August 1 '08)
* Please send any bugs, complaints, comments, and suggestions
to the email you recieved this from, most likely to be bai.li.2005@gmail.com.

-What is BALL?

BALL stands for BaiSoft All-purpose List-oriented Language. It's a simple
language, slightly reminiscent of BASIC, and can be used for anything based
on console input and output. Well, not everything. Right now it's pretty limited,
actually. But I hope it will one day be as powerful as any other language. It's
written in Java so it can be run anywhere. BALL is an interpreted language, so the BALL
IDE (Integrated Development Environment) is the only software capable of running it.

-BALL sucks!

I agree, you might find that BALL sucks. In that case, please take the time to email
it's creator at bai.li.2005@gmail.com. Be specific about what you dislike about it and
it may be fixed.

-Known Bugs:
* Running two consoles at the same time will produce incorrect results. This is when you
press Run before it completes. You can, however, run as many BALL's as you want without
any problems.
* Version 1.x does not support the GUI console fully. Now it does.
* If you set it to File Console but click Cancel, you will not get any results. The output is redirected to sysout.
* On OS's other than Windows, closing BALL might throw an exception.

-Should I use the File console or the GUI console?

You can switch console modes by going to Help->Options. For most purposes, using the GUI
console is okay. However, for very long output, the GUI console will lag considerably.
In this case, you can redirect the output to a file. The file console does not support
input, beep, or clear.

-So, how do I run a program in BALL?

It's pretty simple actually. To run a program, load a text file by File->Open or typing
something into the text box. Then you click on the big button called Run. If there are
errors, they will pop up.


-Hello World

Let's start with a simple program, Hello World. Here it is:

write Hello *s World

That's it. The write command writes something to the console. You may notice that there's
no quotations. So to write a space, you write, *s. This is an Escape character. Other Escape
characters are:
*s -- space
*t -- tab
*n -- newline

Every instruction in BALL must be given on a new line. Every line may only contain 1
instruction. Word wrapping does not count as a new line. Other than that, you can put as
many spaces as you want between params.


-Comments

In BALL, any line that starts with ; is a comment. A comment is ignored by the interpreter
. Use comments to describe the code.
; this is a comment


-Variables

In BALL, there are two kinds of variables: Strings and Integers. Floating-point numbers
don't exist as of yet. A String is a series of characters, like "Hello World" or "Fk You".
An integer is any whole number, like 10 or -1337. BALL allows a maximum of 200 Strings and
300 Integers, which should be more than enough.

To declare a variable, you use the new command. Then you tell it if it's a string or a number.
Finally you give the variable a name. Like:

new string hello
new number Number_of_thingies_laycock_has

You can also tell BALL the value of your new variable by stating it immediately after. Like:

new string helloworld Hello *s World!
new number Number_of_thingies_laycock_has 3

After declaration, you must tell BALL that you're using the variable and not something else.
To print a number called counter, you write this:

write #counter *n

Remember, *n means new line. Because counter is a variable, you must precede it with a # symbol
. If counter was a string, you would preced it with the & symbol instead.
# -- if it's a number
& -- if it's a string

Numbers and Strings are represented differently so this is perfectly fine:

new string j hi
new number j 77
write &j *s #j

If after you declare a variable you want to change it, you use the set command.
The set command works like this:

set {variable being changed} {new value}

Suppose I wanted to change Number_of_thingies_laycock_has to 0. I would write this:

set #Number_of_thingies_laycock_has 0

To perform mathematical operations you do this:

; somenumber becomes 6x7
set #somenumber 6 * 7

; number becomes other
set #number #other

; othernumber gets multiplied by itself
set #othernumber #othernumber * #othernumber

; add 1 to counter
set #counter #counter + 1

; set hi to "Bye"
set &hi Bye

The {newvalue} can also be an expression: two objects seperated by an operator.
The operators are as follows:

+ addition
- subtraction
* multiplication
/ division
% remainder


-Loops and Goto

In BALL, there are 3 control mechanisms:
hereis
goto
if

To use goto, you must anchor the code pointer to a hereis tag. When you use goto
, the code jumps to wherever you put the hereis tag. Like this:

hereis wenli
write Sup *s Jason *n
goto wenli

This code would write "Sup Jason" infinately.

The if statement makes it possible to make finite loops. The if works like this:

if {expression} {goto}

The expression is 3 params seperated by spaces. The goto must be defined by a hereis tag.

In some languages you would write:

blah:
if(y == 0)
{
goto blah;
}

In BALL you would do this:

hereis blah
if #y = 0 blah

Here's a better example:

; Loop Example

; r is the number of times to repeat.
new number r 20

; c is the counter.
new number c 0

; r1 is inner loop constant
new number r1 1

; c2 is inner loop counter
new number c2 0

; outer loop
hereis loop
set #c #c + 1
goto innerloop
hereis back
write Hi *n
set #r1 #r1 + 1
set #c2 0
if #c < #r loop
goto end

; inner loop
hereis innerloop
set #c2 #c2 + 1
write -
if #c2 < #r1 innerloop
goto back

hereis end

Examine it. It prints:

-Hi
--Hi
---Hi
----Hi
-----Hi
------Hi
-------Hi
--------Hi
---------Hi
----------Hi
-----------Hi
------------Hi
-------------Hi
--------------Hi
---------------Hi
----------------Hi
-----------------Hi
------------------Hi
-------------------Hi
--------------------Hi

Don't put any variable declarations inside a loop, like 'new'. This often causes errors.

Most of them time, though, you would want the loop to end sometime or another.

The operators in if is a little bit different than most languages:

= -- equal
! -- not equal
< -- smaller than
<< -- smaller or equal to
> -- greater than
>> -- greater or equal to

You can compare Strings, but only for equality. You can write:

if &phrase1 = &phrase2 blah

But not:

if &phrase1 > &phrase2 blah


-The redef command

A relatively new addition to BALL is the redef command. This is to help create

obfuscated code(i.e. code that is hard to read). The redef command works like this:

redef write write2

Here's an interesting example:

redef ; baisoft
redef redef please
please beep right'now.
please write dude
dude come'on!
please dude --write'DUDE!!!
baisoft is pleased to confuse you.
right'now.
--write'DUDE!!! *s
please --write'DUDE!!! whatever,bye
whatever,bye dude

You can redefine any command, as well as the 'number' and 'string' keywords.


-Input, Delays, Beeps, and misc.
There is one way to input into a BALL program, the input command. The input command
works like this:

input {variable}
This stops the program until the user inputs something, after which it is stored into
a variable. Like this:

new string in
input &in

If you just want the user to press Enter for whatever reason, just write,

input

Your program may also require a delay, where you can write delay where you want:

write Hello
delay 2000
write *s World

This delays for 2000 milliseconds, or 2 seconds.

You can make it beep.

beep
; This emits a beep

Terminate the application:

end
; Terminates BALL

You can clear the console, or the file:

clear
; Clears the console


Examples:

---99beer.ball
; 99 Bottles Of Beer
; By BaiSoft
new number bottles 99

hereis repeat
write #bottles *s Bottles *s of *s beer *s on *s the *s wall,
delay 600
write *n #bottles *s Bottles *s of *s beer!! *n
delay 600
set #bottles #bottles - 1
write Take *s one *s down, *s pass *s it *s around, *n
delay 600
write That's *s #bottles *s Bottles *s of *s beer *s on *s the *s wall! *n *n
delay 600
if #bottles > 0 repeat

---counter.ball
new number rep 0
write Input *s A *s Number. *n
input #rep
new number counter 0
hereis repeat
set #counter #counter + 1
write #counter *n
delay 30
if #counter < #rep repeat

---primes.ball
; This one is rather complicated..
new number test 3
new number count 1
new string isprime yes
new number t 0
new number times 200

write Prime *s numbers *s up *s to: *n
input #times

hereis main
goto testcase
hereis 1
if &isprime = yes write
hereis 2
set #test #test + 1
set #count 1
set &isprime yes
if #test < #times main
goto end

hereis testcase
set #count #count + 1
if #count = #test 1
set #t #test % #count
if #t = 0 change
goto testcase

hereis change
set &isprime no
goto 1

hereis write
write #test *n
goto 2

hereis end


Copyright 2008 BaiSoft