Capturas: simples, de posición, anidadas y hacia atrás

Buscar sirve de poco si no puedes quedarte con lo encontrado. Las capturas son el mecanismo que convierte el motor de patrones de un detector en un extractor: marcas con paréntesis las partes del patrón que te interesan y las funciones de búsqueda te las devuelven como valores independientes. Lua ofrece cuatro variedades —la simple, la de posición, la anidada y la referencia hacia atrás— y las cuatro caben en el mismo par de paréntesis. La última es, además, la que empuja al humilde motor de patrones fuera de la clase de los lenguajes regulares y le da un poder de reconocimiento que sorprende a quien lo daba por un juguete.

Capturas simples

Un fragmento del patrón rodeado de paréntesis se captura, y las funciones de búsqueda devuelven una copia del texto que encajó en él. Si el patrón no lleva ningún paréntesis, lo que se devuelve es la coincidencia entera; en cuanto aparece uno, la coincidencia entera deja de devolverse y solo se obtienen las capturas, en el orden en que se abrieron.

local linea = "usuario = ada, edad = 36"

print(linea:match("%a+ = %a+"))              --> usuario = ada   (sin capturas)
print(linea:match("(%a+) = (%a+)"))          --> usuario   ada
print(linea:match("edad = (%d+)"))           --> 36
print(("clave: valor"):match("^(%w+):%s*(.+)$"))  --> clave   valor

Si necesitas a la vez el todo y las partes, envuelve el patrón completo en un paréntesis adicional: no existe una variable implícita para la coincidencia entera dentro del patrón, aunque sí la hay en el reemplazo de una sustitución. Y hay un límite duro que casi nunca se alcanza pero conviene conocer: un patrón admite como máximo treinta y dos capturas, y superarlo produce el error de demasiadas capturas.

Las capturas viajan también por las otras funciones de búsqueda, y en cada una ocupan un lugar distinto del retorno. En la localización se añaden detrás de las dos posiciones; en la iteración se entregan como valores del bucle; en la sustitución alimentan el reemplazo. Ese detalle del orden es la causa de un desliz clásico: recoger la primera captura de una localización en la primera variable y encontrarse con un número.

local ini, fin, clave, valor = ("ancho=120"):find("(%w+)=(%w+)")
print(ini, fin, clave, valor)        --> 1   9   ancho   120

-- el desliz: aqui clave recibe la posicion inicial, no el texto
local clave_mal = ("ancho=120"):find("(%w+)=")
print(clave_mal)                     --> 1

Conviene además conocer los tres errores que produce el motor al analizar capturas mal escritas, porque sus mensajes son escuetos y se reconocen mejor si se han leído antes: captura sin terminar cuando falta un paréntesis de cierre, índice de captura no válido cuando te refieres a una captura que no existe o que aún no ha cerrado, y demasiadas capturas al superar el límite. Ninguno es un fallo silencioso, y eso los convierte en los más benignos de este capítulo.

La captura de posición

Un par de paréntesis vacíos no captura texto: captura la posición del sujeto en la que el motor se encontraba al llegar a ese punto del patrón, y la devuelve como número entero. Es la herramienta correcta cuando quieres saber dónde está algo sin pagar la construcción de subcadenas, y también la forma canónica de tokenizar registrando desplazamientos.

local s = "alfa beta gamma"

print(s:match("()beta()"))                 --> 6   10
for pos, palabra in s:gmatch("()(%a+)") do
  print(pos, palabra)                      --> 1 alfa / 6 beta / 11 gamma
end

-- medir sangria sin cortar la cadena
local function sangria(l) return l:match("^%s*()") - 1 end
print(sangria("      texto"))              --> 6

Que el valor devuelto sea un número y no una cadena tiene consecuencias que sorprenden más adelante: en una sustitución con función, ese argumento llega como número; en una sustitución con tabla, se usa como clave numérica; y si intentas referirte a una captura de posición como referencia hacia atrás dentro del patrón, el motor rechaza el índice porque no hay texto que comparar.

Anidadas y su numeración

Los paréntesis pueden contener otros paréntesis, y la regla de numeración es la única posible si se quiere que sea estable: las capturas se numeran por el orden en que se abren, no por el orden en que se cierran ni por el nivel de anidamiento. Una captura exterior siempre precede a las que contiene.

flowchart TB
A[Patron con capturas anidadas] --> B[Captura uno abre primero y abarca la fecha entera]
B --> C[Captura dos es el ano]
B --> D[Captura tres es el mes]
B --> E[Captura cuatro es el dia]
C --> F[Orden de retorno segun apertura de parentesis]
D --> F
E --> F

local fecha = "registro 2026-08-04 fin"
local todo, ano, mes, dia = fecha:match("((%d%d%d%d)-(%d%d)-(%d%d))")
print(todo, ano, mes, dia)        --> 2026-08-04   2026   08   04

-- mezcla de posicion y texto
local p1, clave, p2, valor = ("ancho=120"):match("()(%w+)=()(%d+)")
print(p1, clave, p2, valor)       --> 1   ancho   7   120

Hay una consecuencia de esa regla que conviene tener presente al modificar patrones ajenos: añadir un paréntesis renumera todo lo que viene detrás. Si el patrón alimenta una sustitución cuyo reemplazo se refiere a las capturas por número, envolver un fragmento para capturarlo también rompe silenciosamente esas referencias. Es el argumento más fuerte a favor de mantener los patrones cortos y de asignar sus resultados a variables con nombre en la misma línea en que se obtienen.

El anidamiento no es puramente cosmético: permite obtener una vista jerárquica de una coincidencia en una sola pasada. Como el lenguaje carece de grupos que se cuantifiquen, el anidamiento es también el único mecanismo de estructura que ofrece, y por eso conviene usarlo con moderación. Un patrón con cinco niveles de paréntesis y ocho capturas es ilegible, no verificable y casi siempre la señal de que el problema pedía dos búsquedas encadenadas o un analizador de verdad.

Referencias hacia atrás

Dentro del patrón, un porcentaje seguido de un dígito del uno al nueve no designa una clase ni un carácter literal: designa una copia exacta del texto que capturó esa captura. El motor no vuelve a interpretar el patrón, compara byte a byte con lo ya capturado. Es lo que permite exigir que dos fragmentos distantes de la cadena sean iguales.

-- el delimitador de cierre debe ser el mismo que el de apertura
local s = [[dijo 'hola' y luego "adios"]]
for comilla, texto in s:gmatch("(['\"])(.-)%1") do
  print(comilla, texto)            --> '  hola   /   "  adios
end

-- palabras duplicadas consecutivas
print(("el el gato"):match("(%a+)%s+%1"))     --> el

-- delimitadores largos al estilo de las cadenas largas de Lua
print(("[==[cuerpo]==]"):match("%[(=*)%[(.-)%]%1%]"))  --> ==   cuerpo