# url.dkh: partes de una URL y cadenas de consulta `url.dkh` separa una URL en sus partes, resuelve direcciones relativas y arma o lee cadenas de consulta (`?a=1&b=2`) con la codificación correcta. Viene con la distribución de Devkron 2.0 (`Devkron.Ext.Base.dll`). ## Cuándo usarla - Armar la URL de una API con parámetros que traen espacios, acentos o `&` (`url.with_query`). - Leer los parámetros de una URL que le llega como dato: el regreso de un proveedor de pagos, un webhook (`url.query`). - Convertir los enlaces relativos de una página en absolutos (`url.absolute`). - Validar que una URL recibida apunta a su propio dominio antes de redirigir (`url.host`). ```dkl #include "url.dkh" ``` ## Funciones | Función | Devuelve | Descripción | |---|---|---| | `url.scheme(url)` | cadena | Esquema: `https`, `http`, `ftp`… | | `url.host(url)` | cadena | Host, sin puerto: `tienda.ejemplo.com` | | `url.port(url)` | número | Puerto; si la URL no lo trae, el del esquema (443 para https, 80 para http) | | `url.path(url)` | cadena | Ruta, sin consulta: `/api/v1/clientes` | | `url.absolute(base, relativa)` | cadena | `relativa` resuelta contra `base` | | `url.is_absolute(url)` | lógico | `@true` si tiene esquema http, https, ftp o file | | `url.query(url)` | registro | Parámetros de la consulta, ya decodificados | | `url.with_query(url, registro)` | cadena | `url` con los campos del registro agregados como parámetros codificados | | `url.encode(texto)` | cadena | Codifica un componente (`ñ` → `%C3%B1`, espacio → `%20`) | | `url.decode(texto)` | cadena | Decodifica un componente | - `url.host`, `url.scheme`, `url.port` y `url.path` requieren una URL absoluta; con una relativa lanzan error. - `url.query` acepta la URL completa o solo la consulta (`a=1&b=2`). Si un parámetro se repite, gana el último. Todos los valores llegan como cadena. - `url.with_query` agrega los parámetros a los que ya trae la URL, antes del `#` si lo hay. - `url.encode` **no es** `url_encode` de `functions.dkh`: aquella codifica en base64. ## Ejemplo ```dkl #include "dkli.dkh" #! program "urls" { #include "functions.dkh" #include "serialize.dkh" #include "url.dkh" u = "https://tienda.ejemplo.com:8443/catalogo/buscar?q=martillo%20de%20u%C3%B1a&pagina=2" do print(url.scheme(u) + " | " + url.host(u) + " | " + str(url.port(u)) + " | " + url.path(u)) do print(to.json(url.query(u))) do print(url.absolute(u, "../productos/m-1.html")) do print(str(url.is_absolute(u)) + " " + str(url.is_absolute("/catalogo"))) new p { @"q": "clavos & tornillos" @"pagina": 3 } do print(url.with_query("https://api.ejemplo.com/v1/productos?orden=precio", p)) do print(url.encode("Pérez & Hijos") + " | " + url.decode("Pi%C3%B1a%20colada")) x = url.host("/catalogo") exception { do print(last_error()) } } ``` Salida: ``` https | tienda.ejemplo.com | 8443 | /catalogo/buscar {"q":"martillo de uña","pagina":"2"} https://tienda.ejemplo.com:8443/productos/m-1.html 1 0 https://api.ejemplo.com/v1/productos?orden=precio&q=clavos%20%26%20tornillos&pagina=3 P%C3%A9rez%20%26%20Hijos | Piña colada {1} Error en 'url.host. (url.host: la URL no es absoluta o no es válida: '/catalogo'Exception has been thrown by the target of an invocation.) [url.dkl][Ln= 20] ``` ## Errores | Mensaje | Causa | |---|---| | `url.host: la URL no es absoluta o no es válida: '…'` | También en `url.scheme`, `url.port` y `url.path`: falta el esquema o la URL está mal formada | | `url.absolute: no se pudo combinar '…' con '…'` | La base no es absoluta | | `url.with_query: los parámetros deben ser un registro` | El segundo argumento no es registro | ## Advertencias - Los valores de `url.query` son cadenas; conviértalos a número con las funciones de `functions.dkh` si los necesita así. - Antes de redirigir a una URL que viene en un parámetro (`?volver=…`), compruebe con `url.host` que es su dominio: así nadie usa su sitio para mandar usuarios a sitios falsos.