vex-ast 0.2.7

A Python package for generating Abstract Syntax Trees for VEX V5 code.

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.

Recent Updates (v0.2.6)

Major Registry Overhaul

• Introduced a modern category system with VexCategory and BehaviorType enums
• Improved function organization and querying capabilities
• Added missing Brain and Controller constructors
• Maintained full backward compatibility

Enhanced API

• New methods for behavior-based function queries
• Combined category and behavior search functionality
• Improved validation mechanisms

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.
• Modern registry system with dual-axis categorization.

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.
• vex_ast/registry/: Modern function registry with category/behavior classification.
• vex_ast/types/: Type system for VEX components and values.

Setup

1. Clone the repository:

   git clone https://github.com/heartx2/vex_ast # Replace with actual URL
   cd vex_ast
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
   

3. Install dependencies:

   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:

   pip install -e .[dev]
   

Usage Example

Basic Parsing and Printing

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}")

Registry Access

from vex_ast.registry.api import registry_api
from vex_ast.registry.categories import VexCategory, BehaviorType

# Find motor control functions
motor_control = registry_api.get_functions_by_category_and_behavior(
    VexCategory.MOTOR,
    BehaviorType.CONTROL
)

# Validate function calls
valid, error = registry_api.validate_call("motor.spin", [FORWARD, 50, "RPM"], {})

Serialization and Deserialization

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

# Running Tests
pytest

# Type Checking
mypy vex_ast

# 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

HX2's Vex AST © 2025 by charkwayteowy is licensed under CC BY-NC 4.0