Introducción

Alvz es un lenguaje de programación de alto rendimiento basado en Python, diseñado para ser intuitivo y potente, con palabras clave en español. Permite crear aplicaciones conectadas a la nube y generar contenido web de forma nativa.

Plan de Aprendizaje Paso a Paso 🚀

Domina Alvz desde cero con este camino guiado, sin prisa pero sin pausa. Cada lección explica qué harás, los conceptos clave que aprenderás y un reto para practicar. ¡Tú pones el ritmo!

Presiona "Ejecutar" para ver el resultado aquí.

Instalación

Alvz funciona en Windows, Linux y macOS. Hay varias formas de instalarlo.

Windows — Instalador

Descarga el ZIP con el instalador y la extensión de VS Code.

• Windows 10 u 11
• No requiere Python instalado (el .exe es standalone)

Linux / macOS / Windows — vía PyPI

Alvz está disponible en PyPI (Python Package Index), el repositorio oficial de paquetes Python. Instálalo con un solo comando:

pip install alvz-lenguaje

# Con soporte WebAssembly (wasmtime)
pip install alvz-lenguaje[wasm]

# Con servidor web (FastAPI)
pip install alvz-lenguaje[web]

• Requiere Python 3.10+
• Disponible en pypi.org/project/alvz-lenguaje
• Con alvz build puedes generar ejecutables standalone con PyInstaller

Verificar instalación

$ alvz --version
Alvz v0.18.0

Extensión para VS Code

Mejora tu experiencia de desarrollo con resaltado semántico, autocompletado real y más de 60 snippets inteligentes para Alvz.

Instalación

Disponible directamente en el Marketplace de VS Code. Dos formas de instalar:

Opción 1 — Desde el Marketplace:

1. Abre VS Code
2. Ve a la sección de Extensiones (Ctrl+Shift+X)
3. Busca "Alvz en Español"
4. Haz clic en Instalar

Opción 2 — Desde el navegador:

1. Visita marketplace.visualstudio.com
2. Haz clic en Install

Nota: También puedes descargar el archivo .vsix desde el instalador (.zip) e instalarlo manualmente si no tienes acceso al Marketplace.

Características

• Resaltado Semántico: El editor entiende el rol de cada token — variables declaradas con variable, funciones definidas con funcion, clases, builtins de la StdLib y más — y los colorea con precisión.
• Autocompletado Contextual: Sugiere keywords del lenguaje, snippets con Tab, funciones de la StdLib con firmas, constantes (verdadero, falso, nulo) y módulos stdlib al escribir importar "...".
• 60+ Snippets Inteligentes: Escribe funcion, si, para, clase, async, servidor, supabase, crud, menu, api y presiona Tab para autocompletar la estructura completa.
• Soporte FastAPI & Supabase: Resaltado especial para funciones de servidor y base de datos.

Snippets incluidos

Glosario de Palabras Reservadas

En Alvz, el código se lee casi como una oración en español. Aquí tienes las palabras que el lenguaje usa para entenderte:

Hola Mundo

Compara cómo se ve el mismo código en Alvz y en Python:

variable mensaje = "¡Hola desde Alvz!"
imprimir(mensaje)

mensaje = "¡Hola desde Alvz!"
print(mensaje)

Ejecútalo desde la terminal:

$ alvz inicio.alvz
¡Hola desde Alvz!

Variables y Tipos

Alvz es dinámicamente tipado con soporte opcional de anotaciones de tipo estáticas.

Tipos de datos

Anotaciones de tipo (opcionales)

Puedes declarar el tipo esperado de una variable usando : después del nombre.

variable x: numero = 5
variable s: texto = "hola"
variable b: booleano = verdadero
variable n: nulo = nulo

Tipado Estático

Alvz incluye un verificador de tipos estático opcional que analiza tu código en tiempo de compilación. Se activa con --check-types o -T.

Anotaciones en variables

Puedes declarar el tipo de una variable usando : después del nombre.

variable x: numero = 5
variable nombre: texto = "Alvz"
variable activo: booleano = verdadero

Anotaciones en funciones

Puedes anotar tipos en parámetros y valor de retorno. El verificador valida que los argumentos coincidan.

funcion suma(a: numero, b: numero): numero {
    retornar a + b
}

# Error en compilacion:
variable x: texto = suma(1, 2)  # esperaba texto, encontro numero

Tipos disponibles

• numero — enteros y decimales
• texto — cadenas
• booleano — verdadero/falso
• nulo — valor nulo
• lista — arreglos dinámicos
• diccionario — mapas clave-valor
• funcion — funciones como valor
• cualquiera — tipo dinámico (predeterminado)

Funciones

Las funciones te permiten reutilizar bloques de código. Compara la sintaxis:

funcion sumar(a: numero, b: numero): numero {
    retornar a + b
}

variable resultado = sumar(10, 5)
imprimir(resultado)

def sumar(a, b):
    return a + b

resultado = sumar(10, 5)
print(resultado)

Funciones Anónimas (Lambdas)

Las funciones anónimas (también llamadas lambdas) permiten definir funciones sin nombre como expresiones. Son ideales para callbacks, operaciones sobre listas y composición funcional.

Sintaxis

Una función anónima se define con la palabra clave funcion seguida de parámetros y cuerpo entre llaves, todo como una expresión:

funcion(a, b) {
    retornar a + b
}

Asignación a variable

variable suma = funcion(a, b) {
    retornar a + b
}
imprimir(suma(3, 4))  # 7

Uso como argumento (callbacks)

funcion aplicar_operacion(x, y, operacion) {
    retornar operacion(x, y)
}

variable resultado = aplicar_operacion(10, 5, funcion(a, b) {
    retornar a * b
})
imprimir(resultado)  # 50

Con listas: mapear y filtrar

Las lambdas son especialmente útiles al trabajar con listas:

variable numeros = [1, 2, 3, 4, 5]

# Mapear: doblar cada valor
variable dobles = numeros.mapear(funcion(n) {
    retornar n * 2
})
imprimir(dobles)  # [2, 4, 6, 8, 10]

# Filtrar: solo pares
variable pares = numeros.filtrar(funcion(n) {
    retornar n % 2 == 0
})
imprimir(pares)  # [2, 4]

Clases y Objetos (POO)

Alvz soporta programación orientada a objetos con sintaxis limpia en español.

Definición básica

self se agrega automáticamente como primer parámetro. No necesitas declararlo.

clase Persona {
    variable nombre = ""
    funcion saludar() {
        imprimir("Hola, soy " + self.nombre)
    }
}

variable p = nuevo Persona()
p.nombre = "Juan"
p.saludar()

class Persona:
    def __init__(self):
        self.nombre = ""
    def saludar(self):
        print("Hola, soy " + self.nombre)

p = Persona()
p.nombre = "Juan"
p.saludar()

Constructor con argumentos

Define inicializar() para recibir argumentos al crear la instancia.

clase Punto {
    variable x = 0
    variable y = 0
    funcion inicializar(x, y) {
        self.x = x
        self.y = y
    }
}

variable p = nuevo Punto(10, 20)
imprimir(p.x)

Propiedades con expresiones

Las propiedades pueden inicializarse con cualquier expresión, no solo con valores simples.

clase Caja {
    variable items = [1, 2, 3]
    variable total = 5 + 10
}

variable c = nuevo Caja()
imprimir(c.items)
imprimir(c.total)

Herencia

Usa clase Hijo de Padre para heredar propiedades y métodos.

clase Animal {
    variable nombre = ""
    funcion inicializar(nombre) {
        self.nombre = nombre
    }
    funcion saludar() {
        retornar "Soy " + self.nombre
    }
}
clase Perro de Animal {
    funcion ladrar() {
        retornar "Guau!"
    }
}

variable p = nuevo Perro("Rex")
imprimir(p.saludar())
imprimir(p.ladrar())

super e instanceof

Alvz soporta dos características clave de POO avanzado: llamadas a métodos de la clase padre y verificación de tipo en tiempo de ejecución.

super.metodo()

Llama explícitamente a un método de la clase padre desde una clase hija.

clase Animal {
    funcion saludar() {
        retornar "Hola, soy un animal"
    }
}
clase Perro de Animal {
    funcion saludar() {
        retornar super.saludar() + " (perro)"
    }
}

variable p = nuevo Perro()
imprimir(p.saludar()) # "Hola, soy un animal (perro)"

obj instancia Clase

Verifica si un objeto es una instancia de una clase (o de sus clases padre).

clase Animal {}
clase Perro de Animal {}

variable p = nuevo Perro()
imprimir(p instancia Perro)    # verdadero
imprimir(p instancia Animal)   # verdadero (hereda)
imprimir(p instancia Texto)     # falso
imprimir(42 instancia Perro)    # falso (no es objeto)

Getters y Setters

Define propiedades calculadas con acceso controlado usando la sintaxis propiedad.

clase Persona {
    variable _nombre = ""
    propiedad nombre {
        obtener {
            retornar mayusculas(self._nombre)
        }
        establecer(valor) {
            self._nombre = valor
        }
    }
    funcion inicializar(nombre) {
        self._nombre = nombre
    }
}

variable p = nuevo Persona("juan")
imprimir(p.nombre)  # "JUAN" (getter aplica mayusculas)
p.nombre = "maria"
imprimir(p.nombre)  # "MARIA"

Los getters y setters soportan herencia. Una clase hija puede heredar propiedades con getter/setter de la clase padre.

Métodos Estáticos

Define métodos que pertenecen a la clase, no a la instancia, usando funcion estatico.

clase Matematicas {
    funcion estatico cuadrado(n) {
        retornar n * n
    }
    funcion estatico pi() {
        retornar 3.1416
    }
}

imprimir(Matematicas.cuadrado(5))  # 25
imprimir(Matematicas.pi())           # 3.1416

Los métodos estáticos se llaman directamente desde la clase, sin necesidad de crear una instancia con nuevo.

Control de Flujo

Alvz soporta las estructuras de control clásicas para tomar decisiones y repetir tareas.

Condicionales (si / sino)

si edad >= 18 {
    imprimir("Eres mayor de edad")
} sino {
    imprimir("Eres menor de edad")
}

Bucles (mientras / para)

Alvz ofrece bucles potentes, incluyendo iteración sobre rangos y listas.

# Bucle mientras
variable i = 1
mientras i <= 5 {
    imprimir(i)
    i = i + 1
}

# Bucle para (rango)
para j de 1 a 5 {
    imprimir(j)
}

# Bucle para cada (listas)
variable colores = ["rojo", "verde", "azul"]
para cada c en colores {
    imprimir(c)
}

global keyword

La palabra clave global permite declarar y modificar variables globales dentro del ámbito de una función.

Declaración

Usa global para indicar que una variable pertenece al ámbito global:

variable contador = 0

funcion incrementar() {
    global contador
    contador = contador + 1
}

incrementar()
imprimir(contador)  # 1

Lectura y escritura

Sin global, una función crea una variable local al asignar. Con global, lee y escribe la variable del ámbito global:

variable mensaje = "Hola"

funcion cambiar_mensaje() {
    global mensaje
    mensaje = "Mundo"
}

cambiar_mensaje()
imprimir(mensaje)  # "Mundo"

Asignación compuesta

variable total = 100

funcion agregar(valor) {
    global total
    total += valor
}

agregar(50)
imprimir(total)  # 150

Múltiples variables globales

Puedes declarar varias variables globales en una sola línea:

variable x = 1
variable y = 2
variable z = 3

funcion reiniciar() {
    global x, y, z
    x = 0
    y = 0
    z = 0
}

reiniciar()
imprimir(x, y, z)  # 0 0 0

Desarrollo Web con FastAPI Pro

Alvz soporta ahora la potencia completa de FastAPI, permitiendo parámetros de ruta, diferentes métodos HTTP y recepción de datos JSON.

API REST Completa

# Función con parámetro de ruta {id}
funcion obtener_usuario(id) {
    retornar {"id": id, "nombre": "Usuario " + id}
}

# Función para POST con datos del Body
funcion crear(nombre, precio) {
    retornar {"estado": "ok", "nombre": nombre}
}

variable rutas = {
    "/usuarios/{id}": "obtener_usuario",
    "/items": {"metodo": "POST", "funcion": "crear"}
}

iniciar_servidor(8000, rutas)

from fastapi import FastAPI
app = FastAPI()

@app.get("/usuarios/{id}")
async def obtener_usuario(id: str):
    return {"id": id, "nombre": f"Usuario {id}"}

@app.post("/items")
async def crear(item: dict):
    return {"estado": "ok", "nombre": item.get("nombre")}

import uvicorn
uvicorn.run(app, port=8000)

Python Power: Características Avanzadas

Alvz hereda las características más potentes de Python. Mira las diferencias:

Herencia

clase Perro de Animal {
    funcion inicializar() {
        self.tipo = "Canino"
    }
}

class Perro(Animal):
    def __init__(self):
        self.tipo = "Canino"

Slicing

imprimir(lista[1:4])
imprimir(texto[0:4])

print(lista[1:4])
print(texto[0:4])

Integración con Supabase

Conecta tu app a la nube en segundos. Alvz permite interactuar con bases de datos PostgreSQL a través de la API de Supabase sin configuraciones complejas.

variable url = "https://tu-proyecto.supabase.co"
variable key = "tu-anon-key"

# Insertar datos
variable datos = {"usuario": "alvz_user", "puntos": 100}
variable status = supabase_insertar(url, key, "ranking", datos)

# Consultar datos
variable resultado = supabase_consultar(url, key, "ranking")
imprimir(resultado)

Módulos (importar)

Divide tu código en archivos para una mejor organización. También puedes importar módulos de la librería estándar.

Importar un archivo local

importar "calculos.alvz"

variable r = calcular_total(100, 15)
imprimir(r)

Importar de la librería estándar

importar "matematicas"
imprimir(factorial(5))  # 120
imprimir(maximo(10, 20)) # 20

Importar desde paquetes instalados

Los paquetes instalados con alvz install se importan igual que los módulos de la StdLib:

importar "http"

variable resp = http_obtener("https://api.example.com")
imprimir(resp)

Librería Estándar (StdLib)

Alvz incluye módulos reutilizables que puedes importar con importar "nombre".

matematicas

importar "matematicas"
imprimir(factorial(5))       # 120
imprimir(maximo(10, 20))    # 20
imprimir(promedio([1,2,3])) # 2

cadenas

importar "cadenas"
imprimir(reversa("Hola"))        # aloH
imprimir(capitalizar("hola"))    # Hola
imprimir(contiene("Hola Mundo", "Mundo"))  # verdadero
imprimir(recortar("  texto  "))  # "texto"

colecciones

importar "colecciones"
imprimir(primero([10, 20, 30]))       # 10
imprimir(ultimo([10, 20, 30]))        # 30
imprimir(contiene([1, 2, 3], 2))     # verdadero
imprimir(sin_duplicados([1, 1, 2]))  # [1, 2]

http

Cliente HTTP para consumir APIs REST. Los métodos devuelven un diccionario con codigo, cuerpo y json.

importar "http"
variable resp = http_obtener("https://api.github.com", {})
si http_exito(resp) {
    variable datos = http_json(resp)
    imprimir(datos)
}

fecha

Funciones para obtener y formatear fecha/hora actual.

importar "fecha"
imprimir(ahora())                  # 2026-05-27 12:00:00
imprimir(dia_actual())             # 27
imprimir(formatear_fecha("%d/%m/%Y"))  # 27/05/2026

testing

Framework de pruebas unitarias para testear tu código Alvz.

importar "testing"

describir("Matematicas")
probar("suma funciona", funcion() {
    afirmar_igual(5, 2 + 3, "2+3=5")
})
probar("division", funcion() {
    afirmar_igual(2, 10 / 5, "10/5=2")
})
resumen()

sistema

Operaciones del sistema: archivos, JSON, rutas.

importar "sistema"
variable datos = {"nombre": "Alvz", "version": 1}
archivo_escribir_json("datos.json", datos)
variable leido = archivo_leer_json("datos.json")
imprimir(leido["nombre"])  # Alvz

sqlite

Base de datos SQLite embebida para persistencia local.

importar "sqlite"
variable db = base_abrir("ejemplo.db")
base_crear_tabla(db, "usuarios", ["id INTEGER PRIMARY KEY", "nombre TEXT", "edad INTEGER"])
base_insertar(db, "usuarios", {"id": 1, "nombre": "Ana", "edad": 30})
variable resultados = base_seleccionar(db, "usuarios", "")
cada r en resultados {
    imprimir(r["nombre"])  # Ana
}
base_cerrar(db)

aleatorio

Números aleatorios, selección y mezcla de colecciones, generación de cadenas aleatorias.

importar "aleatorio"
variable dado = aleatorio_numero(1, 6)
variable cartas = ["A", "K", "Q", "J"]
variable mano = aleatorio_escoger_varios(cartas, 2)
variable token = aleatorio_cadena(16)
imprimir(dado, mano, token)

csv

Lectura y escritura de archivos CSV con soporte para formato de diccionarios y listas.

importar "csv"
importar "sistema"

variable usuarios = [
    {"nombre": "Ana", "edad": "30"},
    {"nombre": "Bob", "edad": "25"}
]
csv_escribir("usuarios.csv", usuarios)
variable datos = csv_leer("usuarios.csv")
cada u en datos {
    imprimir(u["nombre"])
}

expresiones_regulares

Validación y extracción de patrones con expresiones regulares.

importar "expresiones_regulares"
variable email = "usuario@ejemplo.com"
si regex_coincide(email, "^.+@.+\\..+$") {
    imprimir("Email válido")
}
variable texto = "precio: $10, $20, $30"
imprimir(regex_todas(texto, "\\$\\d+"))  # ["$10", "$20", "$30"]

consola

Utilidades interactivas para terminal: menús, confirmaciones, colores y barras de progreso.

importar "consola"
variable nombre = consola_preguntar("¿Cómo te llamas?")
si consola_confirmar("¿Quieres continuar?") {
    variable opcion = consola_menu("Elige:", ["Opción A", "Opción B"])
    imprimir(consola_color("Listo", "verde"))
}

json

Codificación y decodificación JSON, validación y lectura/escritura de archivos.

importar "json"
variable datos = {"nombre": "Ana", "edad": 30}
variable texto = json_a_texto(datos)
imprimir(texto)              # {"nombre": "Ana", "edad": 30}
variable recuperado = texto_a_json(texto)
imprimir(recuperado["nombre"])  # Ana

Funciones incorporadas

importar "matematicas"
importar "fecha"
importar "aleatorio"
importar "json"

imprimir(factorial(5))                    # 120
imprimir(ahora())                          # "2026-05-27 12:00:00"
variable token = aleatorio_cadena(16)
imprimir(json_a_texto({"token": token}))  # {"token": "a3f8..."}

Async / Await

Alvz soporta programación asíncrona con las palabras clave async y aguardar. Las funciones marcadas como async se ejecutan mediante un event loop real con threads, permitiendo concurrencia verdadera.

funcion async obtener_datos(id) {
    retornar id * 2
}

variable resultado = aguardar obtener_datos(5)
imprimir(resultado)  # 10

Concurrencia real

Múltiples tareas async se ejecutan en paralelo usando ThreadPoolExecutor. Ejemplo con esperar():

funcion async tarea(n, segundos) {
    imprimir("Inicia tarea " + n)
    esperar(segundos)
    imprimir("Termina tarea " + n)
}

aguardar tarea("A", 0.5)
aguardar tarea("B", 0.3)

Sintaxis

• Función async: funcion async nombre(args) { cuerpo } — define una función que devuelve una corutina.
• Aguardar: aguardar expresion — ejecuta una corutina y espera su resultado.

aguardar puede usarse tanto en expresiones (asignación) como en sentencias (llamada directa):

// Como expresión
variable x = aguardar foo()

// Como sentencia
aguardar foo()

Optimizador de Bytecode

Alvz incluye un optimizador de bytecode que mejora el rendimiento de tus programas. Se activa con la bandera --optimize o -O al ejecutar un archivo.

$ alvz --optimize script.alvz

Ejecución WebAssembly

Alvz puede ejecutar archivos directamente via WebAssembly con --wasm, usando wasmtime en vez de la VM Python. 37 opcodes se ejecutan como WASM nativo y el resto via host calls.

$ alvz --wasm programa.alvz    # Ejecuta via WASM (requiere wasmtime)

Optimizaciones

• Plegado de constantes (Constant Folding): Evalúa expresiones aritméticas y lógicas con operandos constantes en tiempo de compilación. Ejemplo: 2 + 3 se convierte en 5 antes de ejecutar.
• Eliminación de código muerto: Remueve instrucciones después de OP_HALT que nunca se ejecutarán.
• Reasignación de saltos: Actualiza direcciones de salto automáticamente tras las optimizaciones.

Compatibilidad

El optimizador es completamente transparente: el programa produce el mismo resultado con o sin --optimize. La diferencia está en la velocidad de ejecución y el tamaño del bytecode.

Package Manager

Alvz incluye un gestor de paquetes para instalar y compartir librerías. Los paquetes se obtienen del registro público en github.com/interpago/alvz-packages.

Paquetes disponibles

Actualmente hay 30 paquetes en el registro:

Instalación

$ alvz install math          # Instala la última versión
$ alvz install json-utils    # Utilidades JSON
$ alvz install fs-extra@1.0.0 # Versión específica
$ alvz search json           # Busca paquetes relacionados

Comandos

Instalación de paquetes

$ alvz install stats           # Estadísticas
$ alvz install html-utils      # Generación HTML
$ alvz install semver          # Versionado semántico
$ alvz install retry           # Reintentos
$ alvz list-packages           # Ver instalados

$ alvz list-packages
$ alvz info math
$ alvz uninstall json-utils

Los paquetes se instalan en ~/.alvz/packages/ y pueden importarse con importar "nombre".

Uso desde código

# Después de instalar un paquete:
importar "strings"
importar "stats"
importar "html-utils"

variable texto = "Hola Mundo"
imprimir(invertir(texto))    # odnuM aloH

variable nums = [4, 7, 1, 9, 3]
imprimir(media(nums))        # 4.8

Compilación Nativa & Multiplataforma

Alvz genera ejecutables independientes mediante alvz build que funcionan en Windows, Linux y macOS. Todos los 83 opcodes del VM están soportados: clases, SQLite, HTTP, lambdas, async/await, etc. Los binarios se empaquetan con PyInstaller y no requieren dependencias externas.

$ alvz build programa.alvz
$ ./programa

Cómo funciona

1. El código fuente Alvz se compila a bytecode
2. El bytecode se empaqueta con el VM Python vía PyInstaller
3. Se genera un ejecutable standalone para la plataforma actual

funcion suma(a: numero, b: numero): numero {
    retornar a + b
}
variable x = suma(10, 20)
imprimir(x)

Compilación WASM

Alvz puede compilar tu código a WebAssembly (WASM), permitiendo ejecutar programas Alvz en cualquier runtime WASM como wasmtime, wasmer o en el navegador web.

$ alvz build --wasm programa.alvz
$ wasmtime programa.wasm

Opcodes Soportados (40+/83)

funcion suma(a: numero, b: numero): numero {
    retornar a + b
}
variable x = suma(10, 20)
imprimir(x)

$ alvz build --wasm programa.alvz
# Genera programa.wasm
$ wasmtime programa.wasm
# 30

Arquitectura Interna de Alvz

Alvz está construido sobre una arquitectura modular de 6 capas que transforman código fuente en ejecución. A continuación se explica cada componente clave del lenguaje.

Pipeline de Compilación

# 1. Lexer   Código .alvz → Tokens (Lexer)
# 2. Parser   Tokens → Árbol + Bytecode (ParserBase + Parser)
# 3. Opt.     Bytecode → Bytecode optimizado (Optimizer)
# 4. Type     Bytecode → Verificación de tipos (TypeChecker)
# 5. VM       Bytecode → Ejecución (VM con 83 opcodes)
# 6. Backends Bytecode → WASM / Nativo (wasm_compiler / compiler)

1. Lexer (Lexer)

El lexer (alvz/core/lexer.py, 262 líneas) tokeniza el código fuente usando expresiones regulares en un solo paso. Reconoce 30+ tipos de tokens incluyendo palabras clave en español (funcion, clase, mientras, importar, etc.), identificadores, números, strings, operadores y símbolos. Soporta strings con escape de comillas y comentarios de línea con #.

2. Parser (ParserBase + Parser)

El parser (parser_base.py + parser.py, ~2100 líneas) es un compilador de una sola pasada que genera bytecode directamente sin AST intermedio. Características clave:

• Forward references: Pre-scan de funciones para permitir llamadas antes de la definición.
• Clases y herencia: Compila clase Hijo de Padre con cadena de prototipos.
• Async/await: Compila funcion async y aguardar a opcodes especializados.
• Funciones anónimas: Lambdas como expresiones con naming interno __anon_N.
• Acceso encadenado: a.b.c() se compila como llamadas anidadas.
• global keyword: Declaración de variables globales dentro de funciones.

3. Bytecode (83 opcodes)

El bytecode Alvz (alvz/core/bytecode.py) es una representación intermedia basada en pila con 83 opcodes. Cada instrucción es un byte (0-81) seguido de 0-2 bytes de operandos. Categorías:

4. Máquina Virtual (VM)

El VM (alvz/core/vm.py, ~1127 líneas) es un intérprete de bytecode basado en pila implementado en Python puro. Características:

• Pila de valores: Enteros como flotantes (precisión de 64 bits), strings, listas, diccionarios, objetos, null.
• Pila de llamadas: Soporta recursión y llamadas anidadas.
• POO completa: Clases, herencia, getters/setters, métodos estáticos, super, instanceof.
• Async/event loop: ThreadPoolExecutor para concurrencia real con futuros.
• SQLite: Opcodes directos para operaciones de base de datos.
• HTTP: Peticiones web vía opcode dedicado.
• Stack traces: Muestra la línea de código fuente ofensiva con el contexto de llamadas.

5. Optimizador de Bytecode

El optimizador (alvz/core/optimizer.py, ~230 líneas) mejora el bytecode antes de ejecución:

• Plegado de constantes: 2 + 3 → 5 en compilación.
• Eliminación de código muerto: Instrucciones después de OP_HALT.
• Reasignación de saltos: Actualiza offsets tras optimizaciones.

Se activa con --optimize / -O.

6. Type Checker (Tipado Estático)

El verificador de tipos (alvz/core/type_checker.py, ~457 líneas) analiza el bytecode post-compilación:

• Verifica anotaciones de tipo en variables, parámetros y retorno.
• Inferencia automática desde literales (5 → numero).
• Validación en llamadas a funciones con tipos anotados.
• Se activa con --check-types / -T; activado por defecto.

7. Backend WASM

El compilador WASM (wasm_compiler.py + wasm_encoder.py, ~2300 líneas) traduce bytecode Alvz a módulos WebAssembly binarios:

• Arquitectura: VM de bytecode dentro del módulo WASM. Pila de valores en memoria lineal (tag i32 + data f64 = 16 bytes/entry).
• Memoria compartida: El módulo importa memoria del host (add_import_memory) en vez de crearla propia, compartiendo el espacio de direcciones con host functions.
• 40+ opcodes nativos implementados en WASM + 42 host calls para operaciones complejas (print, string ops, list/dict, SQLite, HTTP, random, etc.).
• Compatibilidad: wasmtime 45 con access_caller=False, sin memory64.
• Uso directo: alvz --wasm programa.alvz compila y ejecuta al instante.
• Build: alvz build --wasm programa.alvz → wasmtime programa.wasm.
• Datos: Bytecode y constantes como data segments en memoria WASM.

8. Backend Nativo (PyInstaller / Nuitka)

El compilador nativo (alvz/core/compiler.py, ~227 líneas) genera ejecutables standalone:

• PyInstaller: Empaqueta bytecode + VM Python en un solo .exe. Rápido y confiable.
• Nuitka: Compila Python → C++ → binario nativo. Mayor rendimiento pero más lento.
• Flags: alvz build (PyInstaller), alvz build --nuitka (Nuitka), alvz build --wasm (WASM).

9. LSP (Language Server Protocol)

El servidor LSP (alvz/lsp/, ~880 líneas) se comunica vía JSON-RPC sobre stdin/stdout:

• Diagnóstico real: Ejecuta el parser completo para errores de sintaxis y semántica.
• Autocompletado: Keywords, StdLib, funciones, variables, snippets.
• Ir a definición: Navega a la definición de símbolos.
• Hover info: Muestra tipo y documentación.
• Símbolos del documento: Lista estructurada de funciones/clases/variables.

10. DAP (Debug Adapter Protocol)

El depurador DAP (alvz/lsp/dap.py) permite depuración interactiva:

• Breakpoints en líneas específicas.
• Step over/into/out para ejecución paso a paso.
• Inspección de variables locales y globales.
• Stack trace con cadena de llamadas completa.
• Evaluación de expresiones en contexto.

Se ejecuta con alvz-dap o alvz debug.

11. StdLib (Librería Estándar)

13 módulos en alvz/stdlib/ escritos en Alvz puro:

12. Package Manager

30 paquetes disponibles en github.com/interpago/alvz-packages. El registro se obtiene de index.json vía GitHub raw. Los paquetes se instalan en ~/.alvz/packages/ y se importan con importar "nombre". Soporta dependencias entre paquetes.

Comandos: alvz install, alvz uninstall, alvz search, alvz list-packages, alvz info.

Estadísticas del Proyecto

Herramientas CLI

Alvz incluye herramientas de línea de comandos para testear, formatear y generar proyectos.

Test Runner

Ejecuta pruebas unitarias automáticamente. Descubre archivos test_*.alvz o *_test.alvz.

$ alvz test tests/              # Ejecuta todos los tests en la carpeta
$ alvz test test_mi_app.alvz    # Ejecuta un archivo específico

importar "testing"

funcion suma(a, b) {
    retornar a + b
}

describir("Pruebas de suma")

probar("suma funciona", funcion_suma_test)
funcion funcion_suma_test() {
    afirmar_igual(5, suma(2, 3), "2 + 3 = 5")
}

resumen()

Formateador

Formatea automáticamente tu código Alvz con indentación correcta de llaves.

$ alvz fmt app.alvz              # Formatea el archivo
$ alvz fmt --check app.alvz     # Solo verifica (no modifica)

Scaffolding

Genera proyectos completos con estructura lista para usar.

$ alvz nuevo proyecto mi_app    # Proyecto completo
$ alvz nuevo api mi_api          # API REST con FastAPI
$ alvz nuevo cli mi_cli          # Aplicación CLI
$ alvz nuevo lib mi_lib          # Librería reutilizable
$ alvz nuevo test mis_pruebas    # Archivo de test

Servidor de Lenguaje (LSP)

Alvz incluye un servidor LSP (Language Server Protocol) que proporciona asistencia inteligente en tu editor.

Características

• Autocompletado: Sugiere palabras clave, funciones incorporadas y nombres de variables.
• Diagnóstico en vivo: Detecta errores de sintaxis (paréntesis/llaves desbalanceados, caracteres inesperados).
• Ir a definición: Navega a la definición de funciones, variables y clases.
• Información al hover: Muestra el tipo y documentación de símbolos al pasar el ratón.
• Símbolos del documento: Lista estructurada de funciones, variables, clases y propiedades.

Uso

Ejecuta el servidor LSP desde la terminal:

$ alvz-lsp

Luego configura tu editor para conectarse al servidor. El LSP se comunica vía JSON-RPC sobre stdin/stdout.

Depurador (DAP)

Alvz implementa el Debug Adapter Protocol (DAP) para depuración interactiva desde tu editor.

Características

• Breakpoints: Pausa la ejecución en líneas específicas.
• Paso a paso: Step over, step into, step out.
• Inspección de variables: Examina variables locales y globales.
• Stack trace: Muestra la cadena de llamadas actual.
• Evaluación: Evalúa expresiones en contexto de depuración.

Uso

$ alvz-dap

El depurador se comunica vía JSON-RPC sobre stdin/stdout. Compatible con editores que soporten DAP (VS Code, etc.).

Consola Interactiva (REPL)

Prueba código al instante sin crear archivos. Solo escribe alvz en tu terminal.

alvz> variable a = 5
alvz> variable b = 5
alvz> imprimir(a + b)
10

Gestión de Errores Amigable

Alvz está diseñado para ayudarte a programar. Si cometes un error tipográfico o intentas acceder a algo que no existe, el lenguaje te dará sugerencias inteligentes.

$ alvz script.alvz
Error: La función 'imprimr' no existe. ¿Quisiste decir 'imprimir'?

Manejo de Excepciones (intentar / capturar)

Puedes capturar errores para evitar que tu programa se detenga inesperadamente.

intentar {
    variable resultado = 10 / 0
} capturar {
    imprimir("¡Ocurrió un error: " + error_msj() + "!")
}

Tipos de Errores Soportados

• Errores Léxicos: Caracteres no reconocidos.
• Errores de Sintaxis: Estructuras incompletas o mal formadas (incluye sugerencias de palabras clave).
• Errores de Referencia: Variables o funciones no definidas (incluye sugerencias de nombres cercanos).
• Errores en Tiempo de Ejecución: Errores durante la ejecución (como división por cero o índice fuera de rango) con stack trace completo que muestra la línea exacta y la cadena de llamadas.