Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

仕様検索クエリ

SpecForgeは仕様を整理するためのツールとして設計されており、各仕様にdocstring、ラベル、エイリアス、カスタムフィールドで注釈を付けることができます。SpecForgeシステムでは、CLIまたはVSCode拡張機能のサイドバーを使用して、関連する仕様を問い合わせることができます。

クエリの構文と意味論

仕様検索は、GitHub検索構文やLIQEに類似したクエリ言語を使用します。

docstringや定義名に基づくあいまい検索または完全一致検索、数値フィールドの比較、ラベルによるフィルタリング、および複数のフィルターのブール結合をサポートしています。仕様は数値フィールドを使用してソートすることもできます。

基本構文

あいまい検索と完全一致のテキスト検索

テキストを使用して仕様を検索するには、クエリを直接入力します。例えば、pumpという入力に対しては、名前、エイリアス、またはdocstringにpumpを含む仕様を検索します。

デフォルトでは、テキスト検索はあいまい検索です。完全一致検索を行うには、引用符を使用します（例："pump"）。

複数のあいまい検索語または完全一致検索語（スペースで区切られたもの）がある場合、クエリはこれらのクエリの論理和として解釈されます。例えば、クエリtube "pump"は、tubeにあいまい一致するか、"pump"に完全一致する仕様に一致します。

フィールドに対する述語

クエリでは、カスタムフィールドの値に基づくフィルターを指定できます。

  • 比較： priorityという名前のフィールドがある場合、priority:>50、priority:>=50などのクエリを書くことができます。
  • 真偽値： Boolean型のフィールドreviewedがある場合、reviewed:trueまたはreviewed:falseと書くことができます。
  • 文字列： 文字列型のフィールドreviewerを参照するには、reviewer:Samまたはreviewer:"Samwell Tarly"と書くことができます。
  • コンストラクタ： 述語を使用してコンストラクタと照合することができます。これを行うには、通常通りコンストラクタの前に#を付けます。例：color:#Red

ラベル

クエリでは、ラベルを使用してフィルタリングすることが可能です。例えば、label:todoはtodoラベルを持つすべての項目に一致します。

システム

クエリでは、仕様が属するシステムに基づいてフィルタリングすることもできます。例えば、system:engineはengineシステム内の仕様にのみ一致します。system:cooling::pumpのような修飾名を指定することもできます。

依存関係

depends-on:構文を使用すると、仕様の定義に使用されている他の仕様、def、signal、paramに基づいて仕様をフィルタリングできます。例えば、depends-on:pressureはpressureというsignal（またはpressureという名前のdefやparam）に依存する仕様に一致します。depends-on:chamber2::pressureのような修飾名を指定することもできます。

論理結合

クエリ言語は、AND、OR、NOTを使った複数のクエリの論理結合による組み合わせもサポートしています。クエリをグループ化するには、括弧を使用します。

NOT演算子は、-接頭辞を使用して書くこともできます。例えば、-label:todoはNOT label:todoと等価です。

明示的な接続詞が使われていない場合、クエリは以下のように解釈されます： 基本構文のグループがスペースで区切られている場合、あいまいテキスト検索語と完全一致テキスト検索語は論理和を用いて結合され、述語は論理積を用いて結合されます。例えば、tube "pump" priority:>50 label:todoは、(tube) OR ("pump") AND (priority > 50) AND (label:todo)として解釈されます。このほか、(NOT priority:>10) reviewed:true label:important foo barは、(NOT priority > 10) AND reviewed:true AND label:important AND (foo OR bar)として解釈されます。

並べ替え

クエリの結果を並べ替えるには、sort:キーワードの後にフィールド名を指定します。例えば、クエリの末尾にsort:priorityを追加すると、結果がpriorityフィールドの降順で並べ替えられます。

昇順で並べ替えるには、フィールド名の末尾に-ascを追加します。例えば、sort:priority-ascは、結果をpriorityフィールドの昇順で並べ替えます。同様に、-descを追加すると降順で並べ替えられます。デフォルトでは、並べ替えは降順です。

複数のsortクエリを使って、同点時の並べ替えルールを指定することができます。例えば、sort:priority sort:created_atは、結果をpriorityの降順で並べ替え、同点の場合はcreated_atの降順で並べ替えます。

並べ替えは、スペースで区切ることでフィルタリングクエリと組み合わせることができます。例えば、label:todo sort:priorityは、todoラベルを持つ仕様をフィルタリングし、priorityフィールドで並べ替えます。

検証

クエリの結果が論理的な整合性条件を満たしているかを確認したい場合がしばしばあるかと思います。例えば、todoラベルを持つすべての仕様のpriorityフィールドが50より大きいかを確認したい場合などです。

validate CLIコマンドを使うと、前件クエリの結果が後件クエリの結果に含まれていることを確認できます。上記の例の場合、ターミナルで以下のコマンドを実行することで確認できます：

specforge validate --antecedent 'label:todo' --consequent 'priority:>50'

また、以下のようにspecforge.tomlに検証ルールを指定することもできます（プロジェクト設定を参照）：

[[validation_rules]]
antecedent = "label:todo"
consequent = "priority:>50"

[[validation_rules]]
antecedent = "label:blue OR label:green"
consequent = "label:grue"

引数なしでspecforge validateを実行すると、specforge.tomlで指定されたすべての検証ルールが確認されます。また、VSCode拡張機能は、specforge.tomlファイル内の満たされていない検証ルールについて自動的に警告を表示します。

一括ラベル付け

bulk-label CLIコマンドを使用すると、クエリに一致するすべての仕様にラベルを追加できます。例えば、以下のコマンドはpriorityが50より大きいすべての仕様にimportantラベルを追加します：

specforge bulk-label --query 'priority:>50' --label 'important'

同様に、以下のコマンドはlabel:greenまたはlabel:blueを満たすすべての仕様にgrueラベルを追加します：

specforge bulk-label --query 'label:green OR label:blue' --label 'grue'