added readme, and fixed linnux compilation

README.md

@@ -0,0 +1,45 @@
+# 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.