machine-dialect 0.1.0a1__py3-none-any.whl

machine_dialect/compiler/vm_runner.py

@@ -0,0 +1,173 @@
+"""VM Runner - Manages Rust VM execution for Machine Dialect™.
+
+This module provides the integration layer between the Python compiler
+pipeline and the Rust VM for executing Machine Dialect™ programs.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from machine_dialect.codegen.register_codegen import (
+    RegisterBytecodeGenerator,
+)
+from machine_dialect.compiler.config import CompilerConfig
+from machine_dialect.compiler.context import CompilationContext
+from machine_dialect.compiler.phases.hir_generation import HIRGenerationPhase
+from machine_dialect.compiler.phases.mir_generation import MIRGenerationPhase
+from machine_dialect.mir.mir_module import MIRModule
+from machine_dialect.mir.optimize_mir import optimize_mir
+from machine_dialect.parser.parser import Parser
+
+
+class VMRunner:
+    """Manages compilation and execution of Machine Dialect™ code on the Rust VM.
+
+    This class provides a high-level interface for:
+    1. Compiling Machine Dialect™ source to bytecode
+    2. Loading bytecode into the Rust VM
+    3. Executing programs and returning results
+    """
+
+    def __init__(self, debug: bool = False, optimize: bool = False) -> None:
+        """Initialize the VM runner.
+
+        Args:
+            debug: Enable debug output
+            optimize: Enable MIR optimizations
+        """
+        self.debug = debug
+        self.optimize = optimize
+        self.vm: Any = None
+        self._init_vm()
+
+    def _init_vm(self) -> None:
+        """Initialize the Rust VM instance."""
+        try:
+            import machine_dialect_vm
+
+            self.vm = machine_dialect_vm.RustVM()
+            if self.debug:
+                self.vm.set_debug(True)
+        except ImportError as e:
+            raise RuntimeError(
+                "Rust VM module not available. Please build it first:\n"
+                "  ./build_vm.sh\n"
+                "or manually:\n"
+                "  cd machine_dialect_vm && maturin develop --features pyo3"
+            ) from e
+
+    def compile_to_bytecode(self, source: str, source_path: Path | None = None) -> bytes:
+        """Compile Machine Dialect™ source code to bytecode.
+
+        Args:
+            source: Machine Dialect™ source code
+            source_path: Optional path to source file
+
+        Returns:
+            Serialized bytecode ready for VM execution
+
+        Raises:
+            CompilationError: If compilation fails at any stage
+        """
+        if source_path is None:
+            source_path = Path("<repl>")
+
+        # Step 1: Parse to AST
+        parser = Parser()
+        ast = parser.parse(source)
+        if ast is None:
+            raise ValueError("Failed to parse source code")
+
+        # Step 2: Generate HIR
+        config = CompilerConfig(verbose=self.debug)
+        context = CompilationContext(source_path=source_path, config=config, source_content=source)
+        hir_phase = HIRGenerationPhase()
+        hir = hir_phase.run(context, ast)
+        if hir is None:
+            raise ValueError("Failed to generate HIR")
+
+        # Step 3: Generate MIR
+        mir_phase = MIRGenerationPhase()
+        mir_module = mir_phase.run(context, hir)
+        if mir_module is None:
+            raise ValueError("Failed to generate MIR")
+
+        # Step 4: Optimize MIR (if enabled)
+        if self.optimize:
+            mir_module, _ = optimize_mir(mir_module)
+
+        # Step 5: Generate bytecode
+        return self._mir_to_bytecode(mir_module)
+
+    def _mir_to_bytecode(self, mir_module: MIRModule) -> bytes:
+        """Convert MIR module to bytecode.
+
+        Args:
+            mir_module: The MIR module to convert
+
+        Returns:
+            Serialized bytecode
+        """
+        # Generate bytecode
+        generator = RegisterBytecodeGenerator()
+        bytecode_module = generator.generate(mir_module)
+
+        # Serialize to bytes
+        return bytecode_module.serialize()
+
+    def execute(self, source: str) -> Any:
+        """Compile and execute Machine Dialect™ source code.
+
+        Args:
+            source: Machine Dialect™ source code
+
+        Returns:
+            The result of program execution
+
+        Raises:
+            RuntimeError: If execution fails
+        """
+        # Compile to bytecode
+        bytecode = self.compile_to_bytecode(source)
+
+        # Write to temporary file (VM loads from file)
+        with tempfile.NamedTemporaryFile(suffix=".mdbc", delete=False) as f:
+            f.write(bytecode)
+            bytecode_path = f.name
+
+        try:
+            # Load and execute in VM
+            self.vm.load_bytecode(bytecode_path)
+            result = self.vm.execute()
+            return result
+        finally:
+            # Clean up temporary file
+            Path(bytecode_path).unlink(missing_ok=True)
+
+    def execute_bytecode(self, bytecode: bytes) -> Any:
+        """Execute pre-compiled bytecode.
+
+        Args:
+            bytecode: Serialized bytecode
+
+        Returns:
+            The result of program execution
+        """
+        # Write to temporary file
+        with tempfile.NamedTemporaryFile(suffix=".mdbc", delete=False) as f:
+            f.write(bytecode)
+            bytecode_path = f.name
+
+        try:
+            self.vm.load_bytecode(bytecode_path)
+            result = self.vm.execute()
+            return result
+        finally:
+            Path(bytecode_path).unlink(missing_ok=True)
+
+    def reset(self) -> None:
+        """Reset the VM to initial state."""
+        self._init_vm()

machine_dialect/errors/__init__.py

@@ -0,0 +1,32 @@
+"""Error handling for Machine Dialect™.
+
+This package provides exception classes and error reporting utilities.
+"""
+
+from machine_dialect.errors.exceptions import (
+    MDException,
+    MDNameError,
+    MDSyntaxError,
+    MDTypeError,
+    MDUninitializedError,
+    MDValueError,
+)
+from machine_dialect.errors.messages import (
+    EXPECTED_BLOCK_MARKER,
+    EXPECTED_EXPRESSION,
+    EXPECTED_PREFIX_OPERATOR,
+    UNEXPECTED_TOKEN,
+)
+
+__all__ = [
+    "EXPECTED_BLOCK_MARKER",
+    "EXPECTED_EXPRESSION",
+    "EXPECTED_PREFIX_OPERATOR",
+    "UNEXPECTED_TOKEN",
+    "MDException",
+    "MDNameError",
+    "MDSyntaxError",
+    "MDTypeError",
+    "MDUninitializedError",
+    "MDValueError",
+]

machine_dialect/errors/exceptions.py

@@ -0,0 +1,369 @@
+"""Machine Dialect™ exception classes.
+
+This module defines the exception hierarchy for the Machine Dialect™ language.
+All exceptions inherit from MDBaseException, which provides a common base
+for error handling throughout the system.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from machine_dialect.errors.messages import ErrorTemplate
+
+
+class MDBaseException(ABC):
+    """Base Machine Dialect™ Exception.
+
+    The base class for all built-in Machine Dialect™ exceptions.
+    This is an abstract base class and should not be instantiated directly.
+
+    Attributes:
+        message (str): The error message.
+        line (int, optional): The line number where the error occurred.
+        column (int, optional): The column number where the error occurred.
+        filename (str, optional): The filename where the error occurred.
+
+    Note:
+        This is a pure ABC that does not inherit from Python's Exception.
+        These exceptions represent errors in Machine Dialect™ code, not Python code.
+    """
+
+    def __init__(
+        self, message: ErrorTemplate, line: int, column: int, filename: str | None = None, **kwargs: Any
+    ) -> None:
+        """Initialize the Machine Dialect™ exception.
+
+        Args:
+            message: The error message template.
+            line: The line number where the error occurred.
+            column: The column number where the error occurred.
+            filename: The filename where the error occurred.
+            **kwargs: Template substitution parameters.
+        """
+        # Format the message with any provided kwargs
+        # If no kwargs, call substitute with empty dict to get the template with no substitutions
+        self._message = message.format(**kwargs) if kwargs else message.substitute()
+        self._line = line
+        self._column = column
+        self._filename = filename or "<standard-input>"
+
+    def __str__(self) -> str:
+        """Return string representation of the exception.
+
+        Returns:
+            A formatted error message with location information if available.
+        """
+        parts = []
+        if self._filename:
+            parts.append(f'File "{self._filename}"')
+        if self._line is not None:
+            parts.append(f"line {self._line}")
+        if self._column is not None:
+            parts.append(f"column {self._column}")
+
+        location = ", ".join(parts)
+        if location:
+            return f"{location}: {self._message}"
+        return self._message
+
+    def __repr__(self) -> str:
+        """Return detailed representation of the exception.
+
+        Returns:
+            A string showing the exception class and all attributes.
+        """
+        mydict = {
+            "message": self._message.__repr__(),
+            "line": self._line,
+            "column": self._column,
+            "filename": self._filename.__repr__(),
+        }
+        concatenated = ", ".join([f"{k}={v}" for k, v in mydict.items()])
+        return f"{self.__class__.__name__}({concatenated})"
+
+    @abstractmethod
+    def error_type(self) -> str:
+        """Return the error type identifier for this exception.
+
+        This should return a string that identifies the type of error
+        in Machine Dialect™ terms (e.g., "SyntaxError", "NameError").
+
+        Returns:
+            The error type as a string.
+        """
+        pass
+
+
+class MDException(MDBaseException):
+    """General Machine Dialect™ Exception.
+
+    This is the base class for all non-syntax Machine Dialect™ exceptions.
+    It provides a concrete implementation of MDBaseException that can be
+    instantiated directly for general errors.
+
+    Note:
+        Most specific error conditions should use a more specialized
+        exception subclass when available.
+    """
+
+    def error_type(self) -> str:
+        """Return the error type identifier.
+
+        Returns:
+            "Exception" for general Machine Dialect™ exceptions.
+        """
+        return "Exception"
+
+
+class MDDivisionByZero(MDException):
+    """Raised when a division or modulo operation has zero as divisor.
+
+    This exception is raised when attempting to divide by zero or perform
+    a modulo operation with zero as the divisor.
+
+    Example:
+        >>> 10 / 0
+        Traceback (most recent call last):
+            ...
+        MDDivisionByZero: division by zero
+
+        >>> 10 % 0
+        Traceback (most recent call last):
+            ...
+        MDDivisionByZero: integer division or modulo by zero
+    """
+
+
+class MDAssertionError(MDException):
+    """Raised when an assertion fails.
+
+    This exception is raised when an assert statement fails in Machine Dialect™ code.
+    It corresponds to Python's built-in AssertionError.
+
+    Example:
+        >>> assert False, "This will raise MDAssertionError"
+        Traceback (most recent call last):
+            ...
+        MDAssertionError: This will raise MDAssertionError
+    """
+
+
+class MDSystemExit(MDException):
+    """Raised to exit from the Machine Dialect™ interpreter.
+
+    This exception is used to exit from the interpreter or terminate
+    program execution. It corresponds to Python's SystemExit.
+
+    Attributes:
+        code (int | str | None): The exit status code. If None, defaults to 0.
+            An integer gives the exit status (0 means success).
+            A string prints the message to stderr and exits with status 1.
+
+    Example:
+        >>> exit(0)  # Normal termination
+        >>> exit(1)  # Termination with error
+        >>> exit("Error message")  # Print message and exit with status 1
+    """
+
+
+class MDNameError(MDException):
+    """Raised when a name is not found in any scope.
+
+    This exception is raised when a local or global name is not found.
+    This applies to unqualified names within functions, methods, or
+    the global scope.
+
+    Attributes:
+        name (str, optional): The name that could not be found.
+
+    Example:
+        >>> print(undefined_variable)
+        Traceback (most recent call last):
+            ...
+        MDNameError: name 'undefined_variable' is not defined
+
+        >>> del nonexistent
+        Traceback (most recent call last):
+            ...
+        MDNameError: name 'nonexistent' is not defined
+    """
+
+    def __init__(self, message: str | ErrorTemplate, line: int = 0, column: int = 0, **kwargs: Any) -> None:
+        """Initialize name error.
+
+        Args:
+            message: Error message string or ErrorTemplate
+            line: Line number where error occurred
+            column: Column position where error occurred
+            **kwargs: Additional template parameters if message is ErrorTemplate
+        """
+        if isinstance(message, str):
+            # Create a simple ErrorTemplate from the string
+            from machine_dialect.errors.messages import ErrorTemplate
+
+            template = ErrorTemplate(message)
+            super().__init__(template, line, column, **kwargs)
+        else:
+            super().__init__(message, line, column, **kwargs)
+
+
+class MDSyntaxError(MDException):
+    """Raised when a syntax error is encountered.
+
+    This exception is raised when the parser encounters syntactically
+    incorrect Machine Dialect™ code. This includes malformed expressions,
+    invalid statement structure, or improper use of keywords.
+
+    Example:
+        >>> if x = 5:  # Should use 'is' for comparison
+        ...     pass
+        Traceback (most recent call last):
+            ...
+        MDSyntaxError: invalid syntax
+
+        >>> def function(
+        ...     # Missing closing parenthesis
+        Traceback (most recent call last):
+            ...
+        MDSyntaxError: unexpected EOF while parsing
+    """
+
+
+class MDTypeError(MDException):
+    """Raised when an operation is applied to an inappropriate type.
+
+    This exception is raised when an operation or function is applied to
+    an object of inappropriate type. It can occur during parsing when
+    type validation fails.
+
+    Example:
+        >>> "string" + 5
+        Traceback (most recent call last):
+            ...
+        MDTypeError: can only concatenate str (not "int") to str
+
+        >>> len(42)
+        Traceback (most recent call last):
+            ...
+        MDTypeError: object of type 'int' has no len()
+    """
+
+    def __init__(self, message: str | ErrorTemplate, line: int = 0, column: int = 0, **kwargs: Any) -> None:
+        """Initialize type error.
+
+        Args:
+            message: Error message string or ErrorTemplate
+            line: Line number where error occurred
+            column: Column position where error occurred
+            **kwargs: Additional template parameters if message is ErrorTemplate
+        """
+        if isinstance(message, str):
+            # Create a simple ErrorTemplate from the string
+            from machine_dialect.errors.messages import ErrorTemplate
+
+            template = ErrorTemplate(message)
+            super().__init__(template, line, column, **kwargs)
+        else:
+            super().__init__(message, line, column, **kwargs)
+
+
+class MDValueError(MDException):
+    """Raised when a value is inappropriate for the operation.
+
+    This exception is raised when an operation or function receives an
+    argument that has the right type but an inappropriate value. It can
+    occur during parsing when value validation fails.
+
+    Example:
+        >>> int("not a number")
+        Traceback (most recent call last):
+            ...
+        MDValueError: invalid literal for int() with base 10: 'not a number'
+
+        >>> list.remove([1, 2, 3], 4)
+        Traceback (most recent call last):
+            ...
+        MDValueError: list.remove(x): x not in list
+    """
+
+
+class MDUninitializedError(MDException):
+    """Raised when a variable is used before being initialized.
+
+    This exception is raised during semantic analysis when a variable
+    that has been defined but not yet assigned a value is used in an
+    expression or assignment.
+
+    Example:
+        >>> Define `x` as Whole Number.
+        >>> Set `y` to `x`.
+        Traceback (most recent call last):
+            ...
+        MDUninitializedError: Variable 'x' is used before being initialized
+    """
+
+    def __init__(self, message: str | ErrorTemplate, line: int = 0, position: int = 0, **kwargs: Any) -> None:
+        """Initialize uninitialized variable error.
+
+        Args:
+            message: Error message string or ErrorTemplate
+            line: Line number where error occurred
+            position: Column position where error occurred
+            **kwargs: Additional template parameters if message is ErrorTemplate
+        """
+        if isinstance(message, str):
+            # Create a simple ErrorTemplate from the string
+            from machine_dialect.errors.messages import ErrorTemplate
+
+            template = ErrorTemplate(message)
+            super().__init__(template, line, position, **kwargs)
+        else:
+            super().__init__(message, line, position, **kwargs)
+
+
+class MDRuntimeError(Exception):
+    """Machine Dialect™ Runtime Error.
+
+    Raised during runtime execution with optional source location.
+    This is used for errors that occur during MIR interpretation or VM execution.
+
+    Note: This inherits from Python's Exception (not MDException) because
+    it represents runtime errors that need to be caught by Python's exception
+    handling mechanism.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        line: int | None = None,
+        column: int | None = None,
+        filename: str | None = None,
+    ) -> None:
+        """Initialize runtime error.
+
+        Args:
+            message: Error message string.
+            line: Line number where error occurred (None if unknown).
+            column: Column position where error occurred (None if unknown).
+            filename: Source file name (None if unknown).
+        """
+        self.message = message
+        self.line = line
+        self.column = column
+        self.filename = filename or "<standard-input>"
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        """Return formatted error message with location."""
+        parts = []
+        if self.filename != "<standard-input>":
+            parts.append(f'File "{self.filename}"')
+        if self.line is not None and self.line > 0:
+            parts.append(f"line {self.line}")
+        if self.column is not None and self.column > 0:
+            parts.append(f"column {self.column}")
+
+        location = ", ".join(parts)
+        if location:
+            return f"{location}: {self.message}"
+        return self.message

machine_dialect/errors/messages.py

@@ -0,0 +1,82 @@
+from string import Template
+from typing import Any
+
+
+class ErrorTemplate(Template):
+    """Custom template class that prevents direct string usage in error messages.
+
+    DO NOT USE THIS CLASS DIRECTLY, USE THE CONSTANTS DEFINED BELOW"""
+
+    def format(self, **kwargs: Any) -> str:
+        """Format the template with keyword arguments.
+
+        This is a more Pythonic alternative to substitute().
+        """
+        return self.substitute(**kwargs)
+
+
+# NameError
+NAME_UNDEFINED = ErrorTemplate("Name '$name' is not defined")
+VARIABLE_NOT_DEFINED = ErrorTemplate(
+    "Variable '$name' is not defined. Use 'Define `$name` as <type>.' to define it first"
+)
+VARIABLE_ALREADY_DEFINED = ErrorTemplate(
+    "Variable '$name' is already defined at line $original_line. Cannot redefine variables in the same scope"
+)
+ASSIGNMENT_TYPE_MISMATCH = ErrorTemplate(
+    "Cannot assign $actual_type value to variable '$variable' of type $expected_type"
+)
+UNEXPECTED_TOKEN = ErrorTemplate(
+    "Unexpected '$token_literal'. Expected a '$expected_token_type', but a got a '$received_token_type'"
+)
+INVALID_INTEGER_LITERAL = ErrorTemplate("Invalid integer literal: '$literal'")
+INVALID_FLOAT_LITERAL = ErrorTemplate("Invalid float literal: '$literal'")
+NO_PARSE_FUNCTION = ErrorTemplate("No suitable parse function was found to handle '$literal'")
+EXPECTED_EXPRESSION_AFTER_OPERATOR = ErrorTemplate("expected expression after operator '$operator', got $got")
+UNEXPECTED_TOKEN_AT_START = ErrorTemplate("unexpected token '$token' at start of expression")
+EXPECTED_EXPRESSION = ErrorTemplate("expected expression, got $got")
+
+# Block and control flow errors
+EMPTY_IF_CONSEQUENCE = ErrorTemplate("If statement must have a non-empty consequence block")
+EMPTY_ELSE_BLOCK = ErrorTemplate("Else/otherwise block must not be empty. If no alternative is needed, omit it.")
+EMPTY_WHILE_BODY = ErrorTemplate("While loop must have a non-empty body block")
+EMPTY_FOR_EACH_BODY = ErrorTemplate("For-each loop must have a non-empty body block")
+EXPECTED_DETAILS_CLOSE = ErrorTemplate("Expected </details> tag after action body, got $token_type")
+EXPECTED_BLOCK_MARKER = ErrorTemplate("Expected block marker '>', got $token_type")
+EXPECTED_PREFIX_OPERATOR = ErrorTemplate("Expected prefix operator, got $token_type")
+MISSING_DEPTH_TRANSITION = ErrorTemplate(
+    "After nested blocks ($nested_depth), add a blank line with just '$parent_depth' "
+    "before continuing at the parent depth. Found '$token_type' at line $line"
+)
+UNEXPECTED_BLOCK_DEPTH = ErrorTemplate("Unexpected block depth: expected $expected '>' but got $actual")
+
+# Collection and list errors
+INVALID_NAMED_LIST_KEY = ErrorTemplate("Named list keys must be string literals. Got $literal")
+
+# Use statement errors
+EXPECTED_FUNCTION_NAME = ErrorTemplate("Expected identifier for function name, got $token_type")
+EXPECTED_IDENTIFIER_FOR_NAMED_ARG = ErrorTemplate("Expected identifier for named argument, got $type_name")
+POSITIONAL_AFTER_NAMED = ErrorTemplate("Positional arguments cannot appear after named arguments")
+INVALID_ARGUMENT_VALUE = ErrorTemplate("Invalid argument value: '$literal'")
+MISSING_COMMA_BETWEEN_ARGS = ErrorTemplate("Expected comma between arguments")
+
+# Generic parser errors
+EXPECTED_TOKEN_AFTER = ErrorTemplate("Expected $expected after $after")
+EXPECTED_IDENTIFIER_AFTER = ErrorTemplate("Expected $what identifier after $after")
+EXPECTED_TOKEN = ErrorTemplate("Expected $token, got $got_token_type")
+ILLEGAL_CHARACTER = ErrorTemplate("Expected $expected but found illegal character '$character'")
+ILLEGAL_TOKEN = ErrorTemplate("Illegal token: '$token'")
+UNEXPECTED_STATEMENT = ErrorTemplate("Unexpected statement type: $type")
+UNHANDLED_OPERATION = ErrorTemplate("Unhandled $what operation: $operation")
+INVALID_TYPE_NAME = ErrorTemplate("'$name' is not a valid type name. Expected one of: $valid_types")
+
+# Interpreter errors
+UNKNOWN_PREFIX_OPERATOR = ErrorTemplate("Unknown prefix operator: $operator")
+UNKNOWN_INFIX_OPERATOR = ErrorTemplate("Unknown infix operator: $operator")
+TYPE_MISMATCH = ErrorTemplate(
+    "Type mismatch: cannot apply operator '$operator' to operands of type '$left_type' and '$right_type'"
+)
+UNSUPPORTED_OPERATION = ErrorTemplate("Unsupported operation: '$operation' on type '$type'")
+DIVISION_BY_ZERO = ErrorTemplate("Division by zero")
+UNSUPPORTED_OPERAND_TYPE = ErrorTemplate("Unsupported operand type(s) for $operator: '$left_type' and '$right_type'")
+UNSUPPORTED_UNARY_OPERAND = ErrorTemplate("Unsupported operand type for unary $operator: '$type'")