io: el modelo de ficheros

La biblioteca io es la primera puerta real al mundo exterior y, como todo lo que Lua toma prestado del sistema anfitrión, es una capa finísima sobre la biblioteca estándar de C. No hay abstracción de rutas, ni de directorios, ni de permisos, ni de codificaciones: hay un objeto manejador de fichero, un puñado de métodos sobre él y dos variables globales ocultas que deciden a dónde va lo que escribes cuando no dices a dónde. Entender io es sobre todo entender esas dos variables globales, la aritmética del búfer que hay detrás de cada escritura y por qué el iterador io.lines es la única función de la biblioteca que se ocupa de cerrar por ti.

El modelo: manejadores y ficheros por defecto

Un manejador de fichero en Lua es un dato de usuario con metatabla propia. Esa metatabla le da un __index con los métodos, un __tostring que produce una descripción legible, un __gc que lo cierra si el recolector lo alcanza abierto y, desde Lua 5.4, un __close que permite atarlo a un ámbito léxico. La función io.type interroga ese objeto y devuelve una de tres respuestas: fichero abierto, fichero cerrado o nada en absoluto si el valor no es un manejador.

Junto a los manejadores explícitos existen dos ranuras globales, el fichero de entrada por defecto y el de salida por defecto, inicializadas a la entrada y la salida estándar del proceso. Las funciones sueltas de la biblioteca operan sobre ellas: io.read lee de la entrada por defecto y io.write escribe en la salida por defecto. Las mismas funciones invocadas con un argumento de fichero cambian la ranura y devuelven el manejador nuevo.

print(io.type(io.stdout))          --> file
print(io.type(42))                 --> nil

local anterior = io.output()       -- leer la ranura sin tocarla
io.output("salida.txt")            -- redirigir toda escritura posterior
io.write("esto va al fichero\n")
io.output(anterior)                -- restaurar

Conviene recordar que print no escribe en la salida por defecto de io, sino directamente en la salida estándar del proceso. Redirigir con io.output no captura lo que imprima print, y esa discrepancia sorprende siempre la primera vez.

Abrir, cerrar y los modos

io.open recibe una ruta y una cadena de modo, y devuelve el manejador o bien un trío formado por nada, un mensaje de error y un código numérico del sistema. No lanza error: el fallo es un valor de retorno, y el idioma canónico consiste en envolverla en assert, que convierte ese trío en excepción con el mensaje intacto.

local f = assert(io.open("datos.bin", "rb"))
-- ... trabajo ...
f:close()

-- Lua 5.4: cierre atado al ambito lexico, incluso si hay error
do
  local g <close> = assert(io.open("datos.bin", "rb"))
  local cabecera = g:read(8)
end   -- aqui g ya esta cerrado, pase lo que pase dentro del bloque

Los modos son los de C, sin añadidos. r abre para lectura y falla si el fichero no existe. w crea o trunca. a abre para añadir y sitúa cada escritura al final sin importar dónde esté el puntero. Los tres admiten el sufijo de actualización, que habilita lectura y escritura simultáneas: r+ mantiene el contenido, w+ lo trunca, a+ permite leer en cualquier posición pero escribe siempre al final. El sufijo b solicita modo binario y solo tiene efecto en sistemas que traducen finales de línea; en sistemas de tipo Unix es inocuo, y ponerlo siempre en ficheros no textuales es una disciplina barata que evita fallos al portar.

Leer: formatos, líneas y bloques

Los formatos de lectura son cuatro y uno numérico. La letra l devuelve una línea sin su salto final y es el valor por defecto. La letra L devuelve la línea con el salto incluido, lo que permite reconstruir el fichero exactamente. La letra n intenta leer un número respetando la sintaxis numérica de Lua y devuelve nada si no lo consigue. La letra a devuelve todo lo que quede, y la cadena vacía si ya no queda nada. Un número entero pide esa cantidad exacta de bytes y devuelve menos si el fichero se acaba, o nada si ya estaba agotado.

local f = assert(io.open("registro.txt", "r"))

local todo   = f:read("a")     -- el fichero entero en una cadena
f:seek("set", 0)               -- volver al principio
local primera = f:read("l")    -- una linea sin el salto
local dos, tres = f:read("l", "l")   -- varios formatos en una llamada

print(f:seek("end"))           -- devuelve el tamano en bytes
f:close()

Entre las tres estrategias de lectura hay un compromiso claro. Leer el fichero entero con a es lo más rápido en llamadas al sistema y lo peor en memoria: un fichero de dos gigabytes se convierte en una cadena de dos gigabytes. Leer línea a línea es lo más cómodo y lo más costoso por unidad de datos, porque cada línea es una cadena nueva que el recolector tendrá que atender. Leer bloques de tamaño fijo es el punto medio de todo procesamiento serio de ficheros grandes.

local f = assert(io.open("enorme.log", "rb"))
local total = 0
while true do
  local bloque = f:read(64 * 1024)
  if not bloque then break end
  total = total + #bloque
end
f:close()
print("bytes leidos:", total)

flowchart TD
A[Necesito leer un fichero] --> B[Cabe comodamente en memoria]
B -->|si| C[Leer todo con el formato a]
B -->|no| D[El formato es de lineas]
D -->|si| E[Iterar con io.lines]
D -->|no| F[Leer bloques de tamano fijo]
E --> G[Cierre automatico al agotar]
F --> H[Cierre manual o variable de ambito]
C --> H

El búfer y io.lines como iterador

Toda escritura pasa por un búfer intermedio de C antes de llegar al disco. El método setvbuf fija su política: sin búfer, por líneas o completo, con un tamaño opcional. La salida estándar suele estar en modo de líneas cuando apunta a un terminal y en modo completo cuando se redirige a un fichero, y ese cambio silencioso explica el desconcierto clásico de ver los mensajes en orden en pantalla y desordenados en el fichero de registro.

io.stdout:setvbuf("line")        -- diagnostico legible aunque se redirija
local f = assert(io.open("salida.dat", "wb"))
f:setvbuf("full", 1024 * 1024)   -- una sola escritura por megabyte

Cerrar un fichero vacía su búfer; abandonar el proceso con os.exit sin argumento de cierre puede no hacerlo. Ese es el motivo por el que un programa que aborta deja a veces un fichero de salida truncado justo antes de la información interesante.

io.lines merece un tratamiento aparte porque es la única función de la biblioteca con una política de recursos propia. Invocada con un nombre de fichero, lo abre, devuelve un iterador y lo cierra sola cuando la iteración se agota. Invocada sin argumentos, lee de la entrada por defecto. El método homónimo sobre un manejador, en cambio, no cierra nada: el manejador es tuyo y sigue siéndolo.

for linea in io.lines("config.txt") do        -- se cierra solo al terminar
  if linea:match("^#") then goto continue end
  print(linea)
  ::continue::
end

local f = assert(io.open("config.txt"))
for linea in f:lines("L") do print(#linea) end  -- f sigue abierto
f:close()                                       -- cierre a tu cargo