From 0a9995340859afadbcb48b3341607aadbd3ddf81 Mon Sep 17 00:00:00 2001
From: Kraemerd <Dominic_Daniel.Kraemer@Student.Reutlingen-University.de>
Date: Mon, 9 Jan 2023 19:14:49 +0100
Subject: [PATCH] added JavaDocs documentation to the Parser.java
---
src/main/Application.java | 4 -
src/main/Parser.java | 155 +++++++++++++++++++++++++-------------
2 files changed, 104 insertions(+), 55 deletions(-)
diff --git a/src/main/Application.java b/src/main/Application.java
index 466f25b..3c5b0cf 100644
--- a/src/main/Application.java
+++ b/src/main/Application.java
@@ -1,10 +1,6 @@
package main;
-import Exceptions.LexerException;
-import Exceptions.ParserException;
-
import java.io.BufferedReader;
-import java.io.FileNotFoundException;
import java.io.FileReader;
import java.io.IOException;
import java.util.LinkedList;
diff --git a/src/main/Parser.java b/src/main/Parser.java
index e29e094..4647716 100644
--- a/src/main/Parser.java
+++ b/src/main/Parser.java
@@ -7,17 +7,21 @@ import java.util.List;
public class Parser {
- //This abstract class is only used for heredity
- //It represents an expression in the form of an Abstract Syntax Tree(AST)
- //A method 'accept' is implemented, it is used for allowing other classes to interact with it
- //through the visiting pattern
+ /**
+ * This abstract class is only used for heredity
+ * It represents an expression in the form of an Abstract Syntax Tree(AST)
+ * A method 'accept' is implemented, it is used for allowing other classes to interact with it
+ * through the visiting pattern
+ */
public abstract class Expression {
public abstract <T> T accept(Visitor<T> visitor);
}
- //This class represents a binary operation
- //it contains a left expression, an operator, and a right expression
- //if this operation is capsuled by brackets, the value of 'capsuled' will be true, else it will be false
+ /**
+ * This class represents a binary operation
+ * it contains a left expression, an operator, and a right expression
+ * if this operation is capsuled by brackets, the value of 'capsuled' will be true, else it will be false
+ */
public class BinaryOperation extends Expression {
Expression leftExpression;
String operator;
@@ -33,13 +37,15 @@ public class Parser {
return visitor.visit(this);
}
- public <T> T accept(Visitor<T> vistor, String operator) {
- return vistor.visit(this);
+ public <T> T accept(Visitor<T> visitor, String operator) {
+ return visitor.visit(this);
}
}
- //This class represents a variable, with it holds a String 'variableName' that contains a character
- //of the alphabet
+ /**
+ * This class represents a variable, with it holds a String 'variableName' that contains a character
+ * of the alphabet
+ */
public class Variable extends Expression {
String variableName;
public Variable(String i, Boolean capsuled) {
@@ -50,13 +56,17 @@ public class Parser {
}
}
- //This abstract class is only used for heredity
- //A value can either be a number or a decimal
+ /**
+ * This abstract class is only used for heredity
+ * A value can either be a number or a decimal
+ */
private abstract class Value extends Expression {
}
- //This class represents a number, it contains a String 'digits' that holds it value
+ /**
+ * This class represents a number, it contains a String 'digits' that holds it value
+ */
public class Number extends Value {
public String digits;
public Number(String i) {
@@ -67,7 +77,9 @@ public class Parser {
}
}
- //This class represents a decimal, it contains two numbers: the one before- and the one after the dot
+ /**
+ * This class represents a decimal, it contains two numbers: the one before- and the one after the dot
+ */
public class Decimal extends Value {
public Number beforeDot;
public Number afterDot;
@@ -81,8 +93,13 @@ public class Parser {
}
}
- //starting method of the parser
- //parses a list of tokens and returns the AST (Abstract Syntax Tree)
+ /**
+ * starting method of the parser that parses a list of tokens into an AST (Abstract Syntax Tree)
+ * @param list The list of tokens
+ * @return Expression Returns the Expression object that represents the AST
+ * @throws ParserException If the list of tokens was empty or not all tokens could be used in
+ * the process due to wrong syntax/semantic
+ */
public Expression parse(List<Lexer.Token> list) throws ParserException {
if(list.isEmpty()) {
throw new ParserException("empty token list");
@@ -97,8 +114,12 @@ public class Parser {
return ast;
}
- //called by method parse(...)
- //parses a list of tokens into an expression
+ /**
+ * parses a list of tokens into an expression (maybe with recursive calls through parseBinaryOperation(...)
+ * @param ts The list of tokens
+ * @return The expression object that got parsed
+ * @throws ParserException If the list of tokens was empty
+ */
private Expression parseExpression(List<Lexer.Token> ts) throws ParserException {
if(ts.isEmpty()) {
throw new ParserException("SyntaxError: empty token list");
@@ -116,12 +137,14 @@ public class Parser {
return ast;
}
- //called by parseExpression
- //checks if there are multiple tokens left, which indicates that they build up a BinaryOperation
- //It splits up the tokens into a left and right expression and with a recursive call of parseExpression
- //each part will be determined, until all BinaryOperations consist of finite left and right expressions
- //Then a new BinaryOperation will be returned, which saves the left- & right expression and the operator
- //between them
+ /**
+ * checks if there are multiple tokens left, which indicates that they build up a BinaryOperation
+ * It splits up the tokens into a left and right expression and with a recursive call of parseExpression
+ * each part will be determined, until all BinaryOperations consist of finite left and right expressions
+ * @param ts The list of tokens
+ * @return null If the list does not contain a BinaryOperation (anymore) or: BinaryOperation The crated BinaryOP
+ * @throws ParserException If the list of tokens was empty
+ * */
private BinaryOperation parseBinaryOperation(List<Lexer.Token> ts) throws ParserException {
if(ts.isEmpty()) {
throw new ParserException("SyntaxError: empty token list");
@@ -178,10 +201,13 @@ public class Parser {
}
- //called by parseBinaryOperator
- //checks if the first token is a bracket
- //If yes: checks if the bracket gets closed correctly and returns the index of the closing bracket
- //If no: returns -1
+ /**
+ * checks if the first token is a bracket
+ * @param ts The List of tokens
+ * @return int The position of the token with the closing bracket or -1 if the first token wasn't a bracket
+ * @throws ParserException If the list of tokens was empty, a bracket never gets closed or there isn't any
+ * value between the brackets
+ */
private int parseBrackets(List<Lexer.Token> ts) throws ParserException{
if(ts.isEmpty()) {
throw new ParserException("SyntaxError: empty token list");
@@ -207,7 +233,7 @@ public class Parser {
}
//If no matching closing bracket was found a ParserException will be thrown
if(!found) {
- throw new ParserException("SyntaxError: brackets never got closed");
+ throw new ParserException("SyntaxError: bracket never got closed");
}
//If the closing bracket was placed immediately after the opening bracket a ParserException will be thrown
if(index==1) {
@@ -220,9 +246,11 @@ public class Parser {
}
- //called by parseBinaryOperation
- //checks if a String only contains an allowed operator with parseCharacter
- //if not: throws a ParserException
+ /**
+ * Checks if a String only contains an allowed operator
+ * @param operator The string that represents the operator
+ * @throws ParserException If the operator token was too big, small or consisted of invalid characters
+ */
private void parseOperator(String operator) throws ParserException {
if(operator.isEmpty()) {
throw new ParserException("RuntimeError: empty String instead of an operator (+, -, *, /, ^");
@@ -235,10 +263,13 @@ public class Parser {
}
}
- //called by parseExpression
- //Checks if a token is a variable:
- //Yes: returns a new Variable that gets created with the received token
- //No: returns null
+ /**
+ * Checks if a token is a variable:
+ * @param ts List of tokens
+ * @return null It the token isn't a variable or: Variable A new Variable that gets created with the received token
+ * @throws ParserException If the list of tokens was empty or the size of the token was too big
+ * or too small for a variable
+ */
private Variable parseVariable(List<Lexer.Token> ts) throws ParserException {
if (ts.isEmpty()) {
throw new ParserException("SyntaxError: empty token list");
@@ -264,7 +295,13 @@ public class Parser {
}
- //called by method parseException
+ /**
+ * Checks if a token is a value and if so creates and returns a new Number or Decimal object
+ * @param ts The List of the tokens
+ * @return null If the token isn't a value/number or: Value The created Number or Decimal Object
+ * @throws ParserException If the list of tokens is empty or
+ */
+
//Checks if a token is a value:
//Yes: returns a new Number or Decimal that gets created with the received token
//No: returns null
@@ -286,8 +323,12 @@ public class Parser {
return parseNumber(data, false);
}
- //called by method parseValue
- //parses a decimal of a string
+
+ /**
+ * parses a String into a Decimal object that consists of two numbers
+ * @param data The String that contains the value
+ * @return Decimal Returns the new Decimal object
+ */
private Decimal parseDecimal(String data) throws ParserException {
if(data.isEmpty()) {
throw new ParserException("SyntaxError: empty data");
@@ -301,9 +342,12 @@ public class Parser {
return new Decimal(beforeDot, afterDot);
}
- //called by method parseValue or parseDecimal
- //parses a String into a number
- //the parameter afterDot will be set on 'true' if the number is used after a dot of a decimal
+ /**
+ * parses a String into a Number object
+ * @param data The String that contains the value
+ * @param afterDot If this Number will be used after a dot in a Decimal object
+ * @return Number Returns the new Number object
+ */
private Number parseNumber(String data, boolean afterDot) throws ParserException{
if (data.isEmpty()) {
throw new ParserException("RuntimeException: empty token");
@@ -328,9 +372,11 @@ public class Parser {
return new Number(data);
}
- //called by method parseNumber
- //checks if a String only contains numbers(including zero) with parseCharacter
- //if not, a ParserException is thrown
+ /**
+ * checks if a String only contains numbers(including zero)
+ * @param data The String that gets checked
+ * @exception ParserException If the data is empty or does contain invalid characters
+ */
private void parseDigit(String data) throws ParserException {
for(int index=0; index<data.length(); index++) {
if(data.isEmpty()) {
@@ -343,9 +389,11 @@ public class Parser {
}
}
- //called by method parseNumber
- //checks if a String only contains numbers(excluding zero) with parseCharacter
- //if not, a ParserException is thrown
+ /**
+ * checks if a String only contains numbers(excluding zero)
+ * @param data The String that gets checked
+ * @exception ParserException If the data is empty or does contain invalid characters
+ */
private void parseDigitWithoutZero(String data) throws ParserException {
if(data.isEmpty()) {
throw new ParserException("RuntimeError: empty String instead of a digit(1-9)");
@@ -358,8 +406,13 @@ public class Parser {
}
}
- //called by multiple methods e.g. parserOperator, parseDigit
- //checks if a certain string can be found in a String of allowed characters and returns the result
+ /**
+ * checks if a certain string can be found in a String of allowed characters
+ * @param data The String
+ * @param allowedCharacters The String of allowed characters
+ * @return boolean Returns if data was found in allowedCharacters or not
+ * @exception ParserException If the data is empty
+ */
private boolean parseCharacter(String data, String allowedCharacters) throws ParserException {
if(data.isEmpty()) {
throw new ParserException("RuntimeError: empty String");
--
GitLab