# Literate Programming with Quarto

## Quick Setup with Quarto

T provides a specialized Quarto filter (`tlang`) that allows you to execute T code chunks directly in your `.qmd` documents. 

### Installing the T Plugin

The T plugin is managed automatically within a T project. You don't need to download it manually; T's dependency management handles it.

1.  **Add Quarto to your project**: In your `tproject.toml`, ensure `quarto` is in the `additional-tools`:
    ```toml
    [additional-tools]
    packages = ["quarto"]
    ```
2.  **Provision the extension**: Run `t update` in your terminal.
3.  **Enter the environment**: Run `nix develop`.
    
Upon entering the environment, T will symlink the `tlang` extension from the Nix store into your project's `_extensions/` directory.

### Enabling the Filter

Add the `tlang` filter to your document's YAML front matter:

```yaml
---
title: "My T Analysis"
format: html
filters:
  - tlang
---
```

## Writing Quarto Blocks

You can now use `{t}` code chunks in your document. These chunks are executed by the T interpreter during rendering.

````markdown
```{t}
#| label: load-data
df = read_csv("mtcars.csv")
df |> glimpse
```
````

### Block Options

- `eval`: Set to `false` to show the code without executing (default: `true`).
- `echo`: Set to `false` to hide the code and only show the output (default: `true`).
- `results`: Set to `hide` to suppress any printed output.
- `fig-cap`: Add a caption if the chunk generates a plot (via an R/Python sub-node).

### Syntax Highlighting

`{t}` chunks are syntax-highlighted identically to R chunks: the `tlang` filter tokenizes T code and emits pandoc short-class spans for HTML/EPUB output and `\Tok` commands for PDF, wrapped in themed `sourceCode` blocks. No configuration is needed beyond the already-enabled `tlang` filter (extension v0.52.0+, provisioned automatically by `t update`).

---


## Defining a Quarto Node

A Quarto node in a pipeline takes a `.qmd` file as input and renders it to a target format (default is HTML).

```t
p = pipeline {
  data = node(command = read_csv("data.csv") |> filter($age > 18))
  
  report = node(
    script = "analysis.qmd",
    runtime = Quarto
  )
}
```

### Implicit Dependencies

When a `.qmd` file uses `read_node("name")`, T automatically detects this and adds a dependency from the Quarto node to the specified node (`data` in the example above).

## Using Data from T in Quarto

Within your `.qmd` file, you can access data generated by other nodes in the same pipeline using the `read_node()` function.

### In R Chunks

````qmd
---
title: "Pipeline Analysis"
format: html
---

# Analysis

```{r}
# read_node is substituted by T during the build
df <- read_node("data")
summary(df)
```
````

### How it Works

When the pipeline is built via Nix:
1. T detects `read_node("node_name")` calls in the `.qmd` source.
2. It generates a Nix derivation where the absolute path to the node's artifact (in the Nix store) is provided via environment variables.
3. During the Nix build, a `sed` substitution replaces `read_node("node_name")` with the actual path to the artifact.
4. Quarto renders the document using these absolute paths.

## Exporting Results

Because T pipelines are built in the Nix store (which is read-only), rendered reports remain in `/nix/store/...`. To inspect or publish them, use the `pipeline_copy()` function to bring them into your local workspace.

```t
-- Build the pipeline
populate_pipeline(p, build = true)

-- Copy all artifacts to ./pipeline-output/
pipeline_copy()
```

The rendered HTML and its accompanying files will be available in `pipeline-output/report/artifact/`.

## Configuring Dependencies

If your Quarto document uses R or Python chunks, you must ensure the necessary packages are available in the project's `tproject.toml`.

```toml
[r-dependencies]
packages = ["jsonlite", "ggplot2"]

[additional-tools]
packages = ["quarto", "which"]
```

> [!NOTE]
> Always include `quarto` and `which` in `additional-tools` if you are using Quarto nodes.

## Multi-Language Reporting

Quarto allows you to blend multiple languages in a single document. Since T orchestrates the data flow, you can:
1. Process raw data in **T**.
2. Perform complex statistical modeling in **R**.
3. Render a comprehensive reporting doc in **Quarto** that consumes both the processed data and the model parameters.