|
|
|
|
| What is the purpose of these Docs? |
|
The KoolB BASIC language is very similar to Rapid-Q, which is similar to QBasic, so if you are familar with either, you should do quite fine with KoolB. However, there may be some differences, so I will explain the KoolB BASIC dialect here. Also, this would be a good place for those with no BASIC experience to learn from.
|
|
| What is the BASIC language? |
|
The traditional BASIC language was nearly always interpreted. KoolB differs in that it actually compiles the BASIC into native executables. KoolB follows most of the BASIC rules regard the language syntax, however. KoolB is line based, meaning that each single command is on its own line. To put multiple commands on one line, you need to separate the commands by a colon. For example:
Cls : A# = 1 : B$ = "Hello"
So what happens if your command is really long and you want to split it up over multiple lines? Easy, you just put an an underscore at the end of the line and put the rest of the command on the next line. For example:
A# = 1 + 4 ^ 4 - 32 * _
4.567 MOD 2
|
|
| What data types can I use with KoolB? |
|
KoolB supports three different simple data types: Integer, Double, and String. Integer is a 4 byte number that is strictly positive and negative whole numbers. Any decimal part is rounded off to the nearest whole number. Double is an 8 byte number with decimal capabilities. Because it gets converted so much during processing, it might sometimes be off by a few thousandsths. String very similar to a C-string where you just have a bunch of bytes in a row followed by a zero byte at the end (null-terminated). Strings are dynamically allocated and resized and can be up to 2 GB in length. To create one of these simple data types, just use the Dim statement, which follows the following syntax:
Dim <Name> As <Data Type>
<Name> can be an word starting with a letter of the alphabet and containing letters, numbers, or the &, #, or $ symbols at the end of the word (to represent Intetger, Double, or String data types, respectively).
<Data Type> can be Integer, Double, or String
Alternatively, you can create variables on the fly by just attaching the symbol to the end. For example:
<Name<Symbol>> = <Expression>
For example:
PI# = 3.14
Message$ = "Please enter your user name:"
Index& = 1
|
|
|
|
If you do not put the symbol at the end, KoolB will report an error (unlike Rapid-Q). Also, you CANNOT use an undeclared variable in an expression (because it would result in a zero number or an empty string).
So the following example is INCORRECT:
PI# = 1 + UndeclaredVariable#
This is just to protect you from mistakes. Also, it serves no purpose to use an undeclared variable in an expression. You could just as easily substitute 0 or "" instead.
|
|
|
KoolB supports only single-dimentional arrays of simple data types. Arrays are intialized just like simple data types with the Dim statement:
Dim <Name(<Expression>)> As <Data Type>
For example:
Dim Array1(100) As String
Dim Cats(NumberOfCats) As String
Dim FavNumbers(1*5^3-9) As Double
Accessing arrays is not difficult; you just have to keep several things in mind:
- To access an array item use the following syntax:
<Name(<Expression>)>
For example:
Array1(3) = "Hello"
FavNumbers(1) = PI#
- All array items start at 1. So Array(0) or Array(-14) is not correct.
- If the array item is out of bounds, 0 or an empty string will be returned. If you are assigning an array item that is out of bounds, nothing happens.
Copying arrays is easy too, just remember that both arrays must be of the same type. They do not need to be the same size as the the one being assigned will automatically resize itself.
|
|
| Can I use User Defined Types in KoolB? |
|
User defined types is a combination of simple data types arranged under a single heading. Think of it as a simplistic version of an object. UDTs can only contain simple data types. To define an UDT, use the following method:
Type <TypeName>
<Member1> As <Data Type>
<Member2> As <Data Type>
...
End Type
For example:
Type AFamily
Dad As String
Mom As String
NumberOfChildren As Integer
End Type
This only defines the structure of the UDT. To actually create a UDT, use the Dim statement:
Dim <Name> As <UDT>
For example:
Dim MyFamily As AFamily
Once created, you can access or assign any member in the array by using the period. For example:
<Name>.<Member>
For example:
MyFamily.Dad = "John"
You can also copy one UDT to another as long as they are of the same type (in this case, both must be AFamily). The operation would look like this:
Dim MyOriginalFamily As AFamily
Dim MyOtherFamily As AFamily
MyOtherFamily = MyOriginalFamily
There are a couple of limitations to remember. First, members of a UDT cannot be arrays. Second, you cannot create arrays of UDTs (there is a difference).
|
|
|
KoolB uses the standard BASIC convention of false being equivalent to 0. So that means anything else is true. However, KoolB internally uses -1 as true. Since KoolB doesn't support anyway to create constant variables, you will have to use 0 instead of "false" and -1 instead of "true".
|
|
| How do relational operators work? |
|
Relational operators are used to compare two arithmetic or string comparisons. They consist of:
- = (Equal to)
- <> (Unequal to)
- < (Less than)
- > (Greater than)
- <= (Less than or equal to)
- >= (Greater than or equal to)
Important notes:
- There is no precedence among the relation operators
- No parenthesis may be allowed among the relational comparisons.
- Relational comparisons may only be used with If and While conditional statements
Here are some examples:
If 1 + 2 / 5 > 2 ^ 7 Then
While Input$ <> "Quit"
If Name$ = "William Yu" Then
|
|
| What about Boolean stuff like And, Or, & Not? |
|
Boolean expressions And, Or, & Not are supported to combine whole relational statements. They may be used ONLY when used in If or When statements. Boolean expressions may not be used in general arithmetic statements like so:
Result& = NOT 1 = 2 And AnotherVar > MyString
The correct way to do this would be do write this:
If Not 1 = 2 And AnotherVar > MyString Then
Result& = -1
Else
Result& = 0
End If
Boolean operators do have precedence levels. From highest to lowest: Not, Or, And.
Boolean expressions are supported with several limitations. One is that you cannot test a single variable like so:
If Not IsChecked Then
The correct way to write this would be:
If IsChecked = 0 Then
The other thing you have to be a bit careful with is parenthesis. You cannot use parenthesis to group Boolean expressions together. For example:
If ((IsChecked = -1) Or Caption = "Check Me") And Height = 50)
This is not valid at all - you would have to nest If statements. I know it is not the most idea situation, but it too temptingly simple to allow parenthesis in only arithmetic expressions. So the previous example would be:
If IsChecked = -1 Or Caption "Check Me" Then
If Height = 50 Then
|
|
| What conditional statements can I use? |
|
Conditional statements do something when a condition is true. To test a condition, you can use both relational operators and boolean operators to combine arithmetic or string expressions.
The first and probably most important conditional statement is the famous If statement. KoolB supports the extended If statement so you can use it to test multiple conditions via ElseIf. The standard form is:
If <Condition> Then
'Code to run if true
End If
If <Condition> Then
'Code to run if true
Else
'Code to run if false
End If
If <Condition> Then
'Code to run if 1st condition true
ElseIf <Condition> Then
'Code to run if 2cd condition true
ElseIf <Condition> Then
'Code to run if 3rd condition true
'More ElseIf's if necessary
Else
'Code to run if false
End If
Now for some practical examples:
If Age# < 10 And Not Age# = 2 Or Age# > 80 Then
Sleep 4
End
End If
If Choice& = 1 Then
Print "You picked choice #1"
ElseIf Choice& = 2 Then
Print "You picked choice #2"
ElseIf Choice& = 3 Then
Print "You picked choice #3"
Else
Print "You didn't pick a valid choice"
End If
The other conditional statement is the While loop. It loops through a piece of code while a condition is true.
The basic structure of the While loop is pretty simple:
While <Condition>
'Code to loop through while Condition is true
Wend
That isn't too bad is it? Now for a practical example:
Countdown& = 10
While Countdown& > 0
Print Countdown&
Countdown& = Countdown& - 1
Sleep 1
Wend
Print "Blast-off!"
For more examples on this subject, take a look at the example program named "Who are you" in the Examples folder. It gives examples of all this stuff.
|
|
| Can I create my own subroutines and functions? |
|
Subroutines and functions are just pre-coded pieces of your program that you can use any time and anywhere in the program. For example, instead of doing this:
Number# = 4
Print Number# ^ (1/2)
Number# = 16
Print Number# ^ (1/2)
That is sort of clumsy to do it like that, when all you want to do is calculate the square root of a number. Instead, you can assign a piece of your function (called a function) to calculate the square root. You first name it (say SQRT), and then give it a number (this is called a parameter), and it will calculate the square root, and then give you the number back (this is called the return value). Let's see how this could work:
Function SQRT(Number As Double) As Double
Result = Number ^ (1/2)
End Function
Print SQRT(4)
Print SQRT(16)
Although it takes a bit more setting up, it is much simpler. First, you can see the structure of function or sub - it looks something like this:
Function <Name>(Parameter1 As <Data Type>, <etc>) As <Data Type>
'Code
Result = 'Code
End Function
Sub <Name>(Parameter1 As <Data Type>, <etc>)
'Code
End Sub
You should be able to see that the really only difference between a sub and a function is that function returns something - say the result of a calculation. So why use a sub? Because you don't have to type as much! Other than that there is no difference. Also, you see that a function has a special variable named Result - this is the return value. What ever is in Result gets returned.
So how many parameters can you have? Anywhere from 0 to unlimited. If you have zero, make sure that you use empty parenthesis like so:
Sub ExitProgram()
End
End Sub
So where can functions and subroutines be used? Well, subroutines are used on their own separate line like so:
'Code
EndProgram() 'No parameters, but still use the parenthesis anyhow
Functions can be used like subroutines (the return value is discarded), or they can be used in an expression, like the first example.
Important: There are limitations at this point:
- You can only pass by value, not by reference - this will be changed at a later date
- You can only pass simple data types by reference - do not try to pass UDTs or arrays
- You cannot create arrays or UDTs inside functions
|
|
| What about the console statements like Print? |
|
Everybody's favorite: interaction with the user va console input and output. KoolB supports only three console functions: Cls, Print, Input. Not much, but enough to get the basics done.
Cls
Cls is all alone by itself (taking no parameters). It just clears the console screen and positions the cursor at the upper-left hand corner of the screen. A useful statement if you are cleaning up after some other section of the program.
Print <Expression>[; | ,<Expression>...]
Print is the all useful statement to write data to the console. It takes any number of expressions separated by either a semi-colon or comma. An expression can result in a number or string, both will be converted to string and written to the console.
For example:
Print "Hello, I am "; 3, " years old."
Input [Prompt String]<; | , <Variable>>
Input is a strange statement. It starts out with an optional prompt, which will be printed out to the user. If there is a prompt, a semi-colon or comma is required next. Then it waits until the user has entered a full line of text (under 16 KB) and presses ENTER. Then it stores the result in the Variable. The Variable can be a simple data type, array item, or even a UDT member. It doesn't matter wether the Variable is a number or string, it is automatically converted. Also, note that if the variable is not created, it will be automatically created for you (unless the Variable is an array or UDT).
For example:
Input A$ 'No prompt
Input "Enter your dad's name: "; MyFamily.Dad
Input "Enter your favorite number: ", FavNumber(3)
|
|
| Is there anything else KoolB can do? |
|
KoolB supports other miscelaneous statements as well. As of now, the total is 2, but hopefully that will change as KoolB matures.
Sleep <Numeric Expression>
The Sleep statement pauses the program for the number of seconds. <Numeric Expression> can also represent a fractional number such as .5 (half a second).
For example:
Sleep 1-4+6^2
Sleep .25
End
The End statement ends (or quits) the program. You can only use it inside of an If statement, a subroutines, or a function because it serves no purpose outside. For example:
Input "What do you want to do? "; DoWhat$
If DoWhat$ = "Quit" Or DoWhat = "Q" Then
Print "Bye! Thanks for using my program!"
Sleep 2
End
End If
Sub ExitProgram(Seconds As Integer)
Sleep(Seconds)
End
End Sub
|
|
