Updated readme accordingly

README.md

@@ -16,6 +16,11 @@ Each documented instruction has a list of what is pushed, and what is popped.
 the items are listed in chronological order, from first pushed/popped to last
 pushed/popped.
 
+You'll notice that words specifying an address are always at the top of the
+stack. This helps increse security and reduce the likelihood of bugs. When
+writing functions to extend creature, it is highly advised that you follow this
+principle when deciding on an order to pop arguments off of the stack in.
+
 ### 0x0 PUSH
 
 Pushes the next word in program memory onto the stack.
@@ -53,8 +58,8 @@ Pops:
 Adds two words. Tip: this can be used as a logical OR.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand + right operand
@@ -64,8 +69,8 @@ Pushes:
 Subtracts two words.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand - right operand
@@ -75,8 +80,8 @@ Pushes:
 Multiplies two words.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand * right operand
@@ -86,8 +91,8 @@ Pushes:
 Divides two words.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand / right operand
@@ -97,8 +102,8 @@ Pushes:
 Checks if two words are equal. Pushes 1 if true, zero if false.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand == right operand
@@ -108,8 +113,8 @@ Pushes:
 Checks if a word is greater than another word. Pushes 1 if true, zero if false.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand > right operand
@@ -119,8 +124,8 @@ Pushes:
 Checks if a word is less than another word. Pushes 1 if true, zero if false.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand < right operand
@@ -130,8 +135,8 @@ Pushes:
 Checks if two words are *not* equal. Pushes 1 if true, zero if false.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand != right operand
@@ -142,8 +147,8 @@ Performs a modulo operation on two words. Tip: this can be used as a logical
 AND.
 
 Pops:
-1. left operand
+1. right operand
-2. right operand
+2. left operand
 
 Pushes:
 1. left operand % right operand

creature.go

@@ -90,42 +90,38 @@ func (machine *Machine[WORD]) Execute(offset WORD) (err error) {
 	for int(machine.counter) < len(machine.Program) {
 		switch machine.instruction() {
 		case PUSH:
-			// push the next word in program memory onto the stack
 			machine.counter++
 			machine.Push(machine.instruction())
 
 		case POP:
-			// pop the top word off of the stack, and discard it
 			machine.Pop()
 
 		case PEEK:
-			// push the word at an address onto the stack
 			machine.Push(machine.Peek(machine.Pop()))
 
 		case POKE:
-			// store a word at an address
 			address := machine.Pop()
 			word := machine.Pop()
 			machine.Poke(address, word)
 
 		case ADD:
-			// adds the last two words on the stack
+			right := machine.Pop()
-			machine.Push(machine.Pop() + machine.Pop())
+			left  := machine.Pop()
+			machine.Push(left + right)
 
 		case SUB:
-			// subtracts the second to last word on the stack from
+			right := machine.Pop()
-			// the last word on the stack
+			left  := machine.Pop()
-			machine.Push(machine.Pop() - machine.Pop())
+			machine.Push(left - right)
 
 		case MUL:
-			// multiplies the last two words on the stack
+			right := machine.Pop()
-			machine.Push(machine.Pop() * machine.Pop())
+			left  := machine.Pop()
+			machine.Push(left * right)
 
 		case DIV:
-			// divides the last word on the stack by the second to
-			// last word on the stack
-			left  := machine.Pop()
 			right := machine.Pop()
+			left  := machine.Pop()
 			if right == 0 {
 				err = ErrorDivideByZero
 				return
@@ -133,62 +129,56 @@ func (machine *Machine[WORD]) Execute(offset WORD) (err error) {
 			machine.Push(left / right)
 
 		case EQ:
-			// checks if the last two words on the stack are equal
+			right := machine.Pop()
+			left  := machine.Pop()
 			equal := 0
-			if machine.Pop() == machine.Pop() {
+			if left == right {
 				equal = 1
 			}
 			machine.Push(WORD(equal))
 
 		case GT:
-			// checks if the last word on the stack is greater than
+			right := machine.Pop()
-			// the second to last word on the stack
+			left  := machine.Pop()
 			greater := 0
-			if machine.Pop() > machine.Pop() {
+			if left > right {
 				greater = 1
 			}
 			machine.Push(WORD(greater))
 
 		case LT:
-			// checks if the last word on the stack is less than the
+			right := machine.Pop()
-			// second to last word on the stack
+			left  := machine.Pop()
 			less := 0
-			if machine.Pop() < machine.Pop() {
+			if left < right {
 				less = 1
 			}
 			machine.Push(WORD(less))
 
 		case NEQ:
-			// checks if the last two words on the stack are not
+			right := machine.Pop()
-			// equal
+			left  := machine.Pop()
 			notEqual := 0
-			if machine.Pop() != machine.Pop() {
+			if left != right {
 				notEqual = 1
 			}
 			machine.Push(WORD(notEqual))
 
 		case MOD:
-			// performs a modulo operation of the second to last
+			right := machine.Pop()
-			// word on the stack to the last word on the stack
+			left  := machine.Pop()
-			machine.Push(machine.Pop() % machine.Pop())
+			machine.Push(left % right)
 
 		case HALT:
-			// stops execution
 			return
 
 		case JMP:
-			// jump to the address specified by the last word on the
-			// stack if the second to last word on the stack is
-			// nonzero
 			jumpTo := machine.Pop()
 			if machine.Pop() != 0 {
 				machine.counter = jumpTo - 1
 			}
 
 		case CAL:
-			// call an implementation-defined subroutine, with the
-			// id specified by the last word on the stack. this may
-			// push and pop various things from the stack
 			id := machine.Pop()
 			if machine.functions == nil {
 				break

creature_test.go

@@ -41,24 +41,24 @@ func TestPush(test *testing.T) {
 
 func TestArithmetic(test *testing.T) {
 	machine := runMachineTest([]int {
-		PUSH, 2,
 		PUSH, 3,
+		PUSH, 2,
 		ADD,
 		
-		PUSH, 4,
 		PUSH, 10,
+		PUSH, 4,
 		SUB,
 		
-		PUSH, 7,
 		PUSH, 2,
+		PUSH, 7,
 		MUL,
 		
-		PUSH, 3,
 		PUSH, 12,
+		PUSH, 3,
 		DIV,
 		
-		PUSH, 6,
 		PUSH, 8,
+		PUSH, 6,
 		MOD,
 	}, nil, test)
 
@@ -106,16 +106,16 @@ func TestComparison(test *testing.T) {
 		PUSH, 6,
 		EQ,
 		
-		PUSH, 4,
 		PUSH, 324,
+		PUSH, 4,
 		GT,
 		
-		PUSH, 324,
 		PUSH, 4,
+		PUSH, 324,
 		LT,
 		
-		PUSH, 6,
 		PUSH, 54,
+		PUSH, 6,
 		NEQ,
 		
 	}, nil, test)