bisql

# bisql bisqlは、Go向けの双方向SQLテンプレートエンジンです。SQLクライアントで実行可能な有効なSQL文でありながら、アプリケーション向けのパラメータ化されたクエリビルダーとしても機能するSQLテンプレートを作成できます。ディレクティブはSQLコメントとして表現されるため、同じテキストが両方のコンテキストで機能します。 ## 主な機能 - **双方向SQL**: テンプレートは有効なSQL文です。ディレクティブはコメントです。同じテキストがクライアント（サンプル値を使用）で実行され、Goでパラメータ化されたステートメント `(SQL, Args)` を構築します。 - **明示的なモデル**: 空の句やぶら下がりコネクタの暗黙的な削除はありません。作成者は、予測可能な出力のために動的フラグメント（例：`1 = 1`）をアンカーします。 - **ディレクティブ**: バインド（`/* expr */リテラル`）、リテラル補間（`/*^ expr */リテラル`）、条件分岐（`/*%if*/`、`/*%elseif*/`、`/*%else*/`、`/*%end*/`）、ループ（`/*%for x in xs*/`）、インクルード（`/*%! @include name */`）。 - **フラグメントのインクルード**: `@include` で構成される再利用可能なSQLフラグメント。`fs.FS`、インメモリレジストリ、またはカスタムローダーから解決されます。サイクル/深さガード付きの再帰をサポートします。 - **方言サポート**: MySQL、SQLite、PostgreSQL、Oracle、SQL Server向けのプレースホルダー生成。PostgreSQL向けの配列バインディング。 - **式言語**: 条件と反復可能オブジェクトにexpr-langを使用し、比較、論理演算、オプショナルチェーン、nil合体、`in`、`len` をサポートします。 - **安全設計**: 任意の値の生テキスト置換はありません。動的識別子は `/*%if*/` ブランチを介してホワイトリストに登録する必要があります。 ## 使用方法 テンプレートは `.sql` ファイルです。任意の `fs.FS`（例：埋め込み）から `ParseFile` で解析し、パラメータマップまたは構造体でビルドします。 ```go p := bisql.NewParser(bisql.WithDialect(dialect.PostgreSQL)) tmpl, err := p.ParseFile(sqlFS, "users/search.sql") stmt, err := tmpl.Build(map[string]any{"name": "Alice", "activeOnly": true, "status": "active"}) fmt.Println(stmt.SQL) // パラメータ化されたSQL fmt.Println(stmt.Args) // バインド引数 ``` ## 作成ルール - 動的フラグメントをアンカーします（例：`AND` チェーンには `1 = 1`、`OR` チェーンには `1 = 0`）。 - リストには、先頭のコネクタ（`and`/`or`）またはゼロ行シードからの `union all select` をカンマ区切りリストに使用します。 - 文字列/識別子はSQL標準の二重化で引用します。バックスラッシュエスケープは認識されません。 - パーサーコメント（削除）には `/*%! … */` を、通常のブロックコメントには `/** … */` を使用します。 ## パッケージ構成 - `bisql`: 公開API（Parser、Parse、Expand、ローダー）。 - `dialect/`: 方言定義。 - `expr/`: 評価インターフェースとスコープ。 - `internal/`: テンプレートレイヤーとデフォルト評価器。 ## 開発 ツールチェーンは `mise.toml` で固定されています。`mise run check` でフォーマット、ビルド、vet、lint、テストを実行します。PostgreSQLを使用した統合テストには、ビルドタグとDSNが必要です。 完全なドキュメントについては、[Go Reference](https://pkg.go.dev/github.com/mpyw/bisql) を参照してください。