Lib.rs

DarkVM

A new VM that focuses on providing current features without comprimising on speed and simplicity.

This project is also a way for me to learn more about VMs and compilers.

Details About DarkVM

DarkVM operates on a stack and uses different operations to operate on it.

Types In DarkVM

Currently, DarkVM supports the following types:

• void
• any
• int
• float
• boolean
• string

Instruction Set

In this section, each instruction will be elaborated upon, along with examples

The instructions that DarkVM currently supports are:

• push
• pop
• peek
• add
• sub
• mul
• div
• lt
• lte
• gt
• gte
• eq
• neq
• jmp
• rjmp
• jmpt
• jmpf
• set
• call

The Push Instruction

The Push instruction takes one parameter: the value to be pushed on to the stack.

Example:

push 1

The push instruction takes an int, 1, and pushes this value on the stack.

Example:

push 1

After this instruction, the stack will look like this:

[1]

The Pop Instruction

The Pop instruction takes zero parameters.

Example:

pop

The pop instruction removes the top value from the stack and returns this value.

Example:

push 1
pop

After this instruction, the stack will look like this:

[]

The value returned will be the int 1.

The Peek Instruction

The Peek instruction takes zero parameters.

Example:

peek

The peek instruction returns the top value from the stack. It does not remove it from the stack.

Example:

push 1
peek

After this instruction, the stack will look like this:

[1]

The value returned will be the int 1.

The Add Instruction

The Add instruction takes zero parameters.

Example:

add

The add instruction removes the top two values from the stack and adds them together. It then returns this value.

Example:

push 1
push 2
add

After this instruction, the stack will look like this:

[]

The value returned will be the int 3.

The Sub Instruction

The Sub instruction takes zero parameters.

Example:

sub

The sub instruction removes the top two values from the stack and subtracts them. It then returns this value.

Example:

push 1
push 2
sub

After this instruction, the stack will look like this:

[]

The value returned will be the int 1.

The Mul Instruction

The Mul instruction takes zero parameters.

Example:

mul

The mul instruction removes the top two values from the stack and multiplies them. It then returns this value.

Example:

push 1
push 2
mul

After this instruction, the stack will look like this:

[]

The value returned will be the int 2.

The Div Instruction

The Div instruction takes zero parameters.

Example:

div

The div instruction removes the top two values from the stack and divides them. It then returns this value.

Example:

push 1
push 2
div

After this instruction, the stack will look like this:

[]

The value returned will be the int 0 because 1 / 2 = 0 with integer division. If float division was used, the result would be 0.5.

The Lt Instruction

The Lt instruction takes two parameters.

Example:

lt 1 5

The lt instruction checks if the first parameter is less than the second parameter. It then returns a boolean value representing the result of the comparison.

Example:

lt 1 5

After this instruction, the stack will look like this:

[]

The value returned will be the boolean true because 1 < 5.

The Lte Instruction

The Lte instruction takes two parameters.

Example:

lte 1 5

The lte instruction checks if the first parameter is less than or equal to the second parameter. It then returns a boolean value representing the result of the comparison.

Example:

lte 5 5

After this instruction, the stack will look like this:

[]

The value returned will be the boolean true because 5 <= 5.

The Gt Instruction

The Gt instruction takes two parameters.

Example:

gt 1 5

The gt instruction checks if the first parameter is greater than the second parameter. It then returns a boolean value representing the result of the comparison.

Example:

gt 1 5

After this instruction, the stack will look like this:

[]

The value returned will be the boolean false because 1 < 5.

The Gte Instruction

The Gte instruction takes two parameters.

Example:

gte 1 5

The gte instruction checks if the first parameter is greater than or equal to the second parameter. It then returns a boolean value representing the result of the comparison.

Example:

gte 5 5

After this instruction, the stack will look like this:

[]

The value returned will be the boolean true because 5 >= 5.

The Eq Instruction

The Eq instruction takes two parameters.

Example:

eq 1 5

The eq instruction checks if the first parameter is equal to the second parameter. It then returns a boolean value representing the result of the comparison.

Example:

eq 1 5

After this instruction, the stack will look like this:

[]

The value returned will be the boolean false because 1 != 5.

The Neq Instruction

The Neq instruction takes two parameters.

Example:

neq 1 5

The neq instruction checks if the first parameter is not equal to the second parameter. It then returns a boolean value representing the result of the comparison.

Example:

neq 5 5

After this instruction, the stack will look like this:

[]

The value returned will be the boolean false because 5 == 5.

The Jmp Instruction

The Jmp Instruction takes one parameter.

Example:

jmp 1

The jmp instruction checks if the parameter passed is within the bounds of the program, and if it is, it jump to the location specified.

Example:

jmp 4
push "Failed"
push "Succeeded"

After this instruction, the stack will look like this:

["Succeeded"]

No value is returned from the jmp instruction.

The Rjmp Instruction

The Rjmp Instruction takes one parameter.

Example:

rjmp 1

The rjmp instruction checks if the current location + the parameter passed is within the bounds of the program, and if it is, it jump to the current location + the location specified. This parameter can be positive or negative as long as the sum is within the bounds.

Example:

rjmp 4
push "Failed"
push "Succeeded"

After this instruction, the stack will look like this:

["Succeeded"]

No value is returned from the rjmp instruction.

The Jmpt Instruction

The Jmpt Instruction takes one parameter.

Example:

push true
jmpt 3

The jmpt instruction first checks if the top value on the stack is true. If it is, it checks if the parameter passed is within the bounds of the program, and if it is, it jump to the location specified.

Example:

push true
jmpt 6
push "Failed"
push "Succeeded"

After this instruction, the stack will look like this:

["Succeeded", true]

No value is returned from the jmpt instruction.

The Jmpf Instruction

The Jmpf Instruction takes one parameter.

Example:

push false
jmpf 3

The jmpf instruction first checks if the top value on the stack is false. If it is, it checks if the parameter passed is within the bounds of the program, and if it is, it jump to the location specified.

Example:

push false
jmpf 6
push "Failed"
push "Succeeded"

After this instruction, the stack will look like this:

["Succeeded", false]

No value is returned from the jmpf instruction.

The Print Instruction

The Print Instruction takes one parameter.

Example:

print "Hello, World!"

The print instruction prints out the parameter. It does not, however, print a new line character after. If you desire that behavior, check out the "printn" instruction.

Example:

push 1
push 1
push add
print "1 + 1 = "
print pop

After this instruction, the stack will look like this:

[]

No value is returned from the print instruction.

The Printn Instruction

The Printn Instruction takes one parameter.

Example:

printn "Hello, World!"

The printn instruction prints out the parameter with the new line character after.

Example:

printn "Hello, World!"
push 1
push 1
push add
printn "1 + 1 = "
printn pop

After this instruction, the stack will look like this:

[]

No value is returned from the print instruction.

The Set Instruction

The Set Instruction takes two parameters.

Example:

set message "Hello, World!"

The set instruction defines a variable with the name of the first parameter, in this case, message. The value of this variable is the second parameter.

Example:

set message "Hello, World!"
printn message

After this instruction, the stack will look like this:

[]

No value is returned from the set instruction.

The Call Instruction

The Call Instruction takes one parameter.

Example:

call greet

The call instruction calls the label passed in. For more information on labels, visit the section dedicated to them.

Example:

call greet

@greet
  printn "Hello, World!"
end

In the above example, the code within the greet label is run. So, "Hello, World!" is printed out to the screen. After finishing the code in the label, the code resumes from the point after the function call.

After this instruction, the stack will look like this:

[]

No value is returned from the call instruction.

Labels In DarkVM

In the DarkVM, labels are what provide local scopes. They can be thought up as methods or blocks depending on the context. Here is how you define a label:

@label_name
end

Here, you can see that labels start with an @ and are then followed by the name of the label. Finally, they have the end keyword. Any amount of code can go in between the label name and the end keyword.

Labels have access to the parent scope and local scope. What does that mean? Well, if a label is defined inside another label, then the child label has access to all of the variables inside of the parent label. Otherwise, it just has access to its own scope. Though the child label can access the parent label, the parent can not access the child.

Comments In DarkVM

DarkVM supports both single line and multiline comments.

Single line comments can be created using the following syntax:

-- This is a comment.

Multiline comments can be created using the following syntax:

-!
  This is a multiline comment.
  I can write anything I want here.
!-