mimo-lang 1.1.1 → 2.0.6

package/parser/expressions/atomicExpressions.js

@@ -0,0 +1,165 @@
+// parser/expressions/atomicExpressions.js
+import { TokenType } from "../../lexer/TokenTypes.js";
+import { ASTNode } from "../ASTNodes.js";
+import { parseBlock } from "../parserUtils.js";
+import { parseAnonymousFunction, parseCallExpressionParts } from "../statements/functionParsers.js"; // Import the new function
+
+// Forward declaration - will be set by the main parser
+let parseExpression;
+
+export function setParseExpression(parseExpressionFn) {
+  parseExpression = parseExpressionFn;
+}
+
+export function parseAtomicExpression(parser) {
+  const token = parser.peek();
+
+  switch (token?.type) {
+    case TokenType.Identifier: {
+      const consumedToken = parser.consume();
+      return ASTNode.Identifier(consumedToken.value, consumedToken);
+    }
+    case TokenType.Number: {
+      const consumedToken = parser.consume();
+      return ASTNode.Literal(Number.parseFloat(consumedToken.value), consumedToken);
+    }
+    case TokenType.String: {
+      const consumedToken = parser.consume();
+      return ASTNode.Literal(consumedToken.value, consumedToken);
+    }
+    case TokenType.Boolean: {
+      // The lexer already converts 'true'/'false' strings to actual booleans.
+      const consumedToken = parser.consume();
+      return ASTNode.Literal(consumedToken.value, consumedToken);
+    }
+    case TokenType.Null: {
+      const consumedToken = parser.consume();
+      return ASTNode.Literal(null, consumedToken);
+    }
+    case TokenType.Backtick:
+      return parseTemplateLiteral(parser);
+    case TokenType.LBracket:
+      return parseArrayLiteral(parser);
+    case TokenType.LBrace:
+      return parseObjectLiteral(parser);
+    case TokenType.LParen: {
+      parser.consume(); // consume opening parenthesis
+      const expr = parseExpression(parser);
+      parser.expect(TokenType.RParen, undefined, 'SYN018', 'Expected a closing parenthesis for grouped expression.');
+      return expr;
+    }
+    case TokenType.Keyword:
+      if (token.value === "function" || token.value === "fn") {
+        parser.consume(); // CONSUME 'function' or 'fn'
+        return parseAnonymousFunction(parser, token.value === "fn");
+      }
+      if (token.value === "if") {
+        const ifToken = parser.consume(); // CONSUME 'if'
+        const condition = parseExpression(parser);
+        parser.expectKeyword("then", "SYN120", "Expected 'then' after condition in inline if expression.");
+        const consequent = parseExpression(parser);
+        parser.expectKeyword("else", "SYN121", "Expected 'else' in inline if expression.");
+        const alternate = parseExpression(parser);
+        return ASTNode.InlineIfExpression(condition, consequent, alternate, ifToken);
+      }
+      if (token.value === "call") {
+        parser.consume(); // CONSUME 'call' keyword
+        return parseCallExpressionParts(parser, token);
+      }
+      parser.error(`Unexpected keyword "${token.value}" in expression context.`, token, 'SYN010');
+      break;
+    default:
+      parser.error(`Unexpected token in expression "${token?.value}".`, token, 'SYN010', 'Expected a literal, identifier, array, object, or function.');
+  }
+}
+
+export function parseArrayLiteral(parser) {
+  const startBracket = parser.expect(TokenType.LBracket, undefined, 'SYN011', 'Expected an opening square bracket to start an array literal.');
+  const elements = [];
+
+  if (parser.peek()?.type !== TokenType.RBracket) {
+    if (parser.peek()?.type === TokenType.Spread) {
+      const spreadToken = parser.consume();
+      const argument = parseExpression(parser);
+      elements.push(ASTNode.SpreadElement(argument, spreadToken));
+    } else {
+      elements.push(parseExpression(parser));
+    }
+
+    while (parser.peek()?.type === TokenType.Comma) {
+      parser.consume();
+      if (parser.peek()?.type === TokenType.RBracket) break;
+
+      if (parser.peek()?.type === TokenType.Spread) {
+        const spreadToken = parser.consume();
+        const argument = parseExpression(parser);
+        elements.push(ASTNode.SpreadElement(argument, spreadToken));
+      } else {
+        elements.push(parseExpression(parser));
+      }
+    }
+  }
+
+  parser.expect(TokenType.RBracket, undefined, 'SYN012', 'Expected a closing square bracket to end an array literal.');
+  return ASTNode.ArrayLiteral(elements, startBracket);
+}
+
+export function parseObjectLiteral(parser) {
+  const startBrace = parser.expect(TokenType.LBrace, undefined, 'SYN013', 'Expected an opening curly brace to start an object literal.');
+  const properties = [];
+
+  if (parser.peek()?.type !== TokenType.RBrace) {
+    const parsePropertyOrSpread = () => {
+      if (parser.peek()?.type === TokenType.Spread) {
+        const spreadToken = parser.consume();
+        const argument = parseExpression(parser);
+        properties.push(ASTNode.SpreadElement(argument, spreadToken));
+      } else {
+        const keyToken = parser.expect(TokenType.Identifier, undefined, 'SYN016', 'Expected a property name (identifier) in object literal.');
+        parser.expect(TokenType.Colon, undefined, 'SYN017', 'Expected a colon ":" after property name in object literal.');
+        const value = parseExpression(parser);
+        properties.push({ key: keyToken.value, value });
+      }
+    };
+
+    parsePropertyOrSpread();
+
+    while (parser.peek()?.type === TokenType.Comma) {
+      parser.consume();
+      if (parser.peek()?.type === TokenType.RBrace) break;
+      parsePropertyOrSpread();
+    }
+  }
+
+  parser.expect(TokenType.RBrace, undefined, 'SYN018', 'Expected a closing curly brace to end an object literal.');
+  return ASTNode.ObjectLiteral(properties, startBrace);
+}
+
+
+export function parseTemplateLiteral(parser) {
+  const startToken = parser.expect(TokenType.Backtick, '`', 'SYN104', 'Expected backtick ` to start a template literal.');
+  const parts = [];
+
+  while (!parser.isAtEnd() && parser.peek()?.type !== TokenType.Backtick) {
+    const token = parser.peek();
+
+    if (token.type === TokenType.StringFragment) {
+      // It's a plain string part, like "Hello, "
+      parser.consume();
+      if (token.value.length > 0) {
+        parts.push(ASTNode.Literal(token.value, token));
+      }
+    } else if (token.type === TokenType.InterpolationStart) {
+      // It's an expression part, like ${name}
+      parser.consume(); // consume '${'
+      const expr = parseExpression(parser);
+      parts.push(expr);
+      parser.expect(TokenType.InterpolationEnd, '}', 'SYN105', 'Expected closing brace } after expression in template literal.');
+    } else {
+      parser.error(`Unexpected token '${token.value}' inside a template literal.`, token, 'SYN106');
+    }
+  }
+
+  parser.expect(TokenType.Backtick, '`', 'SYN107', 'Expected backtick ` to end a template literal.');
+  return ASTNode.TemplateLiteral(parts, startToken);
+}

package/parser/expressions/operatorExpressions.js

@@ -0,0 +1,79 @@
+// In: parser/expressions/operatorExpressions.js
+
+import { TokenType, END_KEYWORDS } from "../../lexer/TokenTypes.js";
+import { ASTNode } from "../ASTNodes.js";
+
+let parseExpression;
+let parsePrimaryExpression;
+
+// This new Set contains all keywords that can ONLY start a new statement.
+// If the parser sees one of these after an operand, it knows the expression is over.
+const STATEMENT_START_KEYWORDS = new Set([
+  'set', 'let', 'const', 'global', 'if', 'while', 'for', 'loop',
+  'function', 'call', 'show', 'return', 'try', 'throw', 'match',
+  'import', 'export', 'break', 'continue'
+]);
+
+export function setParseExpression(parseExpressionFn) {
+  parseExpression = parseExpressionFn;
+}
+
+export function setParsePrimaryExpression(parsePrimaryExpressionFn) {
+  parsePrimaryExpression = parsePrimaryExpressionFn;
+}
+
+export function parseBinaryOrUnary(parser) {
+  const token = parser.peek();
+
+  const isOperator = (token?.type === TokenType.Operator && !['.', '?.', '|>'].includes(token.value)) ||
+    (token?.type === TokenType.Keyword && ['not', 'and', 'or'].includes(token.value));
+
+  if (!isOperator) {
+    return parsePrimaryExpression(parser);
+  }
+
+  const operatorToken = parser.consume();
+  const operator = operatorToken.value;
+
+  // The 'not' operator is always unary
+  if (operator === 'not') {
+    const argument = parseExpression(parser);
+    return ASTNode.UnaryExpression(operator, argument, operatorToken);
+  }
+
+  const left = parseExpression(parser);
+
+  // ==========================================================
+  // THE DEFINITIVE FIX IS IN THE LOGIC BELOW
+  // ==========================================================
+  const nextToken = parser.peek();
+
+  // An expression is considered "ended" if we are at the end of the file,
+  // or the next token is a structural terminator, or it's a keyword that
+  // *must* start a new statement.
+  const isEndOfExpression = parser.isAtEnd() ||
+    !nextToken ||
+    nextToken.type === TokenType.RParen ||
+    nextToken.type === TokenType.RBracket ||
+    nextToken.type === TokenType.RBrace ||
+    nextToken.type === TokenType.Comma ||
+    nextToken.type === TokenType.Colon ||
+    (nextToken.type === TokenType.Operator && nextToken.value === "->") ||
+    (nextToken.type === TokenType.Keyword && (
+      END_KEYWORDS.includes(nextToken.value) || // 'end', 'else', 'catch' etc.
+      STATEMENT_START_KEYWORDS.has(nextToken.value) // 'show', 'set', 'if', etc.
+    ));
+
+  if (isEndOfExpression) {
+    // There is no second operand, so it must be a unary expression.
+    // Mimo currently only supports '-' as a unary numeric operator.
+    if (operator !== '-') {
+      parser.error(`Operator '${operator}' cannot be used as a unary operator.`, operatorToken, 'SYN039', `Did you mean to provide a second argument?`);
+    }
+    return ASTNode.UnaryExpression(operator, left, operatorToken);
+  } else {
+    // There's more to the expression, so we parse the second operand.
+    const right = parseExpression(parser);
+    return ASTNode.BinaryExpression(operator, left, right, operatorToken);
+  }
+}

package/parser/expressions/primaryExpressions.js

@@ -0,0 +1,77 @@
+// parser/expressions/primaryExpressions.js
+import { TokenType } from "../../lexer/TokenTypes.js";
+import { ASTNode } from "../ASTNodes.js";
+import { parseAtomicExpression } from "./atomicExpressions.js";
+
+// Forward declaration - will be set by the main parser
+let parseExpression;
+
+export function setParseExpression(parseExpressionFn) {
+  parseExpression = parseExpressionFn;
+}
+
+export function parsePrimaryExpression(parser) {
+  let primaryExpr = parseAtomicExpression(parser);
+
+  // Handle postfix operations: property access, array access, safe navigation, function calls
+  while (true) {
+    const nextToken = parser.peek();
+    if (!nextToken) break;
+
+    if (nextToken.type === TokenType.Operator && (nextToken.value === "." || nextToken.value === "?.")) {
+      const operatorToken = parser.consume(); // Consume '.' or '?.'
+
+      // Support Safe Index Access: obj?.[index]
+      if (operatorToken.value === "?." && parser.match(TokenType.LBracket)) {
+        const indexExpr = parseExpression(parser);
+        const endBracket = parser.expect(TokenType.RBracket, undefined, 'SYN041', 'Expected closing square bracket for safe array/object access.');
+        primaryExpr = ASTNode.SafeArrayAccess(primaryExpr, indexExpr, operatorToken);
+        continue;
+      }
+
+      // Support Safe Call: func?.()
+      if (operatorToken.value === "?." && parser.match(TokenType.LParen)) {
+        const args = [];
+        if (parser.peek()?.type !== TokenType.RParen) {
+          do {
+            if (parser.peek()?.type === TokenType.Spread) {
+              const spreadToken = parser.consume();
+              const argument = parseExpression(parser);
+              args.push(ASTNode.SpreadElement(argument, spreadToken));
+            } else {
+              args.push(parseExpression(parser));
+            }
+          } while (parser.match(TokenType.Comma));
+        }
+        parser.expect(TokenType.RParen, undefined, 'SYN067', 'Expected a closing parenthesis for safe function call.');
+        primaryExpr = ASTNode.SafeCallExpression(primaryExpr, args, operatorToken);
+        continue;
+      }
+
+      const property = parser.expect(TokenType.Identifier, undefined, 'SYN042', 'Expected property name after dot operator.');
+
+      if (operatorToken.value === '?.') {
+        primaryExpr = ASTNode.SafePropertyAccess(primaryExpr, property.value, property);
+      } else {
+        primaryExpr = ASTNode.PropertyAccess(primaryExpr, property.value, property);
+      }
+    } else if (nextToken.type === TokenType.LBracket) {
+      // Array/Object access: arr[index] or obj[key]
+      const startBracketToken = parser.consume(); // consume [
+      const indexExpr = parseExpression(parser);
+      parser.expect(TokenType.RBracket, undefined, 'SYN041', 'Expected closing square bracket for array/object access (e.g., arr[index]).');
+      primaryExpr = ASTNode.ArrayAccess(primaryExpr, indexExpr, startBracketToken);
+      // The slicing logic with colon is removed here.
+    } else {
+      break; // No more postfix operators
+    }
+  }
+  return primaryExpr;
+}
+
+export function parseRangeLiteral(parser) {
+  const start = parseAtomicExpression(parser);
+  const rangeToken = parser.expect(TokenType.Range, undefined, 'SYN045', 'Expected range operator (..) between start and end of range.');
+  const end = parseAtomicExpression(parser);
+  return ASTNode.RangeLiteral(start, end, rangeToken);
+}

package/parser/parseStatement.js

@@ -0,0 +1,184 @@
+// parser/parseStatement.js
+import { TokenType } from "../lexer/TokenTypes.js";
+import { parseExpression } from "./parserExpressions.js"; // Needed if expressions can be statements
+
+// Import ALL individual statement parser functions here (ensure names match your files)
+import {
+  parseBreakStatement,
+  parseContinueStatement,
+  parseForStatement,
+  parseIfStatement,
+  parseGuardStatement,
+  parseLoopStatement,
+  parseTryStatement,
+  parseWhileStatement,
+} from "./statements/controlFlowParsers.js";
+import {
+  parseCallStatement,
+  parseFunctionDeclaration,
+  parseDecorators,
+  parseReturnStatement,
+  parseShowStatement,
+  parseThrowStatement,
+} from "./statements/functionParsers.js";
+import { parseMatchStatement } from "./statements/patternMatchParsers.js";
+import {
+  parseVariableOrAssignment,
+  parseDestructuringStatement,
+} from "./statements/variableParsers.js"; // Corrected import
+import {
+  parseImportStatement,
+  parseExportStatement,
+} from "./statements/moduleParsers.js";
+
+// NOTE: parseAnonymousFunction is used by parseAtomicExpression (an expression parser), not directly here.
+// No imports needed for parseClassDeclaration, parseEnumDeclaration, parseInterfaceDeclaration,
+// parseTypeAliasDeclaration, parseModuleBlock as they are not implemented yet.
+// No parseExpressionStatement import is needed, we will define it if Mimo supports it.
+
+/**
+ * Parses an expression used as a standalone statement.
+ * This is for cases where an expression (like `1+2` or a function call without `call` keyword)
+ * is a valid statement in itself.
+ * @param {import("./Parser.js").Parser} parser - The parser instance.
+ * @returns {object} The AST node for the expression statement.
+ */
+function parseExpressionStatement(parser) {
+  const expression = parseExpression(parser);
+  // Mimo doesn't have an explicit ExpressionStatement AST node in ASTNodes.js
+  // so for now, we just return the expression itself.
+  // The interpreter will then evaluate this expression as a statement.
+  return expression;
+}
+
+/**
+ * Parses a single Mimo statement. This function acts as a dispatcher.
+ * It relies on the passed `parser` instance to access its methods (peek, consume, error, etc.)
+ * and other parsing helpers.
+ * @param {import("./Parser.js").Parser} parser - The parser instance.
+ * @returns {object} The AST node for the parsed statement.
+ */
+export function parseStatement(parser) {
+  const token = parser.peek(); // Get the current token
+  if (!token || parser.isAtEnd()) {
+    // Check isAtEnd for robustness
+    parser.error(
+      "Unexpected end of input.",
+      null, // No specific token to point to at EOF
+      "SYN000",
+      "Expected a statement or expression, but found end of file."
+    );
+  }
+
+  if (token.type === TokenType.Keyword) {
+    switch (token.value) {
+      case "destructure":
+        return parseDestructuringStatement(parser);
+      case "set":
+      case "let":
+      case "const":
+      case "global":
+        // Variable declarations and assignments
+        return parseVariableOrAssignment(parser, false, token); // Correctly calls existing function
+      case "if":
+        return parseIfStatement(parser);
+      case "guard":
+        return parseGuardStatement(parser);
+      case "for":
+        return parseForStatement(parser);
+      case "while":
+        return parseWhileStatement(parser);
+      case "loop": // Assuming 'loop' is a keyword for infinite loop or similar
+        return parseLoopStatement(parser);
+      case "break":
+        return parseBreakStatement(parser);
+      case "continue":
+        return parseContinueStatement(parser);
+      case "try":
+        return parseTryStatement(parser); // Corrected function name
+      case "function":
+        return parseFunctionDeclaration(parser, false);
+      case "call":
+        return parseCallStatement(parser);
+      case "return":
+        return parseReturnStatement(parser);
+      case "show":
+        return parseShowStatement(parser);
+      case "throw":
+        return parseThrowStatement(parser);
+      case "match":
+        return parseMatchStatement(parser);
+      case "import":
+        return parseImportStatement(parser); // Direct import parsing
+      case "export":
+        return parseExportStatement(parser); // Direct export parsing
+      default:
+        // If a keyword is encountered that doesn't start a known statement,
+        // AND it's not a keyword that can start an expression (like 'true', 'false', 'null'),
+        // then it's an error.
+        // For Mimo, keywords like 'true', 'false', 'null' are literals, not statements.
+        // So, if a keyword falls through here, it IS an error.
+        parser.error(
+          `Unexpected keyword '${token.value}' at the start of a statement.`,
+          token,
+          "SYN005",
+          "Expected a statement keyword (like 'set', 'if', 'function', 'call', 'show', etc.)."
+        );
+      // This default case should always throw if it's a keyword.
+    }
+  }
+
+  // Handle Decorators: @decorator
+  if (token.type === TokenType.At) {
+    const decorators = parseDecorators(parser);
+    const nextToken = parser.peek();
+    if (nextToken?.type === TokenType.Keyword) {
+      if (nextToken.value === "function") {
+        return parseFunctionDeclaration(parser, false, null, decorators);
+      } else if (nextToken.value === "export") {
+        return parseExportStatement(parser, decorators);
+      }
+    }
+    parser.error("Decorators can only be applied to 'function' or 'export function' declarations.", token, 'SYN143');
+  }
+
+  // Check for LabeledStatement
+  if (token.type === TokenType.Identifier) {
+    const nextToken = parser.peek(1);
+    if (nextToken && nextToken.type === TokenType.Colon) {
+      const labelToken = parser.consume(); // Consume identifier
+      parser.consume(); // Consume colon
+      const statement = parseStatement(parser);
+      // Wait, ASTNode is not imported! I'll just use inline object or import it. Let me import ASTNode at the top.
+      return {
+        type: "LabeledStatement",
+        label: labelToken.value,
+        statement: statement,
+        line: labelToken.line,
+        column: labelToken.column,
+        start: labelToken.start,
+        length: labelToken.length,
+        file: labelToken.file,
+      };
+    }
+  }
+
+  // If the first token is NOT a keyword, it's an expression.
+  // This handles cases where expressions (like `* x 2` or `myVar`) are standalone statements.
+  // Call parseExpressionStatement to handle it.
+  return parseExpressionStatement(parser); // <--- ADD THIS LINE HERE
+
+  // The original `parser.error` here (SYN001) should now only be reachable if parseExpressionStatement
+  // itself fails to parse anything and doesn't throw, or if an unexpected token appears and parser.error is called.
+  // But `parseExpressionStatement` should throw its own specific errors if it can't parse an expression.
+  // So, this final `parser.error` is effectively redundant if `parseExpressionStatement` is robust.
+  // We can remove it and let `parseExpressionStatement`'s errors propagate.
+  /*
+  parser.error(
+    `Unexpected token '${token.value}' (${token.type}) when expecting a statement.`,
+    token,
+    "SYN001",
+    "Expected a statement keyword (like 'set', 'if', 'function', 'call', 'show', etc.) or a valid expression that can form a statement."
+  );
+  */
+}

package/parser/parserExpressions.js

@@ -0,0 +1,115 @@
+import { TokenType } from "./../lexer/TokenTypes.js";
+import { ASTNode } from "./ASTNodes.js";
+import { parseBlock } from "./parserUtils.js";
+
+// Import atomic expression parsing functions and their setter
+import {
+  parseAtomicExpression,
+  parseArrayLiteral,
+  parseObjectLiteral,
+  setParseExpression as setAtomicParseExpression // Alias for atomicExpressions.js's setter
+} from "./expressions/atomicExpressions.js";
+
+// Import primary expression parsing function and its setter
+import {
+  parsePrimaryExpression,
+  setParseExpression as setPrimaryExpressionParseExpression // Alias for primaryExpressions.js's setter
+} from "./expressions/primaryExpressions.js";
+
+
+// Import operator expression parsing functions and their setters
+import {
+  parseBinaryOrUnary,
+  setParseExpression as setOperatorExpressionParseExpression, // Alias for operatorExpressions.js's main setter
+  setParsePrimaryExpression as setOperatorPrimaryExpressionParsePrimary // Alias for operatorExpressions.js's primary setter
+} from "./expressions/operatorExpressions.js";
+
+
+/**
+ * Parses a callee expression for |>: either an identifier, module.prop access,
+ * or an inline-if expression. Optionally consumes extra arguments in parentheses.
+ * Returns { callee, args }.
+ */
+function parsePipeCallee(parser) {
+  // Support inline-if as callee: value |> if cond then fn1 else fn2
+  if (parser.peek()?.type === TokenType.Keyword && parser.peek()?.value === "if") {
+    const ifToken = parser.consume();
+    const condition = parseExpression(parser);
+    parser.expectKeyword("then", "SYN130", "Expected 'then' after condition in pipe inline-if.");
+    const consequent = parseExpression(parser);
+    parser.expectKeyword("else", "SYN131", "Expected 'else' in pipe inline-if.");
+    const alternate = parseExpression(parser);
+    const callee = ASTNode.InlineIfExpression(condition, consequent, alternate, ifToken);
+    // No extra args supported for inline-if callee (the fn itself receives the piped value)
+    return { callee, args: [] };
+  }
+
+  // Parse callee: identifier or module.prop
+  const firstToken = parser.expect(TokenType.Identifier, undefined, "SYN132", "Expected a function name after '|>'.");
+  let callee;
+  if (parser.peek()?.type === TokenType.Operator && parser.peek()?.value === ".") {
+    parser.consume(); // consume '.'
+    const prop = parser.expect(TokenType.Identifier, undefined, "SYN133", "Expected property name after '.' in pipe callee.");
+    callee = ASTNode.ModuleAccess(firstToken.value, prop.value, firstToken);
+  } else {
+    callee = ASTNode.Identifier(firstToken.value, firstToken);
+  }
+
+  // Parse optional extra arguments: value |> func(arg2, arg3)
+  const args = [];
+  if (parser.peek()?.type === TokenType.LParen) {
+    parser.consume(); // consume '('
+    if (parser.peek()?.type !== TokenType.RParen) {
+      do {
+        if (parser.peek()?.type === TokenType.Spread) {
+          const spreadToken = parser.consume();
+          const argument = parseExpression(parser);
+          args.push(ASTNode.SpreadElement(argument, spreadToken));
+        } else {
+          args.push(parseExpression(parser));
+        }
+      } while (parser.match(TokenType.Comma));
+    }
+    parser.expect(TokenType.RParen, undefined, "SYN134", "Expected ')' after pipe arguments.");
+  }
+
+  return { callee, args };
+}
+
+// Main entry point for parsing an expression
+function parseExpression(parser) {
+  // Parse the left-hand side (standard Mimo prefix expression)
+  let left = parseBinaryOrUnary(parser);
+
+  // Then handle any pipe operators (left-associative)
+  while (parser.peek()?.type === TokenType.Operator && parser.peek()?.value === "|>") {
+    const pipeToken = parser.consume(); // consume '|>'
+    const { callee, args } = parsePipeCallee(parser);
+    left = ASTNode.PipeExpression(left, callee, args, pipeToken);
+  }
+
+  return left;
+}
+
+/**
+ * Sets up the forward references for mutually recursive expression parsing functions.
+ * This function MUST be called once, before any expression parsing begins.
+ */
+export function setupExpressionParsers() {
+  // Pass the top-level parseExpression function to any sub-parsers that need to call it.
+  setAtomicParseExpression(parseExpression); // For atomicExpressions.js (e.g., for nested expressions in literals)
+  setPrimaryExpressionParseExpression(parseExpression); // For primaryExpressions.js (e.g., for `arr[index]`
+  setOperatorExpressionParseExpression(parseExpression); // For operatorExpressions.js (e.g., for `+ left right`)
+
+  // Pass parsePrimaryExpression to operatorExpressions.js (for `parseBinaryOrUnary` default case)
+  setOperatorPrimaryExpressionParsePrimary(parsePrimaryExpression);
+
+
+}
+
+// Export the main parsing functions that other parts of the parser might need to call.
+export {
+  parseExpression,
+  parsePrimaryExpression,
+  parseBinaryOrUnary,
+};

package/parser/parserUtils.js

@@ -0,0 +1,19 @@
+import { END_KEYWORDS, TokenType } from "../lexer/TokenTypes.js";
+import { parseStatement } from "./parseStatement.js";
+
+export function parseBlock(parser, customEndKeywords = []) {
+  const endKeywords = new Set([...END_KEYWORDS, ...customEndKeywords]);
+  const statements = [];
+
+  while (!parser.isAtEnd() && !isBlockEnd(parser, endKeywords)) {
+
+    statements.push(parseStatement(parser));
+  }
+
+  return statements;
+}
+
+export function isBlockEnd(parser, endKeywords) {
+  const token = parser.peek();
+  return token.type === TokenType.Keyword && endKeywords.has(token.value);
+}