From ab5584190b83a8cda9cbb3469ce841dbaa3aa38a Mon Sep 17 00:00:00 2001
From: Alfie Eagleton <67986414+TheAlfanator@users.noreply.github.com>
Date: Mon, 22 Nov 2021 16:08:01 +0000
Subject: Github section -- Documentation

Added sections and code segments for Lexer and Parser. Chapter 5
---
 report/esoteric_project_report.tex | 61 ++++++++++++++++++++++++++------------
 1 file changed, 42 insertions(+), 19 deletions(-)

(limited to 'report/esoteric_project_report.tex')

diff --git a/report/esoteric_project_report.tex b/report/esoteric_project_report.tex
index 7f4035b..d4b2b78 100644
--- a/report/esoteric_project_report.tex
+++ b/report/esoteric_project_report.tex
@@ -12,6 +12,10 @@
 \usepackage{algorithmic}
 \usepackage{amsmath}
 \usepackage{mathtools}
+
+\usepackage{graphicx}
+\graphicspath{ {./images/} }
+
 \topmargin = 0pt
 \voffset = -80pt
 \oddsidemargin = 15pt
@@ -222,34 +226,53 @@ asdf
 		\caption{Grammar table for Fortran}
 	\end{center}
 \end{table}
-\chapter{Methodology}\label{MethLab}
 
-Describe here various methods that will be used in your project. Use different sections for distinctly different subjects and use subsections for specific details on the same subject. Only use subsubsections or paragraphs (which are not numbered) if you believe this is really necessary. Since implementation will happen in sprints, this section may need several updates with parts being added and deleted across the project.
 
-\section{Method 1}
-\subsection{Method 1 specific detail 1}
-In case you need maths, here is an example to write an equation:
-\begin{equation}\label{weak_form}
-\int_{\Omega_0} \delta u \frac{\partial \mathbf{P}}{\partial X}d\Omega_0 + \int_{\Omega_0} \delta u \mathbf{b} d\Omega_0 + \int_{\Omega_0} \delta u  \rho_0\mathbf{\ddot u} d\Omega_0 = 0
-\end{equation}
-And here we show how to write a matrix equation:
-\begin{equation}\label{Jacobian}
- \mathbf{X}  \frac{\partial N}{\partial e_c} =  \left[  \begin{array}{cccc} x_1 & x_2 & x_3 & x_4 \\  y_1 & y_2 & y_3 & y_4 \\  z_1 & z_2 & z_3 & z_4 \end{array} \right] \left[  \begin{array}{ccc} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0& 1 \\  -1 & -1 &  -1  \end{array} \right] 
-\end{equation}
+\chapter{Documentation}\label{MethLab}
+
+We decided it would be a good idea to note down and record our application stage by stage while developing our Esolang so that we may refer back to previous parts for reference. It will also help track our progress throughout the project to ensure we stay on track.
+
+\section{Language.java}
+Of course the very first thing that is required when it comes to translating any kind of code into execution, is the ability to read it either from command line or file. In this case, we use \texttt{Language.java} to divide line by line, essentially a while loop until EOF, end-of-file, to read all from file. Essentially our program keeps dividing from an entire source text into lines into characters and then starts building into tokens and expressions and strings until it can recognise commands. \newline
+
+\begin{figure}[h!]
+	\begin{center}
+	\includegraphics{Language.JPG}
+	\caption{A series of steps to examine source text by line using \texttt{while}}
+	\end{center}
+\end{figure}
+
+\section{TokenScanner.java \& TokenType.java}
+
+This begins the lexical analysis of our program, by examining each string by character, and identifying what type of symbol it is, whether it is text or something further such as operations. When the program reads a particular character, such as ``+'', it needs to know that it is firstly, an operator and second, a plus operand; and so we can start to identify left and right expressions to calculate Math, but this is mentioned in more detail later in the document alongside the sprints and implementation. There are other examples other than the addition operator. We also have prepared for ``-'' or subtract, the lookahead function since ``=='' is conveyed differently to ``=''. All of these are converted to tokens one by one before being sent to our parser algorithms. 
 
+\begin{figure}[h!]
+	\begin{center}
+		\includegraphics{TokenScanner.JPG}
+		\caption{An example of using \texttt{switch} to identify operands, including looking ahead for multiple character tokens}
+	\end{center}
+\end{figure}
 
-\subsection{Method 1 specific detail 2}
-blablabla
+In the image above we have identified a means for using switch statements to recognise strings and turning them into fixed tokens. This is also why we use \texttt{TokenType.java}, which uses a fixed number of enums so the program knows exactly what they have read. In t his case for example, case `*' is equal to \texttt{TokenType.STAR}, and so on. As mentioned, some tokens are multiple characters long and so we have further cases to compensate for these. They usually consist of double equals ==, or comparables such as $<$= and $>$=.
 
-\paragraph blablabla
+\section{Parser.java}
 
-\section{Method 2}
+This class is the primary code of our program. It contains everything we need to start recognising the code given and actually \emph{do} something with it. It takes a list of tokens from our analyser, and goes through our list of defined grammar, attempting to work out what each token translates to, essentially breaking down each line to find out what it is. Is it an if statement? Is it a print? Is it an expression or Math equation? We have lots of conditions is this class and each one is tested until one of them is met, denoting the result. Each possible grammar rules must match one of the conditions in the parser, otherwise it does not make sense and the code may fail to compile. We have supported this via exceptions and default case error messages. \newline
 
-\subsection{Method 2 specific detail 1}
+Conditions could include ``have they written \texttt{int} before this keyword'' or ``Is this a single colon or a double colon?'' or ``Is there a string after said colons?'' If all of these conditions are met, we can identify that a variable can be declared, for example.
 
-\section{Etc.}
+\begin{figure}[h!]
+	\begin{center}
+		\includegraphics{ParserStatement.jpg}
+		\caption{If the next line is a statement, this function identifies which statement it is using the enums from \texttt{TokenType.java}}
+	\end{center}
+\end{figure}
 
-\subsection{Etc.}
+The above code represents our decision making when it comes to identifying statements. We have two primary algorithms in this class; \texttt{matchAndAdvance()} and \texttt{matchOrError()}.
+
+\subsection{matchAndAdvance()}
+asdf
+\subsection{matchOrError()}
 
 \chapter{Implementation}\label{Impl}
 
-- 
cgit v1.2.3

