Implement constants in AO lang

Author: arda-guler

docs/AO_language.txt

@@ -1,5 +1,5 @@
 AO Programming Language
-= = = = = = = = = = = = =
+- - - - - - - - - - - - - - - - - - - - - - - 
 
 The AO (ASM Operands) language is a very low-level assembly language designed for TurnaCore machines. 
 It matches 1-to-1 to the equivalent compiled binary machine code. Actually, the only thing it makes is to
@@ -76,7 +76,31 @@ Later, when you want to jump to the label, you can simply do the following:
 	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 
 	JMP this_is_a_label
 	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+	
+Sometimes, you would like to use certain constants in your program. These numbers can be defined in a way similar
+to the C language's #define. The syntax for defining constants is as follows:
 
+	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 
+	#pi=3
+	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+	
+The # denotes that this expression is a constant definition. 'pi' is the name of your constant and 3 is the value. Please note that
+spaces are NOT allowed. 
+
+After defining a constant, you can use it anywhere in your code by simply typing its name. For example, if you want to 
+see whether pi is larger than the value in Register 2 and jump to a label if so, you can write the following:
+
+	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 
+	MR1 pi
+	JG some_label_defined_somewhere_else
+	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+	
+Since we defined the value of pi as 3, this is esentially the same thing as writing:
+
+	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 
+	MR1 3
+	JG some_label_defined_somewhere_else
+	= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 
 AO files are compiled into CIS (compiled instruction sequence) files. These are the files which the CPU reads.
 

programs/conditionals.ao

@@ -1,16 +1,25 @@
+; = = = = = = = = =
 ; CONDITIONALS.AO
+; = = = = = = = = =
 ; Author: arda-guler
-;
-; This is a simple counter that counts up to 200
+; = = = = = = = = =
+; This is a simple counter that counts up to the given value
 ; Uses the JL (jump if less than) instruction
+; = = = = = = = = =
+; INPUTS:
 
-MR1 200
+#TARGET=200
+; = = = = = = = = =
+; OUTPUTS: NONE
+; = = = = = = = = =
+
+MR1 TARGET
 MR1 NULL
 
 loop:
 MR2 1
 ADD
-MR2 200
+MR2 TARGET
 JL loop
 WRITE
 HALT

programs/deceleration_integrator.ao

@@ -9,23 +9,34 @@
 ; Assumes constant time step of 1. (So I don't need to keep
 ; calling the multiplication function every loop.)
 ; = = = = = = = = = = = = = = =
+; INPUTS:
+
+#INIT_POS=3000
+
+; this is actually velocity + 100
+; since there are no negative numbers
+; we will use 100 as our zero point.
+#INIT_VEL=150
+#DECEL_RATE=10
+; = = = = = = = = =
+; OUTPUTS:
+; Final position on display register, Register 5.
+; Also saves it on memory address 2.
+; = = = = = = = = =
 
 JMP start
 
 ; - - - - - - - - - -
 ; VARIABLES
 ; - - - - - - - - - -
 ; address 2 - position
-3000
+INIT_POS
 
 load_vel_into_r2:
 MR2
 
-; this is actually velocity + 100
-; since there are no negative numbers
-; we will use 100 as our zero point
 ; address 4 - velocity
-150
+INIT_VEL
 JMP return_update_pos
 
 ; - - - - - - - - - -

programs/division.ao

@@ -1,17 +1,32 @@
+; = = = = = = = = =
 ; DIVISION.AO
+; = = = = = = = = =
 ; Author: arda-guler
-;
-; Dividing 100 by 15, saving the quotient and the remainder on memory
+; = = = = = = = = =
+; Dividing the given dividend by the given divisor, saving the quotient and the remainder on memory
 ; Also displays quotient on display register (register 5)
+; = = = = = = = = =
+; INPUTS:
+
+#DIVIDEND=100
+#DIVISOR=15
+; = = = = = = = = =
+; OUTPUTS:
+; Saves quotient and remainer on memory locations ADR_COUNTER and ADR_REMAINDER
+; Also displays quotient on display register, Register 5.
+
+#ADR_COUNTER=2000
+#ADR_REMAINDER=2001
+; = = = = = = = = =
 
 ; Initialize the counter variable at address 2000
-MR1 1
-MR2 2000
+MR1 0
+MR2 ADR_COUNTER
 MEMW
 
 ; load the dividend and divisor
-MR1 100
-MR2 15
+MR1 DIVIDEND
+MR2 DIVISOR
 
 loop:
 ; subtract divisor
@@ -21,40 +36,39 @@ SUB
 WRITE
 
 ; increase counter
-MR2 2000
+MR2 ADR_COUNTER
 MEMR
 MR2 1
 ADD
-MR2 2000
+MR2 ADR_COUNTER
 MEMW
 
 ; get dividend into R1 again to continue
 RECALL
 
 ; if dividend is still larger than divisor, loop
-MR2 15
+MR2 DIVISOR
 JG loop
 
-; if the int is divisible exactly, we need to increment the counter one more before halting (26)
+; if the int is divisible exactly, we need to increment the counter one more before halting
 JL save_result
 WRITE
-MR2 2000
+MR2 ADR_COUNTER
 MEMR
 MR2 1
 ADD
-MR2 2000
+MR2 ADR_COUNTER
 MEMW
 RECALL
-MR2 15
+MR2 DIVISOR
 SUB
 
 save_result:
-; save remainder at address 2001
-MR2 2001
+MR2 ADR_REMAINDER
 MEMW
 
 ; display result
-MR2 2000
+MR2 ADR_COUNTER
 MEMR
 WRITE
 HALT

programs/infinite_loop.ao

@@ -1,9 +1,16 @@
+; = = = = = = = = =
 ; INFINITE_LOOP.AO
+; = = = = = = = = =
 ; Author: arda-guler
-;
+; = = = = = = = = =
 ; This is an infinite loop example where
 ; we just keep incrementing the same
 ; value.
+; = = = = = = = = =
+; INPUTS: NONE
+; = = = = = = = = =
+; OUTPUTS: NONE
+; = = = = = = = = =
 
 MR1 NULL
 MR2 1

programs/multiplication.ao

@@ -1,26 +1,42 @@
+; = = = = = = = = =
 ; MULTIPLICATION.AO
+; = = = = = = = = =
 ; Author: arda-guler
-;
-; Multiplying 13 and 27.
+; = = = = = = = = =
+; Multiplying two given numbers.
+; = = = = = = = = =
+; INPUTS:
+
+#NUM_1=13
+#NUM_2=27
+; = = = = = = = = =
+; OUTPUT:
+
+; The result will be given in the display register, Register 5.
+; = = = = = = = = =
+
+#ADR_VAR=2000
 
 ; Initialize a loop counter using register 5
-MR1 14
+MR1 NUM_1
+MR2 1
+ADD
 WRITE
 
-; Initialize a variable at memory location 2000
+; Initialize a variable
 MR1 NULL
-MR2 2000
+MR2 ADR_VAR
 MEMW
 
 loop:
 ; read value from memory
-MR2 2000
+MR2 ADR_VAR
 MEMR
-; add 27
-MR2 27
+; add NUM_2
+MR2 NUM_2
 ADD
 ; save updated value to memory
-MR2 2000
+MR2 ADR_VAR
 MEMW
 ; decrease counter
 RECALL
@@ -31,7 +47,7 @@ MR2 1
 JG loop
 
 ; write result to register 5
-MR2 2000
+MR2 ADR_VAR
 MEMR
 WRITE
 

programs/simple_add.ao

@@ -1,10 +1,21 @@
+; = = = = = = = = =
 ; SIMPLE_ADD.AO
+; = = = = = = = = =
 ; Author: arda-guler
-;
+; = = = = = = = = =
 ; A simple adding operation.
+; = = = = = = = = =
+; INPUTS:
 
-MR1 15
-MR2 22
+#NUM_1=15
+#NUM_2=22
+; = = = = = = = = =
+; OUTPUTS:
+; The result will be displayed in display register, Register 5.
+; = = = = = = = = =
+
+MR1 NUM_1
+MR2 NUM_2
 ADD
 WRITE
 HALT