KoiViMa Assembly Language

Introduction

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.

Hello World

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.

Counting

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.

Using Lists

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.

Basic Flow Control

Common control structures can be easily represented in KoiViMa assembly language.

If


if condition code

translates to:


{ condition } Evaluate
3 JumpOnNotCondition
{ code } Evaluate
Nop

Example:


{ 1 } Evaluate
3 JumpOnNotCondition
{ "condition is true" PrintLine } Evaluate
Nop

If Else


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


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


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	

99 Bottles

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.