Merge pull request #207 from KennyOliver/issue-54

Issue 54
KennyOliver · Jan 15, 2025 · ceb6e81 · ceb6e81
2 parents 388cb47 + d783a15
commit ceb6e81
Show file tree

Hide file tree

Showing 48 changed files with 3,804 additions and 825 deletions.
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ FlavorLang blends coding with culinary creativity! Write programs like recipes &
 ---
 
 > [!IMPORTANT]
-> FlavorLang is currently in **Alpha**. While core functionality is largely stable, new features, syntax, and language designs are subject to change without prior notice.
+> FlavorLang is currently in **Beta**. While core functionality is largely stable, new features, syntax, and language designs are subject to change without prior notice.
 >
 > Please feel free to contribute by reporting any issues or suggestions in the repository's [Issues](https://github.com/KennyOliver/FlavorLang/issues/).
 
@@ -31,15 +31,15 @@ FlavorLang blends coding with culinary creativity! Write programs like recipes &
 
 2. [⚡ Quick Start](#quick-start)
 
-3. [🚀 Execution Flags & Behaviors](#execution-flags--behaviors)
+3. [🚀 Execution Flags &amp; Behaviors](#execution-flags--behaviors)
 
 4. [🎨 Install Syntax Highlighter Extension](#extension)
 
 ### `docs/`
 
-5. [Standard Library](docs/standard_library.md)
+5. [Tutorial](docs/tutorial.md)
 
-6. [Syntax Examples](docs/syntax_examples.md)
+6. [Standard Library](docs/standard_library.md)
 
 7. [Brainf Interpreter](docs/brainf_interpreter.md)
 
@@ -53,6 +53,8 @@ FlavorLang blends coding with culinary creativity! Write programs like recipes &
 
 12. [Interpreter](docs/interpreter.md)
 
+13. [Resources &amp; Inspirations](docs/resources.md)
+
 ---
 
 ## 🌶️ Why FlavorLang? <a id="why-flavorlang"></a>

diff --git a/docs/debugging.md b/docs/debugging.md
@@ -1,158 +1,247 @@
-# Debugging
+# FlavorLang Debugging Guide
+
+## Overview
+
+The FlavorLang interpreter provides comprehensive debugging capabilities through the `--debug` flag. This guide explains how to use debugging features effectively and understand the output at each stage of program execution.
 
 ---
 
 ## Table of Contents
 
-- [Overview](#debugging-overview)
-- [Example Script](#debugging-example-script)
-- [Debug Output Breakdown](#debugging-debug-output-breakdown)
-- [Output With and Without Debugging](#debugging-output-with-and-without-debugging)
+1. [Using the Debug Flag](#using-the-debug-flag)
+2. [Debugging Stages](#debugging-stages)
+3. [Example Debug Session](#example-debug-session)
+4. [Understanding Debug Output](#understanding-debug-output)
+5. [Common Debug Patterns](#common-debug-patterns)
+6. [Tips for Effective Debugging](#tips-for-effective-debugging)
+7. [Reference](#reference)
 
 ---
 
-## Overview <a id="debugging-overview"></a>
-
-In this section, `test3.flv` is used as an example to demonstrate how the `--debug` flag works in the Flavor interpreter. The `--debug` flag provides step-by-step insights into the tokenization, parsing, and execution of the script. This helps developers debug their code and understand the internal processing of statements like `if`, `elif`, `else`, and `serve`.
-
-## Example Script <a id="debugging-example-script"></a>
+## Using the Debug Flag
 
-```py
-let oven_temperature = 200;
+To enable debugging, append `--debug` to your FlavorLang command:
 
-if oven_temperature > 180 {
-  serve("The oven is hot!");
-} elif oven_temperature == 180 {
-  serve("The oven is just right!");
-} else {
-  serve("The oven is too cold!");
-}
+```bash
+flavor your_script.flv --debug
 ```
 
-- This script assigns a value to the variable `oven_temperature` and checks its value using conditional statements.
-- Based on the condition:
-- If the `temperature` is greater than `180`: it serves `"The oven is hot!"`.
-- If the `temperature` equals `180`: it serves `"The oven is just right!"`.
-- Otherwise, it serves `"The oven is too cold!"`.
+## Debugging Stages
 
-In this case, `test3.flv` will be executed with the `--debug` flag to illustrate how the interpreter tokenizes, parses, and executes the script step by step.
+The debugging output is divided into three main stages:
 
-## Debug Output Breakdown <a id="debugging-debug-output-breakdown"></a>
+### 1. Tokenization Stage `[DEBUG TOK]`
 
-This detailed output helps track variable values, condition evaluations, and the flow of execution, which can be extremely useful for understanding how the interpreter processes and executes your script.
+Shows how source code is broken into tokens. Each token includes:
 
-### 1. Tokenization
-
-The lexer splits the script into tokens. Each line in the script generates tokens for variable declarations, conditions, and outputs.
+- Line number
+- Token type (numeric ID)
+- Lexeme (actual content)
 
 Example:
 
 ```
-[DEBUG TOK] 1     Type: `0`  Lex: `let`
-[DEBUG TOK]       Type: `1`  Lex: `oven_temperature`
-[DEBUG TOK]       Type: `4`  Lex: `=`
-[DEBUG TOK]       Type: `2`  Lex: `200`
-[DEBUG TOK]       Type: `5`  Lex: `;`
+[DEBUG TOK] 1 Type: 0 Lex: `let`
+[DEBUG TOK] Type: 1 Lex: `stop_loop`
+[DEBUG TOK] Type: 6 Lex: `=`
 ```
 
-- **Type**: Describes the kind of token (e.g., keyword, operator, literal).
-- **Lex**: The content of the token.
+### 2. Parsing Stage `[DEBUG PRS]`
 
-### 2. Parsing
+Shows AST (Abstract Syntax Tree) construction:
 
-The parser constructs a logical structure (AST) from the tokens, identifying blocks and conditions.
+- Block structure
+- Expression parsing
+- Statement organization
 
-#### Example
+Example:
 
 ```
+[DEBUG PRS] Current Token: Type=`0`, Lexeme=`let`
+[DEBUG PRS] Starting variable declaration parse
 [DEBUG PRS] Starting to parse block
-[DEBUG PRS] Parsing token in block: type=`0`, lexeme=`if`
-[DEBUG PRS] Parsing token in block: type=`0`, lexeme=`serve`
 ```
 
-Logs indicate the parsing of each token into structured blocks for execution.
+### 3. Interpretation Stage `[DEBUG INT]`
 
-### 3. Interpretation
+Shows program execution:
 
-The interpreter executes the script step by step:
+- Variable operations
+- Function calls
+- Control flow
+- Expression evaluation
 
-- Assigns values to variables.
-- Evaluates conditional statements.
-- Executes corresponding branches.
-
-#### Example
+Example:
 
 ```
-[DEBUG INT] Matched: `AST_CONDITIONAL`
-[DEBUG INT] `interpret_conditional()` called
-[DEBUG INT] Evaluating `if`/`elif` branch
-[DEBUG INT] Binary operation `200.000000 > 180.000000`
-[DEBUG INT] Condition evaluated to: `1.000000`
-[DEBUG INT] Condition is true, executing branch body
+[DEBUG INT] Added variable `count` with is_constant=0
+[DEBUG INT] Looking up variable: `count`
+[DEBUG INT] Variable found: `count` with value `10`
 ```
 
-### `serve` in Debug Mode
+## Example Debug Session
 
-The `serve` statement is executed as part of the conditional blocks:
+Let's examine a countdown program that demonstrates various language features:
 
-#### 1. Tokenization
-
-```
-[DEBUG TOK] 4     Type: `0`  Lex: `serve`
-[DEBUG TOK]       Type: `3`  Lex: `The oven is hot!`
+```javascript
+let stop_loop = False;
+let count = 10;
+serve("Preparing for launch!");
+while stop_loop != True {
+    serve(count);
+    if count > 0 {
+        count = count - 1;
+    } else {
+        stop_loop = True;
+    }
+}
+serve("Blast off!");
 ```
 
-#### 2. Parsing
+Normal output:
 
 ```
-[DEBUG PRS] Parsing token in block: type=`0`, lexeme=`serve`
+Preparing for launch!
+10
+9
+8
+7
+6
+5
+4
+3
+2
+1
+0
+Blast off!
 ```
 
-#### 3. Interpretation
+### Understanding Debug Output
 
-This:
+Key debug messages from each stage:
 
-```
-[DEBUG INT] Matched: `AST_PRINT`
-[DEBUG INT] `interpret_print()`
-```
+1. **Tokenization**:
 
-Displays this message:
-
-```
-The oven is hot!
+```bash
+[DEBUG TOK] 1 Type: 0 Lex: `let`              # Variable declaration
+[DEBUG TOK] Type: 1 Lex: `stop_loop`          # Variable name
+[DEBUG TOK] Type: 6 Lex: `=`                  # Assignment operator
+[DEBUG TOK] Type: 2 Lex: `False`              # Boolean literal
 ```
 
-## Output With and Without Debugging <a id="debugging-output-with-and-without-debugging"></a>
+2. **Parsing**:
 
-### With Debugging (`--debug`)
+```bash
+[DEBUG PRS] Starting variable declaration parse
+[DEBUG PRS] Starting to parse block
+[DEBUG PRS] Parsing token in block: type=`8`, lexeme=`serve`
+```
 
-Full debug logs for each stage are printed.
+3. **Interpretation**:
 
 ```bash
-$ flavor tests/test3.flv --debug
-[DEBUG TOK] ...
-[DEBUG INT] ...
-The oven is hot!
+[DEBUG INT] Added variable `stop_loop` with is_constant=0
+[DEBUG INT] Variable found: `count` with value `10`
+[DEBUG INT] Operator: `>`
 ```
 
-### Without Debugging
+## Common Debug Patterns
 
-Only the final output of the script is served.
+1. **Variable Operations**
 
 ```bash
-$ flavor tests/test3.flv
-The oven is hot!
+[DEBUG INT] Added variable `count` with is_constant=0
+[DEBUG INT] Looking up variable: `count`
+[DEBUG INT] Variable found: `count` with value `10`
 ```
 
-### Running with Debugging
-
-Run this to enable debugging for `test3.flv`.
+2. **Control Flow**
 
 ```bash
-$ flavor tests/test3.flv --debug
+[DEBUG INT] Matched: `AST_CONDITIONAL`
+[DEBUG INT] `interpret_conditional()` called
+[DEBUG INT] Operator: `>`
 ```
 
+3. **Function Calls**
+
+```bash
+[DEBUG INT] Starting function call interpretation
+[DEBUG INT] Looking up variable: `serve`
+[DEBUG INT] builtin_output() called
+```
+
+## Tips for Effective Debugging
+
+1. **Read Token Types**
+
+   - 0: Keywords (`let`, `if`, `while`)
+   - 1: Identifiers (variable names)
+   - 2: Boolean literals (`True`, `False`)
+   - 3: Floating-point number literals
+   - 4: Integer number literals
+   - 5: String literals
+   - 6: Operators (`+`, `-`, `==`, etc.)
+   - 7: Delimiters (e.g., `;`, `,`)
+   - 8: Function names
+   - 9: Function parameter identifiers
+   - 10: Open parentheses (`(`)
+   - 11: Close parentheses (`)`)
+   - 12: Open braces (`{`)
+   - 13: Close braces (`}`)
+   - 14: Colon (`:`)
+   - 15: Array operations (e.g., access)
+   - 16: Open square brackets (`[`)
+   - 17: Close square brackets (`]`)
+   - 18: End of file
+
+2. **Track Variable State**
+
+   - Watch for variable declarations (`Added variable`)
+   - Monitor value changes (`Variable found: with value`)
+   - Check condition evaluations
+
+3. **Follow Control Flow**
+   - Look for `AST_CONDITIONAL` and `AST_WHILE_LOOP`
+   - Track block entry/exit
+   - Monitor condition evaluations
+
+## Reference
+
+### Token Types
+
+| ID  | Meaning               | Example              |
+| --- | --------------------- | -------------------- |
+| 0   | Keyword               | `let`, `if`, `while` |
+| 1   | Identifier            | Variable names       |
+| 2   | Boolean               | `True`, `False`      |
+| 3   | Floating-point Number | `3.14`, `2.718`      |
+| 4   | Integer Number        | `10`, `42`           |
+| 5   | String                | `"Hello"`            |
+| 6   | Operator              | `=`, `+`, `-`, `>`   |
+| 7   | Delimiter             | `;`, `,`             |
+| 8   | Function Name         | `serve`              |
+| 9   | Function Parameter    | `x`, `y`             |
+| 10  | Open Parenthesis      | `(`                  |
+| 11  | Close Parenthesis     | `)`                  |
+| 12  | Open Brace            | `{`                  |
+| 13  | Close Brace           | `}`                  |
+| 14  | Colon                 | `:`                  |
+| 15  | Array Operation       | `arr[0]`             |
+| 16  | Open Square Bracket   | `[`                  |
+| 17  | Close Square Bracket  | `]`                  |
+| 18  | End of File           | (None)               |
+
+### Common Debug Messages
+
+| Message Pattern          | Meaning                   |
+| ------------------------ | ------------------------- |
+| `Added variable`         | New variable created      |
+| `Looking up variable`    | Variable access           |
+| `Starting function call` | Function invocation       |
+| `Operator:`              | Operation being performed |
+| `Matched: AST_`          | Node type being processed |
+
 ---
 
 ## License