English

CLI リファレンス¶

graphcal コマンドラインツールは、.gcl ファイルの評価、サーブ、フォーマット、チェックを行うサブコマンドと、LSP サーバーを起動するサブコマンドを提供します。

グローバルオプション¶

graphcal [OPTIONS] <COMMAND>

コマンド一覧¶

Graphcal のソースを読み込むコマンドは、ファイルシステムへのアクセスを、明示的に指定された --root、最も近くで検出された graphcal.toml のディレクトリ、または（単独ファイルの場合） そのファイルを含むディレクトリにサンドボックス化します。ルートは存在し、アクセス可能で ある必要があります。ソースとマニフェストのパスは通常ファイルを指す必要があります。

graphcal deps lock¶

パッケージの正確なリビジョン指定の Git 依存関係を解決し、ローカルの Graphcal キャッシュに 実体化し、そのソースハッシュを検証して、graphcal.lock を書き出します。

graphcal deps lock [OPTIONS]

オプション:

このコマンドは graphcal.toml の [dependencies] を読み、不足しているソースを取得します。 依存関係には HTTPS または SSH の Git URL と、完全なコミットハッシュの rev が必要です。 ローカルパスと平文 HTTP はサポートされません。検証済みのキャッシュはネットワークアクセスなしで 再利用され、最新のロックファイルは変更されません。

このコマンドはまた、パッケージの .gcl ソースをスキャンして WASM プラグインのインポート を探し、 参照されている各 .wasm ファイルの SHA-256 を [[plugin]] エントリとしてピン留めします。 読み込み時にはこのピンが強制されます。ピン留めされていない、またはハッシュが一致しないプラグインは ハードエラーとなるため、プラグインのバイナリはレビュー可能なロックファイルの差分と一緒にしか 変更できません。

依存関係を利用するコマンド（check、eval、dump、graph、model serve、および LSP）は、 パッケージに関して読み取り専用です。これらは graphcal.lock とキャッシュされたソースを 読み取りますが、ロックファイルのエントリを取得、作成、更新することはありません。ロックファイルが 存在しない、古い、異なる Graphcal または標準ライブラリのバージョンを使用している、あるいは 存在しないかハッシュが一致しないキャッシュエントリを参照している場合、これらのコマンドは失敗し、 graphcal deps lock の実行を求めます。

プライベートな Git リポジトリは、基盤となる Git のフェッチが現在の環境から認証情報を取得できる 場合にのみサポートされます。これは意図的に移植性のある保証とはしていません。SSH は設定済みの 鍵やエージェントで動作する一方、HTTPS は互換性のある認証情報ヘルパーまたは非対話的な 認証情報プロバイダーが利用可能でない限り失敗することがあります。graphcal.toml の git URL に 認証情報を直接記述しないでください。GRAPHCAL_CACHE_DIR はキャッシュのルートを上書きします。

例:

# Resolve dependencies from the discovered project root
$ graphcal deps lock
wrote /path/to/project/graphcal.lock

# Resolve dependencies for an explicit project root
$ graphcal deps lock --root mission
up to date: /path/to/mission/graphcal.lock

マニフェストの構文とソース解決の規則については、 パッケージ依存関係 を参照してください。

graphcal plugin new¶

graphcal-plugin Rust SDK を使用する新しい WASM プラグインクレートの 雛形を生成します。生成されるのは、Cargo.toml（cdylib + rlib）、 wasm32-unknown-unknown ターゲットを指定した rust-toolchain.toml、サンプルの plugin! ブロックを含む src/lib.rs、ネイティブの単体テスト、justfile、および ビルド・ベンダリング・ピン留めのワークフローを説明する README です。

graphcal plugin new <NAME> [OPTIONS]

引数:

オプション:

終了コード:

$ graphcal plugin new fluid-props
created plugin crate `fluid-props` at fluid-props

graphcal plugin test¶

ビルド済みの .wasm モジュールをプラグイン ABI に対して検証し、その識別情報と シグネチャを出力します。すべての読み込み時チェックは、プラグインコードが実行される前に 行われます。埋め込まれたマニフェストがデコードできること、モジュールが graphcal::fail 以外を 何もインポートしていないこと、そしてマニフェストの各関数の wasm パラメーター/結果の型が 宣言されたシグネチャと一致することが確認されます。成功すると、出力には SHA-256 （graphcal deps lock がピン留めする値）と、.gcl 構文でそのまま貼り付けられる import plugin ブロックが含まれます。モジュールの検査は通常ファイルのみを受け付け、 シンボリックリンクと特殊ファイルは開く前に拒否し、WASM の検証前に最大 16 MiB まで 読み取ります。

graphcal plugin test <MODULE> [--call <FUNCTION> [ARGS]...]

引数:

オプション:

終了コード:

呼び出しは、通常の Graphcal 評価と同じ ABI 値ポリシーを使用します。量の引数と結果 （配列要素とレコードフィールドを含む）は有限でなければならず、Int スロットは正確に 変換できなければならず、Bool スロットは数値の 0 または 1 でなければなりません。 プラグインが返す数値 -0.0 は、別のエンコーディングとして扱われるのではなく、false または 整数のゼロとして受け付けられます。

$ graphcal plugin test plugins/fluid_props.wasm --call lerp 1.0 3.0 0.5
plugin: plugins/fluid_props.wasm
sha256: 3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855c
abi: version 5, 2 function(s)

import plugin "plugins/fluid_props.wasm" as fluid_props {
    fn air_density(p: Length^-1 * Mass * Time^-2, t: Temperature) -> Length^-3 * Mass;
    fn lerp<D: Dim>(a: D, b: D, t: Dimensionless) -> D;
}

lerp(1.0, 3.0, 0.5) = 2

描画される固定次元は、プレリュードの基本次元（マニフェストのアルファベット）の上に 構造的に表記されます。.gcl の宣言では、Pressure のような派生名を同等に書くことが できます。検証は構造的に行われます。--call への配列引数は角括弧で囲んだリテラル （--call share [1.0,3.0]）で、配列の結果も同じ形式で描画されます。構造体を返す関数の 場合、インポートブロックの前に、一緒に貼り付けるための推奨レコード宣言が出力されます。 このブロックはソースコードであるため、Bool 配列には JSON の真偽値（[true,false]）、 Int 配列には JSON の整数（[1,-2,3]）、量の配列には SI 基本単位での JSON の数値を使用します。 Bool の葉に数値の 0/1 は受け付けられません。Int の葉に小数や損失なく表現できない数値は 受け付けられません。結果も同じ意味論的な JSON の葉の種別で描画されます。

このブロックはソースコードであるため、マニフェストの関数名、パラメーター名、ジェネリック名、 結果フィールド名は、予約語ではなく有効な Graphcal 識別子でなければなりません。ワイヤ名を 安全に表現できないモジュールは、それらの名前をブロックに補間する代わりに拒否されます。 Graphcal の文字列リテラルには現在エスケープ構文がないため、引用符や改行を含むモジュールパスも 同様に拒否されます。

graphcal eval¶

.gcl ファイルを評価して結果を出力します。

graphcal eval [OPTIONS] <FILE>

引数:

オプション:

--params-json と --params-json-file は同時に指定できません。繰り返し指定可能な --param の束縛は、選択された JSON ドキュメントを補完できますが、各パラメーター名は CLI のソースのうちちょうど 1 つにのみ現れなければなりません。--param を繰り返したり、 同じ名前を直接と JSON の両方で束縛したりすることは、後勝ちの上書きではなくエラーです。 --params-json-max-bytes は、JSON ソースのいずれかが選択されている場合にのみ有効です。

束縛名は、エントリファイルで直接宣言された修飾なしのパラメーター名です。インポートまたは インクルードされた実装のパラメーターは独立して指定できません。代わりに、エントリの パラメーターを公開し、それを依存先に渡してください。module::x=... のような修飾された 文字列は、葉の名前として解釈されるのではなく、CLI の境界で拒否されます。

エントリファイルの param は、エントリ DAG の名前付き入力ポートです。どのパラメーター オプションでも供給されないポートは、宣言されたデフォルト値を保持します。デフォルト値のない ポートは必須であり、必ず供給しなければなりません。

値は再帰的に閉じていなければなりません。受け付けられる形式には、有限の量、 Int、Bool、datetime(...)、epoch<S>(...)、直交形式の complex(...)、 名前付き/キーのリテラル、完全な代数的コンストラクター、および完全な固定軸のマップリテラルが 含まれ、任意にネストできます。マップのエントリは、宣言されたインデックス付きの値が許容する より多くのキー階層を含むことはできません。過剰にネストされたエントリは形状エラーであり、 スキーマなしで低レベル化されることは決してありません。グラフ参照、2 * PI のような算術、 定数、通常の関数/プラグイン呼び出し、動的単位、条件式、内包表記、match、scan、unfold は 拒否されます。これにより、準備済みの DAG に第二の計算を注入するのではなく、CLI の入力を 型付きデータとして保ちます。

同じ上限付き JSON パーサーが、インライン文字列、ファイル、標準入力を処理します。意味論的な エラーはソース内のパラメーターキーを指し示し、ファイルパス、<--params-json>、または <stdin> のラベルが付き、影響を受けるエントリパラメーター名を含みます。インライン JSON は 小さな生成された呼び出しには便利ですが、シェルの履歴、プロセス一覧、CI のログに記録される 可能性があります。機密性の高い、または大きなパラメータードキュメントには、ファイルまたは 標準入力を使用してください。

デフォルトの --output-view surface は、エントリ DAG が宣言するすべての const、param、node に 加えて、各インクルードが意図的に公開している出力を表示します。ブレースインクルードは、 選択されたローカルエイリアスのみを提供します。インスタンス全体のインクルード （include ... as alias）は、そのエイリアスのもとで param ポートと公開 const/node を 提供します。成功したプライベートな実装の値と、生成側の重複は省略されます。

インクルードされた DAG の完全なインスタンス化状態（束縛された param、プライベートな ヘルパーノード、生成側の値を含む）をデバッグするには、--output-view all を使用します：

graphcal eval mission.gcl --output-view all

このビューは表示のみを変更します。プライベートな宣言を Graphcal のソースから参照可能に することは決してありません。アサーションは常に報告され、失敗した内部の値は surface ビューでも表示されるため、非ゼロの終了コードが説明なしになることはありません。

出力エントリ（テキストと JSON）は、インスタンス全体のインクルードについてはエイリアスで 修飾された完全なパス（例: good.out、good.v_positive）をキーとするため、同じ DAG を 複数回インスタンス化しても衝突せず、JSON 出力がインスタンスを黙って落とすこともありません。 この修飾は出力名にのみ適用され、CLI のパラメーター束縛のインターフェースには影響しません。

テキスト出力は、有限の量を有効数字 7 桁に丸めます。丸めた後の 10 進指数が -4 から 14 までの 場合は位取り表記を、その範囲外では指数表記を使用します。JSON 出力は基礎となる binary64 の 値を保持し、この表示用の丸めを適用しません。

表示のみの失敗は有効な SI 値を保持し、ノードの失敗とは別に報告されます。eval は presentation: 診断を標準エラー出力に出力し、終了ステータス 1 で終了します。JSON 出力には presentation_diagnostics 配列も含まれます。HTML/Markdown レポートは、表示に関する診断を独立したセクションとして表示します。ブラウザとエディターは、有効な値を計算エラーで置き換えることなく、表示に関する通知を表示します。準備済みの行は、回復とデフォルトへのリセットを含めて、行ごとに表示を再計算します。

終了コード:

例:

# Basic evaluation
$ graphcal eval rocket.gcl
dry_mass   = 1200 kg
fuel_mass  = 2800 kg
isp        = 320 s
g0         = 9.80665 m/s^2
v_exhaust  = 3138.128 m/s
mass_ratio = 3.333333
delta_v    = 3778.221 m/s

# Bind all parameters directly
$ graphcal eval rocket.gcl --param 'dry_mass=1200.0 kg' --param 'fuel_mass=3500.0 kg' --param 'isp=320.0 s'
dry_mass   = 1200 kg
fuel_mass  = 3500 kg
isp        = 320 s
g0         = 9.80665 m/s^2
v_exhaust  = 3138.128 m/s
mass_ratio = 3.916667
delta_v    = 4284.301 m/s

# Provide a required param (param declared without a default value)
graphcal eval engine.gcl --param 'dry_mass=800.0 kg'

# Bind several params from inline JSON
graphcal eval engine.gcl --params-json '{"dry_mass":"800.0 kg","mode":"Mode#Nominal"}'

# Read the same JSON schema from a file or stdin
graphcal eval engine.gcl --params-json-file scenario.json
generate-scenario | graphcal eval engine.gcl --params-json-file -

JSON パーサーは、構造化された値のペイロード内のモジュール修飾されたコンストラクターおよび インデックスのパスを保持します。構造化された値内の修飾なしのコンストラクターは、 パラメーターの正規の期待型から解決され、ネストされたレコードに対しては再帰的に解決されます。 そのフィールド値は、型を定義しているモジュールの単位とインデックスのスコープを使用するため、 type Request をインポートするエントリは、Request や、Request のスキーマで使用される 次元、単位、インデックス、ネストされたコンストラクターを追加でインポートする必要はありません。 これらの定義箇所の規則は、準備済み境界でのデコードにのみ適用されます。Graphcal のソースに 書かれたコンストラクターは、引き続き項のインポートです。

トップレベルの JSON キーは引き続きエントリのパラメーター名であり、同じ閉じた値の コンパイラーが、すべてのフィールドとインデックス付きエントリをそのパラメーターの具体的な型に 対して再帰的にチェックします。オブジェクトのキーは、すべてのネストレベルで一意でなければ なりません。同じキーにデコードされるエスケープされた表記も重複とみなされます。 整数構文のトークンは Graphcal の符号付き 64 ビット Int の範囲に正確に収まらなければならず、 浮動小数点として再解釈されることは決してありません。小数点または指数を含むトークンは 有限の binary64 値として解析されます。オーバーフローと非ゼロのアンダーフローは拒否され、 通常の binary64 の丸めは JSON の数値ポリシーに従います。

{
  "phase": { "index": "mission::Phase", "entries": { "Burn": 1, "Coast": 0 } },
  "choice": { "variant": "mission::Pick", "fields": { "distance": "2.0 m" } }
}

複素数のパラメーターは、他の量と同じ式文字列の葉の形式を使用し、次元と単位を 明示的に保ちます：

{
  "displacement": "complex(3.0 m, 4.0 m)"
}

# JSON output
$ graphcal eval rocket.gcl --format json
{
  "const": {
    "g0": {
      "display_value": 9.80665,
      "si_value": 9.80665,
      "unit": "m/s^2"
    }
  },
  "node": {
    "delta_v": {
      "si_value": 3778.2207684937407,
      "unit": "m/s"
    },
    ...
  },
  "param": {
    "dry_mass": {
      "display_value": 1200.0,
      "si_value": 1200.0,
      "unit": "kg"
    },
    ...
  }
}

複素数の出力は各成分を明示的に表現します。si_value は常に SI 基本単位を使用し、 display_value は -> で表示単位が選択された場合に含まれます：

{
  "si_value": { "re": 3.0, "im": 4.0 },
  "display_value": { "re": 300.0, "im": 400.0 },
  "unit": "cm"
}

多重インデックス付きの値（2 次元以上）は、整形されたテーブルとして表示されます：

# Indexed values displayed as tables
$ graphcal eval mission.gcl
delta_v[Departure]  = 2.46 km/s
delta_v[Correction] = 0.12 km/s
delta_v[Insertion]  = 1.83 km/s

spacecraft_mass (kg):
╭─────────┬───────────┬────────────┬───────────╮
│         │ Departure │ Correction │ Insertion │
├─────────┼───────────┼────────────┼───────────┤
│ Launch  │      5000 │          0 │         0 │
│ Cruise  │         0 │       4500 │         0 │
│ Arrival │         0 │          0 │      4000 │
╰─────────┴───────────┴────────────┴───────────╯

1 次元のインデックス付き値はフラットな行のまま表示され、2 次元の値はテーブルグリッドとして 表示されます。3 次元以上の値は、セクション見出し付きの複数の 2 次元テーブルスライスとして 表示されます。単位は、すべてのセルが同じ物理次元、表示スケール、ラベルを持つ場合にのみ、 テーブルのキャプションに一度だけ表示されます。不均一なテーブルでは共有のキャプションを 省略し、量または複素数の各セルに個別にラベルを付けます。

ファイルにアサーションが含まれている場合、評価後にチェックされ、値の下に出力されます：

$ graphcal eval rocket.gcl
dry_mass   = 1200 kg
fuel_mass  = 2800 kg
...

Assertions:
  fuel_budget    PASS
  fuel_positive  PASS
  pressure_safe  FAIL  (assertion evaluated to false)
                       affected: safety_factor

プロット出力¶

ファイルに plot、figure、layer 宣言が含まれている場合、--plot オプションを使用して それらを描画します。3 つの出力モードが利用できます：

ブラウザモードは、すべての図を含む自己完結型の HTML ファイルを生成し （Vega-Embed で描画され、Vega のバンドルが インライン化されているため、ページはネットワークアクセスを必要とせず file:// パスからも 動作します）、デフォルトのブラウザで開きます。通常の評価出力は --format に従って 引き続き出力されます：

graphcal eval analysis.gcl --plot browser

JSON モードは、図オブジェクトの JSON 配列のみを標準出力に出力します。他のツールへの パイプや Vega-Lite エディター への貼り付けに便利です。 このモードでは通常の評価出力は抑制され、--format によって評価値が標準出力に追加される ことはありません：

graphcal eval analysis.gcl --plot json

HTML ファイルモードは、ブラウザモードが生成するものと同じ自己完結型の HTML ページを、 ブラウザを開かずに指定したパス（パスは .html で終わる必要があります）に書き出します。 ヘッドレス環境や CI 環境で便利です。通常の評価出力は --format に従って引き続き 出力されます：

graphcal eval analysis.gcl --plot report.html

配列内の各図は name と spec（Vega-Lite JSON）を持ちます：

[
  { "name": "curve_a", "spec": { /* Vega-Lite spec */ } },
  { "name": "comparison", "spec": { /* Vega-Lite hconcat spec */ } }
]

各 plot 宣言は独立した図を生成します。各 figure 宣言は Vega-Lite の hconcat を 使用した結合チャートを生成します。各 layer 宣言は Vega-Lite の layer を使用した チャートを生成します。#[hidden] が付けられたプロットは独立した出力からは抑制されますが、 それを参照する figure や layer には引き続き現れます。

plot、figure、layer 宣言が見つからない場合、JSON モードは [] を標準出力に、 警告を標準エラー出力に出力します。ブラウザモードは警告を出力し、何も開きません。

言語構文については プロット宣言 リファレンスを参照してください。

graphcal report build¶

モデルから完全に導出された、共有可能で自己完結型のインタラクティブな HTML レポートを ビルドします。プレゼンテーション層を作成する必要はありません。この機能は実験的です。

graphcal report build model.gcl

モデルの隣に model.report.html を書き出します（-o/--output でパスを上書きできます）。 ページはモデルがすでに宣言している内容から導出されます：

コントロールは param の型とドメイン制約に従います。量には単位チェック付きの入力フィールド （有限の min/max 境界が宣言されている場合はスライダーも）、Bool にはチェックボックス、 Int には正確な 10 進数のテキスト入力（両端点とその差が安全な JavaScript 整数である場合に のみ単位ステップのスライダーも）、名前付きインデックス上の Key<Index> にはセレクトが 用意されます。代数的な値にはコンストラクターのセレクトと各フィールドの再帰的なコントロールが 表示され、固定軸のインデックス付き値にはすべての要素が再帰的に（大きな軸ではページ単位で） 表示されます。葉のコントロールは引き続き閉じたリテラルを受け付けるため、量、正確な整数、キー、 日時、およびそれらをネストした組み合わせでも、検査済みの型と単位が保持されます。高度な完全値 入力には Raw literal も利用できます。閲覧者は eval --param と同じ規則のもとで閉じた型付きの 値を束縛します。誤った単位や欠落した単位は該当するネストしたフィールドまたは要素で拒否され、値は 宣言されたドメインを満たす必要があり、式が準備済みモデルに注入されることは決してありません。 Auto run は既定で有効です。編集が短時間止まると、構造的に完成した下書きが検査され、変更して いないフィールドも含むパラメーター全体をアトミックに置き換えます。未完成または拒否された下書きは、 最後に受け付けられた結果を表示し続けます。Auto run を無効にすると、Apply を選ぶまで編集を 未適用のまま保持できます。どちらのモードでも Discard edits は開始時のスナップショットを復元します。 ただし、束縛していないパラメーターのリアクティブな既定値が下書きの編集中に変わった場合、破棄すると その最新の既定値を読み込みます。 新しく選んだコンストラクターの必須フィールドは空で始まり、ゼロ、false、単位、既定値を捏造しません。 自動または手動の実行に成功すると、埋め込まれたエンジン（この CLI と同じコンパイラーと評価器を WebAssembly にコンパイルし、Web Worker で実行するもの）が再評価を行い、値、グリッド、バッジ、 チャートをその場で更新します。静的な値カードとハイドレートされた 値カードは同じ投影を使用します。ランク 2 の値はグリッドになり、より高いランクは、すべての葉と 外側の軸のラベルを保持したラベル付きの 2 軸スライスになります。 構造化された値は、ラベル付きでキーボードフォーカス可能なスクロール領域内に収まるため、 幅の広いグリッドや長いフィールドパスが隣のカードと重なることはありません。

対話型レポートでは、デスクトップ画面で入力の構造に応じたアウトラインと、独立してスクロールできる 結果ペインを並べて表示します。狭い画面では、2 つの窮屈なペインではなく、通常のページスクロールを 使用します。上部に追従する Inputs と Results ボタンで、下書き、ピン留め、結果タブの選択を 保持したまま移動できます。入力欄は行の幅いっぱいに表示し、操作対象をタッチしやすい大きさにします。 幅の広いプロットは指定された寸法を保持し、ページ全体を広げずに、キーボードフォーカス可能な専用領域内で スクロールできます。スカラーと 1 フィールドのレコードは直接編集 できる行として表示し、小さなレコードは展開した状態、大きな構造は必要に応じて開く形式にします。 Search inputs は名前、フィールドパス、パラメーターの説明を検索し、一致する枝を展開します。 星印で入力をピン留めすると、完全なパス付きで編集できます。Pinned only はその他の入力を 非表示にします。ピン留めは現在のブラウザーセッションだけの設定で、ソースや共有する束縛には 含まれません。ネストした入力のピン留めはコンストラクターに関連付けられ、別のコンストラクターの 同名フィールドには引き継がれません。

各行の ⋯ メニューには Apply、Discard edits、利用可能な場合は Use default があります。 これらはその行だけでなく、その行を含むパラメーター全体に作用します。Advanced controls では パラメーターのメタデータ、範囲付きスライダー、元の再帰的フォーム、Raw literal 入力を利用でき、 アウトラインに戻っても下書きを保持します。インデックス付きエディターは完全な下書きを保持したまま、 各軸で最初に 32 要素をマウントします。Show more entries で続きを表示できます。検索でも現在選択中の コンストラクターのページを追加で読み込みますが、追加 128 ページまたは読み込み済みフィールド数が 4096 に達した時点で停止します。検索が制限された場合は通知を表示するので、Show more entries で 続けてください。選択していないコンストラクターのフィールドは検索しません。

結果タブでは値、プロット、チェック、診断（存在する場合）、来歴を切り替えます。出力をピン留めすると、 タブの切り替えや名前による絞り込みにかかわらず表示し続けます。構造化された出力カードは最初は 折りたたまれており、View value で内容を確認できます。 結果領域にフォーカスし、矢印キーを使うと、はみ出した列を確認できます。再計算時も 領域のフォーカスとスクロール位置は 保持されます。画面上では、これらの領域の高さは最大 24 rem（またはビューポートの高さの 60%）に 制限され、短いカードが隣の高いカードに合わせて引き伸ばされることはありません。スクロールすると すべての行を確認でき、値は切り捨てられません。静的レポートでは Report sections リンクと文書形式の レイアウトを維持します。印刷時は入力の検索、出力の絞り込み、出力カードの折りたたみ状態にかかわらず、 受け付け済みの入力値とすべての結果タブを含めます。高さ制限が解除され、 表のセルが折り返され、カードが 1 列に配置されるため、長い表を複数ページにわたって印刷できます。 Markdown 出力にも引き続きすべての値が含まれます。受け付けられたすべての結果は すべてのチャートも整合させます。失敗した、または欠落したプロットは以前のデータを失い、 個別のエラーを表示します。最初に失敗したプロットも、入力の編集後に回復できます。 レンダラーの失敗は明示的であり、古い結果の遅延した描画が現在のチャートを置き換えることは できません。いずれかの入力が公開時のベースラインと異なった瞬間に、ワンクリックでリセット できる永続的なバナーが表示されます。表示されるデフォルト値はリアクティブなままです。 触れられていないコントロールはそのパラメーターを束縛せず、依存するデフォルト値は評価後に 更新されます。その間も開いている下書きは上書きされず、変更が通知され、Discard で受け付け済みの スナップショットを再読み込みできます。自動または手動で実行すると、明示的なパラメーター全体の 閲覧者束縛が作成されます。Use default は、その束縛（ビルド時の上書きを含む）を除いた完全な束縛集合を 検査します。編集した葉が空の場合は未完成として報告されます。リセットは、表示されたすべての デフォルト値のリテラルなコピーではなく、元のビルド時の束縛の集合を正確に復元します。名前付きキーのセレクトは、表示専用の正規名ではなく、ソースで可視な インデックスの表記（インポートされたエイリアスと修飾を含む）を使用した Index#Variant リテラルを発行します。

各 raw 束縛または構造化された葉は UTF-8 で 4096 バイトまでです。構造化パラメーターはさらに 深さ 32、値ノード 4096 個までに制限され、不正な参照や過大なリクエストは評価前に拒否されます。 1 リクエストあたり 256 束縛という既存の上限は変わりません。

成果物は、エンジン、ソース、Vega バンドル、スタイルのすべてがインライン化された単一の ファイルです。オフラインでも、file:// パスからでも、メールの添付ファイルとしても動作します。 静的なベースラインは JavaScript なしで描画されます。チャートとインタラクティブ性には JavaScript が必要です。出力は決定的です。同一のソース、エンジン、コンパイラーからは バイト単位で同一のページが生成され、ビルドのタイムスタンプはありません。

エンジンバンドル。 CLI はリリースに対応する評価器の WebAssembly ビルドを埋め込んでいるため、 インタラクティブなレポートは別途インストール手順なしに任意のディレクトリから動作します。 Graphcal の開発者は、--engine-dir または $GRAPHCAL_REPORT_ENGINE_DIR で wasm-pack build crates/graphcal-wasm --target no-modules の出力を指定して上書きできます。 無効な明示的上書きは、黙って別のエンジンを使用するのではなく失敗します。 --static は、エンジンを埋め込まずに非インタラクティブなレポートをビルドします。

プラグインと依存関係。 インタラクティブなレポートは、ルートプロジェクトと依存パッケージの Wasm プラグイン、マニフェスト、検証済みロックファイルを埋め込みます。ネイティブ評価と同じ 実行量を計測するインタープリターでオフライン実行し、シグネチャの検査、ロックファイルの ピン、fuel 制限、呼び出しの分離を維持します。プラグインはファイルシステムやネットワークに アクセスできません。テキスト専用のプレイグラウンドエディターは、このバイナリーバンドルを受け付けません。

ロックされた依存関係の完全な閉包を、分離したパッケージスナップショットとして埋め込みます。 推移的依存関係や複数バージョンも対象です。インポートを書き換えずに、エイリアス、バージョン、 依存辺を維持します。各パッケージは自身のプラグインポリシーを保持します。レポートを開く際に パッケージを取得したり、ネイティブのキャッシュを読んだりすることはありません。元のチェックアウトと キャッシュを削除した後でも動作します。レポートを作る前に graphcal deps lock でロックを作成してください。

依存スナップショットは、ハッシュ対象の全バイト列を保持します。マニフェスト、補助データを含む ソースディレクトリ、およびそのディレクトリ外のインポート済み Wasm ファイルが対象です。 ブラウザーはプラグイン登録前に、グラフ、ハッシュ、成果物のパス、リソース予算を再検証します。 依存成果物の欠落、余分な追加、変更は拒否されます。この整合性検査は発行者の署名ではありません。 HTML を置き換えられる人は、埋め込みロックファイルも置き換えられます。

HTML の共有は、ルートソース、完全な依存スナップショット、プラグインバイナリー、パッケージの メタデータ、ベースラインのパラメーター値を開示します。配布前に成果物を確認してください。 診断や Issue 報告には合成フィクスチャを使用してください。

レポートバンドルの上限は 1024 依存パッケージ、全パッケージ合計で 4096 成果物、 成果物ごとに 16 MiB、デコード後の内容の合計が 64 MiB（JSON エンベロープは 96 MiB）です。既存のローダーとプラグインの制限も適用されます。 無効または上限を超えるバンドルは、黙って静的レポートになるのではなく明示的に失敗します。

ワーカーの期限に達すると、ワーカー全体を置き換えてブロック中の評価をキャンセルします。 その後に有効な値へ編集すると、評価を再開できます。リソースポリシーを黙って切り下げたり、 未対応モデルを黙って静的に変換したりすることはありません。非インタラクティブなベースラインが 意図的に必要な場合だけ --static を使用してください。

オプション：

終了コード: 0 は成功。1 はレポートは書き出されたが、評価エラーまたは失敗した アサーションを含む（エラーチップと FAIL バッジとして描画されます）。2 はプロジェクトの コンパイルに失敗したか、ハイドレートできない（何も書き出されません）。

graphcal model serve¶

Graphcal プロジェクトを一度準備し、stdio Arrow IPC 経由で永続的な Tenax モデルとして 公開します。

graphcal model serve <FILE> --output <NAME> [--output <NAME> ...] [--root <ROOT>]

引数とオプション:

初期の統合では、Tenax stdio プロトコルバージョン 1 と Arrow スキーマ契約バージョン 2 を 実装しています。プロジェクトとプラグインを一度コンパイルし、スキーマのみの発見ストリームに 続いて 1 つの永続的な結果ストリームを標準出力に出力し、1 つの永続的なリクエストストリームを 標準入力から読み取り、リクエスト行を順次評価します。標準出力には Arrow IPC のみが含まれます。 人間向けの診断とログは標準エラー出力に送られます。

Tenax v2 は、デフォルト値を持つパラメーターを含むすべてのエントリパラメーターを公開します。 完全なインターフェースには、少なくとも 1 つの入力と 1 つの選択された出力が含まれていなければ なりません：

Bool、datetime、複素数、代数的、インデックス付き、座標キー、有限キーの入力は、Graphcal の 準備済み束縛コアではサポートされていますが、Tenax スキーマ v2 では表現できません。これらは 平坦化や強制変換されるのではなく、モデルの準備を失敗させます。選択される出力は、現在のところ 明示的に pub で、スカラーの Bool ノードでなければなりません。不明、プライベート、重複、 非 Boolean の選択は、IPC のバイトが書き込まれる前に失敗します。

モデルの例：

pub index Mode = { Nominal, Degraded };

param load: Force(min: 0.0 N, max: 10_000.0 N);
param cycles: Int(min: 0, max: 100_000);
param mode: Key<Mode>;

pub node failure: Bool =
    @load > 8_000.0 N && @cycles > 50_000 && @mode == Mode#Degraded;

graphcal model serve reliability.gcl --output failure

モデル/ランタイム/ドメイン/アサーションの失敗は、null の出力と診断を持つ失敗した結果行に なります。不正な形式の Arrow、スキーマの不一致、無効な共有入力ドメインの値、重複した 評価 ID、壊れたパイプ、内部の不変条件の失敗は、プロセスを無効化します。リクエストストリームの 正常な EOS は結果ストリームを完了させ、正常に終了します。ライフサイクル図とクライアント向けの ガイダンスについては Tenax 統合 を参照してください。

終了コード:

graphcal format¶

.gcl ファイルをフォーマットします。ディレクトリが指定された場合、その中の通常の .gcl ファイルを再帰的にフォーマットします。ディレクトリ走査中に見つかったシンボリック リンクのエントリはスキップされ、明示的に指定されたシンボリックリンクのパスは辿られずに 拒否されます。

フォーマットはプログラムの意味を変えずにレイアウトを整え、表示幅 100 カラムを目安とします。 リストの末尾にカンマを付けると、複数行のレイアウトを指定できます。

ファイルはその場で置き換えられます。パーミッションは保持されますが、所有者、ACL、 拡張属性、ハードリンクの同一性は保持されません。ファイルを変更せずに確認するには --check を使ってください。

graphcal format [OPTIONS] [PATHS]...

引数:

オプション:

例:

# Format all .gcl files in the current directory
graphcal format

# Format specific files
graphcal format rocket.gcl hohmann.gcl

# Check formatting in CI (non-destructive)
graphcal format --check

終了コード:

graphcal check¶

ランタイム評価なしで .gcl ファイルをチェックします。構文解析、モジュールと名前の解決、型/次元/ポリシーの検証、コンパイル時定数のチェック、および extern シグネチャの検証を行います。通常のノード、アサーション、動的な単位スケール、呼び出し可能なホスト関数は評価しません。

graphcal check [OPTIONS] [PATHS]...

それ以外に問題のない未完成のノードについては概要を表示し、検査自体は成功します。未使用の DAG 定義も含めて式の完成を必須にするには --deny-todo を指定します。この場合も静的検査であり、実行時の値のドメイン検証ではありません。

引数:

例:

# Check all .gcl files in the current directory
graphcal check

# Check a specific file
graphcal check rocket.gcl

# Check a directory
graphcal check my_project/

終了コード:

graphcal dump¶

コンパイラーまたは評価器の成果物を 1 つデバッグ出力します：

graphcal dump <STAGE> <FILE> [OPTIONS]

意図的に、all ステージ、JSON 形式、フィルタリング言語、レコードエンベロープ、互換性の 保証はありません。デバッグセッションに必要な特定のステージを実行してください。 HirProject はダンプ専用の投影ではなく、実際のコンパイラーの継続です。すべての ファイルルートおよびインライン DAG の HIR モジュールを所有し、静的チェックがそれを消費して CheckedProject を生成します。

source、tokens、ast、desugared はインポートを辿りません。modules は HIR への 低レベル化の前で停止します。hir は完全なプロジェクトを解決しますが、TIR を構築せず、 式の型/次元をチェックせず、定数を評価せず、ホストシグネチャを検証しません。したがって、 後段の静的チェックが失敗しても hir は利用可能なままです。tir と plan は、通常の ランタイムパラメーター、ノード、アサーション、動的な単位スケール、呼び出し可能なホスト関数を 評価しません。runtime と result のみが通常のランタイム評価を実行します。

例：

graphcal dump tokens model.gcl
graphcal dump ast model.gcl
graphcal dump modules src/mission/main.gcl --root .
graphcal dump hir model.gcl
graphcal dump tir model.gcl
graphcal dump plan model.gcl
graphcal dump runtime model.gcl --param 'mass=1200 kg'
graphcal dump result model.gcl --params-json-file params.json

すべてのステージは --root を受け付けます。runtime と result はさらに、 graphcal eval の上限付き --param、--params-json、--params-json-file、 --params-json-max-bytes パーサーを再利用します。 失敗したステージは通常の診断を出力し、コード 2 で終了します。ノード、アサーション、 プロットの失敗を含む完了した runtime/result のダンプは、それでも出力され、コード 1 で 終了します。

graphcal graph¶

graphcal graph は実験的です。DAG ビジュアライザー の設計が進化する間、DOT 出力（ノードの命名、ラベル、スタイル）と CLI のインターフェース （フラグ、形式）はどのリリースでも変更される可能性があります。このコマンドはその旨の警告を 標準エラー出力に出力します。標準出力にはエクスポートされたグラフのみが含まれます。

.gcl ファイルの依存関係グラフを、外部の描画ツール向けのテキストとしてエクスポートします。 グラフはコンパイルされたプログラムの一方向の投影です。param、const node、node 宣言は 頂点になり、すべての @ 参照は、読み取られる値からそれを読み取る宣言への有向辺になります。 この投影は、各インスタンスの背後にある再利用可能なテンプレートを含め、ソースモジュールと 具体的なインクルードインスタンスの来歴を保持します。アサーション、プロット、figure、layer は データフローの一部ではないため省略されます。

graphcal graph [OPTIONS] <FILE>

引数:

オプション:

3 つのビューは、概要から詳細へのワークフローをサポートします：

• flat: 構成の境界なしで、すべての宣言と依存辺を表示します。繰り返し現れる宣言名は 所有者で修飾されるため、詳細なデバッグビューは曖昧になりません。
• grouped（デフォルト）: 同じ宣言レベルのグラフを、ルートモジュール、インライン DAG 定義、具体的なインクルードインスタンス、参照される外部モジュールごとに、実際の Graphviz の cluster_* サブグラフに配置します。クラスターは構成に従ってネストし、インクルードのラベルは その再利用可能なテンプレートを識別し、クラスター間の辺は実際のソースと受け取り側の宣言ノードを 結びます。したがって、パラメーターの束縛は受け取り側クラスターの境界ではなく、束縛される パラメーターで終端します。
• module: ソースモジュールまたはインクルードインスタンスごとに 1 つのノードを表示します。 内部の配線は隠され、宣言の依存関係は重複除去されたモジュールレベルのデータフロー辺に 折りたたまれ、破線の辺は包含またはインスタンス化を示します。

-L/--max-depth は、tree -L スタイルのレベルを使用して grouped ビューの展開を 制限します。ルートはレベル 1 です。-L 1 はルートの宣言を表示し、直接の子 DAG をそれぞれ サマリーに折りたたみます。-L 2 は直接の子を展開し、孫を折りたたみます。サマリーは、隠された サブツリー全体に含まれる宣言値の数を報告します。折りたたまれた境界を越える依存関係は サマリーにリダイレクトされ重複除去されるため、モジュールレベルのデータフローは黙って 消えるのではなく可視のままです。-L を省略するとすべてのクラスターが完全に展開されます。 このオプションは flat および module ビューでは拒否されます。

出力は決定的（宣言はソースの順序を保ち、辺はソートされます）なので、エクスポートされた グラフはバージョン管理においてきれいに差分を取ることができます。DOT の文の識別子 （n0、n1、…、折りたたまれたサマリー s0、s1、…、クラスター cluster_c0、 cluster_c1、…、モジュール m0、m1、…）は不透明なレンダラーローカルの ID です。 意味論的なコンパイラー名はラベルとしてのみ現れます。これにより、 たまたま同じ表示パスを持つ別々のパッケージバージョンや、ソースモジュールと具体的な インスタンスを Graphviz がマージすることを防ぎます。

終了コード:

例:

# Render the default composition-preserving graph to SVG
graphcal graph rocket.gcl | dot -Tsvg -o rocket.svg

# Keep root detail but collapse direct child DAG internals
graphcal graph composed-model.gcl -L 1 | dot -Tsvg -o overview.svg

# Expand direct child DAGs but collapse nested children
graphcal graph composed-model.gcl -L 2 | dot -Tsvg -o two-levels.svg

# Render an architecture overview with one node per DAG
graphcal graph rocket.gcl --view module | dot -Tsvg -o rocket-modules.svg

宣言レベルのビューでは、param 宣言は楕円（グラフの入力）、const node 宣言は角丸の ボックス、node 宣言は通常のボックス、公開された計算出力は緑の二重枠線、他のファイルから インポートされた値は破線のボックスで表示されます。各頂点のラベルには宣言名と解決された型が 表示されます。grouped ビューと module ビューには凡例が含まれます。複数の宣言が通常の 表示パスを共有する場合、修飾されたラベルはパッケージの識別情報を別の package … 行に置き、 字句的な（.）階層辺と具体的インスタンスの（@）階層辺を区別します。DOT のラベルが、 Graphcal のパス構文の一部ではない :: 区切りを勝手に作り出すことはありません。

graphcal lsp¶

Language Server Protocol（LSP）サーバーを起動します。サーバーは標準入出力経由で通信し、エディターから起動されることを想定しています。

graphcal lsp

このコマンドに追加のオプションはありません。LSP を使用するようにエディターを設定する方法については エディターのセットアップ を参照してください。

LSP の機能¶

LSP サーバーは以下を提供します：

• 診断 -- リアルタイムの構文解析エラー、次元の不一致、不明な参照、アサーションの失敗
• インレイヒント -- 計算された param/node の値をインラインで表示
• 定義へ移動 -- 参照から宣言へ移動
• ホバー -- 解決された型と次元の情報を表示
• 参照の検索 -- 宣言のすべての使用箇所を検索
• ドキュメントシンボル -- すべての宣言のアウトライン表示
• フォーマット -- 現在のドキュメントをフォーマット
• ドキュメントリンク -- クリック可能な import パス