Metadata-Version: 2.4
Name: egglang
Version: 0.2.0
Summary: A command line tool written in Python
Author: Adib
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Dynamic: license-file

<div align="center">

```
███████╗ ██████╗  ██████╗ 
██╔════╝██╔════╝ ██╔════╝ 
█████╗  ██║  ███╗██║  ███╗
██╔══╝  ██║   ██║██║   ██║
███████╗╚██████╔╝╚██████╔╝
╚══════╝ ╚═════╝  ╚═════╝ 
```

### A programming language I am building from scratch — to understand how programming languages actually work.


<p>
  <b><a href="#-installation">Install</a></b> &nbsp;·&nbsp;
  <b><a href="#-quick-start">Quick Start</a></b> &nbsp;·&nbsp;
  <b><a href="#-architecture-overview">Architecture</a></b> &nbsp;·&nbsp;
  <b><a href="#-testing">Testing</a></b> &nbsp;·&nbsp;
  <b><a href="#-documentation">Docs</a></b> &nbsp;·&nbsp;
  <b><a href="#-contributing">Contributing</a></b>
</p>

</div>

<br>

## 📖 About

 **EggLang** is a small programming language I am building from scratch. I didn't use any existing interpreter, framework, or language toolkit. Every part of it — from reading the code to running it — I built myself.

I made this project so I could really learn how programming languages work, not just use them.

<table>
<tr>
<td width="50%" valign="top">

**What I learned to build**
- How to break code into tokens (lexing)
- How to turn tokens into structure (parsing)
- How to build an AST (a tree that stores the code's logic)
- How to run that tree (runtime)
- How to manage variables and scope (environments)

</td>
<td width="50%" valign="top">

**Why I made this**
> I'm not trying to make EggLang production-ready. I just wanted to build a real language, step by step, and understand every part of it myself.

</td>
</tr>
</table>

<br>

## 🚀 Installation

I published EggLang on **PyPI**, so you can install it with:

```bash
pip install egglang
```

<br>

## ⚡ Quick Start

Once it's installed, you can run any EggLang file like this:

```bash
egg run file.egg
```

No setup, no config file. Just point it at a `.egg` file and it runs.

<br>

## 💡 Why I Made This

I built EggLang to learn, by actually doing it:

| | |
|---|---|
| 🧩 | How a programming language is **designed** |
| 🔄 | How source code turns into something the computer can **run** |
| ⚙️ | How an interpreter **works on the inside** |
| 🗂️ | How variables and memory are **stored and managed** |
| 🔁 | How functions, loops, and expressions actually **run** |

This project is my journey from just *using* programming languages to *understanding and building* one myself.

<br>

## 🏗 How EggLang Works (Architecture)

I built EggLang as a simple pipeline. Each step passes its work to the next one:

```
┌───────────────┐
│  Source Code  │
└───────┬───────┘
        ▼
┌───────────────┐
│     Lexer     │   breaks code into tokens
└───────┬───────┘
        ▼
┌───────────────┐
│    Parser     │   turns tokens into structure
└───────┬───────┘
        ▼
┌───────────────┐
│      AST      │   a tree that stores the code's logic
└───────┬───────┘
        ▼
┌───────────────┐
│  Interpreter  │   walks the tree and runs it
└───────┬───────┘
        ▼
┌───────────────┐
│    Runtime    │   keeps track of values while running
└───────────────┘
```

| Stage | What it does |
|---|---|
| **Lexer** | Turns raw code into tokens |
| **Parser** | Turns tokens into a structured form |
| **AST** | Stores the program's logic as a tree |
| **Interpreter** | Runs the AST, one node at a time |
| **Runtime** | Keeps track of values while the program runs |

<br>

## 🧠 How I Built the Interpreter

I have a class called `Interpreter`, and inside it, every type of AST node has its own method that knows how to run that specific piece of code. So a loop node knows how to run loops, a function-call node knows how to run function calls, and so on.

<table>
<tr><td>

- ✅ Running expressions
- ✅ Running statements
- ✅ Calling functions
- ✅ Handling return values

</td><td>

- ✅ Running loops
- ✅ Managing variables
- ✅ Handling runtime errors
- ✅ Looking up variables in nested scopes

</td></tr>
</table>

<br>

## 🔗 How Scope Works

I built EggLang's scope system using **environments** that are chained together. Each environment stores:

- Variables
- Functions
- A link to its **parent environment**

Because of this chain, I get global variables, function-local variables, nested scopes, and the ability to look up a variable through parent environments.

```
Global Environment
        │
        ▼
Function Environment
        │
        ▼
Nested Block Environment
```

> When the code asks for a variable, EggLang looks in the **current environment first**. If it's not there, it moves up to the parent environment, and keeps going until it finds it.

<br>

## 🔧 How Functions Work

When a function is called, I create a brand new environment just for that call. The arguments get stored as variables inside this new environment. Then I run every line inside the function using that environment. Once the function returns a value, I throw away that environment, so it's ready to be used again next time.

<br>

## ⚠️ How I Handle Errors

I built a custom error system so debugging is easier. Whenever something goes wrong, I show:

- 🏷️ What kind of error it is
- 📝 A clear error message
- 📍 Where it happened, including the exact line

<br>

## 🧪 Testing

I have a `Tests/` folder with a bunch of tests I wrote to check that everything actually works. They cover:

- Variables
- Functions
- `for` loops
- `while` loops

The hardest test I made combines everything together — **20 programs** that use multiple features at once, and all of them run correctly.

> Some of my tests are extreme on purpose. I wanted to push the interpreter as hard as I could, to make sure the lexer, parser, AST, and interpreter can all handle it.

<br>

## 📚 Documentation

I wrote a few docs if you want to go deeper:

| Document | What's inside |
|---|---|
| 📘 [Syntax Guide](https://github.com/codeaddicthq/egg/blob/main/SYNTAX.md) | How to write EggLang code |
| 🧬 [Language Features](https://github.com/codeaddicthq/egg/blob/main/FEATURES.md) | Everything EggLang can do |
| 🏛 [Architecture Details](https://github.com/codeaddicthq/egg/blob/main/MODEL.md) | How I designed it internally |
| 🥚 [Code Examples](https://github.com/codeaddicthq/egg/blob/main/EXAMPLES.md) | Real EggLang programs you can read and run |

<br>

## 📱 I Built This on My Phone

I made EggLang using only an **Android phone**. No laptop, no desktop, no external keyboard.

<table>
<tr>
<td width="50%" valign="top">

**My setup**
- 📝 [Acode](https://acode.app) — my code editor
- 🐧 Alpine Linux — my terminal environment
- ⌨️ The on-screen phone keyboard
- 📴 No computer involved, at all

</td>
<td width="50%" valign="top">

**The numbers**
- Around **1,500 lines** of code
- Every line — lexer, parser, AST, interpreter, runtime — typed by hand on my phone
- Every bug, I found and fixed on a small screen

</td>
</tr>
</table>

> If you've ever complained about coding on a small laptop screen, try building a language on a phone. I think EggLang proves that the only thing you really need is patience.

<br>

## 🌱 What I Learned

Building EggLang taught me a lot about:

`compilers and interpreters` · `recursion` · `data structures` · `tree traversal` · `runtime design` · `software architecture`

Before EggLang, I tried building another language, but that one was more of an experiment: **[egg v1](https://github.com/codeaddicthq/egg/tree/v1)**.

After I learned more, I rebuilt EggLang from scratch with a proper design — my own lexer, parser, AST, interpreter, and runtime.

The hardest part for me was building the **Parser and the AST**. Designing a tree structure that correctly represents code was something I had never done before, and I had to learn a lot of new concepts to get it right.

<br>

## 🗺 What's Next

Things I want to add in the future:

- [ ] A standard library
- [ ] A module system
- [ ] Better debugging tools
- [ ] More advanced data structures
- [ ] Performance improvements

<br>

## 🤝 Contributing

Right now, EggLang needs a **CLI editor**, and I'd love help building it.

I've set aside a `Shell/` folder just for this, so you can work there without touching the core interpreter.

Feel free to explore EggLang, try it out, and send improvements my way. 🚀

<br>

---

<div align="center">

### ✍️ About Me

**I'm Adib**, and I built EggLang to really understand how programming languages work — not just use them.

<br>

** Thanks for checking out EggLang**

</div>
