Artigo Técnico

Índice de fonte BIFF8 pula o 4: runs de rich text no HotXLS

Uma pasta de trabalho BIFF8 com oito registros FONT contém um registro XF cujo campo de fonte lê 8. Contando do zero, é uma posição além do fim da tabela, mas o Excel renderiza a célula na oitava fonte sem reclamar. O valor é legal: a [MS-XLS] §2.5.129 numera os quatro primeiros registros FONT de 0 a 3, pula o 4 inteiramente e numera todo registro posterior pela posição one-based dele

Então o quinto registro FONT é ifnt 5, e um arquivo bem-formado nunca precisa de um valor maior que a contagem de registros FONT dele. A regra parece um erro de digitação na especificação, que é exatamente por que as pessoas a "corrigem", e como formatos de célula, rich text de shared string e runs de comentário carregam todos o mesmo tipo FontIndex, uma leitura que difere entre caminhos liga algumas fontes certo e outras com um registro de defasagem. Ela é da mesma família das esquisitices de comprimento e codificação em decodificar cch e fHigh do XLUnicodeString BIFF8 — o arquivo está bom, a leitura dele é que não está

O que a [MS-XLS] §2.5.129 diz e como conferir num arquivo real

A [MS-XLS] §2.5.129 define FontIndex como uma posição de registro com um buraco. Valores abaixo de 4 são zero-based, valores acima de 4 são one-based, e o valor 4 NÃO DEVE ser usado. Registros XF apontam para fontes com ele, as entradas FormatRun de uma shared string rica o usam, e os runs de formatação TXO descritos na §2.5.272 também

Você não precisa acreditar na especificação por fé. Despeje um .xls que o próprio Excel salvou com qualquer visualizador de registros BIFF, conte os registros FONT (tipo de registro $0031) e depois varra o campo de fonte no começo de cada registro XF ($00E0). O maior valor fica dentro da contagem de registros e o número 4 não aparece na lista. Se você achar um 4, ou um valor acima da contagem de FONT, o arquivo foi escrito por outra coisa que não o Excel e a numeração de fontes dele merece um olhar mais de perto. Para uma ferramenta de diagnóstico ou um teste, o mapeamento inteiro cabe em duas funções

// Helpers seus, não fazem parte de biblioteca alguma
// [MS-XLS] 2.5.129 FontIndex: 0..3 zero-based, > 4 one-based, 4 inválido
function FontIndexToRecordNo(Ifnt: Word): Integer;  // registro FONT com base 1
begin
  if Ifnt < 4 then
    Result := Ifnt + 1
  else if Ifnt > 4 then
    Result := Ifnt
  else
    Result := -1;  // 4 não pode ocorrer
end;

function RecordNoToFontIndex(RecordNo: Integer): Word;
begin
  if RecordNo <= 4 then
    Result := RecordNo - 1
  else
    Result := RecordNo;
end;
Mapeamento de FontIndex pela MS-XLS 2.5.129 em que ifnt 0 a 3 são posições zero-based de registros FONT, ifnt 5 em diante é one-based e o valor 4 nunca ocorre, com a conversão FontIndexToRecordNo
O quinto registro FONT é ifnt 5, então num arquivo com N registros FONT o maior ifnt legal é N e o valor 4 nunca é guardado

Como o HotXLS numera fontes em registros XF e runs de rich text

O HotXLS lê e escreve toda referência de fonte BIFF8 na numeração da especificação. No save a tabela de fontes é compactada para as fontes que algo realmente referencia, e a posição de cada fonte sobrevivente vira um FontIndex: posições 1 a 4 são escritas como 0 a 3, posição 5 em diante sai inalterada. O load desfaz, então qualquer valor de 5 ou mais desce um para achar a fonte na memória e qualquer coisa abaixo de 5 fica onde está. A mesma conversão é aplicada a registros XF, a runs de rich text na tabela de shared strings, a runs de comentário e caixa de texto e às referências de fonte dentro de registros de gráfico clássicos

Para o código da aplicação, a parte visível é TextRuns no TXLSComment e no TXLSTextBox. TextRuns.FontIndex[I] devolve a numeração do arquivo exatamente como lida, com o 4 pulado. Índices de run são one-based, e CharIndex[I] é o offset de caractere em que o run I começa. Expor o número do arquivo em vez de uma posição zero-based de tabela é o padrão melhor aqui: o que a API reporta bate com o que um dump de registros mostra. O custo é uma chamada ao helper acima antes de tratar o valor como posição de tabela

var
  Book: IXLSWorkbook;
  Note: TXLSComment;
  I: Integer;
  Ifnt: Word;
begin
  Book := TXLSWorkbook.Create;
  if Book.Open('review-notes.xls') <> 1 then
    raise Exception.Create('Cannot open review-notes.xls');
  Note := Book.Sheets[1].Range['C2', 'C2'].Comment;
  if Note <> nil then
    for I := 1 to Note.TextRuns.Count do
    begin
      Ifnt := Note.TextRuns.FontIndex[I];   // numeração do arquivo, 4 pulado
      // conferência sua: 4 significa que o arquivo quebra o 2.5.129
      if Ifnt = 4 then
        raise Exception.CreateFmt('Run %d uses invalid ifnt 4', [I]);
      Writeln(Format('run %d at char %d: ifnt %d = FONT record #%d',
        [I, Note.TextRuns.CharIndex[I], Ifnt, FontIndexToRecordNo(Ifnt)]));
    end;
end;

Depois de um save, o número guardado para um run pode diferir do que você leu ou definiu. O save renumera os runs junto com a tabela de fontes compactada, então o número muda e a fonte a que ele aponta não

Por que uma correção zero-based desloca toda fonte personalizada

A armadilha normalmente começa com um relatório de bug plausível. Alguém despeja uma pasta de trabalho com oito registros FONT, vê um XF apontando para a fonte 8, conclui que o escritor produziu um índice fora da faixa e troca escritor e leitor para aritmética zero-based pura. O teste de ida e volta continua passando, porque o escritor remendado e o leitor remendado concordam entre si. O Excel não concorda. Um arquivo escrito desse jeito guarda a primeira fonte personalizada como ifnt 4, que o Excel resolve para a fonte padrão, e toda fonte personalizada posterior aterrissa um registro cedo demais. Ler os arquivos do próprio Excel vai para o outro lado: cada fonte liga um registro tarde

A leitura errada zero-based em que escritor e leitor tratam valores FontIndex one-based como zero-based, guardando a primeira fonte personalizada como o proibido ifnt 4 que o Excel resolve para a fonte padrão e aterrissando cada fonte posterior um registro cedo, enquanto as viagens de ida e volta entre os dois continuam passando
Um escritor e um leitor que dividem a mesma leitura errada passam em todo teste de salvar e reabrir, enquanto toda fonte que o Excel abre aterrissa um registro fora

Dois sinais entregam a leitura errada antes de ela sair. Um é um teste que afirma ifnt < FontCount. Parece uma checagem de limites e na verdade escreve a leitura errada como requisito. Um teste que mapeia cada ifnt escrito de volta a um nome de registro FONT pela fórmula da especificação pega o deslocamento na primeira execução

O outro sinal é código que discorda de si mesmo. Um leitor e escritor BIFF8 completos aplica a regra pular-o-4 em vários lugares: saída de XF, entrada de XF, remapeamento de runs de shared string, runs de comentário, registros de fonte de gráfico. Quando uma mudança move alguns desses para numeração zero-based e deixa o resto quieto, os pontos intocados são a evidência, então desconfie da mudança antes de desconfiar deles. Uma mudança parcial pode se esconder por muito tempo, porque fontes usadas em rich text normalmente também são referenciadas por algum formato de célula

Por que runs de fonte de comentário quebram só no segundo save?

Runs de comentário e caixa de texto podem sobreviver a um save e quebrar no seguinte quando dois hábitos de escritor se encontram. O primeiro hábito é poda assimétrica: manter os primeiros N-1 registros FONT no lugar incondicionalmente e derrubar só o último quando nenhum XF o referencia. O segundo é escrever os runs de formatação TXO ([MS-XLS] §2.4.329) de volta byte a byte sem renumerá-los. Cada hábito passa sozinho num teste de save único. Juntos eles armam uma perda de fonte que espera uma geração

A razão está no que o Excel escreve. Arquivos .xls escritos pelo Excel comumente terminam com uma fonte final sem referência; num sistema em locale chinês é uma DengXian de 9 pt. No primeiro save, a fonte que só um run de comentário usa portanto nunca é a última, e nada se move visivelmente. Esse save derruba a fonte final, porém, e promove a fonte só-de-comentário à última posição. O segundo save encontra uma última fonte sem referência de XF e a descarta. O ifnt do run agora aponta além do fim da tabela, e o Excel cai na fonte padrão. Se a pasta de trabalho ganhou uma fonte no meio do caminho, o run liga no recém-chegado. Notas que são abertas, anotadas e salvas repetidamente, como as de construir um fluxo de revisão com comentários e hyperlinks, são onde isso aparece primeiro

Tabela de fontes ao longo de dois saves em que o registro FONT final sem referência que o Excel escreve é derrubado primeiro, a fonte só-de-comentário vira a última e é então descartada no segundo save quando os runs de formatação TXO são escritos de volta sem contá-los como referências de fonte
O primeiro save parece limpo porque a fonte final leva a perda; a fonte de comentário só desaparece no segundo, então uma checagem de fontes precisa cobrir mais de um save

O HotXLS trata runs de comentário e caixa de texto do mesmo jeito que trata runs de shared string. Antes de a tabela de fontes ser compactada, todo run em toda planilha é convertido do FontIndex com-pulo-do-4 para uma posição de tabela e contado como referência, o que mantém uma fonte que só um run usa. Na saída, os runs passam pela mesma tabela de posição-para-índice-salvo que renumera os registros XF. A entrada de fechamento TxOLastRun não carrega fonte e é escrita como foi lida. Por causa dessa renumeração, comparar valores de FontIndex antes e depois de um save não diz nada; compare os nomes de fonte a que eles resolvem

Cópias, inserções de linha e runs que cruzam pastas de trabalho

No motor clássico, Range.Copy, CopyRange, Sheets.AddCopy e os deslocamentos de célula por trás de Range.Insert e Range.Delete passam todos por um único caminho de cópia de célula, e um deslocamento é só uma cópia seguida de uma limpeza. Uma cópia que carregasse apenas o texto e o autor do comentário transformaria uma nota de dois runs numa nota de uma fonte depois de uma única inserção de linha, sem o usuário tocar no comentário

O HotXLS copia o offset inicial e a fonte de cada run junto com o texto. Dentro de uma pasta de trabalho o FontIndex é reutilizado como está. Entre pastas de trabalho a fonte se move por valor: o número com-pulo-do-4 é convertido para uma posição, a fonte é casada ou acrescentada na tabela de fontes de destino pelos atributos dela, e a posição resultante é convertida de volta para numeração de arquivo. Rich text em shared strings passa pela mesma conversão quando Sheets.AddCopy copia uma planilha para outra pasta de trabalho, então os dois tipos de run não podem se separar. O lado da tabela de fontes segue a mesma abordagem por valor do lado das fórmulas coberto em cópia entre pastas de trabalho e religação de fórmulas

Dois casos de borda valem conhecer quando você escreve testes para isso:

  • Uma colagem no lugar, em que origem e destino resolvem para o mesmo comentário, mantém os runs; nada é limpo antes de ter sido lido
  • Sheets.AddCopy também copia comentários ancorados em células que não têm registro de célula guardado, o que um loop só sobre células guardadas perderia

No motor XLSX, cópias clonam runs de comentário por valor, e a parte de comentários é lida e escrita com rFont, strike, u e vertAlign. O nome da fonte de um run, o tachado, o sublinhado e a configuração de super ou subscrito, portanto, voltam intactos depois de salvar e reabrir

Um teste de regressão que sobrevive à renumeração

Toda armadilha deste artigo passa num teste em memória. A leitura errada zero-based mora num par escritor e leitor casado, a perda de fonte de comentário precisa de dois saves, e runs de comentário perdidos no XLSX só aparecem depois de reabrir. Então o teste tem que reabrir do disco, rodar ao menos duas gerações de save e conferir a estrutura dos runs em vez de números brutos de fonte. Comece de uma pasta de trabalho que o próprio Excel salvou, com um comentário de dois runs no C2 cujo segundo run usa uma fonte que nada mais no arquivo referencia; essa é a fonte que o segundo save derrubaria de outra forma

procedure CheckNoteAcrossTwoSaves(const SrcFile, Out1, Out2: string);
var
  Book: IXLSWorkbook;
  Note: TXLSComment;
  RunCount: Integer;
  SecondRunAt: Word;
begin
  // Chamadas Assert são conferências de teste suas
  Book := TXLSWorkbook.Create;
  Assert(Book.Open(SrcFile) = 1);          // salvo pelo Excel, C2 tem dois runs
  Note := Book.Sheets[1].Range['C2', 'C2'].Comment;
  Assert(Note <> nil);
  RunCount := Note.TextRuns.Count;
  SecondRunAt := Note.TextRuns.CharIndex[2];

  Book.Sheets[1].Range['C2', 'C2'].Copy(Book.Sheets[1].Range['E5', 'E5']);
  Book.Sheets[1].Range['C1', 'C1'].Insert(xlShiftDown);   // C2 vai para C3
  Assert(Book.SaveAs(Out1) = 1);

  Book := TXLSWorkbook.Create;               // geração dois
  Assert(Book.Open(Out1) = 1);
  Assert(Book.SaveAs(Out2) = 1);

  Book := TXLSWorkbook.Create;               // reabre, nunca confie na memória
  Assert(Book.Open(Out2) = 1);
  Note := Book.Sheets[1].Range['C3', 'C3'].Comment;
  Assert((Note <> nil) and (Note.TextRuns.Count = RunCount));
  Assert(Note.TextRuns.CharIndex[2] = SecondRunAt);
  Assert(Note.TextRuns.FontIndex[2] <> 4);
  Note := Book.Sheets[1].Range['E5', 'E5'].Comment;
  Assert((Note <> nil) and (Note.TextRuns.Count = RunCount));
end;

A contagem de runs e os offsets iniciais pegam notas achatadas. A fonte em si precisa de um passo a mais fora do teste: abra o Out2 num visualizador de registros, passe o ifnt de cada run pelo FontIndexToRecordNo e confirme que o registro FONT em que cai carrega o mesmo nome de fonte do arquivo de origem. No Excel, uma fonte perdida aparece como a face padrão no segundo run da nota do C3

XLS clássico ainda aparece em muitos projetos Delphi e C++Builder, e todo consumidor de fonte num arquivo BIFF8 precisa concordar com a §2.5.129 para a saída abrir certo no Excel. O HotXLS, o componente de planilhas Delphi, aplica a numeração com-pulo-do-4 em formatos de célula, shared strings, comentários, caixas de texto e gráficos, renumera os runs a cada save e os move por valor entre pastas de trabalho, e lê e escreve XLS e XLSX sem Excel nem automação OLE