KoiViMa comes with a compiler that translates KoiViMa assembly language into object code. However KoiViMa assembly language is not intended to be written by humans. Instead it serves as an intermediate code to be created by experimental compilers.
Another important aspect is that the compiler uses no fixed instruction set. Different sets of operators may be be provided at compile time. The compiler adapts itself to the given operator set.
This chapter shows how to use the standard operator set.
The directory “src/programs” contains some example programs written in KoiViMa assembly language. The incredible famous program “Hello World” is stored in the file “hello.txt”. It looks like this:
# # Prints Hello World onto the screen # "Hello World!" PrintLine
Looks simple enough, doesn't it? To run the program just type “java de.projectory.koivimatest.Main programs/hello.txt” from the “src” directory.
The # symbol marks the beginning of a comment. A comment may start at any position within a line. It ends at the end of the line. Comments are ignored by the compiler.
“Hello World!” is a string. For KoiViMa it is also an executable element. When “Hello World!” is evaluated it puts itself onto the internal stack, so that it can be used by operators.
“PrintLine” is an operator. It fetches the last element from the stack (Hello World!) and prints it onto the screen. It is possible to provide KoiViMa with different instruction sets. The standard operator set can be found within the “de/projectory/koivima/operators” directory.
Now let's run a slightly more complex example: “java de.projectory.koivimatest.Main programs/count.txt”. This program counts from 1 to 10.
# # Counts from 1 to 10 and prints it onto the screen # 0 1 Add # add first two integers Copy # copy result on stack PrintLine # print the copied result and delete it Copy # copy result again 10 LessThan # compare if result is less than 10 -8 JumpOnCondition # jump back 8 steps
This example illustrates some important concepts. First of all the instructions follow the Korean sentence order. Parameters come first followed by an instruction. Second each value and each operator counts as one single step. That's because even a value is an executable object.
The Add instruction just adds 0 and 1. The result is put onto the stack. Then follows a Copy operator. The Copy operator doubles the element on top of the stack. This is important, because the PrintLine operator removes the element on top of the stack and we want to reuse the result of the previous calculation.
The LessThan operator checks if this result is less than 10. The result acts as an input for the JumpOnCondition operator. If it is true, the JumpOnConditon jumps 8 steps back to the additon of 1.
There is a more elegant way to count: Using lists. Here it is:
[ 1 2 3 4 5 6 7 8 9 10 ] { PrintLine } ForEach
Lists are denoted by sqare brackets []. The list above contains the integers from 1 to 10. Something enclosed by curly brackets like {PrintLine} is called a code block. A code block is like a function or a macro. Code blocks are only evaluated on demand. For KoiViMa a list and a code block are just two elements to be put onto the internal stack. Now comes the ForEach operator. It evaluates the code block for every single element of the list.
As lists are used very often, there is a more convenient way to create them:
1 10 Range { PrintLine } ForEach
The Range operator creates a list from 1 to 10.
Lists may contain arbitrary elements. So this is a valid example to print out each element of a list:
[ "Karin" "Helga" 42 "Jürgen" ] {PrintLine} ForEach
A list may even contain code blocks:
[ { 1 1 Add PrintLine } { "Hello" PrintLine } ] { Evaluate } ForEach
And of course, a code block is some kind of list:
{ { 2 2 Add PrintLine } { "Hello" PrintLine } } { Evaluate } ForEach
The difference between code blocks and lists is that code blocks may be evaluated and code blocks may use their own execution context.
Common control structures can be easily represented in KoiViMa assembly language.
if condition code
translates to:
{ condition } Evaluate 3 JumpOnNotCondition { code } Evaluate Nop
Example:
{ 1 } Evaluate 3 JumpOnNotCondition { "condition is true" PrintLine } Evaluate Nop
if condition then code1 else code2
translates to:
{ condition } Evaluate 1 5 BranchOnCondition { code1 } Evaluate 3 Jump { code2 } Evaluate Nop
Example:
{ 1 } Evaluate 1 5 BranchOnCondition { "if block" PrintLine } Evaluate 3 Jump { "else block" PrintLine } Evaluate Nop
while condition code
translates to:
{ condition } Evaluate 5 JumpOnNotCondition { code } Evaluate -7 Jump Nop
Example (endless loop):
{ 1 } Evaluate 5 JumpOnNotCondition { "inside while" PrintLine } Evaluate -7 Jump Nop
for startvalue endvalue code
translates to:
startvalue endvalue Range { code } ForEach
Example:
1 10 Range { PrintLine } ForEach
There is a traditional alternative:
startvalue { code } Evaluate 1 # step Add Copy endvalue+1 LessThan -8 JumpOnCondition
Example:
0 { Copy Print " inside for" PrintLine } Evaluate 1 Add Copy 10 LessThan -8 JumpOnCondition
The following program prints out the lyrics to the song “99 Bottles of Beer”. Run “java de.projectory.koivimatest.Main programs/bottles.txt”
# # 99 Bottles of Beer # # Put two integers on the stack and substract 1 from 100 100 1 Sub # Print first line. Use the result of the first substraction. Copy Print " bottles of beer on the wall, " Print Copy Print " bottles of beer." PrintLine # Print second line "Take one down and pass it around, " Print Copy 1 Sub Print " bottles of beer on the wall." PrintLine "" PrintLine # Check if result is greater 3 and jump back to the substraction if this is the case Copy 3 GreaterThan -24 JumpOnCondition # Print out the rest "2 bottles of beer on the wall, 2 bottles of beer." PrintLine "Take one down and pass it around, 1 bottle of beer on the wall." PrintLine "" PrintLine "1 bottle of beer on the wall, 1 bottle of beer." PrintLine "Take one down and pass it around, no more bottles of beer on the wall." PrintLine "" PrintLine "No more bottles of beer on the wall, no more bottles of beer." PrintLine "Go to the store and buy some more, 99 bottles of beer on the wall." PrintLine
If like to see how this program looks in other programming languages take a look at 99 Bottles of Beer.