AtlatestRepositorysigil-doc
1
# Checked examples3
An `@example` is Sigil code that `sigil doc verify` (or `verify-document`)4
runs, in a fresh process, and compares against one expectation. Renderers5
show an example only with a verified result, so a published page never6
shows code that didn't run.8
```text9
@example["greeting" expect-stdout: "hello\n"]{10
@code["sigil"]{(display "hello\n")}11
}13
@example["config" source-file: "examples/config.sgl" expect-value: "42"]{}14
```16
Keywords:18
| Keyword | Meaning |19
| --- | --- |20
| `source-file:` | Read the source from a file under the verification root instead of the body. |21
| `session:` | Inline examples with the same session run cumulatively: each one runs after every earlier one in the session. File examples can't join a session. |22
| `expect-stdout:`, `expect-value:`, `expect-error:`, `expect-timeout:` | Exactly one expectation. `expect-value:` compares the written form of the program's last value. |23
| `expect-stderr:` | Expected standard error, `""` by default. |24
| `timeout:` | Seconds, 1 to 60. 5 by default. |25
| `display:` | `'source+expected`, `'source` or `'hidden`. The default is `'source+expected`, or `'source` for an example with a check. |26
| `check:`, `check-file:` | A hidden check; see below. |28
## Hidden checks30
Sometimes the code a reader should see isn't the code that proves it works.31
A configuration example should show only the configuration, while checking32
it means calling functions the reader never would. `check:` and33
`check-file:` keep that checking code out of the page.35
```text36
@example["settings" expect-value: "#t" check: '(equal? (cdr (assq 'theme settings)) "dark")]{37
@code["sigil"]{(define settings (list (cons 'theme "dark")))}38
}40
@example["web-server" source-file: "examples/web.sgl"41
check-file: "examples/web.check.sgl" expect-value: "(80 443)"]{}42
```44
- **`check:`** takes a quoted Sigil expression, or its text as a string.45
Use `begin` for several forms. A quoted expression is written back as46
text with `write`, so it must hold only data that reads back the same:47
keywords such as `name:` don't, so use a string or `check-file:` for48
checks that pass keyword arguments. The reader doesn't allow `@` commands49
inside `[...]`, so a code block can't be written there; code that builds50
examples with `make-example` can pass any of these.51
- **`check-file:`** takes a path under the verification root, resolved the52
same way as `source-file:`. Use it for anything longer than one53
expression. Give `check:` or `check-file:`, not both.54
- **How it runs.** In one process, the verifier loads the shown source,55
binds its last value as `example-result`, then loads the check in the56
same environment. The check sees every definition and import the shown57
source made, plus `example-result`, so it can check an example whose58
last expression is a value with no name, such as a configuration. The59
expectation applies to the whole run: `expect-value:` compares the60
check's last value, and `expect-stdout:` compares the output of both61
parts.62
- **`example-result` is an ordinary binding.** If the shown source63
defines `example-result` itself, the verifier's `set!` replaces that64
value before the check runs, so don't use the name in shown code.65
- **What readers see.** Only the shown source. An example with a check66
can't use `display: 'source+expected`, because the expected value is67
the check's, not the shown code's: `'source` is the default and68
`'source+expected` is refused. The check isn't part of the69
verified result's effective source, so the HTML, plain text and Typst70
renderers, copy buttons and any tool that extracts example source never71
see it. A session's later examples include earlier examples' shown72
source, not their checks.73
- **Caching and contracts.** The cache key and the result's specification74
contract cover the check, so changing a check re-verifies the example.75
An example without a check has the same document datum, cache key and76
contract it had before checks existed. `document->datum`, and the debug77
output built from it, include the check by design: they describe the78
whole document, not what readers see.80
From Sigil code, pass the check to `make-example` as keys after the81
location: `check-kind: 'inline check: "(expression)"`, or82
`check-kind: 'file check: "path/to/check.sgl"`. `example-check-kind`83
returns `#f`, `'inline` or `'file`, and `example-check` returns the text or84
path.