Skip to content

README_ja.md

Latest commit

 

History

History
121 lines (87 loc) · 9.24 KB

README_ja.md

File metadata and controls

121 lines (87 loc) · 9.24 KB
Raw

Formulon

CI npm PyPI codecov License C++17 Platform Docs

Formulon は、Excel なしで Excel のワークブックと数式を再計算するエンジンです。結果は実際の Excel 365 と照合しています。 Excel のインストールも Windows も COM 操作も要りません。1 つの C++17 コアを、ブラウザと Node 向けの WebAssembly、Python パッケージ、ネイティブ CLI として配布しているので、どこで動かしても同じワークブックは同じ値になります。

こんなときに使えます:

  • サーバーでワークブックを再計算する — バッチ処理、CI、データパイプラインで .xlsx / .xlsb を読み込み、入力を変えて、再計算した値で保存できます。
  • ブラウザで表計算ロジックを動かす — 数式もワークブック全体もクライアント側で評価するので、アップロードされたファイルが利用者のマシンの外に出ません。
  • 計算モデルは Excel のまま使う — チームが保守している既存のワークブックを Node や Python から呼び出せます。数式を別の言語で書き直す必要はありません。
  • ロケールごとに Excel と同じ答えを得る — 日本語のバイト数計算、ドイツ語の小数点カンマ、ローカライズされた TRUE / FALSE は、選んだプロファイルに従います。
  • AI エージェントに表計算の道具を渡す — formulon-mcp がエンジンを MCP 経由で提供します。

Excel との既知の差分は tests/divergence.yaml にケースごとに記録し、それぞれに理由と最後に確認した Excel ビルドを添えています。

📖 ドキュメント  ·  はじめに  ·  ロケールプロファイル  ·  数式カバレッジ  ·  API

主な機能

  • 数式エンジン — Excel 関数名 526 件を認識し、511 件をローカルで実装しています。動的配列、LET / LAMBDA、REGEX* にも対応します。残りはクラウドや COM のサービスを呼ぶ関数で、決まったエラーを返します。カバレッジ
  • ワークブック入出力 — .xlsx と .xlsb を読み込み、再計算し、書き出します。スタイル、条件付き書式、テーブル、ピボットテーブル、グラフ、印刷レイアウトも扱います。ファイル形式
  • ロケールプロファイル — 14 ロケール × Mac / Windows ホストの、28 種類の Excel 挙動プロファイルを選べます。ロケールプロファイル
  • Excel oracle — 数式の結果は、14 ロケールの Mac Excel 365 から取得したゴールデンデータとビット単位で照合しています。ピボットと印刷レイアウトは Windows Excel 365 と照合しています。Oracle テスト
  • サイズ上限つきの WASM — 非圧縮 4.5 MiB、Brotli 1280 KiB を超えると CI が失敗します。サイズ予算

インストール

npm install @libraz/formulon   # ブラウザと Node 22+
pip install formulon            # Python 3.9+

darwin-arm64、linux-x64、linux-arm64 向けの CLI バイナリは GitHub Releases にあります。

クイックスタート

import createFormulon from '@libraz/formulon';

const Module = await createFormulon();
console.log(Module.evalFormula('=SUM(1,2,3)').value.number); // 6
import formulon

print(formulon.eval_formula("=SUM(1,2,3)").to_python())  # 6.0
formulon eval '=SUM(1,2,3)'
formulon recalc input.xlsx -o output.xlsx

ワークブックの読み込み、編集、保存は ワークブックを再計算する で説明しています。

ロケールプロファイルの切り替え

新しいワークブックの既定は win-365-en_US です。数式は常に英語の関数名と保存形式の区切り文字で書きます。プロファイルが変えるのは、文字列の解釈と結果の表示です。ワークブックごとに切り替えて再計算します。

const wb = Module.Workbook.createDefault();
try {
  wb.setFormula(0, 0, 0, '=LENB("日本")');  // A1
  wb.setFormula(0, 1, 0, '=VALUE("1,5")');  // A2
  wb.setFormula(0, 2, 0, '=ISEVEN(2)');     // A3

  for (const id of ['mac-365-en_US', 'mac-365-ja_JP', 'mac-365-de_DE']) {
    wb.setExcelProfileId(id);
    wb.recalc(); // a profile change marks formulas dirty
    console.log(id, [0, 1, 2].map((row) => wb.getDisplayText(0, row, 0).text));
  }
} finally {
  wb.delete();
}
// mac-365-en_US [ '2', '#VALUE!', 'TRUE' ]
// mac-365-ja_JP [ '4', '#VALUE!', 'TRUE' ]
// mac-365-de_DE [ '2', '1,5', 'WAHR' ]
with formulon.Workbook.create_default() as wb:
    wb.set_formula(0, 0, 0, '=LENB("日本")')
    wb.set_formula(0, 1, 0, '=VALUE("1,5")')
    wb.set_formula(0, 2, 0, "=ISEVEN(2)")

    for profile in ("mac-365-en_US", "mac-365-ja_JP", "mac-365-de_DE"):
        wb.set_excel_profile_id(profile)
        wb.recalc()
        print(profile, [wb.get_display_text(0, row, 0)[0] for row in range(3)])

プロファイル ID は {mac,win}-365-{ja_JP,en_US,de_DE,fr_FR,zh_CN,ko_KR,th_TH,es_ES,es_MX,pt_BR,ru_RU,zh_TW,it_IT,nl_NL} です。mac-* のすべてと win-365-ja_JP は Excel で測定したもので、それ以外の win-* は Mac での測定値からの推定です。mac-* では、テキストの比較、並べ替え、検索、グループ化が、そのロケールの Mac Excel で測定した照合順序に従います。win-* では、そのロケールの照合順序に、Windows Excel 365 ja-JP で測定した Windows の単語並べ替え規則が加わります。プロファイルはファイルに保存されないため、アプリケーション側で対象の ID を保持し、読み込み後に設定し直してください。

Excel がそのロケールで新規作成するのと同じブックが必要なら、createDefault の代わりに Workbook.createForProfile(id)（Python では Workbook.create_for_profile）を使います。プロファイルを選ぶのに加えて、本文とふりがなのフォント、ローカライズされた標準スタイル名と最初のシート名、ページ余白を、Excel がそのロケールで使う値に合わせます。後から追加したシートは、最初のシートの行の高さ、ページ余白、ふりがな設定を引き継ぎます。

対象外

VBA の実行、旧形式の .xls、グラフの描画、Power Query / DAX、元データからのピボットキャッシュ更新、外部データへのライブ接続、表計算 UI は、恒久的に対象外です。詳しくは 対象外の機能 を参照してください。

コントリビュート

いちばん役立つのは、お使いのロケールの Excel oracle データです。特に Windows Excel 365 のデータを歓迎します。make oracle-contribute が Excel を操作してゴールデンデータを取得します。CONTRIBUTING.md と Oracle データの提供 を参照してください。

ライセンス

Apache License 2.0。NOTICE も参照してください。

関連プロジェクト

  • formulon-cell — @libraz/formulon を使ったブラウザ向け表計算 UI
  • formulon-mcp — AI エージェントにワークブック操作ツールを提供する MCP サーバー