45 lines
2 KiB
Markdown
45 lines
2 KiB
Markdown
# Python-to-Ruby Transpiler (py2rb)
|
|
|
|
A source-to-source transpiler that converts Python syntax into Ruby code. Built using **Flex** for lexical analysis and **Bison** for LALR(1) parsing, this project implements a full compilation pipeline from tokenization to code generation.
|
|
|
|
## Technical Architecture
|
|
|
|
The transpiler is architected into three distinct phases:
|
|
|
|
1. **Lexical Analysis (`Flex`):** Handles Python-specific challenges like indentation-based scoping using a custom `indent_stack`. It supports complex literals including f-strings, triple-quoted strings, and various numeric bases (hex, binary).
|
|
2. **LALR Parsing (`Bison`):** Implements a formal grammar for a significant subset of Python, including class definitions, function nesting, and control flow. It constructs a strongly-typed Abstract Syntax Tree (AST) using C++17 smart pointers.
|
|
3. **Code Generation:** A recursive AST visitor (via the `RubyGenerator`) that maps Python semantics to Ruby equivalents. This includes specialized mapping for Python dunder methods (e.g., `__init__` → `initialize`, `__str__` → `to_s`) and boolean literals.
|
|
|
|
|
|
|
|
## Key Features
|
|
|
|
* **Semantic Mapping:** Automatically converts Python-specific constructs (like `self`) into Ruby syntax.
|
|
* **Indentation-to-Block Conversion:** Correctly translates Python's significant whitespace into Ruby's `end`-delimited blocks.
|
|
* **Comprehensive Test Suite:** Includes test cases covering lexing, parsing, and end-to-end Ruby generation.
|
|
* **AST Auditing:** Built-in support for AST and token stream dumping for debugging and verification.
|
|
|
|
## Build and Usage
|
|
|
|
### Prerequisites
|
|
* `g++`
|
|
* `flex`
|
|
* `bison`
|
|
|
|
### Build
|
|
```bash
|
|
make
|
|
```
|
|
|
|
### Usage
|
|
```bash
|
|
# Transpile a file and output to stdout
|
|
./build/py2rb --file input.py
|
|
|
|
# Run the automated test suite
|
|
make test
|
|
```
|
|
|
|
Implementation Details & Shortcomings
|
|
|
|
For a list of current language subset limitations (e.g., tuple-to-list conversion, specific string processing logic), see shortcomings.md.
|