vex-ast 0.1.0__py3-none-any.whl

vex_ast/serialization/schema.py

@@ -0,0 +1,471 @@
+"""
+JSON Schema generation for AST nodes.
+
+This module provides functionality to generate JSON Schema definitions
+for the AST structure, which can be used for validation and documentation.
+"""
+
+import json
+import os
+from typing import Any, Dict, List, Optional, Set, Type
+
+from ..ast.core import Program, Expression, Statement
+from ..ast.expressions import (
+    AttributeAccess, BinaryOperation, FunctionCall, Identifier, KeywordArgument, 
+    UnaryOperation, VariableReference
+)
+from ..ast.literals import (
+    BooleanLiteral, NoneLiteral, NumberLiteral, StringLiteral
+)
+from ..ast.statements import (
+    Assignment, BreakStatement, ContinueStatement, ExpressionStatement,
+    ForLoop, FunctionDefinition, IfStatement, ReturnStatement, WhileLoop, Argument
+)
+from ..ast.vex_nodes import (
+    DisplayOutput, MotorControl, SensorReading, TimingControl, VexAPICall
+)
+
+
+def generate_ast_schema() -> Dict[str, Any]:
+    """
+    Generate a JSON Schema describing the AST node structure.
+    
+    Returns:
+        A JSON Schema object as a dictionary
+    """
+    schema = {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "VEX AST Schema",
+        "description": "JSON Schema for VEX AST nodes",
+        "type": "object",
+        "required": ["type"],
+        "properties": {
+            "type": {
+                "type": "string",
+                "description": "The type of AST node"
+            },
+            "location": {
+                "$ref": "#/definitions/SourceLocation"
+            }
+        },
+        "oneOf": [
+            {"$ref": f"#/definitions/{node_type}"} 
+            for node_type in _get_all_node_types()
+        ],
+        "definitions": _generate_definitions()
+    }
+    
+    return schema
+
+
+def _get_all_node_types() -> List[str]:
+    """
+    Get a list of all AST node type names.
+    
+    Returns:
+        A list of node type names
+    """
+    # Core types
+    node_types = ["Program"]
+    
+    # Expression types
+    node_types.extend([
+        "Identifier", "VariableReference", "AttributeAccess",
+        "BinaryOperation", "UnaryOperation", "FunctionCall",
+        "KeywordArgument"
+    ])
+    
+    # Literal types
+    node_types.extend([
+        "NumberLiteral", "StringLiteral", "BooleanLiteral", "NoneLiteral"
+    ])
+    
+    # Statement types
+    node_types.extend([
+        "ExpressionStatement", "Assignment", "IfStatement",
+        "WhileLoop", "ForLoop", "FunctionDefinition", "Argument",
+        "ReturnStatement", "BreakStatement", "ContinueStatement"
+    ])
+    
+    # VEX-specific types
+    node_types.extend([
+        "VexAPICall", "MotorControl", "SensorReading",
+        "TimingControl", "DisplayOutput"
+    ])
+    
+    return node_types
+
+
+def _generate_definitions() -> Dict[str, Any]:
+    """
+    Generate schema definitions for all AST node types.
+    
+    Returns:
+        A dictionary of schema definitions
+    """
+    definitions = {}
+    
+    # Add SourceLocation definition
+    definitions["SourceLocation"] = {
+        "type": "object",
+        "required": ["line", "column"],
+        "properties": {
+            "line": {
+                "type": "integer",
+                "description": "The line number (1-based)"
+            },
+            "column": {
+                "type": "integer",
+                "description": "The column number (1-based)"
+            },
+            "end_line": {
+                "type": "integer",
+                "description": "The ending line number"
+            },
+            "end_column": {
+                "type": "integer",
+                "description": "The ending column number"
+            },
+            "filename": {
+                "type": "string",
+                "description": "The source filename"
+            }
+        }
+    }
+    
+    # Add node type definitions
+    
+    # Program
+    definitions["Program"] = {
+        "type": "object",
+        "required": ["type", "body"],
+        "properties": {
+            "type": {"enum": ["Program"]},
+            "body": {
+                "type": "array",
+                "description": "List of statements in the program",
+                "items": {"$ref": "#/definitions/Statement"}
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    # Expression base
+    definitions["Expression"] = {
+        "type": "object",
+        "required": ["type"],
+        "properties": {
+            "type": {"type": "string"},
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        },
+        "oneOf": [
+            {"$ref": f"#/definitions/{expr_type}"} 
+            for expr_type in [
+                "Identifier", "VariableReference", "AttributeAccess",
+                "BinaryOperation", "UnaryOperation", "FunctionCall",
+                "NumberLiteral", "StringLiteral", "BooleanLiteral", "NoneLiteral"
+            ]
+        ]
+    }
+    
+    # Statement base
+    definitions["Statement"] = {
+        "type": "object",
+        "required": ["type"],
+        "properties": {
+            "type": {"type": "string"},
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        },
+        "oneOf": [
+            {"$ref": f"#/definitions/{stmt_type}"} 
+            for stmt_type in [
+                "ExpressionStatement", "Assignment", "IfStatement",
+                "WhileLoop", "ForLoop", "FunctionDefinition",
+                "ReturnStatement", "BreakStatement", "ContinueStatement"
+            ]
+        ]
+    }
+    
+    # Literals
+    definitions["NumberLiteral"] = {
+        "type": "object",
+        "required": ["type", "value"],
+        "properties": {
+            "type": {"enum": ["NumberLiteral"]},
+            "value": {
+                "oneOf": [
+                    {"type": "number"},
+                    {"type": "integer"}
+                ],
+                "description": "The numeric value"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["StringLiteral"] = {
+        "type": "object",
+        "required": ["type", "value"],
+        "properties": {
+            "type": {"enum": ["StringLiteral"]},
+            "value": {
+                "type": "string",
+                "description": "The string value"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["BooleanLiteral"] = {
+        "type": "object",
+        "required": ["type", "value"],
+        "properties": {
+            "type": {"enum": ["BooleanLiteral"]},
+            "value": {
+                "type": "boolean",
+                "description": "The boolean value"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["NoneLiteral"] = {
+        "type": "object",
+        "required": ["type"],
+        "properties": {
+            "type": {"enum": ["NoneLiteral"]},
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    # Expressions
+    definitions["Identifier"] = {
+        "type": "object",
+        "required": ["type", "name"],
+        "properties": {
+            "type": {"enum": ["Identifier"]},
+            "name": {
+                "type": "string",
+                "description": "The identifier name"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["VariableReference"] = {
+        "type": "object",
+        "required": ["type", "identifier"],
+        "properties": {
+            "type": {"enum": ["VariableReference"]},
+            "identifier": {
+                "$ref": "#/definitions/Identifier",
+                "description": "The referenced identifier"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["AttributeAccess"] = {
+        "type": "object",
+        "required": ["type", "object", "attribute"],
+        "properties": {
+            "type": {"enum": ["AttributeAccess"]},
+            "object": {
+                "$ref": "#/definitions/Expression",
+                "description": "The object expression"
+            },
+            "attribute": {
+                "type": "string",
+                "description": "The attribute name"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["BinaryOperation"] = {
+        "type": "object",
+        "required": ["type", "left", "op", "right"],
+        "properties": {
+            "type": {"enum": ["BinaryOperation"]},
+            "left": {
+                "$ref": "#/definitions/Expression",
+                "description": "The left operand"
+            },
+            "op": {
+                "type": "string",
+                "description": "The operator"
+            },
+            "right": {
+                "$ref": "#/definitions/Expression",
+                "description": "The right operand"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["UnaryOperation"] = {
+        "type": "object",
+        "required": ["type", "op", "operand"],
+        "properties": {
+            "type": {"enum": ["UnaryOperation"]},
+            "op": {
+                "type": "string",
+                "description": "The operator"
+            },
+            "operand": {
+                "$ref": "#/definitions/Expression",
+                "description": "The operand"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["FunctionCall"] = {
+        "type": "object",
+        "required": ["type", "function", "args"],
+        "properties": {
+            "type": {"enum": ["FunctionCall"]},
+            "function": {
+                "$ref": "#/definitions/Expression",
+                "description": "The function expression"
+            },
+            "args": {
+                "type": "array",
+                "description": "The positional arguments",
+                "items": {"$ref": "#/definitions/Expression"}
+            },
+            "keywords": {
+                "type": "array",
+                "description": "The keyword arguments",
+                "items": {"$ref": "#/definitions/KeywordArgument"}
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["KeywordArgument"] = {
+        "type": "object",
+        "required": ["type", "name", "value"],
+        "properties": {
+            "type": {"enum": ["KeywordArgument"]},
+            "name": {
+                "type": "string",
+                "description": "The argument name"
+            },
+            "value": {
+                "$ref": "#/definitions/Expression",
+                "description": "The argument value"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    # Statements
+    definitions["ExpressionStatement"] = {
+        "type": "object",
+        "required": ["type", "expression"],
+        "properties": {
+            "type": {"enum": ["ExpressionStatement"]},
+            "expression": {
+                "$ref": "#/definitions/Expression",
+                "description": "The expression"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["Assignment"] = {
+        "type": "object",
+        "required": ["type", "target", "value"],
+        "properties": {
+            "type": {"enum": ["Assignment"]},
+            "target": {
+                "$ref": "#/definitions/Expression",
+                "description": "The assignment target"
+            },
+            "value": {
+                "$ref": "#/definitions/Expression",
+                "description": "The assigned value"
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    definitions["IfStatement"] = {
+        "type": "object",
+        "required": ["type", "test", "body"],
+        "properties": {
+            "type": {"enum": ["IfStatement"]},
+            "test": {
+                "$ref": "#/definitions/Expression",
+                "description": "The condition expression"
+            },
+            "body": {
+                "type": "array",
+                "description": "The if-body statements",
+                "items": {"$ref": "#/definitions/Statement"}
+            },
+            "orelse": {
+                "oneOf": [
+                    {
+                        "type": "array",
+                        "description": "The else-body statements",
+                        "items": {"$ref": "#/definitions/Statement"}
+                    },
+                    {
+                        "$ref": "#/definitions/IfStatement",
+                        "description": "An elif statement"
+                    }
+                ]
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    # Add more definitions for other node types...
+    
+    # VEX-specific nodes
+    definitions["VexAPICall"] = {
+        "type": "object",
+        "required": ["type", "function", "args"],
+        "properties": {
+            "type": {"enum": ["VexAPICall"]},
+            "function": {
+                "$ref": "#/definitions/Expression",
+                "description": "The function expression"
+            },
+            "args": {
+                "type": "array",
+                "description": "The positional arguments",
+                "items": {"$ref": "#/definitions/Expression"}
+            },
+            "keywords": {
+                "type": "array",
+                "description": "The keyword arguments",
+                "items": {"$ref": "#/definitions/KeywordArgument"}
+            },
+            "location": {"$ref": "#/definitions/SourceLocation"}
+        }
+    }
+    
+    # Add more VEX-specific node definitions...
+    
+    return definitions
+
+
+def export_schema_to_file(filepath: str, indent: int = 2) -> None:
+    """
+    Save the generated schema to a file.
+    
+    Args:
+        filepath: The path to save the schema to
+        indent: The indentation level for pretty-printing
+    """
+    schema = generate_ast_schema()
+    
+    # Ensure the directory exists
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+    
+    # Write the schema to the file
+    with open(filepath, 'w') as f:
+        json.dump(schema, f, indent=indent)

vex_ast/utils/errors.py

@@ -0,0 +1,112 @@
+"""Error handling framework for the VEX AST."""
+
+import logging
+from enum import Enum, auto
+from typing import List, Optional, Callable, Protocol, Any, TypeVar, cast
+
+from .source_location import SourceLocation
+
+# Configure basic logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class ErrorType(Enum):
+    """Types of errors that can occur during AST processing."""
+    LEXER_ERROR = auto()
+    PARSER_ERROR = auto()
+    TYPE_ERROR = auto()
+    SEMANTIC_ERROR = auto()
+    INTERNAL_ERROR = auto()
+
+class Error:
+    """Represents a single error detected during processing."""
+    
+    def __init__(self, 
+                 error_type: ErrorType,
+                 message: str,
+                 location: Optional[SourceLocation] = None,
+                 suggestion: Optional[str] = None):
+        self.error_type = error_type
+        self.message = message
+        self.location = location
+        self.suggestion = suggestion
+    
+    def __str__(self) -> str:
+        """Format the error for display."""
+        loc_str = f" at {self.location}" if self.location else ""
+        sugg_str = f"\n  Suggestion: {self.suggestion}" if self.suggestion else ""
+        return f"[{self.error_type.name}]{loc_str}: {self.message}{sugg_str}"
+
+# Error handler callback protocol
+T_Error = TypeVar('T_Error', bound=Error)
+
+class ErrorObserver(Protocol[T_Error]):
+    """Protocol for objects that can observe errors."""
+    
+    def on_error(self, error: T_Error) -> None:
+        """Handle an error notification."""
+        ...
+
+class ErrorHandler:
+    """Manages error collection and notification."""
+    
+    def __init__(self, raise_on_error: bool = False):
+        self._errors: List[Error] = []
+        self._raise_on_error = raise_on_error
+        self._observers: List[ErrorObserver] = []
+    
+    def add_error(self,
+                  error_type: ErrorType,
+                  message: str,
+                  location: Optional[SourceLocation] = None,
+                  suggestion: Optional[str] = None) -> None:
+        """Add an error to the collection."""
+        error = Error(error_type, message, location, suggestion)
+        self._errors.append(error)
+        logger.error(str(error))
+        
+        # Notify observers
+        for observer in self._observers:
+            try:
+                observer.on_error(error)
+            except Exception as e:
+                logger.exception(f"Error observer failed: {e}")
+        
+        if self._raise_on_error:
+            if error_type == ErrorType.PARSER_ERROR:
+                raise VexSyntaxError(message, location)
+            else:
+                raise VexAstError(str(error))
+    
+    def get_errors(self) -> List[Error]:
+        """Get a copy of all collected errors."""
+        return self._errors.copy()
+    
+    def has_errors(self) -> bool:
+        """Check if any errors have been collected."""
+        return bool(self._errors)
+    
+    def clear_errors(self) -> None:
+        """Clear all collected errors."""
+        self._errors.clear()
+    
+    def add_observer(self, observer: ErrorObserver) -> None:
+        """Add an observer to be notified of errors."""
+        if observer not in self._observers:
+            self._observers.append(observer)
+    
+    def remove_observer(self, observer: ErrorObserver) -> None:
+        """Remove an error observer."""
+        if observer in self._observers:
+            self._observers.remove(observer)
+
+class VexAstError(Exception):
+    """Base exception class for VEX AST errors."""
+    pass
+
+class VexSyntaxError(VexAstError):
+    """Exception raised for syntax errors during parsing."""
+    
+    def __init__(self, message: str, location: Optional[SourceLocation] = None):
+        self.location = location
+        super().__init__(message)

vex_ast/utils/source_location.py

@@ -0,0 +1,39 @@
+"""Source location tracking for AST nodes."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class SourceLocation:
+    """Represents a location in source code."""
+    
+    # Start position
+    line: int
+    column: int
+    
+    # End position (optional)
+    end_line: Optional[int] = None
+    end_column: Optional[int] = None
+    
+    # Source file
+    filename: Optional[str] = None
+    
+    def __post_init__(self):
+        """Validate and normalize the location data."""
+        # Ensure end line is at least start line if not specified
+        if self.end_line is None:
+            self.end_line = self.line
+    
+    def __str__(self) -> str:
+        """Format the location for display."""
+        file_prefix = f"{self.filename}:" if self.filename else ""
+        
+        # Just a point or single line span
+        if self.end_line == self.line:
+            if self.end_column is None or self.end_column == self.column:
+                return f"{file_prefix}L{self.line}:{self.column}"
+            return f"{file_prefix}L{self.line}:{self.column}-{self.end_column}"
+        
+        # Multi-line span
+        end_col = f":{self.end_column}" if self.end_column is not None else ""
+        return f"{file_prefix}L{self.line}:{self.column}-L{self.end_line}{end_col}"