vex-ast 0.1.0__py3-none-any.whl

vex_ast/__init__.py

@@ -0,0 +1,65 @@
+"""
+VEX AST Generator Package.
+
+Provides tools for parsing VEX V5 code and generating an Abstract Syntax Tree (AST).
+"""
+
+from .ast.core import Program
+from .ast.navigator import AstNavigator
+from .parser.python_parser import parse_string, parse_file
+from .visitors.printer import PrintVisitor
+from .visitors.analyzer import NodeCounter, VariableCollector
+from .utils.errors import ErrorHandler, ErrorType, VexSyntaxError
+from .registry import registry_api, initialize as initialize_registry
+from .serialization.json_serializer import serialize_ast_to_dict, serialize_ast_to_json
+from .serialization.json_deserializer import deserialize_ast_from_dict, deserialize_ast_from_json
+from .serialization.schema import generate_ast_schema, export_schema_to_file
+
+__version__ = "0.2.0"
+
+# Initialize the registry with default functions
+initialize_registry()
+
+def create_navigator(ast: Program) -> AstNavigator:
+    """Create an AST navigator for the given AST.
+    
+    Args:
+        ast: The AST to navigate
+        
+    Returns:
+        An AST navigator for traversing and querying the AST
+    """
+    return AstNavigator(ast)
+
+__all__ = [
+    # Core functionality
+    "Program",
+    "parse_string",
+    "parse_file",
+    
+    # AST Navigation
+    "AstNavigator",
+    "create_navigator",
+    
+    # Visitors
+    "PrintVisitor",
+    "NodeCounter",
+    "VariableCollector",
+    
+    # Error handling
+    "ErrorHandler",
+    "ErrorType",
+    "VexSyntaxError",
+    
+    # Registry
+    "registry_api",
+    "initialize_registry",
+    
+    # Serialization
+    "serialize_ast_to_dict",
+    "serialize_ast_to_json",
+    "deserialize_ast_from_dict",
+    "deserialize_ast_from_json",
+    "generate_ast_schema",
+    "export_schema_to_file"
+]

vex_ast/ast/__init__.py

@@ -0,0 +1,75 @@
+"""Abstract Syntax Tree (AST) package for VEX code."""
+
+# Core AST classes
+from .interfaces import (
+    IAstNode, IExpression, IStatement, ILiteral, IIdentifier, IFunctionCall, IAssignment,
+    IVisitor, T_VisitorResult, AstNode
+)
+from .core import Expression, Statement, Program
+from .expressions import (
+    Identifier, VariableReference, AttributeAccess,
+    BinaryOperation, UnaryOperation, FunctionCall, KeywordArgument
+)
+from .statements import (
+    ExpressionStatement, Assignment, Argument, FunctionDefinition,
+    IfStatement, WhileLoop, ForLoop, ReturnStatement,
+    BreakStatement, ContinueStatement
+)
+from .literals import (
+    Literal, NumberLiteral, StringLiteral, BooleanLiteral, NoneLiteral
+)
+from .operators import Operator
+from .vex_nodes import (
+    VexAPICallType, VexAPICall, MotorControl, SensorReading,
+    TimingControl, DisplayOutput, create_vex_api_call,
+    create_vex_api_call_from_interface
+)
+from .validators import validate_vex_functions, VexFunctionValidator
+from .navigator import AstNavigator
+
+# Expose the navigator as a factory function
+def create_navigator(root: IAstNode) -> AstNavigator:
+    """Create an AST navigator for the given root node.
+    
+    Args:
+        root: The root node of the AST
+        
+    Returns:
+        An AST navigator for traversing and querying the AST
+    """
+    return AstNavigator(root)
+
+__all__ = [
+    # Interfaces
+    'IAstNode', 'IExpression', 'IStatement', 'ILiteral', 'IIdentifier', 
+    'IFunctionCall', 'IAssignment', 'IVisitor', 'T_VisitorResult', 'AstNode',
+    
+    # Core
+    'Expression', 'Statement', 'Program',
+    
+    # Expressions
+    'Identifier', 'VariableReference', 'AttributeAccess',
+    'BinaryOperation', 'UnaryOperation', 'FunctionCall', 'KeywordArgument',
+    
+    # Statements
+    'ExpressionStatement', 'Assignment', 'Argument', 'FunctionDefinition',
+    'IfStatement', 'WhileLoop', 'ForLoop', 'ReturnStatement',
+    'BreakStatement', 'ContinueStatement',
+    
+    # Literals
+    'Literal', 'NumberLiteral', 'StringLiteral', 'BooleanLiteral', 'NoneLiteral',
+    
+    # Operators
+    'Operator',
+    
+    # VEX-specific
+    'VexAPICallType', 'VexAPICall', 'MotorControl', 'SensorReading',
+    'TimingControl', 'DisplayOutput', 'create_vex_api_call',
+    'create_vex_api_call_from_interface',
+    
+    # Validators
+    'validate_vex_functions', 'VexFunctionValidator',
+    
+    # Navigator
+    'AstNavigator', 'create_navigator',
+]

vex_ast/ast/core.py

@@ -0,0 +1,71 @@
+"""Core AST node implementations."""
+
+from typing import Any, Dict, List, Optional, Union, cast
+
+from .interfaces import AstNode, IAstNode, IExpression, IStatement, IVisitor, T_VisitorResult
+from ..utils.source_location import SourceLocation
+
+class Expression(AstNode):
+    """Base class for expression nodes."""
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        """Default implementation that defers to visitor."""
+        method_name = f"visit_{self.__class__.__name__.lower()}"
+        if hasattr(visitor, method_name):
+            return getattr(visitor, method_name)(self)
+        return visitor.visit_expression(self)
+
+class Statement(AstNode):
+    """Base class for statement nodes."""
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        """Default implementation that defers to visitor."""
+        method_name = f"visit_{self.__class__.__name__.lower()}"
+        if hasattr(visitor, method_name):
+            return getattr(visitor, method_name)(self)
+        return visitor.visit_statement(self)
+
+class Program(AstNode):
+    """Root node of the AST, representing the entire program."""
+    
+    _fields = ('body',)
+    
+    def __init__(self, body: List[IStatement], location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.body = body
+        
+        # Set parent references
+        for statement in self.body:
+            if isinstance(statement, AstNode):
+                statement.set_parent(self)
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        """Accept a visitor."""
+        return visitor.visit_program(self)
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        return cast(List[IAstNode], self.body)
+    
+    def get_statements(self) -> List[IStatement]:
+        """Get all statements in the program."""
+        return self.body
+    
+    def add_statement(self, statement: IStatement) -> None:
+        """Add a statement to the program."""
+        self.body.append(statement)
+        if isinstance(statement, AstNode):
+            statement.set_parent(self)
+    
+    def insert_statement(self, index: int, statement: IStatement) -> None:
+        """Insert a statement at a specific position."""
+        self.body.insert(index, statement)
+        if isinstance(statement, AstNode):
+            statement.set_parent(self)
+    
+    def remove_statement(self, statement: IStatement) -> bool:
+        """Remove a statement from the program."""
+        if statement in self.body:
+            self.body.remove(statement)
+            return True
+        return False

vex_ast/ast/expressions.py

@@ -0,0 +1,233 @@
+"""Expression nodes for the AST."""
+
+from typing import Dict, List, Optional, Union, cast, Any
+
+from .interfaces import IAstNode, IExpression, IVisitor, T_VisitorResult, IIdentifier, IFunctionCall
+from .core import Expression
+from .operators import Operator
+from ..utils.source_location import SourceLocation
+
+class Identifier(Expression, IIdentifier):
+    """An identifier (variable name, function name, etc.)."""
+    
+    _fields = ('name',)
+    
+    def __init__(self, name: str, location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.name = name
+    
+    def get_children(self) -> List[IAstNode]:
+        """Identifiers have no children."""
+        return []
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_identifier(self)
+    
+    def get_name(self) -> str:
+        """Get the identifier name."""
+        return self.name
+
+class VariableReference(Expression):
+    """A reference to a variable."""
+    
+    _fields = ('identifier',)
+    
+    def __init__(self, identifier: Identifier, location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.identifier = identifier
+        if isinstance(identifier, Expression):
+            identifier.set_parent(self)
+    
+    @property
+    def name(self) -> str:
+        """Convenience property to get the variable name."""
+        return self.identifier.name
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        return [self.identifier]
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_variablereference(self)
+    
+    def get_identifier(self) -> IIdentifier:
+        """Get the identifier being referenced."""
+        return self.identifier
+
+class AttributeAccess(Expression):
+    """An attribute access expression (e.g., object.attribute)."""
+    
+    _fields = ('object', 'attribute')
+    
+    def __init__(self, object_expr: IExpression, attribute: str, 
+                location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.object = object_expr
+        self.attribute = attribute
+        if isinstance(object_expr, Expression):
+            object_expr.set_parent(self)
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        return [cast(IAstNode, self.object)]
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_attributeaccess(self)
+    
+    def get_object(self) -> IExpression:
+        """Get the object expression."""
+        return self.object
+    
+    def get_attribute_name(self) -> str:
+        """Get the attribute name."""
+        return self.attribute
+
+class BinaryOperation(Expression):
+    """A binary operation (e.g., a + b)."""
+    
+    _fields = ('left', 'op', 'right')
+    
+    def __init__(self, left: IExpression, op: Operator, right: IExpression, 
+                 location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.left = left
+        self.op = op
+        self.right = right
+        if isinstance(left, Expression):
+            left.set_parent(self)
+        if isinstance(right, Expression):
+            right.set_parent(self)
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        return [cast(IAstNode, self.left), cast(IAstNode, self.right)]
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_binaryoperation(self)
+    
+    def get_left(self) -> IExpression:
+        """Get the left operand."""
+        return self.left
+    
+    def get_right(self) -> IExpression:
+        """Get the right operand."""
+        return self.right
+    
+    def get_operator(self) -> Operator:
+        """Get the operator."""
+        return self.op
+
+class UnaryOperation(Expression):
+    """A unary operation (e.g., -a, not b)."""
+    
+    _fields = ('op', 'operand')
+    
+    def __init__(self, op: Operator, operand: IExpression, 
+                 location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.op = op
+        self.operand = operand
+        if isinstance(operand, Expression):
+            operand.set_parent(self)
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        return [cast(IAstNode, self.operand)]
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_unaryoperation(self)
+    
+    def get_operand(self) -> IExpression:
+        """Get the operand."""
+        return self.operand
+    
+    def get_operator(self) -> Operator:
+        """Get the operator."""
+        return self.op
+
+class KeywordArgument(Expression):
+    """A keyword argument in a function call (name=value)."""
+    
+    _fields = ('name', 'value')
+    
+    def __init__(self, name: str, value: IExpression, 
+                 location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.name = name
+        self.value = value
+        if isinstance(value, Expression):
+            value.set_parent(self)
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        return [cast(IAstNode, self.value)]
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_keywordargument(self)
+    
+    def get_name(self) -> str:
+        """Get the keyword name."""
+        return self.name
+    
+    def get_value(self) -> IExpression:
+        """Get the keyword value."""
+        return self.value
+
+class FunctionCall(Expression, IFunctionCall):
+    """A function call."""
+    
+    _fields = ('function', 'args', 'keywords')
+    
+    def __init__(self, function: IExpression, args: List[IExpression],
+                 keywords: List[KeywordArgument] = None,
+                 location: Optional[SourceLocation] = None):
+        super().__init__(location)
+        self.function = function
+        self.args = args or []
+        self.keywords = keywords or []
+        
+        # Set parent references
+        if isinstance(function, Expression):
+            function.set_parent(self)
+        
+        for arg in self.args:
+            if isinstance(arg, Expression):
+                arg.set_parent(self)
+        
+        for kw in self.keywords:
+            if isinstance(kw, Expression):
+                kw.set_parent(self)
+    
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes."""
+        result: List[IAstNode] = [cast(IAstNode, self.function)]
+        result.extend(cast(List[IAstNode], self.args))
+        result.extend(cast(List[IAstNode], self.keywords))
+        return result
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        return visitor.visit_functioncall(self)
+    
+    def get_function_expr(self) -> IExpression:
+        """Get the function expression."""
+        return self.function
+    
+    def get_arguments(self) -> List[IExpression]:
+        """Get the positional arguments."""
+        return self.args
+    
+    def get_keyword_arguments(self) -> Dict[str, IExpression]:
+        """Get the keyword arguments as a dictionary."""
+        return {kw.name: kw.value for kw in self.keywords}
+    
+    def add_argument(self, arg: IExpression) -> None:
+        """Add a positional argument."""
+        self.args.append(arg)
+        if isinstance(arg, Expression):
+            arg.set_parent(self)
+    
+    def add_keyword_argument(self, name: str, value: IExpression) -> None:
+        """Add a keyword argument."""
+        kw = KeywordArgument(name, value)
+        self.keywords.append(kw)
+        kw.set_parent(self)

vex_ast/ast/interfaces.py

@@ -0,0 +1,192 @@
+"""Fundamental interfaces and protocols for the AST."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Iterable, List, Optional, Protocol, TypeVar, Generic, runtime_checkable, Dict, Union, Tuple
+
+from ..utils.source_location import SourceLocation
+
+# Visitor pattern type variable
+T_VisitorResult = TypeVar('T_VisitorResult')
+
+class IVisitor(Protocol, Generic[T_VisitorResult]):
+    """Protocol for AST visitors."""
+    
+    def visit(self, node: 'IAstNode') -> T_VisitorResult:
+        """Visit an AST node."""
+        ...
+
+@runtime_checkable
+class IAstNode(Protocol):
+    """Protocol defining the minimum interface for an AST node."""
+    
+    location: Optional[SourceLocation]
+    
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        """Accept a visitor (Visitor Pattern)."""
+        ...
+    
+    def get_children(self) -> Iterable['IAstNode']:
+        """Get child nodes of this node."""
+        ...
+    
+    def get_child_by_name(self, name: str) -> Optional['IAstNode']:
+        """Get a child node by its field name."""
+        ...
+    
+    def get_child_names(self) -> List[str]:
+        """Get the names of all child fields."""
+        ...
+    
+    def get_parent(self) -> Optional['IAstNode']:
+        """Get the parent node, if available."""
+        ...
+    
+    def get_attributes(self) -> Dict[str, Any]:
+        """Get all attributes of this node as a dictionary."""
+        ...
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the node to a dictionary representation.
+        
+        This is an optional method for serialization support.
+        
+        Returns:
+            A dictionary representation of the node
+        """
+        ...
+
+@runtime_checkable
+class IExpression(IAstNode, Protocol):
+    """Protocol for expression nodes."""
+    pass
+
+@runtime_checkable
+class IStatement(IAstNode, Protocol):
+    """Protocol for statement nodes."""
+    pass
+
+@runtime_checkable
+class ILiteral(IExpression, Protocol):
+    """Protocol for literal value nodes."""
+    value: Any
+    
+    def get_value(self) -> Any:
+        """Get the literal value."""
+        ...
+
+@runtime_checkable
+class IIdentifier(IExpression, Protocol):
+    """Protocol for identifier nodes."""
+    name: str
+    
+    def get_name(self) -> str:
+        """Get the identifier name."""
+        ...
+
+@runtime_checkable
+class IFunctionCall(IExpression, Protocol):
+    """Protocol for function call nodes."""
+    
+    def get_function_expr(self) -> IExpression:
+        """Get the function expression."""
+        ...
+    
+    def get_arguments(self) -> List[IExpression]:
+        """Get the positional arguments."""
+        ...
+    
+    def get_keyword_arguments(self) -> Dict[str, IExpression]:
+        """Get the keyword arguments as a dictionary."""
+        ...
+
+@runtime_checkable
+class IAssignment(IStatement, Protocol):
+    """Protocol for assignment nodes."""
+    
+    def get_target(self) -> IExpression:
+        """Get the assignment target."""
+        ...
+    
+    def get_value(self) -> IExpression:
+        """Get the assigned value."""
+        ...
+
+class AstNode(ABC):
+    """Abstract base implementation of the IAstNode protocol."""
+    
+    def __init__(self, location: Optional[SourceLocation] = None):
+        self.location = location
+        self._parent: Optional[IAstNode] = None
+    
+    @abstractmethod
+    def accept(self, visitor: IVisitor[T_VisitorResult]) -> T_VisitorResult:
+        """Accept a visitor (Visitor Pattern)."""
+        pass
+    
+    @abstractmethod
+    def get_children(self) -> List[IAstNode]:
+        """Get child nodes of this node."""
+        pass
+    
+    def get_child_by_name(self, name: str) -> Optional[IAstNode]:
+        """Get a child node by its field name."""
+        if not hasattr(self, '_fields') or name not in getattr(self, '_fields'):
+            return None
+        
+        value = getattr(self, name, None)
+        if isinstance(value, IAstNode):
+            return value
+        elif isinstance(value, list) and value and isinstance(value[0], IAstNode):
+            return value[0]  # Return first item if it's a list of nodes
+        
+        return None
+    
+    def get_child_names(self) -> List[str]:
+        """Get the names of all child fields."""
+        if not hasattr(self, '_fields'):
+            return []
+        return list(getattr(self, '_fields'))
+    
+    def get_parent(self) -> Optional[IAstNode]:
+        """Get the parent node, if available."""
+        return getattr(self, '_parent', None)
+    
+    def set_parent(self, parent: IAstNode) -> None:
+        """Set the parent node reference."""
+        self._parent = parent
+    
+    def get_attributes(self) -> Dict[str, Any]:
+        """Get all attributes of this node as a dictionary."""
+        result = {}
+        if hasattr(self, '_fields'):
+            for field in getattr(self, '_fields'):
+                result[field] = getattr(self, field, None)
+        return result
+    
+    def __eq__(self, other: Any) -> bool:
+        """Compare nodes for equality."""
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        
+        # Compare all attributes defined in _fields
+        if hasattr(self, '_fields'):
+            for field in getattr(self, '_fields'):
+                if getattr(self, field, None) != getattr(other, field, None):
+                    return False
+        
+        # Compare location
+        return self.location == other.location
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the node to a dictionary representation.
+        
+        This implementation uses the serialization visitor to create a
+        dictionary representation of the node.
+        
+        Returns:
+            A dictionary representation of the node
+        """
+        from ..serialization.json_serializer import serialize_ast_to_dict
+        return serialize_ast_to_dict(self)