Update Documentation.md

bytexenon · web-flow · commit 29d8e812f8d6 · 2024-04-25T04:31:41.000-07:00
diff --git a/docs/Documentation.md b/docs/Documentation.md
@@ -1,192 +1,28 @@
 # MathParser.lua Documentation
+- [MathParser.lua Documentation](#mathparserlua-documentation)
+  - [Introduction](#introduction)
+  - [Detailed Breakdown](#detailed-breakdown)
+    - [Lexer](#lexer)
+    - [Parser](#parser)
+    - [Evaluator](#evaluator)
 
-## Overview
-`MathParser.lua` is a Lua module that provides functionality for parsing and evaluating mathematical expressions. It uses a Lexer, Parser, and Evaluator to tokenize, parse, and evaluate expressions respectively.
+## Introduction
 
-## Dependencies
-- `Evaluator`: Evaluates the Abstract Syntax Tree (AST) of a mathematical expression.
-- `Lexer`: Tokenizes a mathematical expression into a list of tokens.
-- `Parser`: Parses a list of tokens into an AST.
+MathParser.lua is a tool that can understand and solve math problems given as text. It's built around three main parts: "Lexer", "Parser", and "Evaluator". Each part plays a key role in understanding and solving the math problems that are given to it.
 
-## Methods
+## Detailed Breakdown
 
-### `MathParserMethods:tokenize(expression)`
-Tokenizes the given expression into a list of tokens. Each token represents a mathematical symbol or number.
+### Lexer
 
-Example:
-```lua
-local tokens = MathParser:tokenize("2 + 2")
--- tokens: { {TYPE = "Number", Value = "2"}, {TYPE = "Operator", Value = "+"}, {TYPE = "Number", Value = "2"} }
-```
+The Lexer is the first step. It takes a text input, which is a math problem, and breaks it down into a list of words and symbols. This list is called tokens. The Lexer is good at recognizing different things like numbers, variables, math symbols, and more. This process lets us understand the problem in smaller pieces, getting it ready for the next step.
 
-### `MathParserMethods:parse(tokens)`
-Parses the given tokens into an Abstract Syntax Tree (AST). The AST represents the hierarchical structure of the mathematical expression.
+### Parser
 
-Example:
-```lua
-local AST = MathParser:parse({ {TYPE = "Number", Value = "2"}, {TYPE = "Operator", Value = "+"}, {TYPE = "Number", Value = "2"} })
--- AST: { TYPE = "Operator", Value = "+", Left = { TYPE = "Number", Value = "2" }, Right = { TYPE = "Number", Value = "2" } }
-```
+The Parser takes over from the Lexer. It takes the list of tokens and turns it into a tree structure, called an Abstract Syntax Tree (AST). The AST is a way of showing the math problem where each branch is a math operation, and the leaves are the numbers or variables. This tree structure lets us understand the problem in terms of its math relationships, which is important for solving it correctly.
 
-### `MathParserMethods:evaluate(AST)`
-Evaluates the given AST and returns the result of the mathematical expression.
+Example of an AST:  
+![Parsing Example](https://upload.wikimedia.org/wikipedia/commons/6/68/Parsing_Example.png)
 
-Example:
-```lua
-local result = MathParser:evaluate({ TYPE = "Operator", Value = "+", Left = { TYPE = "Number", Value = "2" }, Right = { TYPE = "Number", Value = "2" } })
--- result: 4
-```
+### Evaluator
 
-### `MathParserMethods:solve(expression)`
-Solves the given expression by tokenizing, parsing, and evaluating it. This is a convenience method that combines the tokenize, parse, and evaluate methods.
-
-Example:
-```lua
-local result = MathParser:solve("2 + 2")
--- result: 4
-```
-
-### `MathParserMethods:addVariable(variableName, variableValue)`
-Adds a variable and sets its value.
-
-Example:
-```lua
-MathParser:addVariable("x", 5)
-local result = MathParser:solve("x + 2")
--- result: 7
-```
-
-### `MathParserMethods:addVariables(variables)`
-Adds multiple variables and sets their values.
-
-Example:
-```lua
-MathParser:addVariables({x = 5, y = 2})
-local result = MathParser:solve("x + y")
--- result: 7
-```
-
-### `MathParserMethods:addFunction(functionName, functionValue)`
-Adds a function to the parser, allowing it to be used in mathematical expressions.
-
-Example:
-```lua
-MathParser:addFunction("double", function(a) return a * 2 end)
-local result = MathParser:solve("double(5)")
--- result: 10
-```
-
-### `MathParserMethods:addFunctions(functions)`
-Adds multiple functions to the parser, allowing them to be used in mathematical expressions.
-
-Example:
-```lua
-MathParser:addFunctions({double = function(a) return a * 2 end, triple = function(a) return a * 3 end})
-local result = MathParser:solve("double(5) + triple(5)")
--- result: 25
-```
-
-### `MathParserMethods:setOperatorPrecedenceLevels(operatorPrecedenceLevels)`
-Sets the operator precedence levels that the parser will use.
-
-Example:
-```lua
-MathParser:setOperatorPrecedenceLevels({
-  Unary = { ["-"] = 2 },
-  Binary = { ["+"] = 1, ["-"] = 1, ["++"] = 1 }
-})
-```
-
-### `MathParserMethods:setVariables(variables)`
-Sets the variables that the evaluator will use.
-
-Example:
-```lua
-MathParser:setVariables({x = 5, y = 2})
-```
-
-### `MathParserMethods:setOperatorFunctions(operatorFunctions)`
-Sets the operator functions that the evaluator will use.
-
-Example:
-```lua
-MathParser:setOperatorFunctions({
-  Unary = { ["-"] = function(a) return -a end },
-  Binary = {
-    ["+"] = function(a, b) return a + b end,
-    ["-"] = function(a, b) return a - b end,
-    ["++"] = function(a, b) return 2 * (a + b) end
-  }
-})
-```
-
-### `MathParserMethods:setOperators(operators)`
-Sets the operators that the lexer will use.
-
-Example:
-```lua
-MathParser:setOperators({"+", "-", "++"})
-```
-
-### `MathParserMethods:setFunctions(functions)`
-Sets the functions that the evaluator will use.
-
-Example:
-```lua
-MathParser:setFunctions({
-  double = function(a) return a * 2 end,
-  triple = function(a) return a * 3 end
-})
-```
-
-### `MathParserMethods:resetToInitialState(operatorPrecedenceLevels, variables, operatorFunctions, operators, functions)`
-Resets the `MathParser` to its initial state with the provided operator precedence levels, variables, operator functions, operators, and functions. If any of these parameters are not provided, the corresponding property will be reset to its default value.
-
-## Class
-
-### `MathParser:new(operatorPrecedenceLevels, variables, operatorFunctions, operators, functions)`
-Creates a new MathParser. You can specify operator precedence levels, variables, operator functions, operators, and functions. If you don't specify any of these, the default values will be used.
-
-Example:
-```lua
---* Dependencies *--
-local MathParser = require("MathParser")
-
---* Constants *--
-local OPERATOR_PRECEDENCE_LEVELS = {
-  Unary = {
-    -- Unary minus precedence
-    ["-"] = 2
-  },
-  Binary = {
-    ["+"] = 1,
-    ["-"] = 1
-  },
-}
-
-local VARIABLES = {
-  x = 5
-}
-
-local OPERATOR_FUNCTIONS = {
-  Unary = {
-    ["-"] = function(a) return -a end,
-  },
-  Binary = {
-    ["+"] = function(a, b) return a + b end,
-    ["-"] = function(a, b) return a - b end
-  }
-}
-
-local OPERATORS = { "-", "+" }
-
-local FUNCTIONS = {
-  double = function(a) return a * 2 end
-}
-
--- Create an instance of MathParser with custom operator precedence levels and functions
-local myMathParser = MathParser:new(OPERATOR_PRECEDENCE_LEVELS, VARIABLES, OPERATOR_FUNCTIONS, OPERATORS, FUNCTIONS)
-local result = myMathParser:solve("2 - -x + double(2)")
-
-print(result) -- Outputs: 11
-```
+The Evaluator is the last step. It takes the AST from the Parser and solves it to give the answer. The Evaluator goes through the AST, doing the math operations as it goes along. The result of this is the final answer to the math problem.
