Uso del CLI

Forja tiene 15+ comandos organizados en 4 categorías: ejecución, compilación, 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          Ejecutar .fa en la VM
  repl                       Modo interactivo
  diagrama          Generar diagrama HTML del código
  compilar          Generar .exe autónomo
  compilar-asm      Compilar a assembly nativo [--target ] [-o ]
  formatear         Formatear código .fa
  transpilar        Exportar a proyecto Rust
  nuevo              Crear nuevo proyecto
  iniciar                    Inicializar proyecto aquí
  aprender                   Tutorial interactivo
  palabras                   Lista de palabras clave
  colorear          Colorear código en terminal
  explicar          Explicar un concepto
  documentar        Generar documentación desde AST
  ayuda [tema]               Mostrar esta ayuda

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

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

`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 examples/01_hola.fa

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

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

# Errores en JSON (ideal para IDEs)
forja transpile examples/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 3 VMs).

⚡ Ejemplos de ejecución

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

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

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

`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 v0.2.0 — 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 examples/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 examples/01_hola.fa

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

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

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

# El assembly generado se puede compilar manualmente
forja build-asm examples/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 vm` (VM v1 Original)	~91,795 μs	~22x más lento que Python
`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 examples/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 examples/204_login_final.fa

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

# GUI Launcher directo
cargo build --features gui
.\target\debug\forja-gui.exe examples/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 examples/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` — 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` — 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 examples/07_funciones.fa
// Genera: examples/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 examples/10_clases.fa

`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 examples/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          # VM Original vs 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

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 — Explicar concepto

new|nuevo|crear — Nuevo proyecto

init|iniciar — Inicializar proyecto aquí

learn|aprender — Tutorial interactivo

diagrama|grafico|diagram — Diagrama HTML del AST

doc|documentar — Documentación desde AST

help|ayuda [tema] — Ayuda detallada

Compilar el Rust generado

Ejecutar benchmarks

`transpile|t|transpilar` — Forja → Rust

`run|ejecutar|correr` — Ejecutar en VM

`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` — Explicar concepto

`new|nuevo|crear` — Nuevo proyecto

`init|iniciar` — Inicializar proyecto aquí

`learn|aprender` — Tutorial interactivo

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

`doc|documentar` — Documentación desde AST

`help|ayuda [tema]` — Ayuda detallada