AtlatestRepositorysigil-doc
1# Checked examples
2
3An `@example` is Sigil code that `sigil doc verify` (or `verify-document`)
4runs, in a fresh process, and compares against one expectation. Renderers
5show an example only with a verified result, so a published page never
6shows code that didn't run.
7
8```text
9@example["greeting" expect-stdout: "hello\n"]{
10@code["sigil"]{(display "hello\n")}
13@example["config" source-file: "examples/config.sgl" expect-value: "42"]{}
14```
16Keywords:
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 checks
30Sometimes the code a reader should see isn't the code that proves it works.
31A configuration example should show only the configuration, while checking
32it means calling functions the reader never would. `check:` and
33`check-file:` keep that checking code out of the page.
35```text
36@example["settings" expect-value: "#t" check: '(equal? (cdr (assq 'theme settings)) "dark")]{
37@code["sigil"]{(define settings (list (cons 'theme "dark")))}
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 as
46 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:` for
48 checks that pass keyword arguments. The reader doesn't allow `@` commands
49 inside `[...]`, so a code block can't be written there; code that builds
50 examples with `make-example` can pass any of these.
51- **`check-file:`** takes a path under the verification root, resolved the
52 same way as `source-file:`. Use it for anything longer than one
53 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 the
56 same environment. The check sees every definition and import the shown
57 source made, plus `example-result`, so it can check an example whose
58 last expression is a value with no name, such as a configuration. The
59 expectation applies to the whole run: `expect-value:` compares the
60 check's last value, and `expect-stdout:` compares the output of both
61 parts.
62- **`example-result` is an ordinary binding.** If the shown source
63 defines `example-result` itself, the verifier's `set!` replaces that
64 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 check
66 can't use `display: 'source+expected`, because the expected value is
67 the check's, not the shown code's: `'source` is the default and
68 `'source+expected` is refused. The check isn't part of the
69 verified result's effective source, so the HTML, plain text and Typst
70 renderers, copy buttons and any tool that extracts example source never
71 see it. A session's later examples include earlier examples' shown
72 source, not their checks.
73- **Caching and contracts.** The cache key and the result's specification
74 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 and
76 contract it had before checks existed. `document->datum`, and the debug
77 output built from it, include the check by design: they describe the
78 whole document, not what readers see.
80From Sigil code, pass the check to `make-example` as keys after the
81location: `check-kind: 'inline check: "(expression)"`, or
82`check-kind: 'file check: "path/to/check.sgl"`. `example-check-kind`
83returns `#f`, `'inline` or `'file`, and `example-check` returns the text or
84path.