Free Pascal と Lazarus のサポート

HotXLS は、Windows Win32 および Win64 上の Free Pascal 3.2.2 と Lazarus/LCL をサポートします。XLS/XLSX ブック API、数式、書式設定、直接ストリーミング、TDataToXLS および TGridToXLS エクスポートコンポーネント、レンダリングヘルパーが含まれます

ネイティブ Linux と macOS のワークブックコア

スコープ付きディレクトリ API、明示的なネイティブストレージ所有権、タイムスタンプ、正規化されたクラシック識別子キーについては、コンパウンドファイルストレージを参照してください

オプトインの LX_PORTABLE_CORE プロファイルは、Linux と macOS で LCL なしに TXLSWorkbook と TXLSXWorkbook を公開します。ネイティブ Linux x64 と macOS ARM64 は Free Pascal 3.3.1 でコンパイルおよび実行済みです。ソースのバージョンガードは 3.2.2 以上を要求しますが、この最小値は、すべてのネイティブコンパイラとターゲットの組み合わせが検証されたという主張ではありません

HotXLS ユニットの前に cthreads と cwstring を置き、ユニット検索パスとインクルードパスに Lib を追加し、ビルド全体で LX_PORTABLE_CORE を定義します。ネイティブコンソールアプリケーションには Interfaces や LCL widgetset は不要です

Unicode のファイルシステムパスを扱うときは、アプリケーション環境でインストール済みの UTF-8 ロケールを選択してください。無効または非 UTF-8 のロケールは、ネイティブ RTL のファイル名変換を不可逆にする可能性があります。検証ヘルパーは、ロケールを変更したりコードページを推測したりする代わりに、その環境を明示的に拒否します

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.

領域	ネイティブコアの契約
ワークブックファイル	公開ワークブック API を通じて、クラシック BIFF8 XLS、XLSX、サポートされる拡張 XLSB サブセット、サポートされる ODS サブセットの作成、オープン、編集、計算、保存を行い、既存の変換チェックとフォーマット境界を適用します。明示的に宣言された CP1252 と CP932 エンコーディングを持つクラシック BIFF2 レコードも、インポートと Unicode BIFF8 エクスポートを通じて検証済みです
Unicode と名前	ワークブックテキストは UTF-16 セマンティクスを保持し、ネイティブ境界ではファイルシステムパスが UTF-8 を使用します。定義名の識別は、固定版の Unicode 16 正規化と BMP 完全ケースフォールディングを使用し、記号、アクセント、トルコ語の区別、追加平面文字のケース ID をホストロケールとは独立に保持します。修飾された数式は正確なシートスコープを保持します。通常のワークシートテキスト順序は引き続きネイティブ RTL のロケール比較を使用します
インフラストラクチャ	ネイティブのクリティカルセクション、全幅スレッド識別子、実ワーカースレッド、登録された排他的テンポラリファイル、アトミックな兄弟ファイル置き換え、オペレーティングシステムのランダムバイトが、Windows エミュレーションなしで使用されます
圧縮と暗号化	バンドルされた Pascal ZIP/圧縮と AES は引き続き利用できます。クラシック RC4 と RC4 CryptoAPI の XLS ファイルは、オペレーティングシステムのランダムバイトを使用してネイティブに読み書きできます。暗号化された OOXML のネイティブ読み取りは純粋なコンパウンドファイルリーダーを使用し、暗号化 OOXML コンパウンドファイルの書き込みには Windows が必要で、ネイティブ Unix 上では明示的なプラットフォーム例外を発生させます
数式 REGEX 関数	固定版の静的 PCRE2 UTF-16 バックエンドは、ネイティブターゲット上でその C コンパイラによりコンパイルされます。数式エンジンを含むアプリケーションのコンパイル前に `sh Lib/thirdparty/build-pcre2-unix.sh` を実行してください。Linux x64 と macOS ARM64 の静的ターゲットが提供されています
Windows サービス	クリップボードアクセス、Windows COM アクティベーション、組み込み ADO/WinHTTP クエリプロバイダー、GDI ジオメトリキャプチャ、HTML 背景画像のデコード、レガシー PDF エクスポートは、明示的な境界で `EXLSPlatformUnsupported` を発生させます。カスタムクエリプロバイダーとテキストプロバイダーは引き続き利用できます
レガシーコンポーネント	クラシックワークブックモデルと BIFF リーダー/ライターはネイティブコアで利用できます。LCL ランタイムパッケージ、データセット/グリッドエクスポートコンポーネント、ビジュアルコントロールは Windows/LCL コンポーネントのままです。クラシッククリップボードメソッド、HTML エクスポート、レガシー PDF エクスポートは、ネイティブ Unix 上で明示的なプラットフォーム例外を発生させます
バイト指向テキスト数式	Windows のアクティブな ANSI/DBCS コードページを必要とする関数は、ネイティブ Unix 上で明示的に未サポートの数式結果（`#NAME?`）を返します。暗黙のロケールやコードページの代替は選ばれません

Open と SaveAs の各メソッドは、通常の結果コードと診断の契約を保持します。プラットフォーム境界への直接呼び出しは EXLSPlatformUnsupported を発生させることがあります。共有アプリケーションコードから Windows 専用サービスを呼び出すときは、この例外を処理してください

再現可能なネイティブ検証

ネイティブゲスト上で、Free Pascal ツールチェーン、Python 3、ネイティブ C コンパイラを揃えて検証ヘルパーを実行します。出力ディレクトリには、ゲストファイルシステム上のソースチェックアウト外にある新規または空のディレクトリを選んでください

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

ヘルパーはソース入力をコピーしてハッシュ化し、FPC のケースセンシティブなファイル名検索に合わせて非公開ビルドコピー内で Pascal ユニットのファイル名を正規化し、PCRE2 をローカルでビルドして、core、AES、圧縮、REGEX、公開ワークブック、統合の各検証プログラムを実行します。チェックアウトを変更せず、ツールをインストールせず、コンパイラ構成を編集せずに、ソースマニフェスト、コンパイラログ、成果物、失敗を保持します。macOS ARM64 ビルドは明示的に macOS 11 以降をターゲットにします

統合検証プログラムには、Unicode パス、Excel が作成した XLSB フィクスチャ、数式キャッシュと再計算、繰り返しオープン、スパースな ODS ノートと保護、チェック付き変換の拒否、呼び出し側の出力先を保持するキャンセル、不変のスコープ付き名前ルックアップ、実ワーカーの失敗の封じ込め、暗号学的ランダムバイトが含まれます

ネイティブクラシック XLS の契約

クラシック TXLSWorkbook には lxHandle を、TXLSXWorkbook には lxHandleX を使用します。クラシックの Recalculate はエラー数を返すため、ゼロが成功です。Calculate メソッドは数式結果を返します。クラシックのセル Formula 代入には先頭の = が必要です。ワークブックの open と save メソッドは、確立済みの成功結果 1 を保ちます

ネイティブクラシックストレージの実装は、実際のコンパウンドファイル階層とストリーム ID を使用し、ネストされたスコープ、MiniFAT データ、拡張 DIFAT チェーンを保持します。ストリームペイロードは実体化され、ライターは、サポートされる符号付き 32 ビットのバッファ/セクター境界を超える集約出力を、出力する前に拒否します。マルチギガバイトのストリーミングストレージ実装ではありません

ネイティブコンパウンドストレージは、直接ストリーム操作、列挙、メタデータ、コピー操作を提供します。トランザクションロールバック、リージョンロック、移動、未サポートの除外モードは、明示的なストレージエラーを返します。Windows COM、クリップボード、GDI サービスはエミュレートしません

クラシックのネイティブファイル保存は、登録された兄弟ファイルをアトミックに置き換える前にシリアライズします。呼び出し側ストリーム保存は、完全なコンパウンドファイルをステージングしてから元の位置にコピーし、コミット前のプレフィックスとキャンセル失敗を保持します。最後の進捗通知はキャンセル不可のままです。直接コンパウンドストレージのヘルパー書き込みは、公開ワークブック保存トランザクションではなく、通常の直接書き込み契約に従います

通常のサマリーおよびドキュメントサマリープロパティは、Unicode テキストと UTC FILETIME タイムスタンプを持つ、境界付きの標準 OLE プロパティセットを使用します。これらのプロパティストリームは、クラシックワークブックデータが暗号化されていても平文のままです。RC4 CryptoAPI ヘッダーはその選択を明示的に記録します。定義名は XLSX ファサードが使用する固定版の正規識別子キーを共有し、元の表記と明示的なワークシートスコープを保持します。エンコードされた PNG/JPEG 描画データはモデルから引き続き利用できます。ネイティブのビットマップ/メタファイル変換には別のサポート済みレンダラーが必要で、なければ EXLSPlatformUnsupported を発生させます

同じネイティブコアオプションで Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr をコンパイルし、Tests/Fixtures/classic-native/native-classic.xls、使い捨てのゲストローカル出力パス、Tests/Fixtures/classic-native/native-classic-encrypted.xls を渡します。このコントロールは、Excel が作成したキャッシュ、再計算、正確な Unicode 名、平文と暗号化のラウンドトリップ、独立してデコードされたプロパティタイムスタンプ、繰り返しオープン、16 MB を超える SST データ、呼び出し側出力の保持をカバーします

レガシー BIFF バイトエンコーディング

TXLSWorkbook.SetCodePage は、SaveAs(..., xlExcel5) で使用される明示的なバイトエンコーディングを選択します。既定は CP1252 です。使用可能な非ゼロの CODEPAGE レコードを持つ BIFF2–BIFF5 ファイルのインポートでも、そのページが後のレガシー保存のために選択されます

レガシーのセルラベル、数式テキスト定数と配列、キャッシュされた数式文字列、定義名、ワークシート名と参照、フォント名、数値書式、スタイル名、ヘッダー、フッター、通常のコメントテキストは、オペレーティングシステムのロケールや UTF-8 ではなく、その宣言されたページを使用します

レコード長とワークシートストリームのオフセットはエンコード済みバイトを数えます。既存の 255 バイトのレガシーラベルと数式リテラルの上限は、文字境界でのみ切り詰めるため、CP932 の 2 バイト文字が分割されることはありません。1 バイト長の名前とメタデータは、表現可能な長さを超えるエンコード済みテキストを、無効な長さを出力する代わりに拒否します

選択したコードページでラウンドトリップできないテキストは、置換文字やベストフィット文字に黙って変わる前に EConvertError を発生させます。ドキュメントテキストを表現できるページを選択するか、Unicode 文字列のために BIFF8 で保存してください

CONTINUE レコードにまたがる数式キャッシュ文字列は、デコードの前にバイトとして組み立てられるため、レコード境界が 2 バイト文字を分割してもキャッシュ値は壊れません

選択したページを変更すると、型付きレガシー数式と定義名のバイトが Unicode モデルから再構築されます。BIFF8 保存は引き続き Unicode を使用し、ディスク上の CODEPAGE 値は 1200 のままです

インポートされた BIFF5 グラフレコードは、ワークブックのコードページ編集やグラフコピーの後も含めて、型付き系列とアタッチされたタイトルの検査のために元のコードページを保持します。別のページへの保存では、保持されたバイトを新しい宣言の下で再解釈する代わりに、サポートされる SeriesText、平文のキャッシュラベルと数式文字列、ヘッダー、フッター、現在のワークブックの外部シート名を明示的にトランスコードします

継続されたグラフテキスト、モデル化されていないレガシー外部シートエンコーディング、不透明なレガシーバイトテキストレコードは、EConvertError でコードページ移行を拒否します。表現できないサポート済みテキストも拒否し、公開ワークブック保存はコミット前に呼び出し側の出力先を保持します。このテキスト契約は、ネイティブグラフ外観変換の完全性を約束するものではありません

BIFF5 のカスタムスタイル名は、1 バイトのエンコード済み長の直後から始まります。一方 BIFF5 の SeriesText には識別子と 1 バイトのエンコード済み長があり、Unicode フラグはありません。BIFF8 の SeriesText は Unicode フラグを追加し、サポートされるグラフテキストの変換はそのレコードとグラフの BOF バージョンを一緒に更新します

空でない BIFF5 グラフのヘッダーとフッターは、255 バイト上限の 1 バイトエンコード済み長を使用します。キャッシュされた LABEL と STRING レコードは 2 バイト長を使用し、BIFF8 のヘッダーとフッターは Unicode フラグ付きの 2 バイト UTF-16 長を使用します。移行は各レコードの実際のレイアウトをチェックし、追加の前に過大なレガシーヘッダーまたはフッターを ERangeError で拒否します

HotXLS は、Windows、Linux、macOS のいずれでも、宣言されたページを使ってレガシーバイトを解釈します。インストール済みの Excel 16.0 ビルド 20430 は受信側の制限を独立して示しました。ネイティブファイルの CODEPAGE レコードだけを CP1252 または CP932 に変更した後でも、Excel はローカルの Windows CP936 を使ってレガシーバイトを解釈しました。そのため、正しい宣言済みバイトでも、その受信側構成で一致するテキストは保証されません

BIFF5 を異なるロケール構成へ配布するときは、ドキュメントの実際のエンコーディング宣言を保持し、受信側アプリケーションをテストしてください。Unicode の BIFF8 はこのレガシーバイト相互運用境界を回避します

このバイトエンコーディング修正は、既存の BIFF5 通常コメントレコードのサイズ上限を保持します。レガシーレコードにコメント作成者、リッチテキスト書式、シェイプジオメトリのフィールドは追加しません

VBA モジュールソース編集は、プロジェクトが宣言したバイトコードページを使用し、ソースオフセットの前のバイナリプレフィックスを保持します。埋め込み null バイトも含まれます。これにより保存されたソーステキストが変わり、マクロは実行しません

fHighByte = 0 の BIFF8 圧縮 Unicode は、各バイトを U+0000 から U+00FF の UTF-16 コード単位へ直接マップします。これは CP1252 でも UTF-8 でもファイルのレガシーコードページでもありません。BIFF8 ファイルに非標準の CODEPAGE レコードが現れる場合でも同様です

ネイティブテキスト数式は、サロゲートペアのコード単位を含めて UTF-16 の長さと位置を保持します。Unicode の LOWER、UPPER、SEARCH、TEXTBEFORE/TEXTAFTER の大文字小文字を区別しない区切り文字、データベースフィールドヘッダー、大文字小文字を区別しない条件、動的テキストキーは、ホストの C ロケールの ASCII 専用ケース関数ではなく、ネイティブコンパイラの Unicode 文字データを使用します。一方、通常のワークシート順序は既存のロケール比較を保持します

ネイティブの LET/LAMBDA ローカル名マッチングとローカル配列ストレージ分類は、同じ Unicode 対応のケース処理を使用します。そのため、大文字小文字の対応は正しいキャプチャ済みバインディングを解決し、その配列形状を保持します。このことは、固定版の公開定義名識別子契約を変更するものではありません

クラシックの大文字小文字を区別しない FindText と ReplaceText は、ネイティブ FPC 上のリテラル検索と Excel ワイルドカード検索のどちらでも Unicode 文字照合を保持します。MatchCase は引き続きケースを区別し、リテラル置換は置換オールの動作を、ワイルドカード置換は既存の左端スパンの動作を保ち、数式セルは引き続き除外されます

ネイティブコアオプションで Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr をコンパイルし、使い捨ての出力ディレクトリと Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls を渡します。この検証プログラムは、宣言された CP1252、CP932、CP936 バイトの独立検証、すべてのワークシートオフセット、コードページ変更、2 バイトの継続境界、圧縮 BIFF8 インポート、数式計算、ネイティブ作成グラフテキスト、保存失敗時の出力先保持をチェックします

フルインストーラー

フルインストーラーは Lazarus を検出し、RAD Studio なしでのインストールに対応します。IDE Integration ページで Lazarus / Free Pascal を選ぶと、ランタイムパッケージ、互換ユニット、ビルドスクリプトがインストールされます。Lazarus だけが検出された IDE のときは、このオプションが既定で選ばれています

Post-install Compilation ページで、Win32 または Win64 用の Free Pascal ランタイムパッケージを選択します。コンパイラ、RTL、LCL、LazUtils ユニットが検出できたターゲットだけが選べます。ターゲットを利用できなくても、パッケージソースはインストールしておいて後からコンパイルできます

このパッケージはランタイム専用で、Lazarus ではプロジェクトの依存関係として追加します。インストーラーが VCL デモを Free Pascal でコンパイルすることはありません

ビルドとテスト

Lazarus で Lib/FPC/HotXLSLaz.lpk を開いてランタイムパッケージをコンパイルするか、HotXLS ディレクトリから次のコマンドを実行します

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

インストールを選択するには LAZARUS_DIR を設定します。必要に応じて FPC_EXE と LAZBUILD_EXE で明示的なコンパイラとパッケージビルダーを選択できます

選択したインストールには、ターゲットアーキテクチャ向けの FPC とコンパイル済みの LCL/LazUtils ユニットが含まれている必要があります。出力とパッケージビルダーの構成は、アーキテクチャごとの専用ディレクトリに保持されます

アプリケーションのセットアップ

ユニット検索パスに Lib と Lib/FPC を、インクルード検索パスに Lib を追加するか、ランタイムパッケージを Lazarus プロジェクトの依存関係として追加します

アプリケーションの uses リストで、コンソールアプリケーションを含め、HotXLS ユニットの前に Interfaces を置きます。これにより、RTL/LCL 境界で LCL widgetset と UTF-8 変換が初期化されます

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.

HotXLS のソースユニットは内部で Delphi の Unicode セマンティクスを選択するため、文字列・文字・数式テキストは UTF-16 の挙動を保ちます。アプリケーションコードは好みの Pascal モードを使えます

互換性の詳細

ランタイムパッケージには Windows と LCL が必要です。TDataToXLS は LCL データセットを、TGridToXLS は TDBGrid を、列を明示するしないにかかわらずエクスポートできます。Linux、macOS、VCL デモフォーム、VCL ワークブックビューアー、DevExpress グリッドアダプターはこのパッケージの対象外です
ZIP と圧縮ストリームはバンドルされた Pascal バックエンドを使用するため、別途 zlib DLL は不要です
AES は両アーキテクチャとも Pascal バックエンドを使用します。パスワード保護された XLSX ファイルも含みます
PNG はアルファを保持し、EMF は Windows のメタファイル記録と再生を使用し、マルチページ TIFF は Windows の GDI+ ランタイムを使用します
直接テキスト読み込みは UTF-8 と BOM 付き UTF-16/UTF-32 を受け付け、ストリーミング入力を処理し、呼び出し元のストリーム所有権を維持します
個々のフィールドを変更する前に、TXlsCsvImportOptions.Default で TXlsCsvImportOptions を初期化します
FPC のレポート式とインポートパターンは、Delphi の PCRE バックエンドではなく Unicode URegExpr 構文を使用します。空の入力への応答は TRegEx と同じです。^$ や .* のように空文字列を受け付けるパターンは空文字列にマッチし、[0-9]+ はマッチしません。空文字列の置換は、パターンが空文字列を受け付ける場合にのみ置換テキストを返します。未サポートのパターンや空のパターンは ERegularExpressionError を送出し、レポート式では REPORT_EXPRESSION_INVALID_REGEX として現れます

Free Pascal と Lazarus のサポート

ネイティブ Linux と macOS のワークブック コア