vex-ast 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

vex_ast/README.md

@@ -0,0 +1,51 @@
+VEX AST Package (vex_ast)
+
+This directory is the root of the vex_ast Python package. It orchestrates the different components of the VEX AST generation and processing system.
+
+Purpose
+
+The vex_ast package provides a unified interface for parsing VEX V5 Python code into an Abstract Syntax Tree (AST) and tools for working with that AST.
+
+Structure
+
+The package is organized into several sub-packages:
+
+ast/: Contains the definitions for all AST node types, representing the structure of the parsed code. See vex_ast/ast/README.md.
+
+parser/: Includes the parsing logic responsible for converting source code text into an AST instance. See vex_ast/parser/README.md.
+
+visitors/: Provides implementations of the Visitor pattern for traversing, analyzing, or transforming the AST. See vex_ast/visitors/README.md.
+
+utils/: Contains utility classes and functions, primarily for error handling and source location tracking. See vex_ast/utils/README.md.
+
+Core Exports
+
+The main components are exposed through the vex_ast/__init__.py file, making them easily accessible:
+
+parse_string(source, ...): Parses Python code from a string.
+
+parse_file(filepath, ...): Parses Python code from a file.
+
+Program: The root node type of the generated AST.
+
+PrintVisitor: A visitor to generate a string representation of the AST.
+
+NodeCounter: A visitor to count nodes in the AST.
+
+VariableCollector: A visitor to collect variable names used in the AST.
+
+ErrorHandler: Class for managing errors during parsing and processing.
+
+VexSyntaxError, VexAstError: Custom exception types.
+
+Workflow
+
+The typical workflow involves:
+
+Using parse_string or parse_file from this package to generate an AST (Program object) from source code.
+
+Instantiating one or more visitors from vex_ast.visitors (or custom ones).
+
+Calling the visit method of the visitor with the root Program node to perform analysis, transformation, or other operations on the AST.
+
+Using the ErrorHandler to manage and inspect any errors encountered during the process.

vex_ast/READMEAPI.md

@@ -0,0 +1,318 @@
+# VEX AST (`vex_ast`) - Public API Reference
+
+This document describes the main functions and classes exposed by the `vex_ast` package, intended for users who want to parse VEX V5 Python code and interact with the resulting Abstract Syntax Tree (AST).
+
+## Overview
+
+The core workflow typically involves:
+
+1.  Parsing source code (from a string or file) using `parse_string` or `parse_file`. This requires an optional `ErrorHandler` instance.
+2.  Receiving a `Program` object, which is the root of the generated AST.
+3.  Instantiating one or more `AstVisitor` subclasses (like `PrintVisitor`, `NodeCounter`, `VariableCollector`, or custom ones).
+4.  Calling the visitor's `visit()` method with the `Program` node to traverse the AST and perform actions.
+5.  Checking the `ErrorHandler` instance for any reported errors during parsing or visiting.
+
+---
+
+## Parsing Functions
+
+These functions are the entry points for converting source code into an AST.
+
+### `parse_string`
+
+Parses VEX V5 Python code provided as a string.
+
+**Signature:**
+
+```python
+def parse_string(
+    source: str,
+    filename: str = "<string>",
+    error_handler: Optional[ErrorHandler] = None
+) -> Program:
+
+
+Arguments:
+
+source (str): The string containing the Python code to parse.
+
+filename (str, optional): The name to associate with the source code, used in error messages and source locations. Defaults to "<string>".
+
+error_handler (Optional[ErrorHandler], optional): An instance of ErrorHandler to collect parsing errors. If None, a default ErrorHandler is created internally (which will raise VexSyntaxError on the first syntax error). It's recommended to provide your own handler to manage errors more flexibly.
+
+Returns:
+
+Program: The root node of the generated Abstract Syntax Tree.
+
+Raises:
+
+VexSyntaxError: If a syntax error is encountered during parsing and the error_handler is configured to raise errors immediately (or if no handler is provided).
+
+VexAstError: For other internal parsing or AST conversion issues if the error_handler is configured to raise errors.
+
+parse_file
+
+Parses VEX V5 Python code read from a specified file.
+
+Signature:
+
+def parse_file(
+    filepath: str,
+    error_handler: Optional[ErrorHandler] = None
+) -> Program:
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Arguments:
+
+filepath (str): The path to the Python file to be parsed.
+
+error_handler (Optional[ErrorHandler], optional): An instance of ErrorHandler to collect parsing errors. See parse_string for details.
+
+Returns:
+
+Program: The root node of the generated Abstract Syntax Tree.
+
+Raises:
+
+FileNotFoundError: If the specified filepath does not exist.
+
+IOError: If there is an error reading the file.
+
+VexSyntaxError: If a syntax error is encountered (see parse_string).
+
+VexAstError: For other internal parsing errors (see parse_string).
+
+Core AST Node
+Program
+
+Represents the root node of the entire Abstract Syntax Tree.
+
+Description:
+
+The Program node is the object returned by parse_string and parse_file. It serves as the entry point for traversing the AST using visitors.
+
+Key Attribute:
+
+body (List[IStatement]): A list containing the top-level statements (like function definitions, assignments, expression statements) found in the parsed code.
+
+Usage:
+
+You typically don't instantiate Program directly. You receive it from a parsing function and pass it to the visit() method of an AstVisitor.
+
+ast_root: Program = parse_string("x = 1")
+printer = PrintVisitor()
+printer.visit(ast_root) # Pass the Program node to the visitor
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+Standard Visitors
+
+Visitors provide mechanisms to traverse and process the AST. You instantiate a visitor and then call its visit method on an AST node (usually the Program root).
+
+PrintVisitor
+
+Generates a formatted, indented string representation of the AST structure. Useful for debugging and inspection.
+
+Instantiation:
+
+printer = PrintVisitor()
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Core Method:
+
+visit(node: IAstNode) -> str: Traverses the AST starting from node (typically the Program root) and returns a multi-line string representing the tree.
+
+Example:
+
+ast_root = parse_string("y = a + 5")
+visitor = PrintVisitor()
+ast_string_representation = visitor.visit(ast_root)
+print(ast_string_representation)
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+NodeCounter
+
+Counts the number of nodes in the AST.
+
+Instantiation:
+
+counter = NodeCounter()
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Core Method:
+
+visit(node: IAstNode) -> int: Traverses the AST starting from node and returns the total count of nodes visited.
+
+Additional Attribute:
+
+counts_by_type (Dict[str, int]): After calling visit, this dictionary holds the counts for each specific node type encountered (e.g., {'Assignment': 1, 'BinaryOperation': 1, ...}).
+
+Example:
+
+ast_root = parse_string("def f():\n  return 10")
+visitor = NodeCounter()
+total_nodes = visitor.visit(ast_root)
+print(f"Total nodes: {total_nodes}")
+print(f"Nodes by type: {visitor.counts_by_type}")
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+VariableCollector
+
+Collects the names of all variables referenced (read from) in the AST. Does not include variables only assigned to or function/class names being defined.
+
+Instantiation:
+
+collector = VariableCollector()
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Core Method:
+
+visit(node: IAstNode) -> Set[str]: Traverses the AST starting from node and returns a set containing the names of all referenced variables (identifiers used in a Load context).
+
+Example:
+
+code = """
+x = 10
+y = x + z
+def my_func(p):
+    q = p
+"""
+ast_root = parse_string(code)
+visitor = VariableCollector()
+referenced_vars = visitor.visit(ast_root)
+print(f"Referenced variables: {referenced_vars}") # Output: {'x', 'z', 'p'}
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+Error Handling
+
+Components for managing and reporting errors during parsing and processing.
+
+ErrorHandler
+
+Manages the collection and reporting of errors.
+
+Instantiation:
+
+# Option 1: Collect errors, don't raise exceptions immediately
+handler = ErrorHandler(raise_on_error=False)
+
+# Option 2: Raise VexSyntaxError/VexAstError on the first error
+handler = ErrorHandler(raise_on_error=True) # Default behavior if omitted
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+
+Key Methods:
+
+get_errors() -> List[Error]: Returns a list of all Error objects collected so far.
+
+has_errors() -> bool: Returns True if any errors have been collected, False otherwise. Useful after parsing with raise_on_error=False.
+
+clear_errors() -> None: Removes all collected errors.
+
+add_observer(observer: ErrorObserver) -> None: (Advanced) Registers a custom object to be notified whenever an error is added.
+
+remove_observer(observer: ErrorObserver) -> None: (Advanced) Unregisters an observer.
+
+Usage:
+
+Typically, you create an ErrorHandler instance and pass it to parse_string or parse_file.
+
+error_handler = ErrorHandler(raise_on_error=False)
+try:
+    ast = parse_string("x = 1 + ", error_handler=error_handler)
+    if error_handler.has_errors():
+        print("Parsing completed with non-fatal errors:")
+        for err in error_handler.get_errors():
+            print(f"- {err}")
+    else:
+        print("Parsing successful.")
+        # Proceed with AST processing...
+except VexAstError as e:
+     # This shouldn't happen if raise_on_error=False, but good practice
+     print(f"Unexpected VexAstError: {e}")
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+Python
+IGNORE_WHEN_COPYING_END
+ErrorType
+
+An Enum used within Error objects to categorize the type of error.
+
+Values:
+
+LEXER_ERROR
+
+PARSER_ERROR
+
+TYPE_ERROR
+
+SEMANTIC_ERROR
+
+INTERNAL_ERROR
+
+Usage:
+
+You typically check the error_type attribute of Error objects retrieved from ErrorHandler.get_errors().
+
+VexSyntaxError
+
+Exception raised specifically for syntax errors encountered during parsing when the ErrorHandler is configured to raise errors.
+
+Inheritance: VexSyntaxError -> VexAstError -> Exception
+
+Attribute:
+
+location (Optional[SourceLocation]): May contain the location (line, column) where the syntax error occurred.
+
+VexAstError
+
+The base exception class for all errors originating from the vex_ast library. VexSyntaxError is a subclass.
+
+This reference covers the main components needed to use the vex_ast library effectively for parsing and basic AST interaction. For more advanced use cases, you might need to delve into the specific AST node types in vex_ast.ast or create custom visitors inheriting from vex_ast.visitors.AstVisitor.
+
+IGNORE_WHEN_COPYING_START
+content_copy
+download
+Use code with caution.
+IGNORE_WHEN_COPYING_END

vex_ast/__init__.py

@@ -4,13 +4,25 @@ VEX AST Generator Package.
 Provides tools for parsing VEX V5 code and generating an Abstract Syntax Tree (AST).
 """
 
+# Core functionality
 from .ast.core import Program
-from .ast.navigator import AstNavigator
 from .parser.python_parser import parse_string, parse_file
+
+# AST Navigation
+from .ast.navigator import AstNavigator, create_navigator
+
+# Visitors
 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
+
+# Error handling
+from .utils.errors import ErrorHandler, ErrorType, VexSyntaxError, VexAstError, Error
+
+# Registry
+from .registry.api import registry_api
+from .registry import initialize
+
+# Serialization
 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
@@ -18,18 +30,7 @@ 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)
+initialize()
 
 __all__ = [
     # Core functionality
@@ -50,10 +51,12 @@ __all__ = [
     "ErrorHandler",
     "ErrorType",
     "VexSyntaxError",
+    "VexAstError",
+    "Error",
     
     # Registry
     "registry_api",
-    "initialize_registry",
+    "initialize",
     
     # Serialization
     "serialize_ast_to_dict",
@@ -62,4 +65,4 @@ __all__ = [
     "deserialize_ast_from_json",
     "generate_ast_schema",
     "export_schema_to_file"
-]
+]

vex_ast/ast/README.md

@@ -0,0 +1,87 @@
+AST Node Definitions (vex_ast.ast)
+
+This directory defines the structure and types of nodes used in the Abstract Syntax Tree (AST) representation of VEX V5 Python code.
+
+Purpose
+
+The AST provides a structured, hierarchical representation of the source code, abstracting away the specific syntax details. This structure is the foundation for analysis, transformation, and interpretation of the code.
+
+Core Concepts
+
+Interfaces (interfaces.py): Defines the fundamental protocols (IAstNode, IExpression, IStatement, ILiteral, IVisitor) that all nodes and visitors adhere to. This ensures a consistent structure.
+
+Base Classes (core.py): Provides abstract base classes (AstNode, Expression, Statement) that implement common functionality like location tracking and the basic accept method for the Visitor pattern. Program is the root node type.
+
+Visitor Pattern: Each node implements an accept(visitor) method, allowing external IVisitor objects to operate on the AST without modifying the node classes themselves.
+
+Child Nodes: Each node provides a get_children() method to facilitate traversal of the tree.
+
+Source Location: Nodes can store optional SourceLocation information (from vex_ast.utils) linking them back to the original code.
+
+Node Categories
+
+The AST nodes are organized into logical categories:
+
+Expressions (expressions.py): Represent code constructs that evaluate to a value.
+
+Identifier: Variable names, function names.
+
+VariableReference: Usage of a variable.
+
+AttributeAccess: Accessing attributes (e.g., motor.spin).
+
+BinaryOperation: Operations like +, -, *, /, ==, and, or.
+
+UnaryOperation: Operations like - (negation), not.
+
+FunctionCall: Calling functions or methods.
+
+KeywordArgument: Named arguments in function calls (e.g., speed=50).
+
+Literals (literals.py): Represent constant values.
+
+NumberLiteral: Integers and floats.
+
+StringLiteral: Text strings.
+
+BooleanLiteral: True or False.
+
+NoneLiteral: The None value.
+
+Statements (statements.py): Represent actions or control flow constructs.
+
+ExpressionStatement: An expression used on its own line (e.g., a function call).
+
+Assignment: Assigning a value to a variable (=).
+
+IfStatement: Conditional execution (if/elif/else).
+
+WhileLoop: Looping based on a condition.
+
+ForLoop: Iterating over a sequence.
+
+FunctionDefinition: Defining a function (def).
+
+Argument: Parameters in a function definition.
+
+ReturnStatement: Returning a value from a function.
+
+BreakStatement, ContinueStatement: Loop control.
+
+Operators (operators.py): Defines Operator enums used within BinaryOperation and UnaryOperation nodes. Includes mappings from Python operators.
+
+VEX-Specific Nodes (vex_nodes.py): Subclasses of FunctionCall tailored to represent common VEX API patterns.
+
+VexAPICall: Base class for VEX calls.
+
+MotorControl: Calls related to motors (e.g., motor.spin).
+
+SensorReading: Calls related to sensors (e.g., sensor.value).
+
+TimingControl: Calls like wait.
+
+DisplayOutput: Calls related to screen output (e.g., brain.screen.print).
+
+Usage
+
+These node classes are typically instantiated by the parser (vex_ast.parser) during the code parsing process. Visitors (vex_ast.visitors) then interact with these node objects to perform tasks.

vex_ast/ast/__init__.py

@@ -72,4 +72,4 @@ __all__ = [
     
     # Navigator
     'AstNavigator', 'create_navigator',
-]
+]

vex_ast/ast/navigator.py

@@ -211,3 +211,15 @@ class AstNavigator:
             if hasattr(access.object, 'name') and getattr(access.object, 'name') == object_name:
                 result.append(access)
         return result
+
+
+def create_navigator(ast_node: IAstNode) -> AstNavigator:
+    """Create a new AST navigator for the given AST node.
+    
+    Args:
+        ast_node: The AST node to navigate
+        
+    Returns:
+        A new AstNavigator instance
+    """
+    return AstNavigator(ast_node)

vex_ast/parser/README.md

@@ -0,0 +1,47 @@
+Code Parser (vex_ast.parser)
+
+This directory contains the components responsible for parsing VEX V5 Python source code and constructing the Abstract Syntax Tree (AST).
+
+Purpose
+
+The parser's role is to take raw source code (as a string or from a file) and transform it into the structured AST representation defined in vex_ast.ast. It handles syntax rules, identifies different code constructs, and builds the corresponding tree of nodes.
+
+Key Components
+
+Interfaces (interfaces.py):
+
+IParser: Protocol defining the essential parse() method that all parser implementations must provide.
+
+BaseParser: An abstract base class providing common functionality, such as integrating with the ErrorHandler.
+
+Node Factory (factory.py):
+
+NodeFactory: Implements the Factory pattern. It provides methods (create_identifier, create_binary_operation, etc.) to instantiate specific AST node types defined in vex_ast.ast. This decouples the main parsing logic from the details of node creation and allows for easier management of node instantiation, including attaching source locations and potentially handling errors during creation.
+
+Python Parser (python_parser.py):
+
+PythonParser: The concrete implementation of IParser. It leverages Python's built-in ast module to parse the input Python code into a standard Python AST.
+
+It then traverses the Python AST, using the NodeFactory to convert the standard Python nodes (ast.Assign, ast.Call, ast.BinOp, etc.) into the corresponding custom VEX AST nodes (Assignment, FunctionCall, BinaryOperation, etc.).
+
+Provides convenience functions parse_string and parse_file.
+
+Workflow
+
+The user calls parse_string or parse_file.
+
+An instance of PythonParser is created with the source code and an optional ErrorHandler.
+
+The PythonParser uses Python's ast.parse to generate a standard Python AST.
+
+The PythonParser walks through the Python AST. For each Python ast node, it determines the corresponding VEX AST node type.
+
+It calls the appropriate create_... method on its internal NodeFactory instance, passing the necessary components (sub-expressions, statements, names, values) converted recursively.
+
+The NodeFactory creates the VEX AST node, potentially adding source location information extracted from the original Python ast node.
+
+This process continues recursively until the entire Python AST is converted into the custom VEX AST (Program node).
+
+Any syntax errors during Python parsing or unsupported constructs during conversion are reported via the ErrorHandler.
+
+The final Program node representing the VEX AST is returned.

vex_ast/parser/__init__.py

@@ -0,0 +1,27 @@
+"""
+Parser package for VEX AST.
+
+This package provides functionality for parsing VEX code into an Abstract Syntax Tree.
+"""
+
+from .interfaces import (
+    IParser,
+    BaseParser
+)
+from .factory import NodeFactory, default_factory
+from .python_parser import parse_string, parse_file, PythonParser
+
+__all__ = [
+    # Interfaces
+    "IParser",
+    "BaseParser",
+    
+    # Factory
+    "NodeFactory",
+    "default_factory",
+    
+    # Python parser
+    "parse_string",
+    "parse_file",
+    "PythonParser"
+]

vex_ast/registry/README.md

@@ -0,0 +1,29 @@
+# VEX AST Registry Package (vex_ast.registry)
+
+This package manages the registration and organization of VEX V5 Robot Python language features, including functions, objects, and other elements.
+
+Purpose
+
+The registry provides a centralized system for defining and accessing information about VEX-specific language constructs. This information is used by the parser, type checker, and other tools to understand and process VEX code.
+
+Structure
+
+The package is organized into several modules:
+
+*   `categories.py`: Defines categories for organizing registry entries.
+*   `language_map.py`: Maps VEX language features to their Python equivalents.
+*   `registry.py`: Implements the core registry logic.
+*   `signature.py`: Defines the structure for function signatures.
+*   `simulation_behavior.py`: Specifies how VEX features should behave in a simulation environment.
+*   `validation.py`: Provides validation rules for registry entries.
+*   `functions/`: Contains submodules for specific function categories (e.g., drivetrain, motor, sensors).
+
+Key Concepts
+
+*   Registration: VEX language features are registered with the registry, providing metadata about their syntax, semantics, and simulation behavior.
+*   Organization: The registry organizes features into categories and subcategories for easy access and management.
+*   Validation: Registry entries are validated to ensure consistency and correctness.
+
+Usage
+
+The registry is used internally by the VEX AST parser and other tools. It is not typically accessed directly by users.

vex_ast/registry/functions/__init__.py

@@ -0,0 +1,11 @@
+"""
+Registry functions package for VEX AST.
+
+This package contains the function definitions for the VEX API registry.
+"""
+
+from .initialize import initialize_registry
+
+__all__ = [
+    "initialize_registry"
+]