Update README.md

Author: Elzawawy

README.md

@@ -1,33 +1,61 @@
 <h1 align='center'>Yet Another Java ByteCode Generator</h1>
-
-Built using Flex & Bison to take in any java source code and emits its equivalent bytecode. This is a project developed for the PLT (**P**rogramming **L**anguage **T**ranslation) course at Faculty of Engineering, Alexandria University in Spring 2020 Offering.
+<h3 align='center'>(A javac-like Compiler)</h3>
 
 <p align='center'><img src='./images/cover.png'/></p>
 
-## Translation of Productions
-Each production is associated with a **semantic actions**. This semantic actions will be generated when the production is matched by the parser.
+## Overview
+A java bytecode generator/compiler built over the tools Flex & Bison to take in any java source code (a subset only of Java Lang is covered) and emits its equivalent bytecode. This is a project developed for the PLT (**P**rogramming **L**anguage **T**ranslation) course at Faculty of Engineering, Alexandria University in Spring 2020 Offering.
+
+The **goal** is to practice techniques of constructing semantics rules to generate java bytecode. Generated bytecode must follow Standard bytecode instructions defined in [Java Virtual Machine Specification].(http://java.sun.com/docs/books/jvms/second_edition/html/VMSpecTOC.doc.html)
+
+Our **workflow** included the following steps: 
+1. Understanding the **Flex & Bison tools** we are going to build upon. 
+2. Understanding the **Semantic Actions/Rules asscoiated with a Java CFG**.
+3. Understanding the **Java Bytecode** we are required to generate as an intermediate code represenattion. 
+4. Building the Java bytecode generator upon the building blocks we understood.
+
+
+## Flex & Bison Tools
+Flex and bison are modern replacements for the classic lex and yacc that were both developed at Bell Laboratories in the 1970s.
+Flex and bison are tools designed for writers of compilers and interpreters, although they are also useful for many applications that will interest noncompiler writers. Any application that looks for patterns in its input or has an input or command language is a good candidate for flex and bison. Furthermore, they allow for rapid application prototyping, easy modification, and simple maintenance of programs. 
+
+To stimulate your imagination, here are a few things people have used flex and bison, or their predecessors lex and yacc, to develop:
+- The desktop calculator bc
+- The tools eqn and pic, typesetting preprocessors for mathematical equations and complex pictures
+- Many other “domain-specific languages” targeted for a particular application
+- PCC, the Portable C Compiler used with many Unix systems
+- Flex itself
+- A SQL database language translator
+
+
+## Translation of Productions to Semantic Actions/Rules.
+
+Each production is associated with a **semantic actions**. This semantic actions will be generated when the production is matched by the parser. The semantic actions/rules we developed in this case is ones that produce teh equivalent java bytecode to the following statement matched by parser.
+
+We explain next two non-terminals and their semantic actions as example to our idea and the rest can be found and traced in the code itself. Then we move to a further step into inermediate code generaton which is essential, namely, Backpatching. 
+
+### Example 1: Method Body
+The generated code consists of a header,footer alongside with the statment list that contains the rest of the code,where the header appends the equivalent java byte-code for the class,the main method and sets the stack and locals size.
+The footer generetes a return from the method.
 
+### Example 2: IF
+- Sends the true list of the boolean expression and the first marker instruction index to the backpatching function.
+- Sends the false list of the boolean expression and the second marker instrcution index to the backpatching function.
+- Perform the merging of lists logic
 
-## Backpatching
+### More Into Code Generation: Backpatching
 When generating code for boolean expressions and flow-of-control statements is that of matching a jump instruction with the target of the jump. For example, the translation of the boolean expression B in **if ( B ) S**, the target of the jump when **B** is false will not be declared until **S** is examined. In a
 one-pass translation, the problem is solved by passing labels as inherited attributes to where the relevant jump instructions were generated. But a separate pass is then needed to bind labels to addresses.
 
 ***Backpatching*** counters the problem of two-passes translation by having lists of jumps are passed as synthesized attributes. Specifically, when a jump
 is generated, the target of the jump is temporarily left unspecified. Each such jump is put on a list of jumps whose labels are to be filled in when the proper
 label can be determined.
 
-## Method Body
-The generated code consists of a header,footer alongside with the statment list that contains the rest of the code,where the header appends the equivalent java byte-code for the class,the main method and sets the stack and locals size.
-The footer generetes a return from the method.
 
-## IF
--Sends the true list of the boolean expression and the first marker instruction index to the backpatching function.
--Sends the false list of the boolean expression and the second marker instrcution index to the backpatching function.
--Perform the merging of lists logic
+## Assumptions Made
 
-## Assumptions
-### Java Used Grammar
-The input programs we are dealing with follow the below rules. These aren't a full java grammar but a subset of it.
+### The subset of Java grammar used
+These aren't a full java grammar but a subset of it. It covers the requirements that were imposed on us by the project to be delivered. We make the natural assumption that input programs must follow the below rules and not just any java code. Howwever, we develop the code to be extensible easily to the rest of the Java set of rules.
 
 ```
 method_body: 
@@ -82,24 +110,40 @@ boolean_expression:
                     |expression REL_OP expression
 ```
 
-## Running & Testing
+## Design & Code Anatomy
+
+- `java_lexical_analyzer.l` ---> The Flex input file which the tool generates from a Lexical Analayzer for our Java subset.
+
+- `java_parser.y` ---> The Bison input file which the tool generates from a Parser for our Java subset. 
+
+- `semantic_actions_utils.h` ---> The file that contains all utility functions that are used in the intermediate code generation and semantic actions for each production. 
+
+- `Makefile` ---> Defines rules for bash commands that is needed to build,test and run the code. 
+
+- `run.sh` ---> Defines a simple way to execute Make rules easily.
+
+### Running & Testing Using run.sh 
 
 To run the program, use the script `run.sh` as follows:
 
     ./run.sh file_name
 where filename, can be any file that contains java source code.
 
-For testing purposes while development use this,
+For **testing purposes** while development use this,
 
     ./run.sh --debug file_name
 or
 
     ./run.sh -d file_name
 
-where file_name is a file that exists in the `test-cases` folder. The extra argument will ensure we keep all our test files from the `test-cases` folder and picking the suitable unit test case for the part you're developing.
+where file_name in this case is a file that exists in the `test-cases` folder. The extra argument will ensure we keep all our test files from the `test-cases` folder and picking the suitable unit test case for the part you're developing.
 
 ## Resources
 
+- Compilers, Principles, Techniques, & Tools, Second Edition by Alfred V. Aho & Monica S. Lam & Ravi Sethi & Jeffrey D. Ullman
+
+- Engineering a Compiler, Second Edition by Keith D. Cooper & Linda Torczon.
+
 ### Understanding Flex & Bison
 
 - [Flex & Bison by John Levine. The definitive textbok for using these tools.](http://web.iitd.ac.in/~sumeet/flex__bison.pdf)
@@ -112,6 +156,4 @@ where file_name is a file that exists in the `test-cases` folder. The extra argu
 
  - [Wiki's Java bytecode](https://en.wikipedia.org/wiki/Java_bytecode) and the [list of the instructions that make up the Java bytecode.](https://en.wikipedia.org/wiki/Java_bytecode_instruction_listings)
 
-### Understanding Jasmin
-
 - [Jasmin Official Documentation.](http://jasmin.sourceforge.net/)