Supporto per Free Pascal e Lazarus

HotXLS supporta Free Pascal 3.2.2 con Lazarus/LCL su Windows Win32 e Win64, incluse le API dei workbook XLS/XLSX, le formule, la formattazione, lo streaming diretto, i componenti di esportazione TDataToXLS e TGridToXLS e gli helper di rendering

Core del workbook nativo per Linux e macOS

Vedi archiviazione Compound File per le API di directory con scope, la proprietà esplicita dello storage nativo, i timestamp e le chiavi canoniche degli identificatori Classic

Il profilo opt-in LX_PORTABLE_CORE espone TXLSWorkbook e TXLSXWorkbook senza LCL su Linux e macOS. Linux x64 e macOS ARM64 nativi sono stati compilati ed eseguiti con Free Pascal 3.3.1; il guard di versione dei sorgenti richiede almeno 3.2.2, ma quel minimo non è una dichiarazione che ogni combinazione di compilatore nativo e target sia stata validata

Metti cthreads e cwstring prima delle unità HotXLS, aggiungi Lib ai percorsi di unità e include, e definisci LX_PORTABLE_CORE per l'intera build. Un'applicazione console nativa non richiede Interfaces né un widgetset LCL

Seleziona un locale UTF-8 installato nell'ambiente dell'applicazione quando lavori con percorsi filesystem Unicode. Un locale non valido o non UTF-8 può rendere lossy la conversione dei nomi file della RTL nativa; l'helper di validazione rifiuta esplicitamente quell'ambiente invece di cambiare il locale o indovinare una codepage

program NativeWorkbookExample;
{$mode delphiunicode}
uses
  cthreads, cwstring, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.Sheets.Add('Data').Cells[1, 1].Value:= 5;
    Workbook.Sheets[1].Cells[1, 2].Formula:= 'A1*2';
    if Workbook.Recalculate<> 1 then
      raise Exception.Create('Workbook calculation failed');
    if Workbook.SaveAs('native.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.

I metodi open e save conservano i loro normali contratti di codice risultato e diagnostica. Le chiamate dirette ai confini di piattaforma possono generare EXLSPlatformUnsupported; gestisci questa eccezione quando invochi un servizio solo-Windows da codice applicativo condiviso

Validazione nativa riproducibile

Esegui l'helper di validazione sul guest nativo con un toolchain Free Pascal esistente, Python 3 e un compilatore C nativo. Scegli una directory di output nuova o vuota fuori dal checkout dei sorgenti sul filesystem del guest

python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --output /guest-local/hotxls-validation
python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --config /path/to/fpc.cfg --output /guest-local/hotxls-validation-2

L'helper copia ed effettua l'hash degli input sorgente, normalizza i nomi file delle unità Pascal nella copia di build privata per la ricerca di nomi file case-sensitive di FPC, compila PCRE2 localmente, ed esegue i witness di core, AES, compressione, REGEX, workbook pubblico e integrazione. Conserva manifest dei sorgenti, log del compilatore, artefatti e guasti senza modificare il checkout, installare tool o modificare la configurazione del compilatore. Le build macOS ARM64 puntano esplicitamente a macOS 11 o successivo

I witness di integrazione includono percorsi Unicode, fixture XLSB autore di Excel, cache delle formule e ricalcolo, aperture ripetute, note ODS sparse e protezione, rifiuto di conversione verificata, annullamento che preserva le destinazioni del chiamante, lookup con scope di nomi invariante, contenimento dei guasti di thread worker reali e byte casuali crittografici

Contratti Classic XLS nativi

Usa lxHandle per TXLSWorkbook Classic e lxHandleX per TXLSXWorkbook. Il Recalculate Classic restituisce un conteggio di errori, quindi zero significa successo; il suo metodo Calculate restituisce un risultato formula. Le assegnazioni Formula delle celle Classic richiedono un = iniziale. I metodi open e save del workbook conservano il loro risultato di successo stabilito, pari a 1

L'implementazione Classic nativa dello storage usa una vera gerarchia compound file e identità di stream, preservando scope annidati, dati MiniFAT e catene DIFAT estese. I payload degli stream vengono materializzati e il writer rifiuta un output aggregato oltre i suoi limiti supportati di buffer/settore con segno a 32 bit prima di emetterlo; questa non è un'implementazione di storage in streaming multi-gigabyte

Lo storage compound nativo fornisce operazioni dirette su stream, enumerazione, metadati e operazioni di copia. Il rollback delle transazioni, il locking di regioni, lo spostamento e le modalità di esclusione non supportate restituiscono errori di storage espliciti. Non emula servizi Windows COM, appunti o GDI

I salvataggi Classic nativi su file serializzano prima di sostituire atomicamente un file sibling registrato. I salvataggi su stream del chiamante mettono in stage il compound file completo prima di copiare alla posizione originale, preservando prefissi e guasti di annullamento prima del commit. L'ultima notifica di progresso resta non-cancellabile. Le scritture dirette degli helper di compound storage seguono il loro ordinario contratto di scrittura diretta, non la transazione di salvataggio pubblica del workbook

Le proprietà di riepilogo e riepilogo documento ordinarie usano property set OLE standard limitati con testo Unicode e timestamp FILETIME UTC. Questi flussi di proprietà restano in chiaro quando i dati del workbook Classic sono crittografati, e l'intestazione RC4 CryptoAPI registra esplicitamente quella scelta. I nomi definiti condividono le chiavi canoniche di identificatore bloccate usate dalla facade XLSX, conservando la loro grafia originale e lo scope esplicito del foglio. I dati di disegno PNG/JPEG codificati restano disponibili al modello; la conversione nativa bitmap/metafile richiede un renderer separato supportato e altrimenti genera EXLSPlatformUnsupported

Compila Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr con le stesse opzioni del core nativo, poi passa Tests/Fixtures/classic-native/native-classic.xls, un percorso di output guest-local usa-e-getta e Tests/Fixtures/classic-native/native-classic-encrypted.xls. I controlli coprono cache autore di Excel, ricalcolo, nomi Unicode esatti, round trip plain e crittografati, timestamp di proprietà decodificati indipendentemente, aperture ripetute, più di 16 MB di dati SST e conservazione dell'output del chiamante

Codifica a byte legacy BIFF

TXLSWorkbook.SetCodePage seleziona la codifica a byte esplicita usata da SaveAs(..., xlExcel5), con CP1252 come predefinito; importare un file BIFF2–BIFF5 con un record CODEPAGE utilizzabile e non zero seleziona anche quella pagina per i successivi salvataggi legacy

Le etichette legacy delle celle, le costanti testuali e gli array delle formule, le stringhe delle formule in cache, i nomi definiti, i nomi e i riferimenti dei fogli di lavoro, i nomi dei font, i formati numerici, i nomi degli stili, intestazioni, piè di pagina e il testo ordinario dei commenti usano quella pagina dichiarata, non il locale del sistema operativo o UTF-8

Le lunghezze dei record e gli offset dei flussi dei fogli di lavoro contano byte codificati; i limiti legacy esistenti di 255 byte per etichette e letterali formula troncano solo a un confine di carattere intero, così un carattere double-byte CP932 non viene mai spezzato; nomi e metadati con lunghezza a un byte rifiutano testo codificato più lungo della loro lunghezza rappresentabile invece di emettere una lunghezza non valida

Il testo che non può fare round-trip attraverso la codepage selezionata genera EConvertError prima di poter diventare silenziosamente un carattere di sostituzione o best-fit; seleziona una pagina che rappresenta il testo del documento, o salva come BIFF8 per stringhe Unicode

Le stringhe delle cache delle formule che attraversano record CONTINUE vengono assemblate come byte prima della decodifica, così un confine di record può spezzare un carattere double-byte senza corrompere il valore in cache

Cambiare la pagina selezionata ricostruisce i byte legacy tipizzati di formule e nomi definiti dal loro modello Unicode; i salvataggi BIFF8 continuano a usare Unicode e il loro valore CODEPAGE su disco resta 1200

I record di grafico BIFF5 importati conservano la loro codepage originale per l'ispezione tipizzata di serie e titoli collegati, anche dopo una modifica della codepage del workbook o una copia di grafico; salvare su una pagina diversa transcodifica esplicitamente SeriesText supportate, etichette in cache semplici e stringhe delle formule, intestazioni, piè di pagina e nomi di fogli esterni del workbook corrente, invece di reinterpretare i byte conservati sotto la nuova dichiarazione

Il testo di grafici continuati, le codifiche legacy di fogli esterni non modellate e i record legacy di testo a byte opachi rifiutano una migrazione di codepage con EConvertError; anche il testo supportato non rappresentabile viene rifiutato, e il salvataggio pubblico del workbook preserva la destinazione del chiamante prima del commit; questo contratto testuale non promette la conversione completa dell'aspetto nativo dei grafici

I nomi di stile personalizzati BIFF5 iniziano immediatamente dopo la lunghezza codificata a un byte, mentre SeriesText BIFF5 ha un identificatore e una lunghezza codificata a un byte senza flag Unicode; SeriesText BIFF8 aggiunge il suo flag Unicode, e convertire il testo supportato dei grafici aggiorna quel record e la versione BOF del grafico insieme

Intestazioni e piè di pagina BIFF5 dei grafici non vuoti usano una lunghezza codificata a un byte con un massimo di 255 byte; i record in cache LABEL e STRING usano lunghezze a due byte, mentre le intestazioni e i piè di pagina BIFF8 usano una lunghezza UTF-16 a due byte più il loro flag Unicode; la migrazione verifica il layout effettivo di ogni record e rifiuta un'intestazione o un piè di pagina legacy oversized con ERangeError prima di accodarlo

HotXLS interpreta i byte legacy usando la loro pagina dichiarata su Windows, Linux e macOS; l'installazione di Excel 16.0 build 20430 ha dimostrato indipendentemente un limite del destinatario: interpreta i byte legacy usando il CP936 Windows locale anche dopo che il solo record CODEPAGE di un file nativo era stato cambiato in CP1252 o CP932, quindi byte dichiarati corretti non garantiscono testo corrispondente in quella configurazione del destinatario

Preserva la dichiarazione effettiva di codifica del documento e testa l'applicazione ricevente quando distribuisci BIFF5 attraverso configurazioni di locale diverse; il BIFF8 Unicode evita questo particolare confine di interoperabilità dei byte legacy

Questa correzione della codifica a byte conserva il limite esistente di dimensione del record dei commenti ordinari BIFF5; non aggiunge autore, formattazione rich-text o campi di geometria delle forme al record legacy

L'editing dei sorgenti dei moduli VBA usa la codepage a byte dichiarata del progetto e preserva il prefisso binario prima dell'offset dei sorgenti, inclusi i byte null incorporati; questo cambia il testo dei sorgenti memorizzati e non esegue macro

Il Unicode compresso BIFF8 con fHighByte = 0 mappa ogni byte direttamente a un'unità di codice UTF-16 da U+0000 a U+00FF; non è CP1252, UTF-8 o la codepage legacy del file, anche quando un record CODEPAGE non standard appare in un file altrimenti BIFF8

Le formule testuali native conservano lunghezze e posizioni UTF-16, incluse le unità di codice delle coppie surrogate; LOWER, UPPER, SEARCH, delimitatori TEXTBEFORE/TEXTAFTER case-insensitive Unicode, header dei campi dei database, criteri case-insensitive e chiavi di testo dinamiche usano i dati di caratteri Unicode del compilatore nativo invece delle funzioni di casing solo-ASCII del locale C dell'host, mentre l'ordinamento ordinario dei fogli di lavoro conserva il suo confronto di locale esistente

Il matching dei nomi locali LET/LAMBDA nativo e la classificazione dello storage degli array locali usano lo stesso casing consapevole di Unicode, così le controparti di maiuscole risolvono il binding catturato corretto e ne conservano la forma dell'array; questo non cambia il contratto pubblico bloccato di identità dei nomi definiti

FindText e ReplaceText Classic case-insensitive conservano il matching di caratteri Unicode per ricerche di letterali e wildcard Excel su FPC nativo; MatchCase distingue comunque le maiuscole, la sostituzione di letterali mantiene il comportamento replace-all, la sostituzione wildcard conserva il comportamento esistente di span più a sinistra, e le celle formula restano escluse

Compila Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr con le opzioni del core nativo e passa una directory di output usa-e-getta seguita da Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls; il witness verifica indipendentemente i byte dichiarati CP1252, CP932 e CP936, ogni offset del foglio di lavoro, i cambi di codepage, i confini di continuazione double-byte, l'import BIFF8 compresso, il calcolo delle formule, il testo dei grafici autore nativo e la conservazione della destinazione dei salvataggi falliti

Installer completo

L'installer completo rileva Lazarus e supporta l'installazione senza RAD Studio. Selezionare Lazarus / Free Pascal nella pagina di integrazione con l'IDE per installare il package runtime, le unità di compatibilità e gli script di build; l'opzione è selezionata per impostazione predefinita quando Lazarus è l'unico IDE rilevato

Nella pagina di compilazione post-installazione, selezionare il package runtime di Free Pascal per Win32 o Win64. Un target è disponibile quando vengono rilevati il suo compilatore e le unità RTL, LCL e LazUtils; anche quando un target non è disponibile si possono comunque installare i sorgenti del package e compilarli più avanti

Il package è solo runtime e viene aggiunto come dipendenza del progetto in Lazarus. L'installer non compila le demo VCL con Free Pascal

Compilazione e test

Aprire Lib/FPC/HotXLSLaz.lpk in Lazarus e compilare il package runtime, oppure eseguire questi comandi dalla directory HotXLS

build-FPC-Lib.cmd Win64
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win64
build-FPC-Lib.cmd Win32
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win32

Impostare LAZARUS_DIR per selezionare un'installazione; FPC_EXE e LAZBUILD_EXE possono selezionare eseguibili espliciti del compilatore e del builder di package quando necessario

L'installazione selezionata deve contenere FPC e le unità LCL/LazUtils compilate per l'architettura di destinazione; gli output e la configurazione del builder di package vengono conservati in directory separate per architettura

Configurazione dell'applicazione

Aggiungere Lib e Lib/FPC al percorso di ricerca delle unità e Lib al percorso di ricerca degli include, oppure aggiungere il package runtime come dipendenza del progetto Lazarus

Mettere Interfaces prima delle unità HotXLS nell'elenco uses dell'applicazione, comprese le applicazioni console; questo inizializza il widgetset LCL e la conversione UTF-8 ai confini RTL/LCL

program WorkbookExample;
{$mode delphiunicode}
uses
  Interfaces, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.AddSheet('Data');
    Workbook.Sheets[1].Cells[1, 1].Value:= 'Hello';
    if Workbook.SaveAs('example.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.

Le unità sorgente di HotXLS selezionano internamente la semantica Unicode di Delphi così che stringhe, caratteri e testo delle formule conservino il comportamento UTF-16; il codice dell'applicazione può usare la sua modalità Pascal preferita

Dettagli sulla compatibilità

• Il package runtime richiede Windows e LCL; TDataToXLS esporta dataset LCL e TGridToXLS esporta un TDBGrid, con o senza colonne esplicite, mentre Linux, macOS, i form demo VCL, il visualizzatore di workbook VCL e l'adattatore di griglia DevExpress restano fuori da questo package
• Gli stream ZIP e di compressione usano il backend Pascal in bundle e non richiedono una DLL zlib separata
• AES usa un backend Pascal per entrambe le architetture, inclusi i file XLSX protetti da password
• Il PNG conserva il canale alfa, l'EMF usa la registrazione e la riproduzione di metafile Windows, e il TIFF multipagina usa il runtime GDI+ di Windows
• La lettura diretta del testo accetta UTF-8 e UTF-16/UTF-32 con BOM, gestisce input in streaming e lascia la proprietà dello stream al chiamante
• Inizializzare TXlsCsvImportOptions con TXlsCsvImportOptions.Default prima di modificare i singoli campi
• Le espressioni di report e i pattern di importazione FPC usano la sintassi Unicode URegExpr anziché il backend PCRE di Delphi. Un input vuoto riceve la stessa risposta di TRegEx: un modello che accetta una stringa vuota, come ^$ o .*, la confronta mentre [0-9]+ no, e la sostituzione di una stringa vuota produce il testo di sostituzione solo quando il modello lo accetta; i modelli non supportati e i modelli vuoti sollevano ERegularExpressionError, che le espressioni di report espongono come REPORT_EXPRESSION_INVALID_REGEX