# Primer programa de consola

En esta guía escribirá y ejecutará dos programas de consola: el clásico "Hola mundo" y un pequeño reporte que lee un archivo JSON, suma importes y recibe un parámetro por la línea de comandos. Al terminar sabrá la estructura de un programa DKL, cómo ejecutarlo y cómo leer sus errores.

Necesita Devkron 2.0 instalado: vea [Instalar en Linux](/es/devkron/2.0/instalacion/linux.md) o [Instalar en Windows](/es/devkron/2.0/instalacion/windows.md). No necesita licencia.

## 1. Hola mundo

Cree una carpeta de trabajo (por ejemplo `~/dkl` o `C:\dkl`) y guarde ahí `hola.dkl`, en UTF-8:

```dkl
#include "dkli.dkh"
#!
program "hola"
{
    #include "functions.dkh"

    do print("Hola mundo")
}
```

Qué hace cada línea:

| Línea | Para qué |
|---|---|
| `#include "dkli.dkh"` | carga los patrones de sintaxis del contexto imperativo; va siempre al principio de los programas que usan `if`, `for`, variables, funciones |
| `#!` | cambia al contexto imperativo |
| `program "hola" { … }` | el nodo raíz del programa; su nombre es libre |
| `#include "functions.dkh"` | la biblioteca de funciones de propósito general (`print`, `format`, `file.rtext`…); las bibliotecas se incluyen **dentro** del nodo raíz |
| `do print("Hola mundo")` | llama a una función; una llamada suelta siempre lleva `do` |

Ejecútelo desde la carpeta de trabajo:

```bash
/opt/devkron/dkl hola.dkl
```

```powershell
C:\devkron\dkl.exe hola.dkl
```

Salida:

```text
Iniciado 10/27/2026 17:19:41
ID de ejecución: e538cd8198bb4e128ea7d84d25ef8de0
Hola mundo

Terminado 10/27/2026 17:19:41
00:00:00.0639651
```

Las líneas `Iniciado`, `ID de ejecución` y `Terminado` son la bitácora de la ejecución. Para ver solo la salida del programa agregue `-hide-log`:

```bash
/opt/devkron/dkl hola.dkl -hide-log
```

```text
Hola mundo
```

La extensión `.dkl` se puede omitir (`dkl hola -hide-log`). Si agrega la carpeta de Devkron al `PATH` (vea [Instalar en Linux](/es/devkron/2.0/instalacion/linux.md) o [en Windows](/es/devkron/2.0/instalacion/windows.md)) bastará con escribir `dkl hola.dkl`; así se muestran los comandos en el resto de esta guía.

## 2. Un programa que genera XML

DKL también es declarativo: lo que escribe fuera de `#!` se convierte en elementos. Guarde `personas.dkl`:

```dkl
Personas(cantidad="3")
{
    Persona(nombre="Juan")
    Persona(nombre="Pedro")
    Persona(nombre="Camila")
}
```

```bash
dkl personas.dkl -hide-log
```

```text
<?xml version="1.0" encoding="UTF-8"?>
<Personas cantidad = "3" ><Persona nombre = "Juan" /><Persona nombre = "Pedro" /><Persona nombre = "Camila" /></Personas>
```

Para guardar esa salida en un archivo, sin mostrar nada en la consola:

```bash
dkl personas.dkl -ninja -output:personas.xml
```

Esta es la base de las páginas web: el mismo mecanismo produce HTML. Lo verá en [Primer sitio web](/es/devkron/2.0/introduccion/primer-sitio.md).

## 3. Un reporte que lee un archivo y recibe parámetros

Un caso típico de una tarea de consola: leer datos, calcular y mostrar un resumen. Guarde `ventas.json` en la carpeta de trabajo:

```json
[
    {"sucursal": "Centro", "importe": 1250.5},
    {"sucursal": "Norte", "importe": 980},
    {"sucursal": "Centro", "importe": 310.25}
]
```

Y `reporte.dkl`:

```dkl
#include "dkli.dkh"
#!
program "reporte-ventas"
{
    #include "functions.dkh"
    #include "serialize.dkh"

    // Lee el archivo indicado con -archivo:ruta (o ventas.json si no se indica)
    ref args = commandline(":")
    archivo = field.dstr(args, "-archivo", "ventas.json")

    if not(file.exists(archivo))
    {
        do rise_error(0, "No existe el archivo " + archivo)
    }

    ref ventas = from.json(file.rtext(archivo))

    total = 0
    for i = 0; i < list.count(ventas)
    {
        ref v = list.obj(ventas, i)
        total = total + field.num(v, "importe")
        do print(field.str(v, "sucursal") + ": " + format(field.num(v, "importe"), "#,0.00"))
    }

    do print("Ventas: " + str(list.count(ventas)))
    do print("Total: " + format(total, "#,0.00"))
}
```

Puntos a notar:

- `serialize.dkh` aporta `from.json` y `to.json`.
- `commandline(":")` convierte la línea de comandos en un registro: `-archivo:otro.json` queda como el campo `-archivo` con valor `otro.json`. El programa recibe sus propios argumentos además de las opciones de `dkl`.
- Los objetos (listas, registros) siempre se guardan en variables `ref`.
- El `for` no lleva paréntesis y, con incremento de 1, no se escribe el incremento.
- No hay `;` al final de las sentencias: una por línea.

```bash
dkl reporte.dkl -hide-log
```

```text
Centro: 1,250.50
Norte: 980.00
Centro: 310.25
Ventas: 3
Total: 2,540.75
```

Con otro archivo que no existe:

```bash
dkl reporte.dkl -hide-log -archivo:otro.json
echo $?
```

```text
{0} No existe el archivo otro.json[Ln= 12]
1
```

## 4. Códigos de salida

`dkl` termina con **código 0** si el programa terminó bien (también si un error se capturó con `exception`) y con **código 1** si hubo un error no manejado, un error de sintaxis o el archivo no existe. Así un script o `cron` puede saber si la tarea falló:

```bash
dkl reporte.dkl -hide-log || echo "El reporte falló"
```

```powershell
dkl reporte.dkl -hide-log
if ($LASTEXITCODE -ne 0) { Write-Host "El reporte falló" }
```

En 1.x `dkl` terminaba siempre con 0.

## Errores típicos

| Síntoma | Causa | Solución |
|---|---|---|
| `No se pudo encontrar el archivo: hola.dkl` | la ruta del programa está mal o no está en la carpeta actual | ejecute desde la carpeta del programa o indique la ruta completa |
| `No existe el archivo ventas.json` aunque el archivo sí existe | las rutas relativas se resuelven contra el **directorio de trabajo**, no contra la carpeta del programa | ejecute `dkl` desde la carpeta de los datos o use rutas absolutas |
| `{110} Error de sintaxis … No se encontró el símbolo de cierre` | falta una `}` o un paréntesis | revise los bloques cerca de la línea indicada (el número de línea puede estar desfasado) |
| `Función: format no reconocida o no registrada` (o `file.rtext`, `from.json`…) | falta la biblioteca que define esa función (`functions.dkh`, `serialize.dkh`…) dentro del nodo raíz | agregue el `#include` después de la llave de `program` (`print` es incorporada y funciona sin bibliotecas) |
| `Tipos no coinciden` | se mezcló un objeto (lista, registro) con una cadena o un número | use `ref` para objetos y las funciones `field.str`, `field.num`, `list.obj` para leerlos |
| caracteres raros en acentos | el archivo no está en UTF-8 | guárdelo en UTF-8 |

Para revisar solo la sintaxis, sin ejecutar, use `dkl programa.dkl -parse`. Todas las opciones están en [Ejecutar programas de consola](/es/devkron/2.0/instalacion/consola.md).

## Siguiente paso

- [Primer sitio web](/es/devkron/2.0/introduccion/primer-sitio.md): el mismo tipo de programa, servido por nginx.
- [Referencia del lenguaje](/es/devkron/2.0/lenguaje/): variables, expresiones, sentencias y funciones.