# 🧠 Neuro Langage (NL) — Visão Geral

A **Neuro Langage (NL)** é a linguagem de programação do Neurotron.

Ela nasce com três objetivos claros:

1. **Sintaxe acessível** — parecida com Python, mas em português simples.
2. **Alma de compilador** — desde o início pensada para compilar para um IR estável
   e, mais tarde, para ELF x86_64 real.
3. **Integração neurotrónica** — o compilador é ele mesmo um *agente* do Neurotron
   (o **Programador**), e o código NL pode ser executado num Holodeck (VM interna).

Pipeline conceptual:

```text
código .nl
   ↓
[FRONTEND]    lexer → parser → AST
   ↓
[IR]          geração de IR stack-based (SPEC_IR)
   ↓
[VALIDAÇÃO]   verificação estrutural e semântica básica
   ↓
[HOLODECK]    execução em VM (SPEC_VM / design_vm)
   ↓
[futuro]      backend x86_64 → ELF → NFDOS/QEMU
```

---

## 📂 Estrutura da Linguagem no Repositório

```text
neurotron/lang/
  README_LANG.md        # visão geral mais narrativa
  README.md             # (este ficheiro) hub técnico rápido
  SPEC_SYNTAX.md        # especificação da sintaxe de superfície
  SPEC_IR.md            # especificação do IR stack-based
  SPEC_VM.md            # visão formal da VM/Holodeck
  frontend/             # lexer, parser, AST
  backend/              # IR → otimização → codegen/ELF (futuro)
  holodeck/             # design concreto da VM
  examples/             # programas .nl
  tests/                # ideias de testes da linguagem e VM
```

---

## 📜 Referências principais

### 1. Sintaxe da linguagem

**Ficheiro:** `SPEC_SYNTAX.md`
**Conteúdo:**

* o que é um programa NL v0.1;
* forma de `def` de funções;
* regras de `se … entao … senao …` como expressão;
* operadores disponíveis (`+`, `-`, `<`, etc.);
* escopo do v0.1: apenas inteiros, funções, recursão e expressão final.

👉 Quando quiseres lembrar “como se escreve NL”, este é o documento de referência.

---

### 2. IR — Intermediate Representation

**Ficheiro:** `SPEC_IR.md`
**Conteúdo:**

* formato do módulo de IR (lista de funções);
* instruções primitivas v0.1:

  * `PUSH_CONST`, `LOAD_VAR`, `STORE_VAR`,
  * `ADD`, `SUB`, `LT`,
  * `JUMP`, `JUMP_IF_FALSE`,
  * `CALL`, `RET`;
* convenções de stack:

  * operandos na stack,
  * retornos via topo da stack,
  * labels (`L0`, `L1`, …).

👉 Este ficheiro é a ponte entre o **frontend** e o **Holodeck**.

---

### 3. VM / Holodeck

**Ficheiro:** `SPEC_VM.md`
Complementado por: `holodeck/README_HOLODECK.md` e `holodeck/design_vm.md`.

**Conteúdo principal:**

* modelo de execução:

  * stack de operandos,
  * call stack de frames (variáveis locais, IP),
  * ciclo de execução (bus → decode → exec → next);
* semântica das instruções do IR;
* relação com o TRM e com o agente Programador.

👉 Sempre que tiveres dúvidas sobre “como o IR corre de verdade”, este é o ponto de partida.

---

## 🧩 Frontend (lexer, parser, AST)

📁 `frontend/`

* `README_FRONTEND.md` — visão geral do pipeline de frontend.
* `tokens.md` — definição dos tokens da linguagem.
* `grammar.md` — gramática informal v0.1 (programa, funções, expressões).
* `AST.md` — forma das estruturas de árvore interna (Program, FuncDef, IfExpr, Call, etc.).
* diretórios `lexer/` e `parser/` — espaço reservado para implementação futura.

👉 O frontend converte `.nl` em **AST** e depois em **IR**.

---

## ⚙️ Backend (hoje teórico, amanhã ELF)

📁 `backend/`

* `README_BACKEND.md` — visão do backend NL.
* `validate_ir.md` — regras de validação estrutural do IR.
* `optimize_ir.md` — ideias de otimizações futuras (const folding, etc.).
* `codegen_x86_64.md` — blueprint de geração de código x86_64 a partir do IR.
* `elf_format.md` — layout pensado para gerar ELF bootável.
* `runtime.md` — ideias para runtime mínimo (syscalls, convenção de chamada, etc.)

👉 No v0.1, o backend efetivo é o Holodeck; o backend nativo fica como futuro upgrade.

---

## 🎮 Holodeck

📁 `holodeck/`

* `README_HOLODECK.md` — o que é o Holodeck e como se integra no Neurotron.
* `design_vm.md` — definição concreta da VM (estado, ciclo, manipulação de stack).

👉 O Holodeck é a “CPU virtual” que executa IR antes de gerarmos ELF real.

---

## 🧪 Exemplos e testes

📁 `examples/`

* `fib.nl` — primeiro programa NL (definição de Fibonacci + chamada final).
* `README_EXAMPLES.md` — notas sobre exemplos.

📁 `tests/`

* `README_TESTS.md` — ideias para testes de linguagem, IR e VM.

---

## 🤝 Ligação com o agente Programador

O **agente Programador** vive em:

```text
neurotron/trm/agentes/programador/README.md
```

Ele usa diretamente:

* `SPEC_SYNTAX.md` para interpretar código fonte,
* `SPEC_IR.md` para gerar IR,
* `SPEC_VM.md` + `holodeck/design_vm.md` para preparar execução no Holodeck.

Na prática:

```text
Programador:
  source .nl
    → frontend (tokens + AST)
    → IR
    → validação
    → Holodeck VM
    → resultado + métricas
```

---

## 🗺️ Próximos passos (implementação)

Ordem sugerida de implementação:

1. **Lexer** simples baseado em `tokens.md`.
2. **Parser** recursivo ou Pratt para expressões, baseado em `grammar.md`.
3. Gerador de **IR** para o subconjunto atual (inteiros, `def`, `se/entao/senao`, chamadas).
4. Pequena **VM** em Python para o Holodeck, conforme `SPEC_VM.md`.
5. Integração com o agente Programador e com o NEURO REPL.

Enquanto isso, este diretório `lang/` continua a ser a *documentação fonte* da linguagem.

