Uso del CLI

Forja tiene 20+ comandos organizados en 5 categorías: ejecución, compilación, gestión de paquetes, utilidades y proyectos. Todos los comandos aceptan su nombre en español e inglés.

📋 Ayuda completa

🔨 Forja (fa) — Lenguaje educativo con VM propia

COMANDOS:
  ejecutar <archivo>         Ejecutar .fa en la VM
  test [archivo]            Ejecutar tests (funciones con @test)
  repl                       Modo interactivo
  diagrama <archivo>         Generar diagrama HTML del código
  compilar <archivo>         Generar .exe autónomo
  compilar-asm <archivo>     Compilar a assembly nativo [--target <arch>] [-o <salida>]
  formatear <archivo>        Formatear código .fa
  transpilar <archivo>       Exportar a proyecto Rust
  nuevo <nombre>             Crear nuevo proyecto
  iniciar                    Inicializar proyecto aquí
  add <paquete> [version]   Añadir dependencia
  remove <paquete>           Eliminar dependencia
  install                    Instalar todas las dependencias
  medir <archivo>            Benchmark de VMs [--iters N] [--vm ...] [--asm]
  aprender                   Tutorial interactivo
  palabras                   Lista de palabras clave
  colorear <archivo>         Colorear código en terminal
  explicar <palabra>         Explicar un concepto
  documentar <archivo>       Generar documentación desde AST
  version                    Mostrar la versión de Forja
  ayuda [tema]               Mostrar esta ayuda

Los comandos también aceptan su nombre en inglés:
  run, build, transpile, build-asm, asm, new, init, add, remove, install,
  learn, keywords, highlight, explain, help, fmt, format, doc, test, bench

EJEMPLOS:
   forja ejecutar ejemplos/01_hola.fa
   forja compilar ejemplos/01_hola.fa -o programa.exe
   forja compilar-asm ejemplos/01_hola.fa
   forja compilar-asm ejemplos/01_hola.fa --target arm64 -o programa
   forja repl
    forja formatear ejemplos/01_hola.fa
    forja colorear ejemplos/01_hola.fa
    forja test ejemplos/mis_pruebas.fa
    forja nuevo mi_programa

PGO (Profile-Guided Optimization):
   forja ejecutar programa.fa --pgo            Recolectar perfil (.forjaprof)
   forja ejecutar programa.fa --pgo=usar       Aplicar perfil existente

`transpile|t|transpilar` — Forja → Rust

Genera código Rust compilable desde un archivo .fa. Ideal si querés llevar tu programa a producción con Rust o aprender cómo se traduce cada concepto. Si el argumento pasado al CLI termina en .fa, transpila automáticamente.

💡 ¿Sabías que…? El código Rust generado es perfectamente compilable con rustc. Podés usarlo como puente para aprender Rust progresivamente.

📄 Ejemplos de transpilación

# Automático (default si el arg termina en .fa)
forja ejemplos/01_hola.fa

# Con salida personalizada
forja transpile ejemplos/01_hola.fa -o salida.rs

# Atajo 't'
forja t ejemplos/10_clases.fa

# Errores en JSON (ideal para IDEs)
forja transpile ejemplos/10_clases.fa --json-errors

`run|ejecutar|correr` — Ejecutar en VM

Compila y ejecuta el bytecode directamente en la Máquina Virtual. No necesitás Rust instalado para ejecutar programas. La VM usada es ForjaFast v5 (la más rápida de las VMs).

⚡ Ejemplos de ejecución

forja run ejemplos/01_hola.fa
// → ¡Hola, mundo desde Forja!

forja run ejemplos/10_clases.fa
// → Hola, soy Ana y tengo 20 años
// → Es mayor de edad

forja run ejemplos/14_adivina.fa
// → Juego: adivina el número

# Seleccionar VM (fast | jit)
forja run ejemplos/01_hola.fa --vm fast
forja run ejemplos/01_hola.fa --vm jit

# Compilar a assembly y ejecutar con gcc -O2
forja run ejemplos/01_hola.fa --asm

# Fast math (arritmética flotante optimizada)
forja run ejemplos/01_hola.fa --fast-math

Flags de `run`

Flag	Descripción
`--vm fast\|jit`	Elige la VM a usar (default: fast)
`--asm`	Compila a assembly nativo y ejecuta (gcc -O2)
`--native`	GUI nativa con Xilem (requiere `--features gui`)
`--fast-math`	Aritmética flotante optimizada
`--pgo` / `--pgo=recoger`	Recolecta un perfil de ejecución (`.forjaprof`)
`--pgo=usar`	Aplica un perfil PGO existente
`--hot-reload` / `--hot`	Recarga módulos en caliente
`--contratos` / `--no-contratos`	Activa/desactiva verificación de design by contract
`--allow-net <hosts>`	Permite hosts de red en el sandbox
`--allow-port <puertos>`	Permite puertos de red en el sandbox
`--max-archivo <MB>`	Límite de tamaño de archivo
`--debug` / `--no-debug`	Habilita/deshabilita modo debug

`repl` — Modo interactivo

Intérprete línea por línea. Ideal para aprender, experimentar y debuggear algoritmos sin crear archivos. Las variables persisten entre líneas.

💬 Sesión de ejemplo

$ forja repl
🔨 Forja v1.0-rc — Escribí 'salir' para terminar

> variable x = 5
> x = x + 10
> escribir(x)
15
> constante nombre = "Gaucho"
> escribir("Hola " + nombre)
Hola Gaucho
> salir
👋 ¡Hasta luego!

`build|compilar|construir` — Ejecutable autónomo

Genera un .exe que contiene la VM + bytecode incrustado. Funciona en cualquier PC sin Rust, sin scripts, sin dependencias.

🔧 ¿Cómo funciona? Forja se copia a sí mismo (AOT compiler) y le agrega el bytecode al final del .exe. Al ejecutarlo, el módulo selfrun detecta el bytecode, lo deserializa y lo ejecuta en la VM. ¡Un solo archivo que es compilador y runtime a la vez!

📦 Ejemplo de build

forja build ejemplos/01_hola.fa -o hola.exe
// → ✅ Ejecutable generado: hola.exe (1234 bytes)

// Ahora cualquiera puede ejecutarlo, sin Rust:
./hola.exe
// → ¡Hola, mundo desde Forja!

`build-asm|compilar-asm|asm` — Assembly nativo (⚡ el más rápido)

Genera código assembly x86-64 o ARM64 directamente desde tu .fa y lo compila con gcc -O2. Es la forma más rápida de ejecutar Forja — velocidad nativa, igual que C o Rust compilado.

⚡ Rendimiento: El assembly nativo es ~1,750x más rápido que la VM de Forja, y ~30x más rápido que Python.

🛠️ Ejemplos de build-asm

# Mínimo: genera el ejecutable automáticamente (target = plataforma actual)
forja build-asm ejemplos/01_hola.fa

# Con nombre de salida personalizado
forja build-asm ejemplos/01_hola.fa -o programa.exe

# Especificar arquitectura destino
forja build-asm ejemplos/01_hola.fa --target arm64 -o programa

# Especificar Linux x86-64
forja build-asm ejemplos/01_hola.fa --target x86_64-linux -o prog

# El assembly generado se puede compilar manualmente
forja build-asm ejemplos/01_hola.fa --target x86_64-windows -o prog
gcc -O2 -o prog.exe prog.s

🎯 Targets disponibles

Flag	Arquitectura	Convención	Args (enteros)
(ninguno)	Detección automática	Según SO y CPU	—
`--target x86_64-windows`	x86-64	Microsoft x64	RCX, RDX, R8, R9 + 32B shadow
`--target x86_64-linux`	x86-64	System V AMD64	RDI, RSI, RDX, RCX, R8, R9
`--target arm64`	ARM64 AArch64	ARM64	X0..X7

🔧 ¿Cómo se compara con otros modos?

Modo	Velocidad (fib(30))	vs Python
`build-asm` (gcc -O2)	~51 μs	~80x más rápido que Python
`run --vm fast` (ForjaFast v5 🏆)	~9,544 μs	~2.3x más lento que Python
Python (CPython 3.11)	~4,117 μs	— referencia
`run --vm jit` (VM v3 Direct Threading)	~34,864 μs	~8.5x más lento que Python

`fmt|formatear|format` — Formatear código

Aplica formato consistente al código Forja: indentación de 4 espacios, espacios alrededor de operadores, llaves en la misma línea.

🎨 Ejemplo

# Antes (desordenado)
forja fmt ejemplos/01_hola.fa

# Después: código formateado con estilo consistente

`run|ejecutar --native` — GUI nativa con Xilem

Ejecuta archivos .fa que usen importar gui en una ventana nativa, ya sea compilando el proyecto a Rust+Xilem o usando el runtime de GUI nativa sin cargo previo (si compilaste Forja con --features gui).

🖼️ Ejemplo

# Native runner (AST directo a Xilem, sin compilar Rust)
cargo run --features gui --bin forja -- run --native ejemplos/204_login_final.fa

# Transpilado a Rust (genera .exe autónomo)
cargo run --features gui --bin forja -- transpile ejemplos/204_login_final.fa
cd .forja_gui_cache && cargo run --release

# GUI Launcher directo
cargo build --features gui
.\target\debug\forja-gui.exe ejemplos/204_login_final.fa

`highlight|colorear|color` — Colorear código en terminal

Muestra el código Forja con resaltado de sintaxis ANSI directamente en la terminal. Usa la misma paleta de colores que la documentación web y la extensión de VS Code.

🌈 Ejemplo

forja highlight ejemplos/01_hola.fa
// Muestra el código con keywords en amarillo,
// funciones en verde, tipos en cian, strings en brillante

`keywords|palabras|lista` — Palabras clave

Lista todas las palabras clave del lenguaje con su descripción:

📚 Salida

forja keywords
  📚 Palabras clave de Forja

  PALABRA         QUÉ HACE
  ─────────────── ───────────────────────────────
   escribir        Muestra mensajes en pantalla
   leer            Lee entrada del usuario
   variable/var    Declara una variable (mutable)
   constante/const Declara una constante (inmutable)
   mut             Modificador de mutabilidad
   si/sino         Condicional
   mientras        Bucle condicional
   para            Bucle con contador
   repetir         Repite N veces
   funcion/fun     Define una función
   retornar        Devuelve un valor
   clase           Define una clase
   constructor     Constructor de clase
   nuevo           Crea instancia de clase
   este            Objeto actual (self)
   prestado        Préstamo por referencia (&)
   importar        Importa módulos
   coincidir       Pattern matching
   caso            Caso de pattern matching
   tipo            Tipo algebraico (enum)
   otro            Caso default en seleccionar
   verdadero       Booleano verdadero
   falso           Booleano falso
   nulo            Valor nulo
   BD              Base de datos
   hilo            Lanza un hilo
   canal           Crea un canal de comunicación
   seleccionar     Select sobre canales
   trait           Definición de trait
   implementa      Implementación de trait
   externo         Función externa (FFI)
   asegurar        Asserts en tests
   @test/@derive   Atributos

`explain|explicar <palabra>` — Explicar concepto

Muestra una explicación detallada con ejemplos de cualquier palabra clave:

📖 Ejemplo

forja explicar funcion
📖 'funcion' agrupa código para reutilizarlo.
   Ej: funcion suma(a, b) { retornar a + b }

`new|nuevo|crear <nombre>` — Nuevo proyecto

Crea un proyecto Forja con la estructura de directorios estándar:

📁 Estructura generada

forja nuevo mi_programa
✅ Proyecto 'mi_programa' creado
   cd mi_programa && forja run main.fa

mi_programa/
├── main.fa          # Punto de entrada
├── forja.json       # Configuración del proyecto
└── modulos/         # Directorio para módulos

`init|iniciar` — Inicializar proyecto aquí

Inicializa un proyecto en el directorio actual (igual que new pero sin crear subdirectorio):

📁 Ejemplo

mkdir mi_proyecto && cd mi_proyecto
forja init

`learn|aprender` — Tutorial interactivo

Tutorial paso a paso desde la terminal. Ideal para quienes empiezan desde cero:

🎓 Salida

forja learn
🎓 Forja — Aprendé a programar

Lección 1: Mostrar mensajes
═══════════════════════════

Para mostrar algo en pantalla, usamos:
  escribir("texto")

`diagrama|grafico|diagram` — Diagrama HTML del AST

Genera un archivo HTML interactivo con el árbol de sintaxis abstracta (AST) del código. Cada nodo se puede expandir/colapsar. Ideal para entender cómo el compilador interpreta tu código.

🌳 Ejemplo

forja diagrama ejemplos/07_funciones.fa
// Genera: ejemplos/funciones.html
// Abrí el HTML en el navegador para ver el árbol

`doc|documentar` — Documentación desde AST

Genera documentación automática del código analizando el AST. Extrae funciones, clases y sus parámetros.

📄 Ejemplo

forja doc ejemplos/10_clases.fa

`test|tests|probar [archivo]` — Ejecutar tests

Ejecuta funciones marcadas con @test en archivos .fa. Sin argumento, busca y ejecuta todos los tests en ejemplos/.

🧪 Ejemplos

# Ejecutar tests de un archivo específico
forja test ejemplos/mis_pruebas.fa

# Ejecutar todos los tests en ejemplos/
forja test

`medir|bench|benchmark <archivo>` — Benchmark de VMs

Mide tiempos de ejecución en todas las VMs disponibles: creación, carga, ejecución en frío y en caliente.

⏱️ Ejemplos

# Medir en todas las VMs
forja medir ejemplos/bench_fib.fa

# Medir en una VM específica
forja medir ejemplos/bench_fib.fa --vm fast

# Con iteraciones personalizadas
forja medir ejemplos/bench_fib.fa --iters 10

# Modo ASM nativo
forja medir ejemplos/bench_fib.fa --asm

`PGO — Profile-Guided Optimization`

Forja puede recolectar perfiles de ejecución y recompilar el programa guiado por ese perfil. La recolección genera un archivo .forjaprof con conteos de llamadas por función, branches, tipos y iteraciones de loops.

📈 Ejemplos de PGO

# Recolectar perfil (genera .forjaprof)
forja ejecutar programa.fa --pgo

# Aplicar un perfil existente
forja ejecutar programa.fa --pgo=usar

`add|agregar|remove|remover|install|instalar` — Gestión de paquetes

Administrador de dependencias integrado. Los paquetes se declaran en forja.json y se almacenan en el directorio del proyecto.

📦 Ejemplos

# Añadir dependencia
forja add json-util

# Añadir con versión específica
forja add json-util 0.2.0

# Eliminar dependencia
forja remove json-util

# Instalar todas las dependencias del proyecto
forja install

`help|ayuda [tema]` — Ayuda detallada

Muestra ayuda general o sobre un tema específico:

❓ Ejemplos

forja ayuda
forja help funcion
forja --help

Compilar el Rust generado

Si usaste transpile, el archivo .rs generado se compila con Rust de forma estándar:

🦀 Compilar con rustc

rustc ejemplos/hola_mundo.rs
./hola_mundo

Ejecutar benchmarks

Forja incluye varios benchmarks para medir rendimiento:

📊 Benchmarks disponibles

cargo run --release --bin bench-jit          # JIT Nativo vs ForjaFast vs Rust
cargo run --release --bin bench-jit-100k     # JIT con 100k iteraciones
cargo run --release --bin bench-vms          # JIT(DT) vs ForjaFast
cargo run --release --bin bench-forjafast    # Todas las VMs (cold + hot)
cargo run --release --bin bench-rust-native  # Rust nativo (baseline)
cargo run --release --bin bench-clean        # ForjaFast vs Python
cargo run --release --bin bench-completo     # Completo vs Rust/Python/Go
cargo run --release --bin bench-cpython-opt  # Optimizaciones CPython

Uso del CLI

transpile|t|transpilar — Forja → Rust

run|ejecutar|correr — Ejecutar en VM

Flags de run

repl — Modo interactivo

build|compilar|construir — Ejecutable autónomo

build-asm|compilar-asm|asm — Assembly nativo (⚡ el más rápido)

fmt|formatear|format — Formatear código

run|ejecutar --native — GUI nativa con Xilem

highlight|colorear|color — Colorear código en terminal

keywords|palabras|lista — Palabras clave

explain|explicar <palabra> — Explicar concepto

new|nuevo|crear <nombre> — Nuevo proyecto

init|iniciar — Inicializar proyecto aquí

learn|aprender — Tutorial interactivo

diagrama|grafico|diagram — Diagrama HTML del AST

doc|documentar — Documentación desde AST

test|tests|probar [archivo] — Ejecutar tests

medir|bench|benchmark <archivo> — Benchmark de VMs

PGO — Profile-Guided Optimization

add|agregar|remove|remover|install|instalar — Gestión de paquetes

help|ayuda [tema] — Ayuda detallada

Compilar el Rust generado

Ejecutar benchmarks

`transpile|t|transpilar` — Forja → Rust

`run|ejecutar|correr` — Ejecutar en VM

Flags de `run`

`repl` — Modo interactivo

`build|compilar|construir` — Ejecutable autónomo

`build-asm|compilar-asm|asm` — Assembly nativo (⚡ el más rápido)

`fmt|formatear|format` — Formatear código

`run|ejecutar --native` — GUI nativa con Xilem

`highlight|colorear|color` — Colorear código en terminal

`keywords|palabras|lista` — Palabras clave

`explain|explicar <palabra>` — Explicar concepto

`new|nuevo|crear <nombre>` — Nuevo proyecto

`init|iniciar` — Inicializar proyecto aquí

`learn|aprender` — Tutorial interactivo

`diagrama|grafico|diagram` — Diagrama HTML del AST

`doc|documentar` — Documentación desde AST

`test|tests|probar [archivo]` — Ejecutar tests

`medir|bench|benchmark <archivo>` — Benchmark de VMs

`PGO — Profile-Guided Optimization`

`add|agregar|remove|remover|install|instalar` — Gestión de paquetes

`help|ayuda [tema]` — Ayuda detallada