Please note this user guide refers to Kenya 2. The old user guide for version 1 is available here.
As Kenya is written entirely in Java, it runs on both Linux and Windows platforms.
You need to modify the configuration file 'config' so that Kenya knows where you have installed the Java development kit. If you don't change the configuration file, you will still be able to run kenya, but will not be able to compile and run the java versions of your translated kenya programs.
The config file comes well commented, look at the comments and change the necessary parts for java and javac. change any of the other options if you like, but only the java and javac parts are required to be changed.
In order to take advantage of generics, Kenya uses the GJ compiler rather than the standard Java compiler. This needs to be installed in order to use generics. If you do not wish to use this advanced feature, the system can be configured to work with the standard javac compiler.
To create a personal Kenya setup, you can override any of the options set in the default config file by creating your own personal config file. This should be called .kenya and located in the root of your home directory.
To start the system, on Linux simply run the run.bat (windows) or run.sh (unix) script in the bin directory. This should cause the user interface to appear. NB, if you have downloaded the source code distribution you will need to build the software before it can be run. Notes on how to do this can be found in the readme file.
The main Kenya window looks like this:-
All the tasks that you will need to do can be achieved by clicking on the relevant button in the toolbar. The toolbar allows you to accomplish the following:-
Just below the toolbar are two tabs labelled "Kenya" and "Java". Clicking on these two tabs allows you to switch between editing Kenya code and Java code.
Towards the bottom of the screen is a messages area, any messages from the Kenya system will be displayed here. Compiler messages and interpreter messages will also be displayed here.
Along the left hand side of the main editing area is a gutter area which displays line numbers. You can expand or collapse this gutter area by double clicking on it.
Traditionally the first program that people write in any language is the Hello World program. This prints out Hello World! on the screen. Lets see how to write and run this in Kenya.
First make sure that the Kenya editing area is selected, and type into it the following code:
void main() {
println( "Hello World!" );
}
This simple program uses the println function to print a line of text on the screen. Note the
semicolon at the end of the line. All statements in Kenya programs must be terminated by a semicolon. All programs must include a main() funciton which tells the system where the program starts.
Now click on the Translate button. You will be asked to save the file. Enter HelloWorld.k into the box and click save.
After a second or so, the display should give the message "Finished parsing". Clicking on the Java tab will show the Java area containing the Java code which the system has generated. Now click on the Compile button and after a few seconds you should see a "Compiled OK" message in the box at the bottom of the window.
You can now run the program by clicking the Execute button. An output window will pop up and you should see the words Hello World! in the window.
Close the window and return to the Kenya code. There is another way to exectute kenya programs, using the interpreter. This allows you to step through the program a line at a time and examine the contents of variables etc. This is discussed later.
We have just seen how to use the Kenya system to write, parse, compile and execute a very simple program. We now examine some more features of the language.
Kenya has five inbuilt types. Variables can be created to hold data of any of these types: integer numbers, double precision floating point numbers, strings, characters and boolean values. Variables must be declared before they can be used. Here is a declaration of an integer variable with the name 'age'. The type is specified first, and then the identifier (name) for the variable.
int age;
Here are some examples of declaring variables of the other four inbuilt types (note the capital S in String)
double notAWholeNumber; String aWordOrPhrase; char justOneLetter; boolean trueOrFalse;
Once variables have been created they can have values assigned to them using the assignment operator '='. Each time a new value is assigned to a variable it overwrites the old value. Here each of the variables declared above is assigned a value in the form of a 'literal', a basic value included in the program code.
age = 27; notAWholeNumber = 36.85; aWordOrPhrase = "I like coffee"; justOneLetter = 'x'; trueOrFalse = true;
Note the different forms of literals of different types. Strings are surrounded by double quotes, characters by single quotes. The boolean literals true and false are keywords and do not need any quotes.
If we try and assign a value of the wrong type to a variable, then this will be picked up when the 'parse' button is clicked. For instance if we write the following program:
int age; age = 13.75;
then when the program is parsed the following message will appear:
Error (line 2): Expression assigned to age should have type int
In this way the programming environment picks up when the programmer makes a mistake. Similarly, if we simply made a typing error, like:
int age; afe = 13.75;
we would get the following error reported:
Error (line 2): Variable afe has not been declared
Values can be combined before assignment using familiar mathematical operators etc, and the contents of one variable can be assigned to another:
int total; total = 3 + 4 + ( 5 * 6 ); double fraction; fraction = total / 7;
Multiplication is represented by * and division by /. Other mathematical operators such as sin, log, square root etc are available and details are given in the language reference section of the online help.
To make the program slightly shorter, the above code could have been written as:
int total = 3 + 4 + ( 5 * 6 ); double fraction = total / 7;
where the variables are declared and assigned to in the same statement.
The println function ( and also print which does the same thing but without starting a new line afterwards ) that we say in the Hello World example can be used to output the contents of variables to the screen. For example:
boolean trueOrFalse = false; println( trueOrFalse ); int age = 17; print( "I am " ); print( age ); println( " years old." ); String name = "Jon"; println( name + " is " + ( age * 2 ) + " years old." );
The last line of that example shows how variables and literals can be combined in an expression inside the
println function to save on printing each value separately.
Arrays, indexed sets of variables of the same type, can be declared and used in either of the following ways:
// giving the size
int[] a = new int[3];
a[1] = 5;
println( a[1] );
// or giving an initialiser
int[] a = { 1 , 5 , 9 };
Both of these create an array of three integers, indexed from 0 to 2. In the top example only the middle element (with index 1) has had a value assigned to it. In the second example all of the elements are initialised.
Arrays can have more than one dimension. For instance a 2x2 matrix of Strings could be used like this:
String[] b = new String[2][2]; //arrays are indexed from zero b[0][0] = "Hello"; println( b[0][0] );
The above program fragments feature comments, prefixed by two slashes, //. These are just a note to the programmer or reader of the code to help explain its function. They have no effect on the running program.
There are not many computer programs that work on the same set of data each time they run, so it is common
to want to get input from the user. Kenya provides a number of different functions for reading different types
of data typed by the user at the keyboard into variables. There are four functions corresponding to the four
built in data types of
int,
double,
String and
char
called respectively,
readInt(),
readDouble(),
readString() and
readChar(). They are used like this:
int age;
double height;
String surname;
char initial;
age = readInt();
height = readDouble();
surname = readString();
initial = readChar();
println( initial + ". " + surname + " is aged " + age
+ " and is " + height + " metres tall." );
If this code is entered, parsed, compiled and executed, the program will wait for the user to enter the required data in the box at the bottom of the output window. The different items can either be entered on different 'lines' with a carriage return between each, or on the same line separated by whitespace with just a carriage return at the end, or by a mixture of the two.
Doing things repreatedly is one of the most common things to want to do in a computer program. Kenya has two different flavours of loop construct which allow you to do this. The first is the while loop. The while loop will repeat a set of statements until a certain condition becomes false (or while it is true). The constuct looks like this:
while ( condition )
{
statements ...
}
The statements are surorunded by opening and closing braces ( { and } ) which form a 'block' of statements. These are the statements that will be run repeatedly until the condition becomes false.
int i = 1;
while ( i < 11 )
{
println( i );
i = i + 1;
}
This example will print all the numbers from 1 to 10. It will not print 11. More complicated conditions can be specified using logical operators, for instance:
while ( x > 2 and x < 12 or f > x )
{
statements ...
}
The other type of loop available is the for loop. For loops count through a certain number of iterations using an index variable. There are two different ways of setting up a for loop. The first has a slightly simpler syntax, but the second is closer to the form used in Java. The first looks like this:
int i;
for i = 1 to 10
{
println( i );
}
for i = 2 to 10 step 2
{
println( i );
}
for decreasing i = 10 to 2
{
println( i );
}
The first example prints all the numbers from 1 to 10. The second prints the even numbers from 2 to 10. The third prints the even numbers from 10 to 2 in decreasing order. The count, in each case held in the variable i, can increase or decrease with a given step. If these are not specified the default is increasing with step 1.
The second syntax for defining the for loop control is shown in the following examples, which print the numbers from 1 to 10 and from 10 to 1 respectively.
for ( i = 1 ; i <= 10 ; i++ )
{
println( i );
}
for ( i = 10; i > 0 ; i-- )
{
println( i );
}
The control is in three parts separated by semicolons. The first gives the index variable an initial value. The second gives a condition which must remain true for the exectuion of the loop to continue, and the third gives an operation to perform on the index variable at each iteration. The examples show i being incremented and decremented respectively.
It is often the case that you only want to execute certain statements if a certain condition is true. Kenya has an if ... then ... else construct with the following syntax.
int a = 2;
if ( a == 2 )
{
println( "a equals 2" );
}
else
{
println( "a does not equal 2" )
}
Any boolean condition can go inside the round brackets (see the online help for a list of comparison operators etc). If the condition evaluates to true then the block of statements directly after the condition will be executed. The else keyword and the second block are optional. If they are included then the second block of statements will be operated if and only if the first is not (i.e. the condition evaluates to false).
If there are a number of possible choices all conditional on the same integer (or character) variable, you can use a switch statement to reduce the number of ifs you have to write.
int a = 2;
switch ( a )
{
case 1 : { print( "One" ) ; break; }
case 2 : { print( "Two" ) ; break; }
default : { print( "Many" ); break; }
}
If a is equal to 1, this program will print "One" and then break out of the switch block. Leaving out the break would cause all of the rest of the cases to be executed until a break was reached.
default is a catch all which will match any case.
The switch variable can either be an integer or a char. Using a char, the code might look like this:
char c = readChar();
switch ( a )
{
case ' ' : { println( "Space" ) ; break; }
case '\n' : { println( "New Line" ) ; break; }
default : { println( c ); }
}
A function is defined by giving its return type, name, parameters and a block of statements. If the functon does not return anything then you need to give it a return type of 'void'. Parameters are separated by commas.
int triple( int n )
{
return n*3;
}
The return type of the function, as well as the type of any of the parameters, can be an array. In that case the following syntax (with square brackets) would be used to define the function:
int[] doublearray( int[] d )
{
int i;
for i = 0 to d.length - 1 {
d[i] = d[i] * 2;
}
return d;
}
Calling a Function
Once defined, the function can be called anywhere in the code.
int a = 2;
int b = triple( a );
int[] t = { 1 , 2 , 3 };
t = doublearray( t );
The value assigned to b here is the value returned by the function triple when given the argument a. In this case we would expect b to obtain the value 6. In the second example the array t is passed to the function, and the array returned (and assigned back to t) should have each of the elements doubled.
You can define a record or class to encapsulate a group of variables. Here we define a Person class. A Person has a name and an age. For those with experience of object-oriented programming, note that in Kenya a class cannot contain methods, only attributes, as it only a structure or record. Kenya is not an object-oriented language.
class Person
{
String name;
int age;
}
You can then declare a variable of this type just like any other and access its fields in the following way.
Person me; me.name = "Joe Bloggs"; me.age = 27; println( "I am " + me.name );
The Kenya interpreter allows you to execute your program natively, without having to perform a translation into Java, compiling the Java, and then executing that. The interpreter can also be used as a debugging tool for your Kenya programs.
Lets do an example to get you up and running with using the interpreter. First, click on the 'new' button of the toolbar, if it asks you whether you want to save the current Kenya program, click 'no'. Now, make sure that the Kenya editing area is selected by clicking on the Kenya tab. Now enter the code below:-
void main()
{
println("---- 1");
println("---- 2");
println("---- 3");
println("---- 4");
println("---- 5");
}
Click the 'save' button on the toolbar, and save your program as numbers.k.
To start the interpreter, click on the 'Interpreter' button on the toolbar. The window below should be displayed:-
This is the interpreter window, you use this window to control the Kenya interpreter. Like the main Kenya window, a row of buttons on a toolbar provides all the functionality you need to access for the interpreter. The screenshot below shows the functions of each button.
Click on the 'Run' button on the toolbar, you should see almost immediately, the following output in the output area below the toolbar:-
---- 1 ---- 2 ---- 3 ---- 4 ---- 5You have just run your first program through the Kenya interpreter!
The ability to execute your program a line at a time is a great help in debugging your programming of errors. Luckily, you can do this with the Kenya interpreter.
If you have the numbers.k program still open, click on the 'Kenya interpreter' button on the toolbar to open the interpreter window. Otherwise, click on the 'open file' button, and navigate to where you saved the numbers.k program, and open it. Now, in the interpreter window, click on the 'Step into' button once.
Now look back at the main Kenya window, you see the a line in your program highlighted like in the previous diagram. This shows you the line of your program the interpreter is ready to execute next.
Click on the 'step into' button in the interpreter window once more. You should see
---- 1appear in the output window. If you now look back at the main interpreter window again, you should notice that the line just after the line that was previously highlighted, now highlighted instead. This tells you that the interpreter has finishednow ready to execut Click on the 'step into' button four more times, until the all five lines of output have been printed to the output box in the interpreter window. You have just stepped through your first Kenya program!
Often you will want your program to execute up until a certain point before you start stepping through the code. This can be done by setting a breakpoint in your program. The Kenya interpreter will run and execute your program until it hits the breakpoint, at which point it will stop and highlight the line in blue, indicating that it is rcan step through your code line by line, or continue execution of the interpreter. Try it yourself by following these steps:-
println("---- 3"); line in the Kenya editing area
of the main Kenya window, and the click the 'set breakpoint' button in
the interpreter window. You should see a red marker appear in the gutter
to the left of the main Kenya window. This indicates that a
breakpoint has been set. on that line (see screenshot below).
The variable watch panel of the interpreter window allows you to watch the values of your variables in your program change as the interpreter executes your program. This facility can be invaluable to the debugging of your programs.
To try this facility out, first create a new file, saving anything that you wish to keep. Now, type the following program into the Kenya editing area:-
int factorial (int x)
{
if(x == 0){
return 1;
}else{
return x*factorial(x-1);
}
}
void main(){
println("Factorial of 3 is: " + factorial(3));
}
Open the interpreter window, and click on the variable watch button on the toolbar. You will see a panel appear on the right hand side of the interpreter window. This is the variable watch panel. The variable watch panel is split into two parts, there is a drop down list towards the top, and below this is the main variable watch area. The drop down list is known as the scopes list, it contains an entry for each function call that hasn't returned yet - you will see what this means in a minute when you step through the factorial program presented above. The variable watch window displays a tree view of the variables in your program and their values. With class variables and array variables, you can expand and collapse the trees to show or hide information as you wish, this reduces screen clutter. As a program runs, the tree is continually updated.
Now, lets run the program to see it in action! Click on the 'step into' button six times such that the program enters the second recursive call of the factorial function. As you should have noticed, the variable watch window continually changes with each step you make. Now, click on the scopes list, you should see something like the screen shot below:-
You will see that there are three entries for factorial, and one entry for a main. The entry for main represents the variables within the scope of the main function. Similarly, the three factorial entries each represent one of the calls to factorial. The one called 'factorial' is the original call, while 'factorial_2' and 'factorial_3' are the first and second recursive calls, respectively. For each recursive call that is made to a function, an underscore and a number are appended to the function name. This number is incremented by one for each recursive call made.
If you click on the 'main' item in the list, you will be presented with a blank variable watch window. This is because there are no variables declared in the main() function. If you click on any of the 'factorial' entries, you will see a tree with one element in it - a variable called 'x'. This represents the formal parameter x of each of the factorial functions. (Check that each one is correct for that recursive call!).
Now, continue stepping through the factorial program. As you step, you should notice that after the third recursive call, the scopes list suddenly becomes empty, and the output of the program is displayed in the output window of the interpreter window. The scopes has suddenly become empty because all the functions have returned - the scopes list only maintains a list of functions which have not returned.
You will notice that there are other buttons on the toolbar of the variable watch window, we now briefly describe their functionality:-
At the bottom of both the output window and the interpreter window, just below their output boxes, is a small box known as the input box. This box is used for providing input to a Kenya program. To provide input to a Kenya program when it waiting for some, simply type what you want to input, and then press the ENTER key.
There is also an End of file (EOF) button next to the input box on the output window and the interpreter window. This button is used for entering a EOF character as input into a executing program if it is waiting for input.
You can generate graphical output in a separate window using the following graphics commands. NB, these do not currently work with the interpreter, only with compiled code.
clear(); drawLine( x1, y1, x2, y2 ); drawBox( x1, y1, width, height ); drawTriangle( x1, y1, x2, y2, x3, y3 ); drawEllipse( x1, y1, w, h ); setColour( r, g, b ); setBGColour( r, g, b ); fill( true/false );
All co-ordinates and sizes are integers. The origin is in the top left hand corner. The colour commands ( N.B. colour has a 'u' in it ) take integer r,g and b values. fill takes either true or false to turn filling of shapes on or off.