Artículo técnico

Buscar y reemplazar texto en un PDF existente con Delphi

El cuadro de búsqueda de un visor resalta "Acme Corp" en la página 2 de una factura, y sin embargo una búsqueda de bytes de esos mismos nueve caracteres en el stream de página descomprimido vuelve vacía. Solo para la primera palabra, el stream puede contener algo como <0024004600500048> Tj: códigos de glifo de dos bytes en una fuente subconjunto incrustada, con el hueco entre las dos palabras producido por un offset de posicionamiento y no por un carácter de espacio. Reemplazar ese nombre significa decodificar esos códigos a Unicode, hacer la coincidencia ahí, volver a los bytes exactos que produjeron el acierto y escribir códigos nuevos que la misma fuente entienda. Cuando el subconjunto nunca contuvo un glifo que el texto nuevo necesita, no hay códigos que escribir

Las solicitudes detrás de esto son mantenimiento ordinario de documentos. Una empresa cambia de nombre y tres mil facturas archivadas todavía llevan el nombre viejo. Una plantilla de contrato salió con la fecha de vencimiento del año pasado. Un número de parte retirado tiene que convertirse en su sucesor en cada hoja de datos. En un procesador de textos cada una de estas toma treinta segundos; en un PDF cada una choca con la forma en que las páginas realmente se almacenan

Qué guarda una página PDF en lugar de texto

Una página PDF contiene glifos posicionados, no texto editable. Bajo ISO 32000-1 §9.4, el content stream maneja operadores de mostrado de texto como Tj y TJ, que pintan secuencias de códigos de carácter en posiciones fijadas por la matriz de texto. Esos códigos son índices en la codificación que declare la fuente actual. El camino de vuelta a caracteres legibles puede pasar por un CMap /ToUnicode (§9.10.3), un /Encoding con un arreglo /Differences, o una cadena de mapeo CID para fuentes Type0. No hay objeto de párrafo ni flujo de texto, y nada obliga a un productor a guardar una palabra visible como un solo string: [(Ac) -12 (me)] TJ es una forma perfectamente ordinaria de aplicar kerning a una palabra

El reemplazo agrega un segundo requisito encima de la decodificación. Un extractor de texto puede descartar las posiciones de bytes una vez que tiene el Unicode. Un reemplazador las necesita, porque debe saber qué bytes de qué operando de string produjeron cada glifo, para reescribir exactamente ese rango y dejar todo lo demás en paz. Por eso un simple StringReplace sobre los bytes del stream es la herramienta equivocada incluso en archivos que casualmente usan codificación WinAnsi. No tiene idea de qué ( pertenece a un string ni de qué Tf selecciona la fuente que da a esos bytes su significado

Buscar en la secuencia de glifos decodificada

HotPDF Delphi Component busca en un documento cargado con SearchLoadedPageText y SearchLoadedDocumentText, que comparan el término buscado contra la secuencia de glifos Unicode decodificada de cada página, nunca contra los bytes crudos del stream. Un acierto es por lo tanto un acierto sin importar cómo lo haya codificado la fuente. Al decodificar, cada glifo conserva un registro del operando de string, el ítem del arreglo TJ y el offset de byte de donde vino, que es en lo que se apoya después el paso de reemplazo. El mismo intérprete de glifos impulsa la API cubierta en extraer texto de un PDF cargado en Delphi; la búsqueda simplemente conserva las posiciones de origen que la extracción descarta

Cómo la búsqueda de HotPDF en Delphi rastrea los tramos de bytes StartOfs y EndOfs mientras decodifica glifos a Unicode para resultados THPDFTextMatch
La búsqueda de HotPDF trabaja sobre la secuencia de glifos decodificada a la vez que conserva la procedencia de bytes que el reemplazo necesita

Cada acierto vuelve como un registro THPDFTextMatch: PageIndex, el rango inclusivo de glifos en GlyphStart y GlyphEnd, el origen en espacio de usuario en X e Y, el Width del acierto, el TokenIndex y el ItemIndex de origen, y el Text coincidente. PageIndex es base cero. Un término que no aparece da un arreglo vacío y un resultado True, así que el código que llama no necesita un caso especial para "no se encontró nada"

var
  Pdf: THotPDF;
  Matches: THPDFTextMatchArray;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('invoices-2025.pdf') > 0 then
      if Pdf.SearchLoadedDocumentText('Acme Corp', False, Matches) then
        for I := 0 to High(Matches) do
          WriteLn(Format('page %d at (%.1f, %.1f), width %.1f: "%s"',
            [Matches[I].PageIndex + 1, Matches[I].X, Matches[I].Y,
             Matches[I].Width, Matches[I].Text]));
  finally
    Pdf.Free;
  end;
end;

Que ese bucle imprima algo depende, antes que nada, de los espacios. El texto de búsqueda se construye a partir de los glifos que la página realmente pinta, un carácter por glifo, y un offset de TJ que separa visualmente dos palabras es un número en un arreglo y no un glifo. Un productor que fija los huecos entre palabras con offsets en lugar de un carácter de espacio produce "AcmeCorp" en la secuencia de glifos, y el término "Acme Corp" no va a coincidir. Cuando una frase visible se niega a coincidir, busque primero su palabra más larga y mire el Text de lo que vuelve

Las mayúsculas y minúsculas son lo otro que revisar. Con CaseSensitive en False, las builds de Delphi XE2 en adelante comparan caracteres a través del mapeo simple a minúsculas de Unicode, que es independiente del locale, así que É coincide con é y las mayúsculas griegas o cirílicas coinciden con sus formas en minúscula. Las builds con compiladores más antiguos pliegan solo A–Z. El mapeo es de un carácter a un carácter, lo que mantiene cada posición del término alineada con exactamente un glifo; la consecuencia es que ß no coincide con SS. Para flujos de interfaz de palabra completa, SearchLoadedPageTextWholeWord descarta los aciertos que quedan dentro de una palabra más larga, y GetLoadedSearchHitRect convierte una coincidencia en un solo rectángulo para dibujar un resaltado

Tanto la búsqueda como el reemplazo trabajan sobre los propios streams /Contents de la página. El texto pintado dentro de un Form XObject, que es donde muchas herramientas ponen los encabezados y pies estampados, vive en un stream aparte que la página invoca con Do, y queda fuera de ambas operaciones

Reescribir los bytes coincidentes con ReplaceLoadedDocumentText

ReplaceLoadedPageText y ReplaceLoadedDocumentText reescriben cada aparición de un término ejecutando la decodificación de la fuente hacia atrás. Cada carácter de reemplazo se busca a través de la misma cadena que usa el decodificador, en reversa: entradas bfchar y bfrange de /ToUnicode, mapeos CID para fuentes Type0, mapeos de identidad y las tablas predefinidas WinAnsi y MacRoman. Los códigos de carácter resultantes se escriben de vuelta como un string literal, o como un string hexadecimal cuando algún byte cae fuera del ASCII imprimible, siguiendo las mismas reglas de escape que lee el parser de content streams

Solo cambian los bytes cubiertos por la coincidencia. Los bytes no coincidentes del mismo operando, el espacio en blanco entre tokens, los comentarios y cada operador circundante pasan intactos. Reemplazar bca dentro de abcabc produce a + reemplazo + bc. El reemplazo puede ser más corto o más largo que el término, y cada stream del arreglo /Contents de una página se procesa por separado para que la página siga bien formada. Cuando una coincidencia se extiende por varios operandos de string, como Hello guardado como [(He) -20 (llo)] TJ, el reemplazo se escribe en el operando donde empieza la coincidencia y los bytes coincidentes se quitan de los operandos siguientes

Cómo el reemplazo de HotPDF en Delphi invierte la cadena de decodificación con HPDFEncodeUnicode y empalma solo el rango de bytes coincidente del operando de cadena
La codificación inversa reconstruye los char codes de la fuente, y luego solo el rango de bytes coincidente dentro del operando se reescribe
var
  Pdf: THotPDF;
  Rewrites: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile('contract-draft.pdf') > 0 then
    begin
      if Pdf.ReplaceLoadedDocumentText('2025-12-31', '2026-12-31',
        True, Rewrites) then
        WriteLn(Format('%d operand rewrites', [Rewrites]));
      Pdf.SaveLoadedDocument('contract-final.pdf');
    end;
  finally
    Pdf.Free;
  end;
end;

La página no se vuelve a componer. PDF no tiene reflujo, así que un reemplazo más ancho que el original simplemente ocupa más espacio horizontal y puede chocar con lo que esté pintado a su derecha; la posición del siguiente glifo la fijó el productor y no se mueve. Fechas, cadenas de versión, números de parte y correcciones ortográficas de longitud similar son el trabajo para el que está hecho este método. Reformular un párrafo necesitaría recomponer todo lo que viene después, así que ese cambio pertenece al documento de origen

¿Por qué un subconjunto de fuente no puede tomar caracteres que nunca contuvo?

Un carácter de reemplazo que el subconjunto incrustado nunca incluyó no tiene código de carácter al cual revertir. Cuando un productor hace subconjunto de una fuente, su CMap /ToUnicode y su codificación cubren solo los glifos que el documento original usó, y los contornos de glifo de todo lo demás simplemente no están en el archivo. Si el documento nunca imprimió una E mayúscula en esa fuente, ninguna secuencia de bytes selecciona una. Esa limitación está en el archivo, no en la herramienta que hace el reemplazo

ReplaceLoadedDocumentText trata un reemplazo no codificable de manera conservadora: si un solo carácter no se puede recodificar, esa aparición se omite completa. No hay excepción ni string a medio reemplazar, y el texto original sigue legible. En el ejemplo de la fecha de arriba, el dígito 6 tiene que existir en algún lugar de esa misma fuente para que la reescritura tenga éxito. Suponga que la fuente solo imprimió alguna vez "2025" y unos cuantos totales de pedido sin ningún 6: las fechas se quedan como están

Por qué HotPDF omite un reemplazo de texto PDF completo en Delphi cuando el subconjunto de la fuente incrustada carece de un carácter necesario, verificado vía ReplaceCount
Los caracteres de reemplazo que el subconjunto de la fuente no puede recodificar omiten la ocurrencia completa, así que un faltante en ReplaceCount es una señal real

ReplaceCount reporta reescrituras de operandos, y una coincidencia repartida en varios operandos puede sumar más de una reescritura. Un conteo menor que el número de aciertos sigue significando que algo se omitió, pero la respuesta exacta viene de buscar otra vez después del reemplazo. Lo que encuentre la segunda búsqueda es lo que quedó atrás, con página y posición incluidas

procedure ReplaceAndAudit(Pdf: THotPDF; const OldText, NewText: UnicodeString);
var
  Before, After: THPDFTextMatchArray;
  Rewrites, I: Integer;
begin
  // Volver a buscar solo funciona cuando NewText no contiene a su vez OldText
  Pdf.SearchLoadedDocumentText(OldText, True, Before);
  Pdf.ReplaceLoadedDocumentText(OldText, NewText, True, Rewrites);
  Pdf.SearchLoadedDocumentText(OldText, True, After);
  WriteLn(Format('%d found, %d operand rewrites, %d left',
    [Length(Before), Rewrites, Length(After)]));
  for I := 0 to High(After) do
    WriteLn(Format('  left on page %d at (%.1f, %.1f)',
      [After[I].PageIndex + 1, After[I].X, After[I].Y]));
end;

Cuando el subconjunto se queda corto: previsualizar y aplicar con una fuente nueva

Para las apariciones que el método a nivel de bytes no puede codificar, PreviewLoadedPageTextReplacement y ApplyLoadedPageTextReplacement toman otra ruta: quitan los glifos coincidentes y dibujan el reemplazo en su lugar con una fuente que usted elige, al tamaño original y sobre la línea base original. El THPDFLoadedTextReplacementOptions por defecto usa Arial al tamaño de fuente del texto coincidente, dimensiona la caja al ancho del texto coincidente y mantiene Atomic activo. Una sola coincidencia rechazada en la página revierte entonces las demás. La previsualización devuelve un plan con un resultado por coincidencia, cada uno con un Status y, cuando se rechaza, un Reason

var
  Opts: THPDFLoadedTextReplacementOptions;
  Plan, Applied: THPDFLoadedTextReplacementPlan;
  I: Integer;
begin
  // Pdf es un THotPDF cargado; PageIndex es una página base cero que la auditoría marcó
  Opts := THPDFLoadedTextReplacementOptions.Default;
  Opts.Appearance.FontName := 'Arial';
  Opts.Appearance.OverflowPolicy := ltopShrinkToFit;
  Opts.Appearance.MinFontSize := 6;
  if not Pdf.PreviewLoadedPageTextReplacement(PageIndex, 'Acme Corp',
    'Apex Corporation', True, Opts, Plan) then
    for I := 0 to High(Plan.Results) do
      if Plan.Results[I].Status = ltrsRejected then
        WriteLn(Format('match %d at (%.1f, %.1f): %s',
          [I, Plan.Results[I].X, Plan.Results[I].Y, Plan.Results[I].Reason]));
  if (Plan.RejectedCount = 0) and (Plan.ReadyCount > 0) then
  begin
    Pdf.ApplyLoadedPageTextReplacement(Plan, Applied);
    WriteLn(Format('%d of %d matches applied',
      [Applied.AppliedCount, Applied.MatchedCount]));
  end;
end;

Vale la pena imprimir los motivos de rechazo porque se corresponden directamente con la geometría de la página. Una coincidencia que cruza de una línea de texto a la siguiente se rechaza, y también el texto vertical. Con la política de desborde por defecto ltopReject, un reemplazo que no cabe en el ancho coincidente también se rechaza. ltopShrinkToFit en cambio baja el tamaño por pasos hacia MinFontSize, y por eso el ejemplo la fija para un reemplazo cinco caracteres más largo que el término. Un reemplazo que contiene caracteres que la fuente elegida no puede mostrar se rechaza también

El plan lleva una huella del contenido y las fuentes de la página. Si algo cambia la página entre la previsualización y la aplicación, ApplyLoadedPageTextReplacement lanza EInvalidOpException en lugar de escribir en una página que la previsualización nunca vio. Las páginas con pares q/Q o BT/ET desbalanceados, y los documentos que contienen campos de firma, lanzan EArgumentException; los documentos firmados piden actualizaciones incrementales para que la revisión firmada quede intacta

El reemplazo a nivel de bytes va primero, y la ruta de cambio de fuente corre solo en las páginas donde la auditoría todavía encuentra el texto viejo. La reescritura a nivel de bytes conserva la fuente original, sus métricas y su kerning, así que el texto editado hace juego con sus vecinos en la línea. La ruta de previsualización dibuja con otra tipografía, y en una línea compuesta en una fuente condensada o con serifas un lector atento va a notar el cambio. Cuando el objetivo es hacer desaparecer texto y no reformularlo, la eliminación real de contenido es la mejor herramienta; redactar y reestructurar PDFs cargados en Delphi cubre esa ruta

Qué cambia en el archivo guardado

Un content stream editado por ReplaceLoadedPageText se guarda sin comprimir. El stream se decodifica para editarlo, y cuando los bytes reconstruidos se escriben de vuelta sus entradas /Filter y /DecodeParms se eliminan y /Length se actualiza. El PDF es válido y se renderiza con normalidad; el costo es un archivo más grande por cada stream editado. Un trabajo por lotes sobre miles de facturas debería presupuestar ese crecimiento o correr después una pasada de compresión

La ruta de previsualizar y aplicar cambia un poco más. Una página aplicada recibe un solo content stream nuevo sin comprimir en lugar de su /Contents original, más su propia copia del diccionario de recursos con la fuente de reemplazo agregada. Todo lo demás en el documento se deja en paz: los streams sin tocar conservan su compresión, las fuentes e imágenes existentes no se reescriben, y las páginas sin aciertos nunca se abren para escritura. Cómo aterrizan los objetos reescritos en la estructura de referencias cruzadas al guardar se cubre en object streams y actualizaciones incrementales en HotPDF

La búsqueda, el reemplazo a nivel de bytes, el reemplazo con previsualizar y aplicar, la extracción y la redacción corren todos sobre el mismo intérprete de content streams, desde Delphi 5 hasta el RAD Studio actual, sin dependencias externas. Las referencias de métodos, las opciones de reemplazo y una build de prueba están en la página de producto del HotPDF Delphi Component