luma-lang 1.0.0
A calm, minimal, human-readable programming language
License: MIT
Requires Python: >=3.7
Keywords: luma, programming-language, compiler, interpreter, calm, minimal

# Luma Programming Language

**Code that breathes. Programming with calm.**

Luma is a programming language designed for clarity, simplicity, and breathing space. It combines natural language syntax with powerful modern features, creating a peaceful coding experience.

---

## 🌸 Philosophy

- **Calm over Clever** — Readable code beats terse code
- **Breathing Space** — Whitespace and clarity are sacred
- **Natural Language** — Code should read like thoughts
- **Minimal Noise** — No unnecessary symbols or punctuation
- **Gentle Learning** — Approachable for beginners, powerful for experts

---

## 🚀 Quick Start

### Installation

**Option 1: Install as Python Package (Recommended)**

```bash
# Install from source
git clone https://github.com/yourusername/luma.git
cd luma
pip install -e .

# Now use luma anywhere!
luma version
```

**Option 2: Install from PyPI (Coming Soon)**

```bash
pip install luma-lang
```

See [INSTALL.md](INSTALL.md) for detailed installation instructions.

### Your First Program

Create `hello.luma`:

```luma
say "Hello, calm world!"

let mood be "peaceful"
say "Current mood: " + mood

breathe
say "Take a moment to appreciate simplicity."
```

Run it:

```bash
luma run hello.luma
```

---

## 📚 Core Concepts

### Variables

```luma
let name be "River"
let age be 25
let calm be true

const MAX_DEPTH be 100

// Assignment
age is 26
```

### Functions

```luma
define greet(name)
  say "Hello, " + name
  return "Greeted " + name
end

let result be greet("Luna")
```

### Control Flow

```luma
if temperature more than 30
  say "It's warm"
else
  say "It's cool"
end

repeat 5 times
  say "Breathe"
end

for item in collection
  say item
end
```

### Async Operations

```luma
define async fetchData(url)
  let response be wait fetch(url)
  let data be wait response.json()
  return data
end

let users be wait fetchData("/api/users")
```

---

## 🎨 LumaStyle (CSS)

Write calm, readable styles:

```lumastyle
.button
  background: soft blue
  text: white
  padding: comfortable
  corners: round
  
  on hover
    background: deep blue
    lift: slight
```

Compiles to standard CSS:

```bash
python src/luma_cli.py style button.lumastyle output.css
```

---

## ⚡ LumaFlow (Frontend Framework)

Build reactive components:

```javascript
import { Component, state } from 'lumaflow';

class Counter extends Component {
  init() {
    this.count = state(0);
  }
  
  increment() {
    this.count.value += 1;
  }
  
  template() {
    return `
      <div class="counter">
        <h2>${this.count}</h2>
        <button onclick="increment">+</button>
      </div>
    `;
  }
}
```

---

## 🌐 LumaServer (Backend Runtime)

Create calm APIs:

```luma
import "server" as srv

let app be srv.create()

app.get "/" (request, response) ->
  response.send {
    message: "Welcome to Luma"
    status: "breathing"
  }
end

app.listen 3000
```

---

## 🛠️ CLI Tools

### Create New Project

```bash
python src/luma_cli.py new my-app
cd my-app
python ../src/luma_cli.py dev
```

### Build Project

```bash
python src/luma_cli.py build
```

### Run File

```bash
python src/luma_cli.py run src/main.luma
```

### Compile to JavaScript

```bash
python src/luma_cli.py compile src/app.luma output.js
```

---

## 📦 Package Management

### Initialize Package

```bash
python src/lumapkg.py init my-package
```

### Add Dependencies

```bash
python src/lumapkg.py add calm-ui
python src/lumapkg.py add test-utils --dev
```

### Install Dependencies

```bash
python src/lumapkg.py install
```

---

## 📖 Examples

Check the `examples/` directory for:

1. **Hello World** — Basic syntax
2. **Counter** — DOM manipulation
3. **Todo List** — Interactive app
4. **API Server** — Backend with LumaServer
5. **Fibonacci** — Algorithms
6. **Async Fetch** — Async operations
7. **Class Timer** — OOP approach
8. **Flow Mode** — Pipeline programming

---

## 🗂️ Project Structure

```
LUMA/
├── src/
│   ├── tokenizer.py       # Lexical analyzer
│   ├── parser.py          # AST parser
│   ├── interpreter.py     # Runtime interpreter
│   ├── compiler.py        # Luma → JavaScript
│   ├── lumastyle.py       # Style compiler
│   ├── lumaflow.py        # Frontend framework
│   ├── lumaserver.py      # Backend runtime
│   ├── luma_cli.py        # CLI tool
│   └── lumapkg.py         # Package manager
├── examples/              # Example programs
├── LANGUAGE_SPEC.md       # Language specification
├── LUMASTYLE_SPEC.md      # Style syntax spec
└── README.md              # This file
```

---

## 🎯 Language Features

### ✅ Implemented

- ✓ Natural language keywords
- ✓ Whitespace-based blocks
- ✓ Variables and constants
- ✓ Functions and closures
- ✓ Control flow (if/else, loops)
- ✓ Classes and objects
- ✓ Error handling (try/catch)
- ✓ Async/await
- ✓ DOM manipulation
- ✓ Event handling
- ✓ Module system
- ✓ Operators (arithmetic, comparison, logical)
- ✓ Collections (lists, maps)
- ✓ Interpreter
- ✓ JavaScript compiler
- ✓ Style language (LumaStyle)
- ✓ Frontend framework (LumaFlow)
- ✓ Backend runtime (LumaServer)
- ✓ CLI tools
- ✓ Package manager

### 🔮 Planned

- Pattern matching
- Pipe operators
- Type hints (optional)
- Macros
- REPL
- Language server (LSP)
- VS Code extension
- npm package
- Online playground
- Standard library
- Test framework
- Documentation generator

---

## 🤝 Contributing

Contributions are welcome! Areas to help:

- Bug fixes and improvements
- Standard library functions
- Example programs
- Documentation
- VS Code extension
- Web playground
- Performance optimization

---

## 📄 License

MIT License - Feel free to use, modify, and share.

---

## 💭 Philosophy in Practice

Luma isn't just about syntax — it's about creating a coding experience that feels natural and calm. Every design decision prioritizes:

1. **Readability** — Can someone understand this a year from now?
2. **Simplicity** — Is this the simplest solution?
3. **Clarity** — Is the intent obvious?
4. **Breathing Space** — Does the code have room to breathe?

---

## 🌟 Why Luma?

```luma
// Other languages:
// function calculateTotal(items) { return items.reduce((sum, item) => sum + item.price, 0); }

// Luma:
define calculateTotal(items)
  let total be 0
  
  for item in items
    total is total + item.price
  end
  
  return total
end
```

The code breathes. The intent is clear. The logic flows naturally.

**Welcome to Luma. Code calmly. 🌸**