Skip to content

README.md

Latest commit

 

History

History
305 lines (223 loc) · 6.98 KB

README.md

File metadata and controls

305 lines (223 loc) · 6.98 KB

🎓 Educational Compiler in Python

A fully functional educational compiler demonstrating all five phases of compilation with a beautiful, interactive web interface! 🚀

Python Flask License

📖 Overview

This project is a complete compiler implementation built from scratch in Python, designed for educational purposes. It takes you through the entire journey of how compilers work—from raw source code to executable output—with clean, well-documented code and an interactive web GUI.

Perfect for students, educators, and anyone curious about compiler design! 🎯

✨ Features

🔧 5-Phase Compiler Pipeline

Phase Component Description
1️⃣ Lexical Analysis 🔤 Tokenizes source code into meaningful units (keywords, operators, identifiers)
2️⃣ Syntax Analysis 🌳 Builds Abstract Syntax Tree (AST) using recursive descent parsing
3️⃣ Semantic Analysis ✅ Validates variable declarations and usage with symbol table
4️⃣ Code Generation ⚙️ Generates Three Address Code (TAC) intermediate representation
5️⃣ Execution ▶️ Interprets and executes the TAC instructions

🎨 Interactive Web GUI

  • 💅 Modern, gradient-based UI with smooth animations
  • 📊 Real-time visualization of all compilation phases
  • 💻 Live code editor with instant feedback
  • 🔍 Step-by-step execution tracking
  • 📈 Memory state visualization
  • 🎯 Token breakdown display
  • 🌲 AST tree visualization
  • 📝 TAC instruction listing

🛠️ Tech Stack

  • Backend: 🐍 Python 3.7+
  • Web Framework: 🌶️ Flask
  • Frontend: 🎨 HTML5, CSS3, JavaScript
  • Architecture: 🏗️ Visitor Pattern, Recursive Descent Parser
  • Design Patterns: 🎭 Object-Oriented Programming

📦 Project Structure

compiler-in-python/
│
├── 📄 lexer.py              # Lexical analyzer (tokenizer)
├── 📄 ast_parser.py         # Syntax analyzer & AST builder
├── 📄 semantic.py           # Semantic analyzer with symbol table
├── 📄 intermediate.py       # TAC code generator
├── 📄 interpreter.py        # TAC interpreter/executor
├── 📄 compiler_gui.py       # Flask web server
├── 📄 main.py               # CLI interface
├── 📄 test.py               # Test suite
│
├── 📁 templates/
│   └── 📄 index.html        # Modern web interface
│
└── 📄 README.md             # You are here! 👋

🚀 Quick Start

Prerequisites

Make sure you have Python 3.7+ installed on your system.

Installation

1️⃣ Clone the repository

git clone https://github.com/NoumanAfzal54/compiler-in-python.git
cd compiler-in-python

2️⃣ Install dependencies

pip install flask

3️⃣ Run the web interface

python compiler_gui.py

4️⃣ Open your browser

🌐 Navigate to: http://localhost:5000

Alternative: CLI Mode

Run the compiler in command-line mode:

python main.py

Or run the test suite:

python test.py

💡 Usage Example

Sample Program

x = 5;
y = x + 10;
z = y * 2;
print(z);

Compilation Output

Phase 1: Tokens 🔤

Token(ID, 'x', 0)
Token(ASSIGN, '=', 2)
Token(NUMBER, '5', 4)
Token(SEMICOLON, ';', 5)
...

Phase 2: AST 🌳

Program
├── Assignment(x)
│   └── Number(5)
├── Assignment(y)
│   └── BinaryOp(+)
│       ├── Variable(x)
│       └── Number(10)
...

Phase 3: Symbol Table ✅

Symbol Table:
  x: declared
  y: declared
  z: declared

Phase 4: TAC ⚙️

t0 = x + 10
y = t0
t1 = y * 2
z = t1
print z

Phase 5: Execution ▶️

OUTPUT: 30

🎯 Supported Language Features

  • ✅ Integer arithmetic (+, -, *, /)
  • ✅ Variable assignment
  • ✅ Print statements
  • ✅ Parenthesized expressions
  • ✅ Operator precedence
  • ✅ Semantic error detection

📚 Educational Value

This compiler is designed with learning in mind:

  • 📖 Comprehensive Comments: Every function and class is thoroughly documented
  • 🎓 Clear Structure: Each phase is in a separate, well-organized file
  • 💭 Conceptual Explanations: Comments explain WHY, not just WHAT
  • 🔍 Real-World Comparisons: References to GCC, LLVM, Java, Python compilers
  • 🧪 Test Cases: Includes working examples and test programs
  • 🎨 Visual Learning: Web GUI shows each phase in action

Perfect For:

  • 🎓 Computer Science students learning compiler design
  • 👨‍🏫 Educators teaching compiler construction
  • 💻 Developers curious about how compilers work
  • 🚀 Anyone building their own programming language

🏗️ Architecture

Design Patterns Used

  1. Visitor Pattern 🎭

    • Used in semantic analysis and code generation
    • Clean separation of concerns
    • Easy to extend with new node types

  2. Recursive Descent Parsing 📐

    • Simple and intuitive
    • One method per grammar rule
    • Easy to understand and debug

  3. Symbol Table 📋

    • Tracks variable declarations
    • Enables semantic checking
    • Foundation for type systems

🔬 How It Works

The Compilation Pipeline

Source Code
    ↓
📝 Lexer → Tokens
    ↓
🌳 Parser → Abstract Syntax Tree (AST)
    ↓
✅ Semantic Analyzer → Validated AST + Symbol Table
    ↓
⚙️ Code Generator → Three Address Code (TAC)
    ↓
▶️ Interpreter → Execution & Output

🎨 Web Interface Preview

The web GUI features:

  • 🌈 Beautiful gradient backgrounds
  • ✨ Smooth animations and transitions
  • 📱 Responsive design
  • 🎯 Interactive phase navigation
  • 💡 Real-time compilation feedback
  • 🎭 Modern typography (Inter, Helvetica)

🤝 Contributing

Contributions are welcome! Feel free to:

  • 🐛 Report bugs
  • 💡 Suggest new features
  • 🔧 Submit pull requests
  • 📖 Improve documentation

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by classic compiler design principles from:

  • 📚 "Compilers: Principles, Techniques, and Tools" (Dragon Book)
  • 🔧 Real-world compilers: GCC, LLVM, Python, Java
  • 🎓 Computer Science education community

📧 Contact

Nouman Afzal

⭐ Star this repo if you found it helpful!

Made with ❤️ and Python

🎉 Happy Compiling! 🎉