Added some helpful comments to the creature command

cmd/creature/main.go

@@ -26,10 +26,10 @@ func main() {
 	}
 
 	machine := cre.Machine[int]{}
-	
+
 	machine.LoadProgram(program)
 	machine.LoadMemory(block)
-	
+
 	machine.Register(0, read)
 	machine.Register(1, write)
 
@@ -40,6 +40,9 @@ func main() {
 	}
 }
 
+// read implements a basic input function for the creature. It waits until it
+// has recieved one byte of user input, and then pushes that byte onto the
+// stack.
 func read(machine *cre.Machine[int]) (stop bool) {
 	ch := []byte{0}
 	os.Stdin.Read(ch)
@@ -47,16 +50,23 @@ func read(machine *cre.Machine[int]) (stop bool) {
 	return
 }
 
+// write implements a basic output function for the creature. It pops one byte
+// off of the stack, and writes it to stdout.
 func write(machine *cre.Machine[int]) (stop bool) {
 	print(string(rune(machine.Pop())))
 	return
 }
 
-func logLine (message ...any) {
+// logLine prints a message to stderr.
+func logLine(message ...any) {
 	fmt.Fprintln(os.Stderr, message...)
 }
 
-func readFile (reader io.Reader) (program []int, block []int, err error) {
+// readFile reads data from an io.Reader into a program slice and a block slice.
+// Data in the file is represented by signed hexidecimal numbers, separated by
+// whitespace. Three dashes (---) divide the block data from the program data.
+// See examples/echo.
+func readFile(reader io.Reader) (program []int, block []int, err error) {
 	scanner := bufio.NewScanner(reader)
 	scanner.Split(bufio.ScanWords)
 
@@ -67,7 +77,7 @@ func readFile (reader io.Reader) (program []int, block []int, err error) {
 			break
 		}
 		if blockLen >= len(block) {
-			newSlice := make([]int, len(block) * 2)
+			newSlice := make([]int, len(block)*2)
 			copy(newSlice, block)
 			block = newSlice
 		}
@@ -77,7 +87,7 @@ func readFile (reader io.Reader) (program []int, block []int, err error) {
 			return
 		}
 		block[blockLen] = int(number)
-		blockLen ++
+		blockLen++
 	}
 	block = block[:blockLen]
 
@@ -85,7 +95,7 @@ func readFile (reader io.Reader) (program []int, block []int, err error) {
 	program = make([]int, 8)
 	for scanner.Scan() {
 		if programLen >= len(program) {
-			newSlice := make([]int, len(program) * 2)
+			newSlice := make([]int, len(program)*2)
 			copy(newSlice, program)
 			program = newSlice
 		}
@@ -95,10 +105,8 @@ func readFile (reader io.Reader) (program []int, block []int, err error) {
 			return
 		}
 		program[programLen] = int(number)
-		programLen ++
+		programLen++
 	}
 	program = program[:programLen]
 	return
 }
-
-