vex-ast 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

vex_ast/README.md

@@ -1,51 +1,101 @@
-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 Package
+
+The VEX AST (Abstract Syntax Tree) package provides a comprehensive framework for parsing, analyzing, and simulating VEX V5 Robot Python code.
+
+## Key Features
+
+### Advanced Registry System
+- Dual-axis categorization (Category × Behavior)
+- Intelligent function signature validation
+- Language mapping (Python ↔ C++)
+- Full backward compatibility
+
+### Robust AST Generation
+- Python 3.8+ parsing with modern features
+- VEX-specific node types
+- Source location tracking
+- Error recovery and reporting
+
+### Extensible Visitor Pattern
+- Analysis visitors (NodeCounter, VariableCollector)
+- Transformation capabilities
+- Pretty printing and serialization
+
+## What's New in 0.2.6
+
+### Unified Category System
+- Introduced `VexCategory` enum for component types
+- Added `BehaviorType` enum for function behaviors
+- Maintained `SubCategory` for detailed classification
+- Deprecated `SimulationCategory` (still supported)
+
+### Enhanced Registry API
+- New query methods for behavior-based lookups
+- Combined category/behavior queries
+- Improved validation logic
+
+### Missing Components Added
+- Brain and Controller constructors
+- Complete VEX object type coverage
+
+## Usage
+
+### Basic Parsing
+```python
+from vex_ast import parse_string
+
+code = """
+motor1 = Motor(PORT1)
+motor1.spin(FORWARD, 50, RPM)
+"""
+
+ast = parse_string(code)
+```
+
+### Registry Access
+```python
+from vex_ast.registry.api import registry_api
+from vex_ast.registry.categories import VexCategory, BehaviorType
+
+# Find control functions
+control_funcs = registry_api.get_functions_by_behavior(BehaviorType.CONTROL)
+
+# Find motor functions
+motor_funcs = registry_api.get_functions_by_category(VexCategory.MOTOR)
+```
+
+## Architecture Overview
+
+```
+vex_ast/
+├── ast/          # AST node definitions
+├── parser/       # Parsing logic
+├── registry/     # Function registry system
+│   ├── api.py    # Public API
+│   ├── categories.py  # Category system
+│   └── functions/     # Function definitions
+├── types/        # Type system
+├── utils/        # Utilities
+└── visitors/     # AST traversal
+```
+
+## Installation
+
+```bash
+pip install vex-ast
+```
+
+## Documentation
+
+- [API Reference](./READMEAPI.md)
+- [Registry Guide](./registry/README.md)
+- [Type System](./types/README.md)
+- [Visitor Pattern](./visitors/README.md)
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines and code of conduct.
+
+## License
+
+HX2's Vex AST © 2025 by charkwayteowy is licensed under CC BY-NC 4.0

vex_ast/READMEAPI.md

@@ -1,318 +1,133 @@
-# 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 Registry API Reference
+
+The Registry API provides a comprehensive interface for accessing and querying VEX function information in the AST system.
+
+## Core API
+
+### Registration and Access
+
+#### `registry_api`
+Singleton instance providing access to all registry functionality.
+
+```python
+from vex_ast.registry.api import registry_api
+```
+
+### Function Queries
+
+#### `get_function(name: str, language: str = "python") -> Optional[VexFunctionSignature]`
+Retrieve a function signature by name.
+
+```python
+spin_function = registry_api.get_function("spin")
+```
+
+#### `get_functions_by_category(category: VexCategory) -> List[VexFunctionSignature]`
+Get all functions in a specific category.
+
+```python
+motor_functions = registry_api.get_functions_by_category(VexCategory.MOTOR)
+```
+
+#### `get_functions_by_behavior(behavior: BehaviorType) -> List[VexFunctionSignature]`
+Get all functions with a specific behavior.
+
+```python
+control_functions = registry_api.get_functions_by_behavior(BehaviorType.CONTROL)
+```
+
+#### `get_functions_by_category_and_behavior(category: VexCategory, behavior: BehaviorType) -> List[VexFunctionSignature]`
+Get functions matching both category and behavior.
+
+```python
+motor_control = registry_api.get_functions_by_category_and_behavior(
+    VexCategory.MOTOR,
+    BehaviorType.CONTROL
+)
+```
+
+### Method Access
+
+#### `get_method(object_type: Union[VexType, str], method_name: str) -> Optional[VexFunctionSignature]`
+Get a method signature for an object type.
+
+```python
+spin_method = registry_api.get_method(MOTOR, "spin")
+```
+
+### Validation
+
+#### `validate_call(function_name: str, args: List[Any], kwargs: Dict[str, Any], language: str = "python") -> Tuple[bool, Optional[str]]`
+Validate a function call against its signature.
+
+```python
+valid, error = registry_api.validate_call("motor.spin", [FORWARD, 50, "RPM"], {})
+```
+
+### Category Enumerations
+
+#### VexCategory
+- `MOTOR`: Motor control functions
+- `DRIVETRAIN`: Drivetrain control functions
+- `SENSOR`: Sensor reading functions
+- `DISPLAY`: Display output functions
+- `TIMING`: Timing control functions
+- `COMPETITION`: Competition control functions
+- `CONTROLLER`: Controller input functions
+- `BRAIN`: Brain functions
+- `UTILITY`: Utility functions
+- `EVENT`: Event handling
+
+#### BehaviorType
+- `CONTROL`: Actively controls/changes state
+- `READ`: Reads/retrieves information
+- `CONFIG`: Configuration/setup
+- `OUTPUT`: Produces output (display, signals)
+- `EVENT`: Event handling/callbacks
+
+## Advanced Usage
+
+### Creating Custom Queries
+
+```python
+# Find all motor functions that read data
+motor_readers = [
+    func for func in registry_api.get_functions_by_category(VexCategory.MOTOR)
+    if func.behavior == BehaviorType.READ
+]
+
+# Find all functions with specific subcategories
+spin_functions = registry_api.get_functions_by_subcategory(SubCategory.MOTOR_SPIN)
+```
+
+### Registry Extension
+
+```python
+from vex_ast.registry.signature import VexFunctionSignature
+from vex_ast.registry.categories import VexCategory, BehaviorType
+
+# Create and register custom function
+custom_signature = VexFunctionSignature(
+    name="custom_function",
+    category=VexCategory.UTILITY,
+    behavior=BehaviorType.CONTROL,
+    # ... other parameters
+)
+
+registry.register_function(custom_signature)
+```
+
+## Migration from Legacy Systems
+
+If upgrading from older versions:
+
+```python
+# Old code (still works)
+functions = registry_api.get_functions_by_simulation(SimulationCategory.MOTOR_CONTROL)
+
+# Modern equivalent
+functions = registry_api.get_functions_by_category_and_behavior(
+    VexCategory.MOTOR, 
+    BehaviorType.CONTROL
+)
+```