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

make

Usage

# 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.