# csv.dkh: leer y escribir archivos CSV `csv.dkh` convierte archivos y textos CSV en listas de registros de DKL, y listas de registros en CSV. Usa la biblioteca de terceros CsvHelper (Devkron.Ext.Csv.dll), así que **se instala aparte** del motor: vea [Bibliotecas de terceros](/es/devkron/2.0/bibliotecas/terceros/). ## Cuándo usarla - Importar catálogos, existencias o listas de precios que el usuario exporta de Excel o de otro sistema. - Recibir un CSV en una petición web (subido o pegado en un formulario) y procesarlo sin guardarlo. - Exportar un reporte para que el usuario lo abra en Excel. Si lo que necesita es un archivo de Excel con formato de celdas (números, fechas, varias hojas), use [xlsx.dkh](/es/devkron/2.0/bibliotecas/terceros/office.md). ## Instalación Copie junto a `dkl` (o a la carpeta del servidor FastCGI) `csv.dkh`, `Devkron.Ext.Csv.dll` y `CsvHelper.dll`, y agregue el encabezado a su programa: ```dkl #include "csv.dkh" ``` ## Cómo lee los datos - **Primera fila = nombres de los campos.** Cada fila siguiente es un registro. - **Separador detectado.** `csv.read` y `csv.from_text` cuentan `,`, `;` y tabuladores fuera de comillas en la primera línea y eligen el que más aparece (con empate gana la coma). Si la primera línea es `sep=X` (convención de Excel), se usa `X` y esa línea se descarta. - **Comillas según RFC 4180**: un campo entre comillas puede contener el separador, saltos de línea y comillas dobladas (`""`). - **Todo llega como cadena**, salvo las columnas que usted declare numéricas en `columnas_numericas` (nombres separados por coma, sin distinguir mayúsculas). Esas se convierten a número con punto decimal; en archivos con `;`, un valor con coma y sin punto se toma con coma decimal (`120,50` → `120.50`). Un valor vacío (`;;`) en una columna numérica llega como `""`, un campo que falta porque la fila viene incompleta llega como `0`, y un valor que no es número se queda como texto. - **Codificación**: UTF-8 por omisión; si el archivo trae marca BOM (UTF-8 o UTF-16) se respeta. - **Encabezados repetidos o vacíos**: un nombre repetido recibe `_2`, `_3`…; uno vacío se llama `columna_N` (N es la posición, desde 1). - **Filas incompletas**: los campos que faltan llegan como nulo. Las líneas en blanco se ignoran. - Un archivo con solo encabezados devuelve una lista vacía. ## Funciones | Función | Devuelve | Descripción | |---|---|---| | `csv.read(archivo, columnas_numericas)` | lista | Lee un archivo con separador detectado | | `csv.read_sep(archivo, columnas_numericas, separador)` | lista | Lee un archivo con el separador indicado | | `csv.from_text(texto, columnas_numericas)` | lista | Lee un texto CSV con separador detectado | | `csv.from_text_sep(texto, columnas_numericas, separador)` | lista | Lee un texto CSV con el separador indicado | | `csv.detect(texto)` | cadena | Separador que usaría `csv.read`: `","`, `";"` o tabulador | | `csv.write(archivo, lista)` | — | Escribe un archivo con coma | | `csv.write_sep(archivo, lista, separador)` | — | Escribe un archivo con el separador indicado | | `csv.to_text(lista)` | cadena | CSV con coma, sin escribir archivo | | `csv.to_text_sep(lista, separador)` | cadena | CSV con el separador indicado, sin escribir archivo | ### Parámetros comunes - `archivo`: ruta del archivo (relativa a la carpeta de trabajo o absoluta). - `columnas_numericas`: cadena con los nombres de las columnas que deben convertirse a número, separados por coma (`"id,precio"`). Use `""` para recibir todo como texto. - `separador`: un solo carácter. Para tabulador puede escribir `"\\t"` (barra y `t` literales), `"tab"` o `"tabulador"`. No se admiten comillas ni saltos de línea. - `lista`: lista de registros. Las columnas del CSV son la **unión de los campos de todos los registros** en el orden en que aparecen; un registro al que le falta un campo deja la celda vacía. ### Escritura - `csv.write` y `csv.write_sep` escriben en **UTF-8 con BOM** (Excel lo abre con acentos correctos) y fin de línea CRLF; si el archivo existe lo sobrescriben. - Los números se escriben con punto decimal, sin separador de miles. - Los valores con separador, comillas o saltos de línea se encierran en comillas automáticamente. - `csv.to_text` y `csv.to_text_sep` devuelven lo mismo como cadena (sin BOM), útil para responder una descarga en un servicio web. ### Errores Todos se atrapan con `exception { }` y `last_error()`; el mensaje empieza con `csv:`. | Mensaje | Causa | |---|---| | `csv: no existe el archivo '…'.` | La ruta no existe (revise la carpeta de trabajo) | | `csv: falta la ruta del archivo.` | `archivo` vacío | | `csv: el separador no puede estar vacío.` | `separador` es `""` | | `csv: el separador debe ser un solo carácter (se recibió '…').` | Pasó más de un carácter | | `csv: el separador no puede ser comillas ni salto de línea.` | Separador `"` o salto de línea | | `csv: no se pudo leer el texto en la fila N: …` | CSV mal formado (por ejemplo, comillas sin cerrar) | | `csv: se esperaba una lista de registros.` / `csv: cada elemento de la lista debe ser un registro.` | Al escribir, el argumento no es una lista de registros | ## Ejemplo: importar un CSV exportado de Excel en español Excel con configuración regional de México o España exporta con `;` y coma decimal. `csv.from_text` lo detecta solo: ```dkl #include "dkli.dkh" #! program "importar csv" { #include "functions.dkh" #include "serialize.dkh" #include "csv.dkh" // Así llega el texto de un archivo exportado de Excel en español (separador ;) texto = "clave;descripcion;existencia;costo\r\nA-01;Tornillo 1/4;150;0,85\r\nA-02;\"Taquete; plástico\";80;1,20\r\nA-03;Rondana;;0,10\r\n" do print("Separador detectado: [" + csv.detect(texto) + "]") ref filas = csv.from_text(texto, "existencia,costo") do print(to.json(filas)) valor = 0 for i=0; i