# HeartbreakCode

### Turn your emotional baggage into executable code.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Welcome to **HeartbreakCode**, the world's first esoteric programming language inspired by the raw, lyrical honesty of artists like Taylor Swift and Olivia Rodrigo. Here, you don't just write programs—you write anthems of love, loss, and logic.

HeartbreakCode is a fully-featured, interpreted programming language where the syntax is a tribute to pop music's most iconic storytellers. We've swapped out cold, impersonal keywords for the passionate, dramatic phrases that define a generation's anthems.

This project is a significant technical undertaking involving a custom-built lexer, parser, and runtime environment, all created from the ground up. It's an exploration of how we can bridge the gap between creative expression and computational thinking, making code more relatable, fun, and a little more theatrical.

## Key Features

*   **Lyrical & Expressive Syntax:** Write code that reads like a pop song. Assign variables with `The story of us is...`.
*   **Lyrical Conditional Logic:** Implement conditional branching using `Would've, Could've, Should've` for `if`, `else if`, and `else` blocks.
*   **Reusable 'Verses' (Functions):** Define and call functions (Verses) using `Define Verse 'Chorus': ... End Verse` and `Perform 'Chorus'`.
*   **Themed Object-Oriented System: 'Albums' and 'Records'**: Define 'Albums' as classes and create 'Records' as instances.
*   **Structured Error Handling: 'This is me trying...'**: Implement try/catch/finally error handling with lyrical themes.
*   **"The Vault": A File System API**: Interact with the local file system using built-in 'Verses' like `Read The Letter` and `Write In The Diary`.
*   **"Tell Me Why": Interactive Debugging**: Pause program execution at any point with `Tell Me Why` to inspect variable states.
*   **The Record Label: A Lyrical Package Manager**: Discover, distribute, and install third-party HeartbreakCode 'Albums' (libraries).
*   **The Setlist: A Web Server Micro-framework**: Build lightweight, interactive web applications and APIs.

## Installation

You can install HeartbreakCode directly from PyPI:

```bash
pip install heartbreak-code
```

## Usage

Once installed, you can run HeartbreakCode programs.

1.  Create a new file with the `.hbc` (HeartbreakCode) extension, e.g., `my_song.hbc`:

    ```hbc
    # my_song.hbc
    The story of us is my_variable 1989
    Would've my_variable is 1989 Speak Now:
        Speak Now: 'It was a good year!'
    End Verse
    ```

2.  Run your HeartbreakCode program from the command line:

    ```bash
    heartbreak-code run my_song.hbc
    ```

## Contribute

We welcome contributions! Check out our GitHub repository for more details on how to contribute to the project.

## License

HeartbreakCode is licensed under the [MIT License](LICENSE).