Prequery

https://typst-community.github.io/prequery/
Admin
Prequery is a Typst package and command line tool that allows you to get external information into...
Tokens:7,538
Snippets:101
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Interactive Python Notebook Example

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Demonstrates how to create an interactive Python notebook where later code blocks can depend on the results of earlier ones. This setup requires a Python script to manage execution and output.

```typst
#metadata((path: "out.json"))<python>

#metadata((data: ```py
x = 1
```.text))<python>

#metadata((data: ```py
y = x + 1
```.text))<python>
```

--------------------------------

### Query Configuration

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

These examples show how to configure the query selector and field for the shell preprocessor.

```typst
query.selector = "<shell>"
```

```typst
query.field = "value"
```

--------------------------------

### Install prequery using cargo-binstall

Source: https://typst-community.github.io/prequery/quickstart/installation.html

Use cargo-binstall to install prequery by referencing its git repository. This method avoids manual compilation.

```bash
cargo binstall --git https://github.com/typst-community/prequery-preprocess prequery-preprocess
```

--------------------------------

### Install prequery stable from source

Source: https://typst-community.github.io/prequery/quickstart/installation.html

Install the stable version of prequery from its git repository using cargo install, specifying a tag for the version.

```bash
cargo install --locked --git https://github.com/typst-community/prequery-preprocess --tag v0.2.0
```

--------------------------------

### Install prequery nightly from source

Source: https://typst-community.github.io/prequery/quickstart/installation.html

Install the nightly version of prequery from its git repository using cargo install. This method typically adds the binary to your PATH automatically.

```bash
cargo install --locked --git https://github.com/typst-community/prequery-preprocess
```

--------------------------------

### Execute Python Script and Render Output

Source: https://typst-community.github.io/prequery/package/prequeries.html

Example of how to use a prequery to execute a Python script and display its output. The output is saved to 'out.txt'.

```typst
#python("out.txt", ```py
print("hello world")
```)
```

--------------------------------

### Run the Prequery Preprocessor

Source: https://typst-community.github.io/prequery/quickstart/preprocessor.html

Execute the `prequery` command with your main Typst file as an argument to process the configured jobs. This step downloads any specified web resources.

```bash
prequery main.typ
```

--------------------------------

### Configure Prequery Jobs in typst.toml

Source: https://typst-community.github.io/prequery/quickstart/preprocessor.html

Define prequery jobs, like downloading web resources, within the `typst.toml` file. Each `[[tool.prequery.jobs]]` entry specifies a job to be executed when running the `prequery` command.

```toml
[package]
name = "..."
version = "0.0.1"
entrypoint = "..."

[[tool.prequery.jobs]]
name = "download"
kind = "web-resource"
```

--------------------------------

### Implement the image() prequery

Source: https://typst-community.github.io/prequery/package/prequeries.html

This prequery shadows the built-in `image()` function to provide custom preprocessing. It utilizes the `prequery()` function with metadata, a resource type, and a fallback image.

```typst
#let image(
  url,
  ..args,
) = prequery(
  (url: url, path: args.pos().at(0)),
  <web-resource>,
  std.image.with(..args),
  fallback: [\u{1F5BC}],
)
```

--------------------------------

### Command Output Formatting

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Explains how to set the output format for commands, defaulting to JSON and allowing plain text output.

```typst
format.stdout = "plain"
```

--------------------------------

### Command Input via Stdin (Plain Text)

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Shows how to configure stdin to pass plain text to commands, useful when all values are strings.

```typst
format.stdin = "plain"
```

--------------------------------

### Prequery Web Resource Download Output

Source: https://typst-community.github.io/prequery/quickstart/preprocessor.html

Observe the output of the `prequery` command when downloading web resources. This output indicates the progress of each download job.

```text
[download] beginning job...
[download] Downloading to example.png: https://example.com/example.png...
[download] Downloading to example.png finished
[download] job finished
```

--------------------------------

### Compile Typst Document with Prequery Fallback

Source: https://typst-community.github.io/prequery/quickstart/documents.html

Compile your Typst document using the command line, enabling the prequery fallback option. This allows for previewing even if external images are not yet downloaded.

```bash
typst compile --input prequery-fallback=true main.typ
```

--------------------------------

### Compile Typst Document After Preprocessing

Source: https://typst-community.github.io/prequery/quickstart/preprocessor.html

After running `prequery` and preparing resources, compile your Typst document using the `typst compile` command.

```bash
typst compile main.typ
```

--------------------------------

### Command Input via Stdin (JSON)

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Demonstrates the JSON data passed to commands via stdin when metadata contains complex values.

```json
"any value"
```

```json
["complex","value",2]
```

--------------------------------

### Enable Prequery Fallback for Previewing

Source: https://typst-community.github.io/prequery/quickstart/documents.html

Toggle the fallback option to preview your document without downloading external images. This can be done directly in the code or via the command line.

```typst
// toggle this comment or pass `--input prequery-fallback=true` to enable fallback
// #prequery.fallback.update(true)
```

--------------------------------

### Output File Format (Plain Text)

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Use 'format.output = "plain"' to store command results as plain text files when each output is in a separate file and the command returned text.

```typst
format.output = "plain"
```

--------------------------------

### Use prequery image function

Source: https://typst-community.github.io/prequery/package/prequeries.html

Call the image function from the prequery package with a URL and a local filename. This demonstrates how prequery handles external image sources.

```typst
#image("https://example.com/example.png", "example.png")
```

--------------------------------

### Configure Web Resource Job

Source: https://typst-community.github.io/prequery/preprocessors/web-resource.html

Defines a web-resource job within the Prequery configuration. Requires a name and specifies the kind as 'web-resource'.

```toml
[[tool.prequery.jobs]]
name = "..."  # required
kind = "web-resource"

# the query getting metadata from the document
# see https://typst.app/docs/reference/introspection/query/#command-line-queries
query.selector = "<web-resource>"
query.field = "value"
# query.one = false  # this can not be changed for web-resource jobs

# force re-downloading existing files
overwrite = false
# can be set to `true` or a file name to keep a file with all known resources
index = false
```

--------------------------------

### Advanced Python Prequery with JSON Output Handling

Source: https://typst-community.github.io/prequery/package/prequeries.html

A detailed implementation of the `#python` prequery that handles JSON output. It retrieves the file path from state, calculates the correct output index, and renders the output.

```typst
#let python(code) = prequery.prequery(
  (data: code.text),
  <python>,
  () => {
    // get the file path, as args
    let args = python-out-path.get()
    // get the number of preceding <python> metadata,
    // zero-based and correcting for `configure-python`
    let index = query(selector(<python>).before(here())).len() - 2
    let outputs = json(..args)
    raw(block: true, outputs.at(index))
  },
  fallback: [
    ```
        ...
        ```
  ],
)
```

--------------------------------

### Individual File Output Mode

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Use this mode when each queried value needs to be stored in its own file. The metadata must include 'path' and 'data' keys.

```typst
#metadata((path: "file1.json", data: "any value"))<shell>
```

```typst
#metadata((path: "file2.json", data: ("complex", "value", 2)))<shell>
```

--------------------------------

### Configure Python for Plain Text Input/Output

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Configure the `python` command to accept and produce plain text. This is useful for running individual Python scripts without JSON encoding/decoding.

```toml
query.selector = "<python>"
command = "python"
format.stdin = "plain"
format.stdout = "plain"
```

```toml
query.selector = "<python>"
command = "python"
format.stdin = "plain"
format.stdout = "plain"
```

```toml
query.selector = "<python>"
command = "python"
format.stdin = "plain"
format.stdout = "plain"
```

```toml
query.selector = "<python>"
command = "python"
format.stdin = "plain"
format.stdout = "plain"
```

--------------------------------

### Python Prequery with Fallback Content

Source: https://typst-community.github.io/prequery/package/prequeries.html

Extends the `python` prequery function to include fallback content. If the primary content cannot be rendered, the fallback content is displayed. It reads the output from a file and renders it as raw block content.

```typst
#let python(
  ..args,  // this contains the file path
  code,
) = prequery.prequery(
  (data: code.text, path: args.pos().at(0)),
  <python>,
  // a function without parameters, only called if not in fallback mode
  () => {
    let output = read(..args)  // the file path is relative to the caller
    raw(block: true, output)
  },
  // the fallback content, only rendered if in fallback mode
  fallback: [
    ```
        ...
        ```
  ],
)
```

--------------------------------

### Basic Shell Job Configuration

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Defines a shell job with a name and specifies the command to execute. Paths are relative to the containing `typst.toml` file.

```toml
[[tool.prequery.jobs]]
name = "..."  # required
kind = "shell"

# the query getting metadata from the document
# see https://typst.app/docs/reference/introspection/query/#command-line-queries
query.selector = "..."  # required
query.field = "value"
query.one = false

command = "..." # required, can also be an array like `["ls" "-l"]`

# execute a single command with an array of all inputs
joined = false

# data passed to commands via stdin is in JSON format
format.stdin = "json"

# data received for commands via stdout is in JSON format
format.stdout = "json"

# data written to files for prequeries to read is in JSON format
format.output = "json"
```

--------------------------------

### Web Resource Job with Custom Index File

Source: https://typst-community.github.io/prequery/preprocessors/web-resource.html

Configures a web-resource job to use a custom-named index file for tracking resources. This allows for more granular control over resource synchronization.

```toml
[[tool.prequery.jobs]]
name = "..."  # required
kind = "web-resource"

# the query getting metadata from the document
# see https://typst.app/docs/reference/introspection/query/#command-line-queries
query.selector = "<web-resource>"
query.field = "value"
# query.one = false  # this can not be changed for web-resource jobs

# force re-downloading existing files
overwrite = false
# can be set to `true` or a file name to keep a file with all known resources
index = "my-custom-index.toml"
```

--------------------------------

### Combined Input for Shell Command

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

When `joined = true`, a single command is run for all inputs, provided as a JSON array. Output must also be a JSON array of the same length.

```json
["any value",["complex","value",2]]
```

--------------------------------

### Import Prequery Image Function

Source: https://typst-community.github.io/prequery/quickstart/documents.html

Import the Prequery image function for use in your Typst document. This allows you to reference external images.

```typst
#import "@preview/prequery:0.2.0": image
```

--------------------------------

### Single File Output Mode

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Use this mode to store all results as a JSON array in a single file. The first metadata entry must have a 'path' key, followed by entries with only a 'data' key.

```typst
#metadata((path: "file.json"))<shell>
```

```typst
#metadata((data: "any value"))<shell>
```

```typst
#metadata((data: ("complex", "value", 2)))<shell>
```

--------------------------------

### Embed External Image with Prequery

Source: https://typst-community.github.io/prequery/quickstart/documents.html

Use the Prequery `image` function to embed an external image by providing its URL and a local filename. This prepares the image for download by an external tool.

```typst
#figure(
  image("https://example.com/example.png", "example.png"),
  caption: [An image],
)
```

--------------------------------

### Configuring Python Output Path with State

Source: https://typst-community.github.io/prequery/package/prequeries.html

Defines a state variable `python-out-path` and a configuration function `configure-python` to manage the output file path for Python prequeries.

```typst
#let python-out-path = state("python-out-path")

#let configure-python(..args) = {
  [#metadata((path: args.pos().at(0)))<python>]
  python-out-path.update(args)
}
```

--------------------------------

### Preprocessor Configuration for Python Execution

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Configuration settings for the preprocessor to execute Python code snippets. It specifies the selector for Python code blocks and the command to run the execution script.

```typst
query.selector = "<python>"
command = ["python", "exec.py"]
joined = true
```

--------------------------------

### Python Execution without Explicit File Name

Source: https://typst-community.github.io/prequery/package/prequeries.html

Shows how to call the `#python` prequery without specifying an output file name, useful for notebook-like structures. The code is embedded directly.

```typst
#python(```py
print("hello world")
```)
```

--------------------------------

### Python Execution with `pre-py` Syntax

Source: https://typst-community.github.io/prequery/package/prequeries.html

An alternative syntax for embedding Python code using the ```pre-py``` block within the `#python` prequery.

```typst
#python(```pre-py
print("hello world")
```)
```

--------------------------------

### Web Resource Job with Indexing Enabled

Source: https://typst-community.github.io/prequery/preprocessors/web-resource.html

Configures a web-resource job to use an index file for better synchronization of local files and remote resources. The default index file name is 'web-resource-index.toml'.

```toml
[[tool.prequery.jobs]]
name = "..."  # required
kind = "web-resource"

# the query getting metadata from the document
# see https://typst.app/docs/reference/introspection/query/#command-line-queries
query.selector = "<web-resource>"
query.field = "value"
# query.one = false  # this can not be changed for web-resource jobs

# force re-downloading existing files
overwrite = false
# can be set to `true` or a file name to keep a file with all known resources
index = true
```

--------------------------------

### Define image function with direct argument passing

Source: https://typst-community.github.io/prequery/package/prequeries.html

Define a custom image function that forwards all arguments directly to the prequery image function. This highlights a different approach to argument handling.

```typst
#let my-image2(..args) = image(..args)
```

--------------------------------

### Define image function forwarding arguments

Source: https://typst-community.github.io/prequery/package/prequeries.html

Define a custom image function that forwards its path and other arguments to the prequery image function. This showcases argument forwarding.

```typst
// xy/lib.typ
#let my-image(path, ..args) = image(path, ..args)
```

--------------------------------

### Call custom image function with relative path

Source: https://typst-community.github.io/prequery/package/prequeries.html

Import and call a custom image function that forwards arguments. Observe how the path resolution differs based on argument forwarding.

```typst
// main.typ
#import "xy/lib.typ": *

#my-image("assets/foo.png")  // tries to show "xy/assets/foo.png"
#my-image2("assets/foo.png")  // tries to show "assets/foo.png"
```

--------------------------------

### Typst Show Rule for Raw Python Blocks

Source: https://typst-community.github.io/prequery/package/prequeries.html

Applies a Typst show rule to automatically format and execute raw blocks with the language 'pre-py' using the previously defined 'python' prequery. This simplifies the process of rendering Python output.

```typst
#show raw.where(block: true, lang: "pre-py"): set text(1em / 0.8)
```

```typst
#show raw.where(block: true, lang: "pre-py"): python
```

--------------------------------

### Shell Job with Array Command

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Configures a shell job where the command is specified as an array of strings, allowing for arguments. Input and output formats are set to JSON.

```toml
[[tool.prequery.jobs]]
name = "..."  # required
kind = "shell"

# the query getting metadata from the document
# see https://typst.app/docs/reference/introspection/query/#command-line-queries
query.selector = "..."  # required
query.field = "value"
query.one = false

command = ["ls" "-l"] # required, can also be an array like `["ls" "-l"]`

# execute a single command with an array of all inputs
joined = false

# data passed to commands via stdin is in JSON format
format.stdin = "json"

# data received for commands via stdout is in JSON format
format.stdout = "json"

# data written to files for prequeries to read is in JSON format
format.output = "json"
```

--------------------------------

### Define Python Prequery Function

Source: https://typst-community.github.io/prequery/package/prequeries.html

Defines a prequery function for Python code execution. It takes arguments including a file path and the code content, and specifies fallback content if needed.

```typst
#let python(
  ..args,  // this contains the file path
  code,
) = prequery.prequery(
  (data: code.text, path: args.pos().at(0)),
  <python>,
  // a function without parameters, only called if not in fallback mode
  () => {
    let output = read(..args)  // the file path is relative to the caller
    raw(block: true, output)
  },
  // the fallback content, only rendered if in fallback mode
  fallback: [
    ```
        ...
        ```
  ],
)

```

--------------------------------

### Define Python Prequery Function

Source: https://typst-community.github.io/prequery/package/prequeries.html

Defines a Typst function `python` that utilizes the `prequery.prequery` function to execute code and save its output to a specified file. This snippet shows the basic structure for handling arguments and specifying the prequery type.

```typst
#let python(
  ..args,  // this contains the file path
  code,
) = prequery.prequery(
  (data: code.text, path: args.pos().at(0)),
  <python>,
  // ...
)
```

--------------------------------

### Typst Document with Python Snippets for Plain Text Output

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

Embed Python code snippets within a Typst document to generate individual output files. The `#metadata` function is used to specify the output path and embed the Python code.

```typst
#metadata((path: "out.json"))<python>

#metadata((data: ```py
print("Hello World")
```.text))<python>

#metadata((data: ```py
print("Hello Prequery")
```.text))<python>
```

```typst
#metadata((path: "out.json"))<python>

#metadata((data: ```py
print("Hello World")
```.text))<python>

#metadata((data: ```py
print("Hello Prequery")
```.text))<python>
```

```typst
#metadata((path: "out.json"))<python>

#metadata((data: ```py
print("Hello World")
```.text))<python>

#metadata((data: ```py
print("Hello Prequery")
```.text))<python>
```

```typst
#metadata((path: "out.json"))<python>

#metadata((data: ```py
print("Hello World")
```.text))<python>

#metadata((data: ```py
print("Hello Prequery")
```.text))<python>
```

--------------------------------

### Python Script for Executing Code Snippets

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

A Python script that executes code snippets sequentially, maintaining a shared scope for variables. It reads code from stdin, executes it, and writes the captured stdout to stdout.

```python
import contextlib
import io
import json
import sys

def run(code, scope):
    # redirect output to a string
    with contextlib.redirect_stdout(io.StringIO()) as f:
        # execute the code snippet, using the given dictionary as the scope
        exec(code, scope)
    return f.getvalue()

# load inputs (JSON array) from stdin
inputs = json.loads(sys.stdin.read())

scope = {}

# run all code snippets in order,
# using the same scope to share "global" variables
outputs = [run(code, scope) for code in inputs]

# write outputs (JSON array of the same length) back to stdout
sys.stdout.write(json.dumps(outputs))
```

--------------------------------

### Execute Python Code Snippets

Source: https://typst-community.github.io/prequery/preprocessors/shell.html

This function executes a given Python code string within a provided scope. It redirects stdout to capture any printed output. Use this to run isolated code blocks.

```python
import contextlib
import io
import json
import sys

def run(code, scope):
    # redirect output to a string
    with contextlib.redirect_stdout(io.StringIO()) as f:
        # execute the code snippet, using the given dictionary as the scope
        exec(code, scope)
    return f.getvalue()
```
Tokens:
Raw