数式エンジン
評価器は、スカラー値、範囲、配列、エラー、参照、ロケール依存の挙動を Excel と一致させることを目指しています。Formulon は認識対象の関数名を起動時に登録し、各バインディングはその中で評価できる関数を呼び出せます。
用語: tree-walker / bytecode VM
Formulon は 2 つの評価器を持ちます。tree-walker はパース済み AST をそのまま解釈し、bytecode VM は数式をコンパクトな命令列に下げて高速に実行します。両者は同じ結果を返す必要があり、テストでは並走させて差分が出ないか常に検査します。
用語: value kind（値の種類）
セル値・数式結果に付く弁別子です。Blank / Number / Bool / Text / Error / Array / Ref / Lambda の 8 種類があります。各バインディングは enum として公開します（例: WASM ValueKind.Number、Python ValueKind.NUMBER）。
- 数式テキスト=SUM(A1:A10)
- 字句 / 構文解析
- AST
- 参照解決names・tables・ranges
- 評価器tree-walker と bytecode VM が parity を保ちつつ実行。関数カタログ（ローカル実装 505/522）と有効な互換性プロファイルを参照する
- ValueNumber・Text・Bool・Error・Array・Ref・Lambda・Blank
認識対象の関数
Formulon は、数学、統計、論理、テキスト、日付 / 時刻、検索、財務、エンジニアリング、情報、データベース、Web、キューブ、LET / LAMBDA / 動的配列系など、合計 522 件の Excel 関数名を認識します。これは認識カタログであり、Microsoft 365 の外部サービスに依存する関数まですべてローカル実装済みという意味ではありません。
現在は 505 / 522 件が実際のローカルエンジン実装、2 件が環境依存（CELL、INFO）、15 件が外部サービスやライブ接続を必要とするため意図的に用意された未提供スタブです。カテゴリ別、状態別の内訳は 数式カバレッジ を参照してください。
評価モード
tree-walker と bytecode VM は並走でき、互いの parity を検査します。同じワークブック・同じプロファイルで両者が一致することが、最適化を進める前提条件です。
アドホック評価
同じ評価器の上に、WASM と Native Node（C API）は読み取り専用のアドホック数式評価を公開しています。evaluateFormulaText() と evaluateConditionalFormula() は、セルに何も書き込まずに「この数式をここで評価したら何が返るか」に答えます。API の形状、WASM / Native Node のみという scope、配列・スピル結果をトップレフトのスカラーへ縮約する制約については ワークブック操作 — アドホック数式評価 を参照してください。v0.9.5 では、縮約せずに Array 全体を返す evaluateFormulaArray() / evaluate_formula_array()（Python を含む）も加わりました。
v0.9.5 の評価挙動更新
v0.9.5 では、配列に関わる評価の忠実度を高める修正が入りました。
- 範囲を指す defined name（例:
Sheet1!$A$1:$A$5）は、暗黙の交差でスカラーへ縮約せず、Array として評価されるようになりました。 - スピルによって生じる phantom セルが完全に列挙されるようになり、
cell_count/cell_atの忠実度が向上しました。
v0.9.3 の評価挙動更新
v0.9.3 では、このページに直結する評価器レベルの修正が入りました。
date1904が tree-walker と bytecode VM の両方に伝播するようになり、1900 年基準・1904 年基準どちらの日付システムのワークブックも、どちらの評価器でも一貫した結果を返します。- defined name の解決が循環参照を検出するようになり、以前のようにハングしたり古い値を黙って返したりしません。
- 列全体 / 行全体参照（
A:A、3:3）は、固定の上限ではなくシートの used range に対して展開されます。 - 形状が一致しない配列同士の暗黙のブロードキャストが、Excel の実際の array-broadcast ルールに従うようになりました（動的配列 参照）。
- 単一セルの 3-D 参照だけでなく、
Sheet1:Sheet3!A1:B2のような 3-D range の末尾指定も正しく解決されます。
v0.9.2 の評価挙動更新
v0.9.2 では、Excel 由来の期待値に合わせるため、いくつかの境界ケースで結果が変わります。
- 数値リテラルは、構文解析時に Excel と同じ 15 桁有効数字の表現へ丸める。
ARRAYTOTEXTは、スカラーのエラー引数を文字列化せず、そのエラー値を伝播する。FREQUENCYは、bin の並びに関する Excel の挙動へ近づけた。PERCENTILE.EXCは、上限境界（pos == n）で最大値ではなく#NUM!を返す。
エラーの扱い
Excel error はホスト言語の例外ではなく 値 として扱います。
| Excel error | 意味 |
|---|---|
#DIV/0! | 0 除算、または除数が空 |
#VALUE! | 引数・オペランドの型不一致 |
#REF! | 参照を解決できない（削除されたシート、壊れた range など） |
#NAME? | 未知の関数 / defined name |
#NUM! | 数値オーバーフローや不正な数値入力 |
#N/A | 値なし。MATCH / VLOOKUP 系で発生 |
#NULL! | 範囲交差が空 |
#SPILL! | 動的配列のスピルが成立しない（衝突・範囲外） |
#CALC! | エンジンが結果を返せない（再帰・未完了評価など） |
#GETTING_DATA | 外部参照の取得中 |
セルの error とホスト失敗は別物
#DIV/0! を返す数式は API として 失敗していません。呼び出しは成功しており、結果がエラー値なのです。value.kind === ValueKind.Error で判定してください。バイト列不正・ハンドル失効・IO 失敗などはステータス envelope / 例外 / 非ゼロ終了で別経路で報告されます。
座標
バインディングは 0 から始まる数値座標を使い、ロケールごとのアドレス解析を避けます。
| Excel のアドレス | バインディングのタプル (sheet, row, col) |
|---|---|
Sheet1!A1 | (0, 0, 0) |
Sheet1!B4 | (0, 3, 1) |
Sheet2!C10 | (1, 9, 2) |
A1 テキストは CLI 引数・数式文字列・MCP ツール入力など、明示的に要求している場面でのみ受け付けます。
ロケール依存挙動
テキスト整形・日付パース・通貨・リスト区切りなど、一部関数は有効な互換性プロファイルを参照します。既定は win-365-ja_JP です。対応する Oracle データが揃ったプロファイルだけが公開されます。詳しくは ロケールプロファイル。