# Directivas
Las directivas empiezan con `#` y se procesan **al analizar** (parsear) el archivo, conforme aparecen, antes de ejecutar cualquier sentencia. Por eso un `#include` dentro de un `if` se incluye siempre, se cumpla o no la condición.
| Directiva | Para qué sirve |
|---|---|
| `#include` | Inserta otro archivo en ese punto. |
| `#path` | Agrega una carpeta donde buscar los `#include`. |
| `#def` / `#redef` | Asocia un identificador con un nombre de elemento y sus atributos (plantillas). |
| `#pattern` | Define una sintaxis nueva que se traduce a un elemento. |
| `#set` | Asigna un meta-atributo al siguiente elemento. |
| `#!`, `#$`, `##` | Cambian el contexto: vea [Contexto declarativo e imperativo](/es/devkron/2.0/lenguaje/declarativo/contextos.md). |
## #include
Inserta el contenido de otro archivo en la posición de la directiva; todo se interpreta como un solo documento.
```text
#include "archivo"
#include CODIFICACIÓN "archivo"
```
- `archivo` es una ruta local o una URL (`http://`, `https://`, `ftp://`, `ftps://`).
- `CODIFICACIÓN` (opcional) es `UTF8`, `ASCII`, `UTF7`, `UNICODE`, `ENDIANUNICODE` o `UTF32`.
- Una ruta relativa se busca primero junto al archivo que la incluye y luego en las carpetas de `#path` y en la carpeta de `dkl` (ahí están `dkli.dkh`, `functions.dkh`, etc.).
- Como es una cadena, en Windows escriba `\\` o `/`: `"c:\\libs\\util.dkh"` o `"c:/libs/util.dkh"`; `"c:\libs\util.dkh"` es incorrecto.
**Regla importante:** un archivo incluido se analiza empezando en contexto **declarativo**, aunque el `#include` esté en código imperativo. Si el archivo tiene funciones o sentencias, debe empezar con `#!`.
Archivo `lib/util.dkh`:
```dkl
#!
module "Utilerías:util"
{
saludo :: nombre
{
return "Hola, " + nombre
}
@util_cargado = "sí"
}
```
Programa que lo usa:
```dkl
#include "dkli.dkh"
#!
program "usa-util"
{
#include "functions.dkh"
#include UTF8 "lib/util.dkh"
do print(util.saludo("Ana"))
do print(@util_cargado)
}
```
```text
Hola, Ana
sí
```
Si a `lib/util.dkh` le falta el `#!`, el módulo se toma como XML: la función no existe (`Función: util.saludo no reconocida o no registrada`) y el contenido aparece en la salida como elementos `dkli-module`, `dkli-function`…
Un archivo que no se encuentra detiene el análisis:
```dkl
#include "dkli.dkh"
#!
program "inc"
{
#include "lib/no_existe.dkh"
do print("no llega")
}
```
```text
{9999} Error de sintaxis [/home/usuario/ejemplos/ejemplo.dkl] [9999] - No se puede encontrar el archivo lib/no_existe.dkh[Ln= 4]
```
### #include frente a la sentencia include
`#include` se resuelve al analizar y siempre inserta el archivo. La **sentencia** `include "archivo"` (sin `#`) es imperativa: carga y ejecuta el archivo **solo si la ejecución pasa por ella**, y el nombre puede ser una expresión. Vea [Organización del programa](/es/devkron/2.0/lenguaje/imperativo/organizacion.md).
### Plantillas GT (retiradas)
Las formas `#include "archivo" build` y `#include "archivo" with "plantilla"` usaban el generador de plantillas GT, que **ya no existe en 2.0**. Ahora producen `{131} … #include ... with usaba las plantillas GT, que se retiraron en Devkron 2.0`. La alternativa es `ftext(file.rtext("plantilla.htt"))` con [marcas `#<…>`](/es/devkron/2.0/lenguaje/declarativo/marcas-de-expresion.md).
## #path
Agrega una carpeta a la lista donde se buscan los archivos de `#include` (y de la sentencia `include`).
```dkl
#!
module "fechas:fechas"
{
hoy.texto :: f
{
return ndatetime.tostr(f, "dd/MM/yyyy")
}
}
```
```dkl
#include "dkli.dkh"
#path "libs"
#!
program "con-path"
{
#include "functions.dkh"
#include "fechas.dkh"
do print(fechas.hoy.texto(20261027))
}
```
```text
27/10/2026
```
En 2.0, `#include "sub/archivo.dkh"` también se resuelve dentro de las carpetas de `#path` en Linux (en 1.x no se encontraba), y `#path` sin cadena es un error `{131} … Se esperaba una cadena de ruta`. En el servidor FastCGI, un `#path` dura solo esa ejecución (en 1.x lo heredaban las peticiones siguientes).
## #def y #redef
`#def` asocia un identificador con una cadena (normalmente un nombre de elemento) y, opcionalmente, con una lista de atributos por orden y unos atributos predeterminados.
```text
#def identificador "valor"
#def identificador (atributos por orden) "valor" [(atributos predeterminados)]
```
### Como macro
En su forma más simple, el identificador se reemplaza por la cadena dondequiera que aparezca: nombre de elemento, de atributo o valor.
```dkl
#def J "Juan"
#def P "Pedro"
#def n "nombre"
Personas(cantidad="3")
{
Persona(n=J)
Persona(n=P)
n(n=n){}
#redef J "José"
Persona(n=J)
}
```
```text
```
`#redef` cambia la cadena de un `#def` anterior; el cambio solo afecta al código que le sigue.
Los `#def` de un archivo incluido valen en el que lo incluye: puede reunir sus definiciones en un `.dkh` y compartirlas.
### Atributos por orden y predeterminados
Con la lista de atributos por orden, los valores se escriben por posición, separados por comas; después de `;` van atributos con nombre que reemplazan a los predeterminados.
```dkl
#include "dkli.dkh"
#def emisor (Rfc, Nombre) "cfdi:Emisor" (Rfc="XAXX010101000" Nombre="" RegimenFiscal="601")
#def boton (texto, tipo) "button" (class="btn")
#!
program "ejemplo-def"
{
##
comprobante
{
emisor ("EKU9003173C9", "EMPRESA DE EJEMPLO")
emisor ("EKU9003173C9"; RegimenFiscal="612")
boton ("Aceptar", "submit"){}
boton (id="cancelar"){}
}
}
```
```text
```
Reglas que conviene recordar:
- Si usa atributos predeterminados, la lista por orden es **obligatoria**: `#def emisor "cfdi:Emisor" (Rfc="X")` es `{100} Símbolo no esperado`, y una lista vacía `()` es `{108}`.
- No se pueden poner dos grupos de paréntesis: `boton("Cancelar")(id="c"){}` es `{100} Símbolo no esperado`; use `;` dentro del mismo paréntesis.
## #pattern
`#pattern` define una sintaxis propia que se reconoce línea por línea y se transforma en un elemento. Toda la sintaxis imperativa de DKL (`if`, `for`, `do`, `new`…) está definida así en `dkli.dkh`.
```text
#pattern identificador "cadena de patrón"
```
`identificador` es uno definido antes con `#def`. En la cadena de patrón, las palabras sueltas son literales y los nombres entre comillas simples capturan una parte de la línea en el atributo del mismo nombre. El prefijo indica qué se captura:
| Prefijo | Captura |
|---|---|
| `$` | un identificador |
| `&` | una expresión (también se asume si no hay prefijo) |
| `%` | una macro: se reemplaza por lo que diga un `#def` previo |
| `@` | una cadena (comillas dobles o simples) |
| `#` | un número |
| `*` | número, cadena o identificador |
```dkl
#def color (nombre) "prefijoXml:Color"
#pattern color "COLOR '$nombre'"
#def precio (clave, importe) "precio"
#pattern precio "PRECIO '$clave' '#importe'"
#def nota (texto) "nota"
#pattern nota "NOTA '*texto'"
#def total (expr) "total"
#pattern total "TOTAL '&expr'"
catalogo
{
COLOR azul
PRECIO lapiz 5.50
NOTA "con cadena"
NOTA 15
TOTAL 5 * (2 + 1)
}
```
```text
```
Restricciones:
- Un patrón solo se intenta si la línea **empieza con un identificador** (así funcionan todas las sentencias de DKL).
- En la cadena de patrón no se permiten las secuencias *expresión expresión*, *identificador expresión* ni *palabra reservada expresión* (no habría forma de saber dónde termina cada una).
- Un patrón definido **después** de `dkli.dkh` que contenga `->` puede quedar tapado por las [flechas de listas](/es/devkron/2.0/lenguaje/novedades-2.0/flechas-de-listas.md) de 2.0 si empieza con un identificador.
- En 2.0 la palabra clave de un patrón puede empezar con `$` (`#pattern $item "$it '@texto'"`).
## #set
Asigna un [meta-atributo](/es/devkron/2.0/lenguaje/declarativo/elementos-y-atributos.md) al **elemento inmediato siguiente**.
```text
#set "meta-atributo" "valor"
```
```dkl
#set "meta-xml-declaration" "\n\n"
raiz(a="1"){}
```
```text
```
Los meta-atributos no aparecen en el XML: los usa el motor. Los de uso común son `meta-xml-declaration` y `dkl/hide-element`.
## Dialectos propios
Con `#def`, `#pattern` y `#set` en un archivo de cabecera (`.dkh`) se puede definir un lenguaje propio para archivos de configuración, descripciones o documentos, y `dkl` lo traduce a XML. Así está hecho el propio DKL imperativo (`dkli.dkh`) y el lenguaje de modelos de datos (`ddm.dkh`).
Cabecera `servicio.dkh`:
```dkl
#def servicio (nombre) "servicio" (version="1.0")
#def host (valor) "host"
#pattern host "host: '@valor'"
#pattern host "host: '$valor'"
#def puerto (valor) "puerto"
#pattern puerto "puerto: '#valor'"
#def clave (secreto) "clave"
#pattern clave "clave: secreto '@secreto'"
#def rango "rango"
#def desde (valor) "desde"
#pattern desde "desde: '#valor'"
#def hasta (valor) "hasta"
#pattern hasta "hasta: '#valor'"
#def cache "cache"
#set "meta-xml-declaration" "\n\n"
```
Archivo `web.svc`, escrito en el dialecto:
```dkl
#include "servicio.dkh"
servicio ("pedidos")
{
host: "api.ejemplo.com"
host: localhost
puerto: 8080
clave: secreto "s3cr3t0"
rango
{
desde: 5
hasta: 20
}
cache {}
}
```
`dkl web.svc` imprime:
```text
```
- **Varios patrones por definición.** Un mismo `#def` admite varios `#pattern`, con distinto tipo de captura (`host` acepta una cadena o un identificador) o con palabras fijas (`clave: secreto "…"`).
- **Atributos predeterminados.** `version="1.0"` aparece en la salida aunque el autor no lo escriba.
- **`#set` al final de la cabecera** se aplica al primer elemento del archivo que la incluye. Así la cabecera fija la declaración XML y la instrucción `` del documento producido, sin que el autor las escriba.
- **Un valor por línea.** Cada patrón se reconoce línea por línea: `rango { desde: 5 hasta: 20 }` o dos valores en la misma línea dan `{100} … Símbolo no esperado`. Escriba uno por línea.
- **Elemento vacío con llaves.** Como en todo el contexto declarativo, un elemento sin hijos ni atributos lleva llaves: `cache {}`. Sin ellas: `{109} … Definición de elemento incompleta`.
- **Código dentro del dialecto.** `#include "dkli.dkh"` y `#include "functions.dkh"` dentro del elemento raíz no agregan nodos, y una [marca de expresión](/es/devkron/2.0/lenguaje/declarativo/marcas-de-expresion.md) en un texto se evalúa: el texto `"#"`, en su propia línea dentro de un elemento, inserta el contenido de `desc.md`.
Para usar el resultado desde un programa, `runscript` devuelve el XML como cadena:
```dkl
#include "dkli.dkh"
#!
program "lee"
{
#include "functions.dkh"
xml = runscript("web.svc")
do print(xml)
}
```
Para validar ese XML contra un esquema XSD, vea [Funciones de interoperabilidad](/es/devkron/2.0/lenguaje/funciones-incorporadas/interoperabilidad.md).