# **SPEC_SYNTAX.md — Neuro Language v0.1 (Superfície)**

*definição mínima necessária para gerar IR e executar no Holodeck*

---

# 📘 **1. Objetivo**

Este documento define a **sintaxe da linguagem Neuro (NL)** — a camada de superfície que o programador escreve e que o compilador transforma em IR.

A versão v0.1 suporta:

* inteiros,
* definições de função,
* chamadas de função,
* expressões aritméticas,
* expressão condicional `se ... entao ... senao ...`,
* indentação significativa,
* expressão final como corpo do programa.

A linguagem é inspirada em Python, mas **minimalista**, **sem acentos**, e com estilo lusófono.

---

# 📗 **2. Estrutura de um programa**

Um programa NL v0.1 tem a forma:

```
<funcoes>
<expressao_final>
```

Onde:

* `<funcoes>` é zero ou mais declarações `def`.
* `<expressao_final>` é obrigatória e será usada como corpo de `__main__/0`.

Exemplo:

```nl
def fib(x)
  se x < 3 entao
    1
  senao
    fib(x-1) + fib(x-2)

fib(40)
```

---

# 📙 **3. Regras gerais de sintaxe**

### **3.1. Identificadores**

Um identificador:

* começa com letra ou `_`,
* segue com letras, números ou `_`,
* é case-sensitive.

Exemplos válidos:

```
fib
x
valor_total
_foo
```

---

### **3.2. Comentários**

Comentários começam com `#` até ao fim da linha:

```
# isto e um comentario
```

---

### **3.3. Espaços e indentação**

A linguagem usa **indentação significativa**:

* **Tab** obrigatório para indicar blocos.
* Cada nível de indentação = 1 tab (`\t`).
* Espaços não contam como indentação.

Isto evita ambiguidade e simplifica o parser.

Exemplo:

```nl
def test(x)
\tse x < 0 entao
\t\t1
\tsenao
\t\t2
```

*(No repositório podes mostrar tabs como `→` para debug.)*

---

# 📕 **4. Definições de função**

A forma geral é:

```
def <nome>(<parametros>)
    <expressao>
```

Onde:

* `<nome>` é um identificador.
* `<parametros>` é uma lista separada por vírgulas.
* O corpo é exatamente **uma expressão**.
  (Blocos múltiplos serão adicionados em v0.2.)

Exemplos:

```
def id(x)
  x

def soma(a, b)
  a + b
```

No IR, cada função vira `func nome/arity:`.

---

# 📘 **5. Expressões**

A linguagem NL v0.1 tem **apenas estes tipos de expressão**:

1. inteiros
2. variáveis
3. chamadas de função
4. operações aritméticas
5. comparação `<`
6. expressão condicional `se/entao/senao`
7. parênteses para controlo de precedência

Vamos formalizar cada uma.

---

## **5.1. Inteiros**

Formato:

```
<number>
```

Apenas inteiros não negativos por v0.1.

Exemplos:

```
0
1
42
9999
```

---

## **5.2. Variáveis**

Uma variável é um identificador:

```
x
total
fib
```

---

## **5.3. Chamadas de função**

Formato:

```
<nome>(<expr>, <expr>, ...)
```

Exemplos:

```
fib(40)
soma(a, b+1)
foo()
```

Chamadas são sempre **expressões**.

---

## **5.4. Operações aritméticas**

Suportamos:

```
<expr> + <expr>
<expr> - <expr>
```

Precedência:

1. parênteses
2. função
3. multiplicadores futuros
4. `+` e `-` (esquerda para direita)

Para v0.1 não há `*`, `/` ainda.

---

## **5.5. Comparação `<`**

Expressão booleana que retorna:

* `1` (verdadeiro)
* `0` (falso)

Formato:

```
<expr> < <expr>
```

Exemplos:

```
x < 3
a+b < c
fib(2) < fib(3)
```

---

## **5.6. Expressão condicional**

A forma mais importante da linguagem:

```
se <cond> entao
    <expr>
senao
    <expr>
```

Regras:

* `se` e `entao` estão na mesma linha.
* O bloco do `entao` é uma única expressão indentada.
* O bloco do `senao` é uma única expressão indentada.
* É um *valor*, não um statement — devolve expressão.

Exemplo:

```nl
se x < 3 entao
    1
senao
    fib(x-1) + fib(x-2)
```

---

# 📗 **6. Precedência e associatividade**

De maior prioridade para menor:

1. parênteses
2. chamadas de função
3. `<`
4. `+`, `-` (esquerda para direita)
5. `se/entao/senao` (mais externo)

---

# 📙 **7. Ambiguidades proibidas**

Para simplificar o parser da v0.1:

* Não há linhas vazias entre blocos.
* Não há blocos múltiplos dentro de funções.
* Tudo é sempre **uma expressão**.
* `senao` deve aparecer imediatamente após o bloco `entao`.
* Não existem operadores unários (`-x` inválido).

---

# 📕 **8. Exemplo formal — fib**

Programa completo:

```nl
# devolve o enesimo numero de fibonacci
def fib(x)
    se x < 3 entao
        1
    senao
        fib(x-1) + fib(x-2)

fib(40)
```

---

# 📘 **9. Correspondência para IR**

A expressão `fib(40)` vira:

```
PUSH_CONST 40
CALL fib 1
RET
```

A definição completa de `fib(x)` está no SPEC_IR.md.

---

# 📕 **10. Limitações da v0.1**

Falta de propósito (serão adicionados em versões futuras):

* `*`, `/`, `%`
* operadores lógicos
* variáveis locais (só argumentos nesta versão)
* múltiplas expressões num bloco
* `retornar`
* loops (`para`, `enquanto`)
* strings, booleanos reais, arrays, records
* escopo lexical completo
* módulos

A missão da v0.1 é **educacional e minimal**, perfeita para gerar o Holodeck IR e visualizar a execução.

---

# 🧠 **11. Filosofia**

A linguagem Neuro foi desenhada para ser:

* **simples de ler**,
* **minimamente poderosa**,
* **100% determinística**,
* **um espelho simbólico** para o TRM,
* **um caminho natural** para codegen → ELF → QEMU.

Ela é o primeiro idioma do teu mundo digital.

---

# 🌑 **Fim do SPEC_SYNTAX.md**
