✦ Referencia del lenguaje

Altair Language Reference v1.7vB

Documentación en español a partir del código C de altairc y altair_rt. Sin inventar sintaxis.

Versión del lenguaje: 1.7vB Compilador: altairc 1.7 (compiler@version = "1.7") Fuente: código C del compilador y runtime (lexer, parser, sema, codegen, altair_rt)

Documenta todo lo que el binario implementa. No inventa sintaxis. Los stubs y lo previsto para otra versión se marcan.

**m# (matemáticas):** keyword m, parseo y _fn_* math están en el código 1.7. Se documentan aquí; la API estable de lenguaje se anuncia como Altair 1.7.5 Math (próximamente).

1. Pipeline

.at → lexer → parser → sema → codegen → .c → gcc/clang/MinGW → binario

Runtime: runtime/altair_rt.c se compila junto al C generado. Sin VM.

2. Cabecera de programa

Opcional:

altair.doc;
    name = MyApp
    version = 1.0.0
    author = "Autor"
create altair.doc

Campos: name, version, author. El resto del fichero es el cuerpo.

3. Comentarios

/ al inicio de línea (tras espacios), seguido de espacio/tab/fin de línea/letra → comentario hasta EOL. El lexer no confunde / de división cuando el token anterior fue un valor.

4. Declaración de variables

Forma que documentamos (declaración por tipo):

<tipo> <nombre> [= expresión] [storage | orbit | prefer] [cualificadores] [persistencia]

numeric count ram = 0
text name disk = "mundo"
bool ok ram = true
list items ram
token code temp = "ABC"
file f ram = open("a.txt")

Storage, orbit, prefer y cualificadores se reconocen tras el nombre / inicializador según el parser.

Storage

Keyword	Runtime	Efecto
`ram`	`ALT_RAM`	Memoria de proceso
`disk`	`ALT_DISK`	Persistente bajo `~/.altair/<programa>/disk/`
`cache`	`ALT_CACHE`	Persistente con TTL opcional
`temp`	`ALT_TEMP`	Se limpia al liberar
`auto`	`ALT_AUTO`	El runtime elige

Si no se escribe storage, el parser pone STOR_AUTO (no es error).

Cualificadores

const — no reasignable (ALT0007)
expire=<dur> — 30s, 5m, 2h, …
weight=<n> — entero ≥ 0

numeric pi const ram = 3.14159
text sess cache expire=30m = ""

Asignación

count = count + 1
count += 10
count -= 1
count *= 2
count /= 2
count %= 3

release

text buf ram = "x"
release buf

5. Tipos

Tipo	Representación	Notas
`numeric`	`double`
`text`	cadena	`+` concatena si hay texto
`bool`	true/false
`list`	lista dinámica
`object`	instancia de clase
`token`	un solo uso
`char`	alias de `text`
`file`	`FILE*`
`p#Tipo`	puntero crudo

AST también tiene tipos gráficos: imagen, sonido, música, color (raylib).

Indexado y longitud

text s ram = "abc"
log s[0]
log length(s)

Fuera de rango → ALT0013.

tonum

text t ram = "42"
numeric v ram = tonum(t)

0 + t concatena (queda texto), no convierte.

6. Operadores

Aritméticos: + - * / % y - unario. Comparación: == != < > <= >= Lógicos: && || ! Bitwise: & | ^ ~ << >> (solo numeric; helpers altair_band … altair_shr) Compuestos: += -= *= /= %=

Precedencia (mayor a menor): unarios → * / % → + - → shifts → & → ^ → | → relacionales → igualdad → && → ||.

7. Control de flujo

Bloques cerrados con break.

if x > 0;
    log "pos"
break
elif x == 0;
    log "cero"
break
else;
    log "neg"
break

numeric i ram = 0
while i < 10;
    i += 1
break

repeat 3 times;
    log "h"
break

forever;
    wait 1s
break

list xs ram = [1, 2]
foreach x in xs;
    log x
break

exit
wait 2s

8. Funciones

fun greet name text;
    log "Hola " + name
    return name
break

fun add -> numeric numeric a, numeric b;
    return a + b
break

greet("Ana")
numeric r ram = add(1, 2)

Codegen: _fn_<nombre>. Recursión permitida.

9. Clases y objetos

class Point;
    numeric x ram = 0
    numeric y ram = 0
    fun dist;
        return x * x + y * y
    break
break

create object Point as p
p.x = 3
log p.dist()

Campo inexistente al leer → ALT0014.

10. Listas

list items ram = [1, 2, 3]
items.append(4)
items.remove(0)
items.clear()
numeric n ram = items.length
items[0] = 9
list z ram = a + b

11. Entrada de usuario

text n ram = user input "Nombre:"

→ altair_user_input.

12. try / catch

try;
    numeric x ram = 1 / 0
break
catch as e;
    log e.code
    log e.message
    log e.line
break

Pila setjmp en runtime.

13. Snapshots

snapshot create "s1"
snapshot restore "s1"
snapshot delete "s1"

Directorio ~/.altair/<programa>/snap/, CRC32.

14. choose

choose r;
    "a" 50
    "b" 50
break

15. Introspección

system@: time, random, pid, hostname, username, os, memory, diskfree compiler@: version ("1.7"), name, build, architecture program@: name, version, author variable: system@storage(v), weight, type, size, value, orbit

Desconocida → ALT0011.

16. token

token t temp = "x"
text a ram = t
text b ram = t    / ALT0004

17. orbit, prefer, migrate

numeric d orbit 1 "hot" ram, 2 "warm" disk = 0
migrate d as "warm"
migrate d as 2

text s prefer ram, cache, disk = ""

prefer vacío → ALT0006. Estado orbit inválido → ALT0012.

18. Servidor HTTP

listen 8080;
    route "GET" "/";
        respond.text("ok")
    break
break

Sockets propios, un hilo.

Rutas

Métodos: GET POST PUT DELETE PATCH *. Params :id → param("id"). header, body, respond.text, respond.json, respond.status, stop.

Middleware

middleware auth;
    text t ram = header("Authorization")
    if t == "";
        respond.status(401)
        stop
    break
break

Rate limit

rate_limit N per_minute o per_second → 429 al exceder.

Health / metrics / jobs / shutdown

health "/health";
    check "db" -> true
break

metrics "/metrics";

job clean every 5m;
    log "c"
break

schedule beat every 30s;
    log "b"
break

on_shutdown;
    log "bye"
break

Sesiones

session tok expires 30m;

session_get / session_set en runtime.

Config

config;
    env("PORT") default "8080"
    env("SECRET") required
break

required sin env → ALT0015.

db_pool

db_pool db = connect("postgres://…") max 20

Stub: se parsea; no hay cliente SQL en el runtime.

19. Gráficos (raylib)

link graphics raylib

Activa include/link a libs/raylib/<os>/ o sistema.

window
    title = "App"
    width = 800
    height = 600
    fps = 60
create window

loop
    clear skyblue
    draw text
        content = "Hola"
        x = 10
        y = 10
        size = 24
        color = white
    create draw
    draw rect
        x = 100
        y = 100
        width = 50
        height = 50
        color = red
    create draw
    draw circle
        x = 200
        y = 200
        radius = 30
        color = gold
    create draw
break

draw kinds en codegen: text, rect/rectangle, circle, line, line_thick/thick_line, triangle, pixel, image/texture.

Audio/imagen: image, sound, music, play (LoadTexture/Sound/MusicStream, PlaySound). stop/pause parciales.

Input: key → IsKeyDown; cursor (hidden/show/default/crosshair/hand/resize).

Widgets UI: keywords existen; button/timer/animate con codegen limitado; menu/dialog/scene/goto/popup/canvas/column/row/grid ≈ stub.

20. Archivos y procesos

Función	Resultado
`open` / `open_write` / `open_append`	`file`
`read` / `read_line`	`text`
`write` / `close`	`bool`
`create_file` / `delete_file` / `mkdir` / `file_exists`	`bool`
`list_dir`	`list`
`exec`	`numeric` (código salida)
`exec_capture`	`text`

numeric n ram = argc()
text a ram = arg(1)

21. Punteros p#

p es keyword reservada.

p#node n = alloc(64)
p#write(n, 0, 42)
numeric v ram = p#read(n, 0)
log p#bytes(n)
log p#null(n)
p#free(n)

Slots de 8 bytes. p#write y p#free mutan por referencia. También en runtime: ptr_alloc, ptr_free, ptr_is_null.

22. Persistencia nombre.archivo

numeric coins ram = 120 player.coins
text name ram = "A" player.name

Carpeta variables/. Prefijos de tipo N/T/B. Carga al declarar; guarda al asignar y al salir.

23. data

data Save disk;
    numeric coins = 120
    text name = "A"
data create

data Save migrate cache

Ficheros variables/<Nombre>.<var>.<lugar>. migrate hace rename; el path compilado de cada var no cambia en caliente.

24. build_* y has_tool

if has_tool("gcc");
    numeric rc ram = build_native("a.c", "a")
break

build_linux, build_windows, build_macos. Devuelven exit code o -1.

25. Matemáticas m# (1.7.5 Math)

En código 1.7: m#sin, m#cos, m#sqrt, m#pow, m#log, m#abs, m#floor, m#ceil, m#tanh, m#exp, m#min, m#max, m#asin, m#acos, m#atan, m#atan2, m#log10, m#cbrt, m#round.

API de lenguaje estable prevista en 1.7.5 Math.

26. import

Keywords import, module, as, call en lexer. Codegen de galaxy: no soportado en esta build.

27. CLI altairc

altairc <file.at> [-o out] [--emit-c] [--emit-ast] [--no-sema]
altairc guide
altairc --version    → altairc 1.7
altairc --help

28. Códigos de error

Código	Significado
ALT0001	Variable / nulo
ALT0002	Tipos
ALT0003	Parseo
ALT0004	Token consumido
ALT0005	Snapshot
ALT0006	prefer vacío
ALT0007	const
ALT0008	weight
ALT0009	orbit duplicado
ALT0010	/ o % por cero
ALT0011	introspección
ALT0012	orbit no hallado
ALT0013	índice
ALT0014	campo objeto
ALT0015	env required

29. Altair-Core (self-host)

selfhost/altair.at → compilador de un subconjunto a C. No cierra el loop sobre su propio fuente completo todavía.

30. Inventario rápido

Feature	Código 1.7vB
Declaración por tipo	Sí
Storage omitido → AUTO	Sí
Tipos + list/object/token/file/p#	Sí
HTTP stack	Sí
db_pool	Stub
Persistencia + data	Sí (límite migrate)
raylib draw listado	Sí (falta lib vendored a menudo)
widgets avanzados	Stub
build_*	Sí
m# math	En código; estable 1.7.5 Math
import real	No
async / safe block	No

Referencia generada desde el código C de altairc / altair_rt. Versión 1.7vB.