query

コンテキスト関数

コンテキスト関数

コンテキスト関数は、コンテキストが既知の場合にのみ使用できます。

文書中の要素の検索。

query関数を用いると特定の型やラベルを持った要素を文書内から探すことができます。 使用するにはまずコンテキストが利用可能であることを確かめる必要があります。

要素の探索

以下の例では、outlineを用いる代わりに手動で目次を作成しています。

このために、まず第1レベルの見出しでoutlinedがtrueなものを検索します。 この例において第1レベルの見出しのみを検索する目的は、第2レベル以下の見出しが目次に含まれないようにすることです。 outlinedフィールドは"Table of Contents"という見出し自身を取り除くために使われます。

query関数を使用可能にするために、contextを作成していることに注意してください。

#set page(numbering: "1")

#heading(outlined: false)[
  Table of Contents
]
#context {
  let chapters = query(
    heading.where(
      level: 1,
      outlined: true,
    )
  )
  for chapter in chapters {
    let loc = chapter.location()
    let nr = numbering(
      loc.page-numbering(),
      ..counter(page).at(loc),
    )
    [#chapter.body #h(1fr) #nr \ ]
  }
}

= Introduction
#lorem(10)
#pagebreak()

== Sub-Heading
#lorem(8)

= Discussion
#lorem(18)

ページ番号を取得するために、まずlocationメソッドを用いてqueryが返す要素のロケーションを取得します。 続けて、その位置にあるページの番号付けとページカウンターを取得し、カウンターに番号付けを適用します。

注意事項

全てのクエリを解決するために、Typstは文書の評価とレイアウトを複数回行います。 しかしながら、実際にクエリが完全に解決されるかは保証されません。 注意しないとクエリ自身に影響しうるクエリを書いてしまい、結果が決して収束しなくなります。

以下の例では、文書中の全ての見出しを検索し、同じ数だけ見出しを生成しています。 最初はRealという見出しが1つだけあります。 したがって、countは1で、Fakeという見出しが作成されます。 Typstはクエリの結果が変わったことに気づき、再度処理を行います。 このときcountは2で、 2つのFake見出しが作成されます。 これが延々と続きます。 ご覧の通り、出力には有限個の見出ししかありません。 これは単にTypstが数回試行した後に諦めるためです。

一般に、クエリ自身に影響を与えるようなクエリを書こうとしてはいけません。 カウンターや状態などの他の内省機能にも同じ注意が必要です。

= Real
#context {
  let elems = query(heading)
  let count = elems.len()
  count * [= Fake]
}

コマンドラインクエリ

typst queryコマンドを用いてコマンドラインからクエリを実行することもできます。 このコマンドは文書上で任意のクエリを実行し、シリアライズされた形で結果の要素を返します。 以下の何らかの不可視のメタデータを含んだexample.typファイルを考えます。

#metadata("This is a note") <note>

Typst CLIを用いて以下のようにこのファイルに対してクエリを実行できます。

$ typst query example.typ "<note>"
[
  {
    "func": "metadata",
    "value": "This is a note",
    "label": "<note>"
  }
]

結果となる要素の特定の1つのフィールドにのみ興味があることが多いです。 metadata要素の場合、valueフィールドが興味の対象です。 --field引数を用いてこのフィールドのみを抽出できます。

$ typst query example.typ "<note>" --field value
["This is a note"]

単一の要素にのみ興味がある場合は、--oneフラグを用いてその要素のみを抽出できます。

$ typst query example.typ "<note>" --field value --one
"This is a note"