cool things

README.MD

@@ -1,7 +1,7 @@
 # The Translators α Compiler
 #### Members: Annie Slenker, Meyer Simon, Partho Bhattacharya, & Scarlett Kadan
 
-## Alpha Compiler Flags & Expected Results
+## Alpha Compiler Flags & Expected Results:
 ### -tok
 Prints the token stream provided by the Lexical Analyzer to a `.tok` file. Output can be found in `/out/<file>.tok`. Tokenization follows the specified format found in the alpha language spec.
 
@@ -27,48 +27,55 @@ Prints debug messages to the console if present. Our debug messages utilizes a w
 Prints a general help message. (If you read this far, you probably won't need this flag)
 
 
-## Testing
+## Alpha Tools: Testing & Building
+We have built a few tools to aid in the development processes. These include `./test.sh` and `./genx.sh`. Below you can find information about each.
 
- **Arguments:** 
-    -exp    Generate expected output files
-    -diff   Compare output files with expected output files
-    -help   Show this help message
+### ./test.sh
+All tests under sprint 1, 2, 3, & 4 will work with the testing suite, along with running it directly with the alpha executable. These files do not use the `#include` directive, instead opting to define everything used within the file.
+> **Arguments:**</br> 
+>    `-exp`     Generate expected output files</br>
+>    `-diff`    Compare output files with expected output files</br>
+>    `-help`    Show this help message</br>
 
- **Usage:**
-    ./test.sh <file.alpha> [flags]   Run the test on a single file
-    ./test.sh <directory> [flags]   Run the test on all files in a directory
+> **Usage:**</br>
+>    `./test.sh <file.alpha> [flags]`   Run the test on a single file</br>
+>    `./test.sh <directory> [flags]`   Run the test on all files in a directory</br>
 
- **Examples:** 
- - ./test.sh test.alpha   
- - - Runs test flags in header on test.alpha
- - ./test.sh test/
- - - Runs test flags in header on all .alpha files in test/
- - ./test.sh test/ -exp
- - - Runs test flags in header on all .alpha files in test/ and generates expected output files
- - ./test.sh test/ -diff
- - - Runs test flags in header on all .alpha files in test/ and compares output files with expected output files
-- ./test.sh test/ -exp -diff
-- - Runs test flags in header on all .alpha files in test/ and generates expected output files and compares output files with expected output files
+> **Examples:** </br>
+>    `./test.sh test.alpha`   Runs test flags in header on test.alpha</br>
+>    `./test.sh test/`   Runs test flags in header on all .alpha files in test/</br>
+>    `./test.sh test/ -exp`   Runs test flags in header on all .alpha files in test/ and generates expected output files</br>
+>    `./test.sh test/ -diff`   Runs test flags in header on all .alpha files in test/ and compares output files with expected output files</br>
+>    `./test.sh test/ -exp -diff`   Runs test flags in header on all .alpha files in test/ and generates expected output files and compares output files with expected output files</br>
 
- **Notes:**
-    To create a test file, on the first line of the .alpha file, add:
-    (* TEST: [ <test_flags> ] *)
-    where <test_flags> are the alpha flags to be used. Ex:
-    (* TEST: [ -debug -asc -tc ] *)
+> **Notes:**</br>
+>    To create a test file, on the first line of the .alpha file, add:</br>
+>    `(* TEST: [ <test_flags> ] *)`</br>
+>    where <test_flags> are the alpha flags to be used. Ex:</br>
+>    `(* TEST: [ -debug -asc -tc ] *)`</br>
 
+### ./genx.sh
+GenX is our preprocessor tool. It is able to handle `#include` statements within an alpha file. The tool allows for includes of `.alpha`, `.s`, and `.c` files, given a relative path to them. You can also include our library file `std.alpha` which does not require a relative path.</br>
 
+**NOTE:** *Due to the nature of include statements, running the alpha compiler on alpha files that use include statements will most likely result in syntax/type errors. When dealing with a file with include statements, it is advised to use GenX.*
 
-## Lexical Analyzer
-* **Undefined Behavior:**
+> **Arguments:** </br>
+>    `-help`    Displays this message</br>
+
+> **Usage:** </br>
+>    `./genx.sh <file.alpha || file.s>`  </br>Generates executable file from <file.alpha></br>
+
+> **Notes:** </br>
+>    Generates .s and links alpha driver and general library and other includes.</br>
+
+## Other Notes: 
+
+### Lexical Analyzer
+**Undefined Behavior:**</br>
 * Spaces are not required between tokens. For instance, an INTEGER and an ID are valid even if there is no space between them
 ```
 Input:		*5variable*
 Output:		2 14 301 "5"
 			1 1 101 "variable"
 ```
-
-## Syntax Analyzer
-* *Incomplete*
-
-## Symbol Table
-* *TODO: Create diagram.*
+* Added an `#include` token to stop syntax errors from being reported on certain alpha files.

tests/programs/array.alpha

@@ -0,0 +1,20 @@
+#include "std.alpha"
+
+type main: string -> integer
+function entry: main
+
+(* maybe some other type definitions *)
+
+entry(arg) := {
+    [ string: one_name; string: another_name ]
+    
+    one_name := "a string literal";
+    
+    another_name := reserve another_name(4);
+    another_name(0) := 'C';
+    another_name(1) := 'a';
+    another_name(2) := 'r';
+    another_name(3) := 'l';
+
+    return 0;
+}

tests/programs/io.alpha

@@ -1,27 +0,0 @@
-#include "std.alpha"
-
-function entry: string2integer
-
-entry (arg) := {
-    [integer: x; string: s; character: c; integer: result]
-
-    result := printCharacter('\t');
-    result := printCharacter('t');
-    result := printCharacter('a');
-    result := printCharacter('b');
-    result := printCharacter('\n');
-    result := printCharacter('\\');
-    result := printCharacter('"');
-    result := printCharacter('\'');
-
-    (*s := inS(1);
-    result := printS(s);
-
-    x := inI(1);
-    result := printI(x);
-
-    c := inC(1);
-    result := printC(c);*)
-
-    return 0;
-}

tests/programs/ll.alpha

@@ -1 +0,0 @@
-(* TODO: creates a linked list and prints out the chain. *)

tests/sprint4/test/sp4_tc_arrays.alpha

@@ -1,27 +0,0 @@
-type string: 1 -> character
-type a_of_s: 1 -> string
-type main: integer -> integer
-function entry: main
-
-(* maybe some other type definitions *)
-
-entry(arg) := {
-    [ string: one_name; string: another_name; a_of_s: many_names ]
-    one_name := "a string literal";
-    another_name := reserve another_name(4); (* reserve space for an an array of character, with 4 members *)
-    another_name(0) := 'C';
-    another_name(1) := 'a';
-    another_name(2) := 'r';
-    another_name(3) := 'l';
-    many_names := reserve many_names(3);
-    many_names(0) := one_name;
-    many_names(1) := another_name;
-    many_names(2) := reserve many_names(2)(6); (* reserve space for an item of the same type as a_of_s(2), an array of character, with 6 members *)
-    many_names(2)(0) := 'P';
-    many_names(2)(1) := 'a';
-    many_names(2)(2) := 'r';
-    many_names(2)(3) := 't';
-    many_names(2)(4) := 'h';
-    many_names(2)(5) := 'o';
-    return 0;
-}