# Organización y estructura del programa ## Ámbitos Todo programa DKL tiene tres ámbitos: - **Global**: variables `@nombre`, disponibles en todas partes. - **Principal**: el código fuera de las funciones. - **De función**: el bloque de cada función definida por el programador. ```dkl #include "dkli.dkh" #! program { funcion1 :: { // ámbito de la función a = 3 // local a la función } // ámbito principal @a = 1 // global a = 2 // local al ámbito principal } ``` Vea [Variables](/es/devkron/2.0/lenguaje/imperativo/variables.md). ## program, module y codeblock Todo archivo DKL es un árbol con un único elemento raíz. Un programa imperativo pone su código dentro de un bloque `program`, `module` o `codeblock`; los tres son equivalentes y sirven como: - **nodo raíz** y contenedor del ámbito principal; - delimitador de un **espacio de nombres** (opcional). ```dkl program "mi programa" { } module "mi programa" { } codeblock "mi programa" { } ``` Se pueden anidar: ```dkl module "módulo raíz" { funcion1 :: { codeblock ":espacio_de_nombres" { } } module "módulo interno" { // también es el ámbito principal } } ``` Estos bloques **no** crean ámbitos aislados: su código pertenece al ámbito en que se encuentran. Con `#include`, el código del archivo se inserta donde está la directiva. Con la sentencia `include` (en ejecución), el archivo se analiza aparte, pero se ejecuta en el ámbito de quien lo incluye (vea «La sentencia include», más abajo). ## Espacios de nombres La cadena de `program`, `module` o `codeblock` es una descripción y, después de `:`, un **espacio de nombres**: ```text module "descripción:espacio.de.nombres" { } ``` Las funciones declaradas en el bloque reciben ese prefijo. Dentro del bloque se llaman por su nombre corto; fuera, por el completo. ```dkl module "Gestión de inventarios:inventarios.movimientos" { entradas :: n { return "entrada " + str(n) } inventarios.movimientos.atipicos :: n { return "atípico " + str(n) } extemporaneos.devoluciones :: n { return "devolución " + str(n) } do print(entradas(1)) do print(atipicos(2)) do print(extemporaneos.devoluciones(3)) } do print(inventarios.movimientos.entradas(4)) do print(inventarios.movimientos.extemporaneos.devoluciones(5)) ``` ```text entrada 1 atípico 2 devolución 3 entrada 4 devolución 5 ``` - `entradas` se llama en realidad `inventarios.movimientos.entradas`. - Si el nombre de la función ya empieza con el espacio de nombres (`inventarios.movimientos.atipicos`), no se le antepone otra vez. - `extemporaneos.devoluciones` queda como `inventarios.movimientos.extemporaneos.devoluciones`. - Sin espacio de nombres, las funciones van al espacio global. > **Cuidado con los dos puntos en la descripción.** `module "utilerías: lectura"` crea el espacio de nombres ` lectura`; para una descripción sin espacio de nombres no use `:`, o póngalo al final (`module "Utilerías:"`). ## namespace `namespace "espacio.de.nombres"` agrega espacios donde buscar una función que no se encuentra por su nombre: ```dkl module "librería:lib.texto" { mayus :: s { return toupper(s) } } codeblock "uso:otro" { namespace "lib.texto" do print(mayus("def")) } ``` ```text DEF ``` Si hay varios `namespace` y el nombre corto coincide con funciones de más de uno, el motor lanza `Nombre de función ambiguo, uno o más namespaces resuelven a funciones diferentes. Use un alias o el nombre completo de la función '…'`. ## alias `alias "nombre.completo.función" "corto"` da un nombre corto válido dentro del bloque donde se declara: ```dkl module ":mi.espacio.de.nombres" { nombre_de_funcion_largo :: x, y { return x + y } } codeblock "uso" { alias "mi.espacio.de.nombres.nombre_de_funcion_largo" "suma" do print(suma(4, 5)) } ``` ```text 9 ``` Los alias **no** valen en `point … to` ni en `go`: ahí use el nombre completo. En 2.0, `namespace` y `alias` también funcionan con funciones .NET mapeadas con `_map_function` (en 1.x daban `KeyNotFoundException`). ## Bibliotecas propias con #include Reúna sus funciones en un archivo `.dkh` con un espacio de nombres y empiécelo con `#!`. Sin `#!`, el archivo incluido arranca en modo declarativo: el `module` queda como un elemento del árbol, sus funciones no se registran y la llamada falla con `Función: clientes.nombre.completo no reconocida o no registrada`. ```dkl #! module "Utilerías de clientes:clientes" { nombre.completo :: &c { return trim(@@(c, "nombre") + " " + @@(c, "apellidos")) } es.valido :: &c { return length(trim(@@(c, "rfc"))) >= 12 } } ``` ```dkl #include "dkli.dkh" #! program "usa-clientes" { #include "functions.dkh" #include "lib/clientes.dkh" new c { @"nombre": "Ana" @"apellidos": "López" @"rfc": "XAXX010101000" } do print(clientes.nombre.completo(c)) do print(clientes.es.valido(c)) } ``` ```text Ana López 1 ``` Vea [Directivas](/es/devkron/2.0/lenguaje/declarativo/directivas.md) para la búsqueda de archivos y `#path`. ## La sentencia include `include expresión` (sin `#`) carga y ejecuta un archivo **en tiempo de ejecución**, solo si la ejecución pasa por ella. El nombre puede calcularse. El archivo se analiza como un **documento propio**: - necesita su propio `#include "dkli.dkh"`, `#!` y un único nodo raíz (`codeblock`, `module`…); sin ellos, la ejecución se detiene con un error de sintaxis del archivo incluido; - no necesita repetir `functions.dkh` ni las demás bibliotecas: las funciones que ya registró quien lo incluye siguen disponibles; - corre en el **ámbito de quien lo incluye**: dentro de una función, ve y cambia las variables de esa función; - un `return` dentro del archivo sale de la función que hizo el `include` (lo que sigue al `include` no se ejecuta). ```dkl #include "dkli.dkh" #! codeblock "paso" { @veces = @veces + 1 do print("paso ejecutado: " + str(@veces)) } ``` ```dkl #include "dkli.dkh" #! program "include-en-ejecucion" { #include "functions.dkh" @veces = 0 if 0 { include "lib/paso.dkl" } archivo = "lib/" + "paso.dkl" for i = 0; i < 3 { include archivo } do print("total " + str(@veces)) } ``` ```text paso ejecutado: 1 paso ejecutado: 2 paso ejecutado: 3 total 3 ``` | | `#include` | `include` | |---|---|---| | Cuándo | al analizar | al ejecutar | | Dentro de un `if` falso | se incluye igual | no se ejecuta | | Nombre | cadena literal | cualquier expresión | | Uso típico | bibliotecas, `.dkh` | enrutadores, plugins, partes opcionales | Correcciones de 2.0: dentro de un ciclo, `include` se ejecuta **una vez por iteración** (en 1.x se ejecutaba 1+2+…+N veces), y una expresión vacía informa `La expresión no produjo un nombre de archivo`. ## Estructura recomendada ```text mi-proyecto/ ├── programa.dkl #include "dkli.dkh", #! y program "…" { … } ├── lib/ │ ├── clientes.dkh #! module "…:clientes" { … } │ └── facturas.dkh #! module "…:facturas" { … } └── vistas/ └── reporte.dkl se carga con include o runscript ``` - Un espacio de nombres por archivo `.dkh`. - Funciones declaradas antes de usarse (los `#include` de bibliotecas al principio del `program`). - Configuración en variables globales `@` al inicio.