vex-ast 0.2.4__py3-none-any.whl → 0.2.6__py3-none-any.whl

vex_ast/utils/__init__.py

@@ -1,38 +1,38 @@
-"""
-Utilities package for VEX AST.
-
-This package provides utility functions and classes for working with the AST.
-"""
-
-from .errors import (
-    ErrorHandler,
-    ErrorType,
-    VexSyntaxError,
-    VexAstError,
-    Error
-)
-from .source_location import (
-    SourceLocation,
-)
-from .type_definitions import (
-    NodeType,
-    VisitorType,
-    TransformerType
-)
-
-__all__ = [
-    # Error handling
-    "ErrorHandler",
-    "ErrorType",
-    "VexSyntaxError",
-    "VexAstError",
-    "Error",
-    
-    # Source location
-    "SourceLocation",
-    
-    # Type definitions
-    "NodeType",
-    "VisitorType",
-    "TransformerType"
+"""
+Utilities package for VEX AST.
+
+This package provides utility functions and classes for working with the AST.
+"""
+
+from .errors import (
+    ErrorHandler,
+    ErrorType,
+    VexSyntaxError,
+    VexAstError,
+    Error
+)
+from .source_location import (
+    SourceLocation,
+)
+from .type_definitions import (
+    NodeType,
+    VisitorType,
+    TransformerType
+)
+
+__all__ = [
+    # Error handling
+    "ErrorHandler",
+    "ErrorType",
+    "VexSyntaxError",
+    "VexAstError",
+    "Error",
+    
+    # Source location
+    "SourceLocation",
+    
+    # Type definitions
+    "NodeType",
+    "VisitorType",
+    "TransformerType"
 ]

vex_ast/utils/errors.py

@@ -1,112 +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 = True):
-        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)
+"""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 = True):
+        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

@@ -1,39 +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 ""
+"""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}"

vex_ast/utils/type_definitions.py

@@ -1,9 +1,9 @@
-# vex_ast/utils/type_definitions.py
-"""Type definitions for type hints in the VEX AST."""
-
-from typing import Any, Dict, List, Optional, TypeVar, Union, Type, Protocol
-
-# Type variables for type hints
-NodeType = TypeVar('NodeType')
-VisitorType = TypeVar('VisitorType')
+# vex_ast/utils/type_definitions.py
+"""Type definitions for type hints in the VEX AST."""
+
+from typing import Any, Dict, List, Optional, TypeVar, Union, Type, Protocol
+
+# Type variables for type hints
+NodeType = TypeVar('NodeType')
+VisitorType = TypeVar('VisitorType')
 TransformerType = TypeVar('TransformerType')

vex_ast/visitors/README.md

@@ -1,49 +1,49 @@
-AST Visitors (vex_ast.visitors)
-
-This directory provides implementations of the Visitor design pattern for traversing and operating on the VEX Abstract Syntax Tree (AST).
-
-Purpose
-
-Visitors allow you to perform operations on the AST without modifying the AST node classes themselves. They provide a clean and extensible way to implement various forms of analysis, transformation, or code generation based on the AST structure.
-
-Core Concepts
-
-Visitor Pattern: The core idea is double dispatch. You call visitor.visit(node), which in turn calls node.accept(visitor). The node's accept method then calls the specific visit_NodeType(node) method on the visitor corresponding to its own type.
-
-Base Visitor (base.py):
-
-AstVisitor[T_VisitorResult]: An abstract generic base class for all visitors. It defines the main visit entry point and provides default visit_NodeType methods that typically delegate to a generic_visit method. Subclasses must implement generic_visit and can override specific visit_NodeType methods for custom behavior.
-
-Traversal: The generic_visit method in concrete visitors often iterates through the node's children (obtained via node.get_children()) and calls self.visit(child) recursively to traverse the tree.
-
-Provided Visitors
-
-Printer (printer.py):
-
-PrintVisitor: Traverses the AST and generates a formatted, indented string representation of the tree structure, including node types, attributes, and source locations (if available). Useful for debugging and understanding the AST structure.
-
-Analyzers (analyzer.py):
-
-NodeCounter: Traverses the AST and counts the total number of nodes, optionally keeping track of counts per node type.
-
-VariableCollector: Traverses the AST and collects the names of all variables referenced (VariableReference nodes).
-
-Usage
-
-Instantiate a Visitor: Create an instance of the desired visitor class (e.g., printer = PrintVisitor()).
-
-Parse Code: Obtain the root node (Program object) of the AST using vex_ast.parse_string or vex_ast.parse_file.
-
-Start Visitation: Call the visitor's visit method with the root node (e.g., result = printer.visit(ast_root)).
-
-Process Result: The visit method will return a result whose type depends on the specific visitor (T_VisitorResult). For PrintVisitor, it's a string; for NodeCounter, an integer; for VariableCollector, a set of strings.
-
-Extensibility
-
-You can create custom visitors to perform specific tasks (e.g., type checking, code optimization, simulation execution) by:
-
-Creating a new class that inherits from AstVisitor[YourResultType].
-
-Implementing the generic_visit method to define default behavior and traversal logic.
-
-Overriding specific visit_NodeType methods for nodes where specialized logic is required.
+AST Visitors (vex_ast.visitors)
+
+This directory provides implementations of the Visitor design pattern for traversing and operating on the VEX Abstract Syntax Tree (AST).
+
+Purpose
+
+Visitors allow you to perform operations on the AST without modifying the AST node classes themselves. They provide a clean and extensible way to implement various forms of analysis, transformation, or code generation based on the AST structure.
+
+Core Concepts
+
+Visitor Pattern: The core idea is double dispatch. You call visitor.visit(node), which in turn calls node.accept(visitor). The node's accept method then calls the specific visit_NodeType(node) method on the visitor corresponding to its own type.
+
+Base Visitor (base.py):
+
+AstVisitor[T_VisitorResult]: An abstract generic base class for all visitors. It defines the main visit entry point and provides default visit_NodeType methods that typically delegate to a generic_visit method. Subclasses must implement generic_visit and can override specific visit_NodeType methods for custom behavior.
+
+Traversal: The generic_visit method in concrete visitors often iterates through the node's children (obtained via node.get_children()) and calls self.visit(child) recursively to traverse the tree.
+
+Provided Visitors
+
+Printer (printer.py):
+
+PrintVisitor: Traverses the AST and generates a formatted, indented string representation of the tree structure, including node types, attributes, and source locations (if available). Useful for debugging and understanding the AST structure.
+
+Analyzers (analyzer.py):
+
+NodeCounter: Traverses the AST and counts the total number of nodes, optionally keeping track of counts per node type.
+
+VariableCollector: Traverses the AST and collects the names of all variables referenced (VariableReference nodes).
+
+Usage
+
+Instantiate a Visitor: Create an instance of the desired visitor class (e.g., printer = PrintVisitor()).
+
+Parse Code: Obtain the root node (Program object) of the AST using vex_ast.parse_string or vex_ast.parse_file.
+
+Start Visitation: Call the visitor's visit method with the root node (e.g., result = printer.visit(ast_root)).
+
+Process Result: The visit method will return a result whose type depends on the specific visitor (T_VisitorResult). For PrintVisitor, it's a string; for NodeCounter, an integer; for VariableCollector, a set of strings.
+
+Extensibility
+
+You can create custom visitors to perform specific tasks (e.g., type checking, code optimization, simulation execution) by:
+
+Creating a new class that inherits from AstVisitor[YourResultType].
+
+Implementing the generic_visit method to define default behavior and traversal logic.
+
+Overriding specific visit_NodeType methods for nodes where specialized logic is required.

vex_ast/visitors/__init__.py

@@ -1,28 +1,28 @@
-"""
-Visitors package for VEX AST.
-
-This package provides visitor pattern implementations for traversing and transforming the AST.
-"""
-
-from .base import (
-    AstVisitor,
-    TypedVisitorMixin
-)
-from .printer import PrintVisitor
-from .analyzer import (
-    NodeCounter,
-    VariableCollector
-)
-
-__all__ = [
-    # Base visitors
-    "AstVisitor",
-    "TypedVisitorMixin",
-    
-    # Concrete visitors
-    "PrintVisitor",
-    
-    # Analysis visitors
-    "NodeCounter",
-    "VariableCollector"
+"""
+Visitors package for VEX AST.
+
+This package provides visitor pattern implementations for traversing and transforming the AST.
+"""
+
+from .base import (
+    AstVisitor,
+    TypedVisitorMixin
+)
+from .printer import PrintVisitor
+from .analyzer import (
+    NodeCounter,
+    VariableCollector
+)
+
+__all__ = [
+    # Base visitors
+    "AstVisitor",
+    "TypedVisitorMixin",
+    
+    # Concrete visitors
+    "PrintVisitor",
+    
+    # Analysis visitors
+    "NodeCounter",
+    "VariableCollector"
 ]