vex-ast 0.1.0__tar.gz

vex_ast-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: vex_ast
+Version: 0.1.0
+Summary: A Python package for generating Abstract Syntax Trees for VEX V5 code.
+Home-page: https://github.com/teowy/vex_ast
+Author: Chaze
+Author-email: chazelexander@example.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# VEX AST Generator
+
+A Python package for generating Abstract Syntax Trees (ASTs) for VEX V5 Robot Python code.
+
+## Project Goal
+
+The primary goal of this project is to provide a robust and extensible framework for parsing VEX V5 Python code and representing it as an Abstract Syntax Tree (AST). This AST can then be used for various purposes, such as static analysis, code transformation, simulation, or integration with other development tools specific to the VEX ecosystem.
+
+## Features (Implemented)
+
+*   Parsing of standard Python syntax relevant to VEX programming.
+*   Generation of a well-defined AST structure using custom node types.
+*   Representation of core Python constructs (variables, functions, loops, conditionals, expressions).
+*   Specific AST nodes for common VEX API patterns (e.g., `MotorControl`, `SensorReading`).
+*   Visitor pattern implementation (`vex_ast.visitors`) for easy AST traversal and manipulation.
+*   Basic analysis visitors (`NodeCounter`, `VariableCollector`).
+*   AST pretty-printing visitor (`PrintVisitor`).
+*   Error handling and reporting with source location information (`vex_ast.utils`).
+*   JSON serialization and deserialization of AST nodes (`vex_ast.serialization`).
+*   JSON Schema generation for AST structure validation and documentation.
+
+## Library Structure
+
+The core library is within the `vex_ast` directory:
+
+*   `vex_ast/ast/`: Defines the structure and node types of the Abstract Syntax Tree.
+*   `vex_ast/parser/`: Contains the logic for parsing Python source code into the AST.
+*   `vex_ast/visitors/`: Provides tools for traversing and analyzing the generated AST.
+*   `vex_ast/utils/`: Includes helper modules for error handling and source location tracking.
+
+## Setup
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/yourusername/vex_ast.git # Replace with actual URL
+    cd vex_ast
+    ```
+
+2.  **Create and activate a virtual environment:**
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+    ```
+
+3.  **Install dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4.  **(Optional) Install for development:**
+    If you plan to contribute to the project, install it in editable mode along with development dependencies:
+    ```bash
+    pip install -e .[dev]
+    ```
+
+## Usage Example
+
+### Basic Parsing and Printing
+
+```python
+from vex_ast import parse_string
+from vex_ast.visitors.printer import PrintVisitor
+
+# VEX-like Python code
+code = """
+left_motor = Motor("port1")
+right_motor = Motor("port10")
+
+def drive_forward(speed_percent):
+    left_motor.spin(FORWARD, speed_percent, PERCENT)
+    right_motor.spin(FORWARD, speed_percent, PERCENT)
+    wait(1, SECONDS)
+    left_motor.stop()
+    right_motor.stop()
+
+drive_forward(50)
+print("Movement complete!")
+"""
+
+try:
+    # Parse the code string into an AST
+    ast_tree = parse_string(code)
+
+    # Use the PrintVisitor to get a textual representation of the AST
+    printer = PrintVisitor()
+    ast_representation = printer.visit(ast_tree)
+
+    print("--- AST Representation ---")
+    print(ast_representation)
+
+except Exception as e:
+    print(f"An error occurred: {e}")
+```
+
+### Serialization and Deserialization
+
+```python
+from vex_ast import (
+    parse_string, 
+    serialize_ast_to_json, 
+    deserialize_ast_from_json,
+    export_schema_to_file
+)
+
+# Parse code into an AST
+code = "x = 10 + 20"
+ast = parse_string(code)
+
+# Serialize the AST to JSON
+json_str = serialize_ast_to_json(ast, indent=2)
+print(json_str)
+
+# Save the AST to a file
+with open("ast.json", "w") as f:
+    f.write(json_str)
+
+# Later, load the AST from JSON
+with open("ast.json", "r") as f:
+    loaded_json = f.read()
+    
+# Deserialize back to an AST object
+loaded_ast = deserialize_ast_from_json(loaded_json)
+
+# Generate and export a JSON schema
+export_schema_to_file("ast_schema.json")
+```
+
+## Development
+```bash
+Running Tests
+pytest
+```
+```bash
+Type Checking
+mypy vex_ast
+```
+```bash
+Formatting and Linting
+black vex_ast tests
+flake8 vex_ast tests
+```
+## Contributing
+
+Contributions are welcome! Please follow the established coding standards and ensure tests pass before submitting a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details (You'll need to add a LICENSE file).

vex_ast-0.1.0/README.md

@@ -0,0 +1,148 @@
+# VEX AST Generator
+
+A Python package for generating Abstract Syntax Trees (ASTs) for VEX V5 Robot Python code.
+
+## Project Goal
+
+The primary goal of this project is to provide a robust and extensible framework for parsing VEX V5 Python code and representing it as an Abstract Syntax Tree (AST). This AST can then be used for various purposes, such as static analysis, code transformation, simulation, or integration with other development tools specific to the VEX ecosystem.
+
+## Features (Implemented)
+
+*   Parsing of standard Python syntax relevant to VEX programming.
+*   Generation of a well-defined AST structure using custom node types.
+*   Representation of core Python constructs (variables, functions, loops, conditionals, expressions).
+*   Specific AST nodes for common VEX API patterns (e.g., `MotorControl`, `SensorReading`).
+*   Visitor pattern implementation (`vex_ast.visitors`) for easy AST traversal and manipulation.
+*   Basic analysis visitors (`NodeCounter`, `VariableCollector`).
+*   AST pretty-printing visitor (`PrintVisitor`).
+*   Error handling and reporting with source location information (`vex_ast.utils`).
+*   JSON serialization and deserialization of AST nodes (`vex_ast.serialization`).
+*   JSON Schema generation for AST structure validation and documentation.
+
+## Library Structure
+
+The core library is within the `vex_ast` directory:
+
+*   `vex_ast/ast/`: Defines the structure and node types of the Abstract Syntax Tree.
+*   `vex_ast/parser/`: Contains the logic for parsing Python source code into the AST.
+*   `vex_ast/visitors/`: Provides tools for traversing and analyzing the generated AST.
+*   `vex_ast/utils/`: Includes helper modules for error handling and source location tracking.
+
+## Setup
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/yourusername/vex_ast.git # Replace with actual URL
+    cd vex_ast
+    ```
+
+2.  **Create and activate a virtual environment:**
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+    ```
+
+3.  **Install dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4.  **(Optional) Install for development:**
+    If you plan to contribute to the project, install it in editable mode along with development dependencies:
+    ```bash
+    pip install -e .[dev]
+    ```
+
+## Usage Example
+
+### Basic Parsing and Printing
+
+```python
+from vex_ast import parse_string
+from vex_ast.visitors.printer import PrintVisitor
+
+# VEX-like Python code
+code = """
+left_motor = Motor("port1")
+right_motor = Motor("port10")
+
+def drive_forward(speed_percent):
+    left_motor.spin(FORWARD, speed_percent, PERCENT)
+    right_motor.spin(FORWARD, speed_percent, PERCENT)
+    wait(1, SECONDS)
+    left_motor.stop()
+    right_motor.stop()
+
+drive_forward(50)
+print("Movement complete!")
+"""
+
+try:
+    # Parse the code string into an AST
+    ast_tree = parse_string(code)
+
+    # Use the PrintVisitor to get a textual representation of the AST
+    printer = PrintVisitor()
+    ast_representation = printer.visit(ast_tree)
+
+    print("--- AST Representation ---")
+    print(ast_representation)
+
+except Exception as e:
+    print(f"An error occurred: {e}")
+```
+
+### Serialization and Deserialization
+
+```python
+from vex_ast import (
+    parse_string, 
+    serialize_ast_to_json, 
+    deserialize_ast_from_json,
+    export_schema_to_file
+)
+
+# Parse code into an AST
+code = "x = 10 + 20"
+ast = parse_string(code)
+
+# Serialize the AST to JSON
+json_str = serialize_ast_to_json(ast, indent=2)
+print(json_str)
+
+# Save the AST to a file
+with open("ast.json", "w") as f:
+    f.write(json_str)
+
+# Later, load the AST from JSON
+with open("ast.json", "r") as f:
+    loaded_json = f.read()
+    
+# Deserialize back to an AST object
+loaded_ast = deserialize_ast_from_json(loaded_json)
+
+# Generate and export a JSON schema
+export_schema_to_file("ast_schema.json")
+```
+
+## Development
+```bash
+Running Tests
+pytest
+```
+```bash
+Type Checking
+mypy vex_ast
+```
+```bash
+Formatting and Linting
+black vex_ast tests
+flake8 vex_ast tests
+```
+## Contributing
+
+Contributions are welcome! Please follow the established coding standards and ensure tests pass before submitting a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details (You'll need to add a LICENSE file).

vex_ast-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vex_ast-0.1.0/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='vex_ast',
+    version='0.1.0',
+    description='A Python package for generating Abstract Syntax Trees for VEX V5 code.',
+    long_description=open('README.md').read(),
+    long_description_content_type='text/markdown',
+    author='Chaze',  # Replace with your actual name
+    author_email='chazelexander@example.com',  # Replace with your actual email
+    url='https://github.com/teowy/vex_ast',  # Replace with your actual repository URL
+    packages=find_packages(exclude=['tests*']),
+    install_requires=[
+        # Add runtime dependencies here if any
+    ],
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Topic :: Software Development :: Compilers',
+        'Topic :: Software Development :: Libraries :: Python Modules',
+    ],
+    python_requires='>=3.8',
+)

vex_ast-0.1.0/tests/test_core.py

@@ -0,0 +1,86 @@
+# tests/test_core.py
+import pytest
+from vex_ast.ast.core import Program, Expression, Statement
+from vex_ast.ast.statements import ExpressionStatement
+from vex_ast.ast.expressions import Identifier
+from vex_ast.visitors.base import AstVisitor
+
+# Simple test visitor for testing
+class TestVisitor(AstVisitor[str]):
+    def generic_visit(self, node):
+        return "generic"
+    
+    def visit_program(self, node):
+        return "program"
+    
+    def visit_expression(self, node):
+        return "expression"
+    
+    def visit_statement(self, node):
+        return "statement"
+    
+    # Implement required methods
+    visit_identifier = generic_visit
+    visit_variablereference = generic_visit
+    visit_binaryoperation = generic_visit
+    visit_unaryoperation = generic_visit
+    visit_functioncall = generic_visit
+    visit_keywordargument = generic_visit
+    visit_numberliteral = generic_visit
+    visit_stringliteral = generic_visit
+    visit_booleanliteral = generic_visit
+    visit_noneliteral = generic_visit
+    visit_expressionstatement = generic_visit
+    visit_assignment = generic_visit
+    visit_ifstatement = generic_visit
+    visit_whileloop = generic_visit
+    visit_forloop = generic_visit
+    visit_functiondefinition = generic_visit
+    visit_argument = generic_visit
+    visit_returnstatement = generic_visit
+    visit_breakstatement = generic_visit
+    visit_continuestatement = generic_visit
+    visit_vexapicall = generic_visit
+    visit_motorcontrol = generic_visit
+    visit_sensorreading = generic_visit
+    visit_timingcontrol = generic_visit
+    visit_displayoutput = generic_visit
+
+class TestCoreNodes:
+    def test_program_node(self):
+        body = [ExpressionStatement(Identifier("x"))]
+        program = Program(body)
+        
+        assert program.body == body
+        assert program.get_children() == body
+        
+        # Test visitor pattern
+        visitor = TestVisitor()
+        result = program.accept(visitor)
+        assert result == "program"
+        
+    def test_expression_base(self):
+        # Create a simple Expression subclass for testing
+        class TestExpression(Expression):
+            def get_children(self):
+                return []
+        
+        expr = TestExpression()
+        
+        # Test visitor pattern
+        visitor = TestVisitor()
+        result = expr.accept(visitor)
+        assert result == "expression"
+        
+    def test_statement_base(self):
+        # Create a simple Statement subclass for testing
+        class TestStatement(Statement):
+            def get_children(self):
+                return []
+        
+        stmt = TestStatement()
+        
+        # Test visitor pattern
+        visitor = TestVisitor()
+        result = stmt.accept(visitor)
+        assert result == "statement"

vex_ast-0.1.0/tests/test_integration.py

@@ -0,0 +1,70 @@
+# tests/test_integration.py
+import pytest
+from vex_ast import parse_string
+from vex_ast.visitors.printer import PrintVisitor
+from vex_ast.visitors.analyzer import NodeCounter, VariableCollector
+
+class TestIntegration:
+    def test_full_program_parse(self):
+        # A complete program with multiple features
+        code = """
+        def drive_forward(speed, time_ms):
+            # Set both motors to the specified speed
+            left_motor.set_velocity(speed, PERCENT)
+            right_motor.set_velocity(speed, PERCENT)
+            
+            # Start the motors
+            left_motor.spin(FORWARD)
+            right_motor.spin(FORWARD)
+            
+            # Wait for the specified time
+            wait(time_ms, MSEC)
+            
+            # Stop the motors
+            left_motor.stop()
+            right_motor.stop()
+            
+            return True
+
+        # Main program
+        def main():
+            # Display welcome message
+            brain.screen.print("Robot starting...")
+            wait(1, SECONDS)
+            
+            # Drive forward at 50% speed for 2 seconds
+            success = drive_forward(50, 2000)
+            
+            if success:
+                brain.screen.print("Drive completed!")
+            else:
+                brain.screen.print("Drive failed!")
+            
+            return 0
+        """
+        
+        # Just test that parsing doesn't raise exceptions
+        ast = parse_string(code)
+        
+        # Check that we have two function definitions
+        assert len(ast.body) == 2
+        assert ast.body[0].__class__.__name__ == "FunctionDefinition"
+        assert ast.body[1].__class__.__name__ == "FunctionDefinition"
+        assert ast.body[0].name == "drive_forward"
+        assert ast.body[1].name == "main"
+        
+        # Test that visitors work with the complex AST
+        printer = PrintVisitor()
+        result = printer.visit(ast)
+        assert isinstance(result, str)
+        
+        counter = NodeCounter()
+        count = counter.visit(ast)
+        assert count > 30  # Should have many nodes
+        
+        collector = VariableCollector()
+        variables = collector.visit(ast)
+        assert "left_motor" in variables
+        assert "right_motor" in variables
+        assert "brain" in variables
+        assert "success" in variables

vex_ast-0.1.0/tests/test_literals.py

@@ -0,0 +1,56 @@
+# tests/test_literals.py
+import pytest
+from vex_ast.ast.literals import NumberLiteral, StringLiteral, BooleanLiteral, NoneLiteral
+from vex_ast.visitors.printer import PrintVisitor
+from vex_ast.utils.source_location import SourceLocation
+
+class TestLiterals:
+    def test_number_literal(self):
+        # Test integer
+        nl = NumberLiteral(42)
+        assert nl.value == 42
+        
+        # Test float
+        nl = NumberLiteral(3.14)
+        assert nl.value == 3.14
+        
+        # Test with location
+        loc = SourceLocation(1, 5)
+        nl = NumberLiteral(100, loc)
+        assert nl.location == loc
+        
+    def test_string_literal(self):
+        sl = StringLiteral("hello")
+        assert sl.value == "hello"
+        
+        # Test empty string
+        sl = StringLiteral("")
+        assert sl.value == ""
+        
+    def test_boolean_literal(self):
+        # Test True
+        bl = BooleanLiteral(True)
+        assert bl.value is True
+        
+        # Test False
+        bl = BooleanLiteral(False)
+        assert bl.value is False
+        
+    def test_none_literal(self):
+        nl = NoneLiteral()
+        assert nl.value is None
+        
+    def test_visitor_pattern(self):
+        # Test that visitor pattern works correctly
+        visitor = PrintVisitor()
+        
+        nl = NumberLiteral(42)
+        sl = StringLiteral("hello")
+        bl = BooleanLiteral(True)
+        none_l = NoneLiteral()
+        
+        # Just test that these don't raise exceptions
+        visitor.visit(nl)
+        visitor.visit(sl)
+        visitor.visit(bl)
+        visitor.visit(none_l)

vex_ast-0.1.0/tests/test_navigator.py

@@ -0,0 +1,121 @@
+"""Tests for the AST navigator."""
+
+import pytest
+from vex_ast import parse_string, create_navigator
+from vex_ast.ast.expressions import Identifier, VariableReference, FunctionCall
+from vex_ast.ast.statements import Assignment, FunctionDefinition
+from vex_ast.ast.literals import NumberLiteral, StringLiteral
+from vex_ast.ast.vex_nodes import VexAPICall
+
+class TestAstNavigator:
+    """Test the AST navigator functionality."""
+    
+    def test_basic_navigation(self):
+        """Test basic navigation functionality."""
+        code = """
+        # Define a motor
+        motor1 = Motor(PORT1)
+        
+        # Define a function
+        def move_forward(speed):
+            motor1.spin(FORWARD, speed, PERCENT)
+            wait(1, SECONDS)
+            motor1.stop()
+            return True
+        
+        # Call the function
+        success = move_forward(50)
+        """
+        
+        # Parse the code
+        ast = parse_string(code)
+        
+        # Create a navigator
+        navigator = create_navigator(ast)
+        
+        # Test finding all identifiers
+        identifiers = navigator.find_identifiers()
+        assert len(identifiers) > 0
+        assert any(ident.name == "motor1" for ident in identifiers)
+        assert any(ident.name == "move_forward" for ident in identifiers)
+        
+        # Test finding all function calls
+        function_calls = navigator.find_function_calls()
+        assert len(function_calls) > 0
+        
+        # Test finding VEX API calls
+        vex_calls = navigator.find_vex_api_calls()
+        assert len(vex_calls) > 0
+        
+        # Test finding function definitions
+        func_defs = navigator.find_function_definitions()
+        assert len(func_defs) == 1
+        assert func_defs[0].name == "move_forward"
+        
+        # Test finding assignments
+        assignments = navigator.find_assignments()
+        assert len(assignments) > 0
+        
+        # Test finding literals
+        literals = navigator.find_literals()
+        assert len(literals) > 0
+        
+        # Test finding a function by name
+        move_forward = navigator.get_function_by_name("move_forward")
+        assert move_forward is not None
+        assert move_forward.name == "move_forward"
+        
+        # Test finding variable references
+        motor_refs = navigator.get_variable_references("motor1")
+        assert len(motor_refs) > 0
+    
+    def test_parent_child_relationships(self):
+        """Test parent-child relationship navigation."""
+        code = """
+        x = 10
+        y = 20
+        z = x + y
+        """
+        
+        # Parse the code
+        ast = parse_string(code)
+        
+        # Create a navigator
+        navigator = create_navigator(ast)
+        
+        # Find the assignment 'z = x + y'
+        assignments = navigator.find_assignments()
+        z_assignment = next(a for a in assignments if hasattr(a.target, 'name') and a.target.name == 'z')
+        
+        # The right side should be a binary operation
+        binary_op = z_assignment.value
+        
+        # Test parent-child relationship
+        assert binary_op.get_parent() is z_assignment
+        
+        # Test finding siblings
+        siblings = navigator.find_siblings(z_assignment)
+        assert len(siblings) == 2  # The other two assignments
+    
+    def test_registry_api_integration(self):
+        """Test integration with the registry API."""
+        code = """
+        motor1 = Motor(PORT1)
+        motor1.spin(FORWARD, 50, PERCENT)
+        """
+        
+        # Parse the code
+        ast = parse_string(code)
+        
+        # Create a navigator
+        navigator = create_navigator(ast)
+        
+        # Find VEX API calls
+        vex_calls = navigator.find_vex_api_calls()
+        assert len(vex_calls) > 0
+        
+        # Test that the signature is resolved correctly
+        spin_call = next(call for call in vex_calls if call.get_function_name() and 'spin' in call.get_function_name())
+        signature = spin_call.resolve_signature()
+        assert signature is not None
+        assert signature.name == "spin"