ColaVM Documentation

Instructions

Cola programs are written using stack-based instructions. Most instructions consume values from the stack (pop them) and may push a result back.

• PUSH <value> - Pushes a value onto the stack.
• POP - Removes the top value from the stack.
• TOP - Reads and prints the top value without removing it.
• ADD - Pops two values, adds them, and pushes the result.
• SUB - Pops two values, subtracts the top value from the next, and pushes the result.
• MUL - Pops two values, multiplies them, and pushes the result.
• DIV - Pops two values, divides the second by the first, and pushes the result.
• MOD - Pops two values, calculates the remainder, and pushes the result.
• PRINT "text" - Prints a string stored inside the instruction.
• CHAR <length> - Pops length values and prints them as characters.
• STORE <index> - Pops the top value and stores it in a variable.
• LOAD <index> - Pushes the stored variable value onto the stack.
• INC - Pops the top value, increments it, and pushes the result.
• DEC - Pops the top value, decrements it, and pushes the result.
• JUMP <label> - Moves the PC to the label.
• JEZ <label> - Pops one value. Jumps if it is zero.
• JEQ <label> - Pops two values. Jumps if they are equal.
• JGT <label> - Pops two values. Jumps if the second value is greater.
• JLT <label> - Pops two values. Jumps if the second value is smaller.
• JGE <label> - Pops two values. Jumps if the second value is greater or equal.
• JLE <label> - Pops two values. Jumps if the second value is smaller or equal.
• END - Stops program execution.

Stack Behaviour

Instructions that perform calculations remove their operands from the stack first. The most recently pushed value is always popped first.

Example:

After SUB, the stack contains 5 because it computes 10 - 5. Both values were removed before the result was pushed back.

Writing and running a program

Following are the steps to successfully write and run a Cola program.

1. Create a file named "program.cola".
2. Write the desired code for the ColaVM.
   For this example, let's assume a single line: PRINT "Hello, World!"
3. Run python assemble.py path/to/program.cola or python3 assemble.py path/to/program.cola depending on your platform.
4. The compiled .can file (cola binary) will be created at the same directory as the source .cola file.
5. Run ./colavm program.can to run the binary.