# ✨ Lucia Transpiler

<p align="center">
	<img src="assets/images/lucia-logo.png" alt="Lucia Logo" width="140" />
</p>

Lucia is the official open source compiler project maintained by Gabriel González.

**Lucia** is an experimental programming language with Java-inspired syntax and a developer experience focused on simplicity, productivity, and clarity.  
Its current compiler pipeline includes:

- **parsing**
- **semantic analysis**
- **IR lowering**
- **multi-target transpilation (Python / JavaScript)**
- **execution through an installable CLI**

---

## 🚀 Project goal

Lucia aims to combine:

- the **ease of use** of languages like Python
- a **familiar structured syntax** for developers coming from Java or other C-style languages
- a compiler architecture that is clean, extensible, and maintainable
- an **educational-first approach** to help students learn programming in a practical way

This project is primarily intended for **educational purposes** (but not limited to them): helping students learn, practice, and experiment with programming in formal education.
At the same time, its long-term direction is to evolve into a robust platform that could support professional use cases.

---

## 📦 Installation

From the project root folder:

### Linux/macOS

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e .
```

### Windows (PowerShell)

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e .
```

After that, you can use the command:

```bash
lucia
```

If you do not activate the environment, run the CLI directly from the virtual environment:

- Linux/macOS: `.venv/bin/lucia`
- Windows: `.venv\Scripts\lucia.exe`

Additional setup and packaging guides:

- `PYTHON_SETUP.md`
- `LOCAL_BUILD_AND_INSTALL.md`
- `RELEASE_AND_PACKAGING.md`

### Quick setup by purpose

Use these commands after activating your virtual environment.

Runtime only (end users):

```bash
pip install -r requirements.txt
```

Development/test/packaging toolchain:

```bash
pip install -r requirements-dev.txt
```

---

## 🖥️ Main commands

### Compile a Lucia file to Python

```bash
lucia compile examples/00_features.lucia
```

### Run a Lucia file

```bash
lucia run examples/00_features.lucia
```

### Compile to JavaScript

```bash
lucia compile examples/00_features.lucia --target js --save
```

### Run with JavaScript target

```bash
lucia run examples/00_features.lucia --target javascript
```

---

## ⚙️ CLI options

### Show the generated Python code in the console

```bash
lucia run examples/00_features.lucia --show-python
```

When `--target js`/`--target javascript` is selected, this option shows generated JavaScript code.

This also works with `compile`:

```bash
lucia compile examples/00_features.lucia --show-python
```

### Select output target language

Python is the default target. You can explicitly select the target with `--target`:

```bash
lucia compile examples/00_features.lucia --target python
lucia compile examples/00_features.lucia --target js
```

### Default behavior (no output file)

By default, `run` and `compile` do **not** create a `.py` output file.

```bash
lucia run examples/00_features.lucia
```

This also applies to `compile`:

```bash
lucia compile examples/00_features.lucia
```

### Save the generated `.py` output file

```bash
lucia run examples/00_features.lucia --save
```

This also works with `compile`:

```bash
lucia compile examples/00_features.lucia --save
```

### Show generated Python and save the output file

```bash
lucia run examples/00_features.lucia --show-python --save
```

### Save the output file to a custom path

```bash
lucia compile examples/00_features.lucia --out output/my_program.py
```

> You can only use `--out` together with `--save`.

> JavaScript execution requires Node.js available in `PATH` as `node`.

### Show full traceback for debugging

Use `--debug` to print the full Python traceback when an error occurs:

```bash
lucia run examples/imports_robust/error_symbol_not_found.lucia --debug
```

---

## 🧠 Current language features

### Control flow

- `if`
- `else`
- `else if`
- `try`
- `catch`
- `finally`
- `switch`
- `case`
- `default`
- `while`
- `for`
- `do/while`
- `for...in`
- ternary `if (cond) ? a : b`
- `break`
- `continue`
- `return`

### Modules

- `import "./path/file.lucia";`

### Supported types

- `int`
- `float`
- `bool`
- `string`
- `date`
- `datetime`
- `void`
- `any`

### Collections

- `list<T>`
- `dict<K, V>`
- list literals
- dictionary literals
- list and dictionary indexing/access
- typed empty collection adoption by context (`[]` and `{}` on typed targets)
- indexed assignment (`items[i] = value`, `dict[key] = value`)

### Object-oriented programming

- `class`
- `extends` (single inheritance)
- `constructor`
- methods
- properties
- field declarations with optional initializer (`let` and `const`)
- `this`
- implicit method calls inside class methods (e.g. `method()` as shorthand for `this.method()`)

### Declarations

- `let`
- `const`

### Operators

#### Arithmetic
- `+`
- `-`
- `*`
- `/`
- `%`

#### Assignment
- `=`
- `+=`
- `-=`
- `*=`
- `/=`
- `%=`
- `++`
- `--`

#### Comparison
- `==`
- `!=`
- `<`
- `<=`
- `>`
- `>=`

#### Logical
- `&&`
- `||`
- `!`
- `not`

#### Null handling
- `??`

### Built-ins

- `print(...)`
- `len(...)`
- `input(...)`
- `str(...)`
- `int(...)`
- `float(...)`
- `bool(...)`
- `type_of(...)`
- `abs(...)`
- `min(...)`
- `max(...)`
- `pow(...)`
- `round(...)`
- `floor(...)`
- `ceil(...)`
- `sqrt(...)`
- `log(...)`
- `sin(...)`
- `cos(...)`
- `tan(...)`
- `random(min, max)`
- `date(year, month, day)`
- `datetime(year, month, day, hour, minute, second)`
- `today()`
- `now()`
- string methods: `upper()`, `lower()`, `trim()`, `ltrim()`, `rtrim()`, `split(sep)`, `join(items)`, `contains(x)`, `starts_with(x)`, `ends_with(x)`, `replace(old, new)`, `indexOf(x)`, `repeat(n)`, `substring(start[, end])`, `pad_left(width[, fill])`, `pad_right(width[, fill])`, `to_int()`, `to_float()`, `to_bool()`, `count(x)`, `capitalize()`, `title()`, `is_numeric()`, `is_alpha()`, `is_alnum()`
- list methods: `append(...)`, `pop()`, `contains(x)`, `sort()`, `reverse()`, `indexOf(x)`, `slice(start[, end])`, `clear()`, `insert(index, value)`, `remove(value)`, `removeAt(index)`, `extend(list)`, `first()`, `last()`, `is_empty()`, `copy()`
- dict methods: `keys()`, `values()`, `contains_key(key)`, `get(key)`, `get(key, default)`, `clear()`, `remove(key)`, `items()`, `is_empty()`, `size()`, `merge(other)`, `put(key, value)`
- method chaining: `text.trim().split(" ")`, `text.trim().lower().contains("x")`

### String interpolation

- Interpolation inside string literals with `${expr}`.
- Example: `"Hola ${name}, total: ${amount}"`

---

## ✅ Semantic validations

Lucia detects several classes of errors before transpilation, including:

- undeclared variables
- unknown functions
- unknown classes
- incorrect argument count
- incompatible `return` type
- `return` outside a function
- redeclaration in the same scope
- incompatible assignment
- calling something that is not callable
- cyclic imports between `.lucia` files
- missing imported modules
- using symbols that do not exist (local or imported)

Whenever possible, errors include **line and column** information.

Example:

```text
Line 2, column 12: Incompatible return type: expected int but got string
```

---

## 🧱 Project architecture

```text
lucia/
├── frontend/
│   ├── grammar.lark
│   ├── ast_nodes.py
│   └── parser.py
├── semantics/
│   ├── errors.py
│   ├── types.py
│   └── analyzer.py
├── ir/
│   ├── nodes.py
│   └── lowering.py
├── codegen/
│   ├── python_transpiler.py
│   └── javascript_transpiler.py
└── cli.py

main.py
pyproject.toml
README.md
requirements.txt
requirements-dev.txt
examples/
tests/
```

---

## 🛠️ Compilation flow

The current compiler pipeline is:

1. **Read the `.lucia` source file**
2. **Parse** using the defined grammar
3. **Build the AST**
4. **Run semantic analysis**
5. **Lower AST to IR**
6. **Transpile IR to target language (Python or JavaScript)**
7. **Optionally execute the generated program**

---

## 📚 Usage examples

### Run the main example

```bash
lucia run examples/00_features.lucia
```

### Compile the class example

```bash
lucia compile examples/00_features.lucia
```

### Run and save the generated Python file

```bash
lucia run examples/00_features.lucia --save
```

### Show the generated Python code

```bash
lucia run examples/00_features.lucia --show-python
```

### Import code from another Lucia file

```lucia
import "./utils.lucia";

func main(): void {
	let x: int = add(1, 2);
	print(x);
}
```

### Robust multi-file import example

Run a complete example with transitive imports, classes, and utility functions:

```bash
lucia run examples/imports_robust/main.lucia
```

You can also validate semantic symbol checks with an intentional error:

```bash
lucia compile examples/imports_robust/error_symbol_not_found.lucia
```

### Example with multiple syntax errors

Use this file to see how Lucia reports multiple syntax errors with a total count:

```bash
lucia compile examples/syntax_multiple_errors.lucia
```

---

## 🧪 Tests

```bash
pytest
```

---

## 🚀 Release Process

For packaging and publication steps (build artifacts, TestPyPI, PyPI, and post-release checks), see:

- `RELEASE_AND_PACKAGING.md`

---

## 📎 References

- CLI usage scenarios: `CLI_COMMANDS.md`
- Standard library functions: `STDLIB_FUNCTIONS.md`
- Python environment requirements and setup: `PYTHON_SETUP.md`
- Publication and packaging guide: `RELEASE_AND_PACKAGING.md`

---

## Legal and Project Identity

Lucia is the official project name of this compiler.

The source code in this repository is licensed under the Mozilla Public License 2.0 (MPL-2.0). See the `LICENSE` file for details.

The name "Lucia", associated logos, icons, and branding are not licensed under the MPL-2.0. Their use is subject to the terms described in `TRADEMARKS.md`.

Forks and modified versions are permitted under the project license, but they must not be presented as the official Lucia project unless prior written permission has been granted by the project owner.

Official project maintainer:
Gabriel González

---

## 💻 Recommended workflow in PyCharm

1. Open the project folder
2. Configure the project Python interpreter
3. Run:

```bash
pip install -e .
```

4. Test the CLI:

```bash
lucia run examples/00_features.lucia
```

If the terminal inside PyCharm is not using the activated environment, use the environment-specific executable:

- Linux/macOS: `.venv/bin/lucia run examples/00_features.lucia`
- Windows: `.venv\Scripts\lucia.exe run examples/00_features.lucia`

---

## 🌱 Current state of the language

Lucia already has a solid base for continued growth as an experimental programming language and educational tooling project.  
That said, it is still an evolving language.

While education is the current priority, the architecture is being developed with long-term scalability and reliability in mind, so Lucia can gradually move toward professional adoption.

### Natural next areas for growth

- a more advanced type system
- a richer standard library
- better parser error messages
- packaging/binaries
- additional compilation targets beyond Python
- deeper semantic and optimization passes

---

## 🎯 Summary

Lucia already includes:

- its own syntax
- an AST
- a parser
- semantic analysis
- Python and JavaScript transpilation
- an installable CLI
- support for modern language constructs
- a strong enough base to evolve into a more complete language platform for education and eventual professional use

---

Built as a practical foundation for teaching programming, classroom experimentation, and evolving a custom programming language for students.
