Checked examples
An @example is Sigil code that sigil doc verify (or verify-document) runs, in a fresh process, and compares against one expectation. Renderers show an example only with a verified result, so a published page never shows code that didn't run.
@example["greeting" expect-stdout: "hello\n"]{
@code["sigil"]{(display "hello\n")}
}
@example["config" source-file: "examples/config.sgl" expect-value: "42"]{}Keywords:
| Keyword | Meaning |
|---|---|
source-file: | Read the source from a file under the verification root instead of the body. |
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. |
expect-stdout:, expect-value:, expect-error:, expect-timeout: | Exactly one expectation. expect-value: compares the written form of the program's last value. |
expect-stderr: | Expected standard error, "" by default. |
timeout: | Seconds, 1 to 60. 5 by default. |
display: | 'source+expected, 'source or 'hidden. The default is 'source+expected, or 'source for an example with a check. |
check:, check-file: | A hidden check; see below. |
Hidden checks
Sometimes the code a reader should see isn't the code that proves it works. A configuration example should show only the configuration, while checking it means calling functions the reader never would. check: and check-file: keep that checking code out of the page.
@example["settings" expect-value: "#t" check: '(equal? (cdr (assq 'theme settings)) "dark")]{
@code["sigil"]{(define settings (list (cons 'theme "dark")))}
}
@example["web-server" source-file: "examples/web.sgl"
check-file: "examples/web.check.sgl" expect-value: "(80 443)"]{}check:takes a quoted Sigil expression, or its text as a string. Usebeginfor several forms. A quoted expression is written back as text withwrite, so it must hold only data that reads back the same: keywords such asname:don't, so use a string orcheck-file:for checks that pass keyword arguments. The reader doesn't allow@commands inside[...], so a code block can't be written there; code that builds examples withmake-examplecan pass any of these.check-file:takes a path under the verification root, resolved the same way assource-file:. Use it for anything longer than one expression. Givecheck:orcheck-file:, not both.- How it runs. In one process, the verifier loads the shown source, binds its last value as
example-result, then loads the check in the same environment. The check sees every definition and import the shown source made, plusexample-result, so it can check an example whose last expression is a value with no name, such as a configuration. The expectation applies to the whole run:expect-value:compares the check's last value, andexpect-stdout:compares the output of both parts. example-resultis an ordinary binding. If the shown source definesexample-resultitself, the verifier'sset!replaces that value before the check runs, so don't use the name in shown code.- What readers see. Only the shown source. An example with a check can't use
display: 'source+expected, because the expected value is the check's, not the shown code's:'sourceis the default and'source+expectedis refused. The check isn't part of the verified result's effective source, so the HTML, plain text and Typst renderers, copy buttons and any tool that extracts example source never see it. A session's later examples include earlier examples' shown source, not their checks. - Caching and contracts. The cache key and the result's specification contract cover the check, so changing a check re-verifies the example. An example without a check has the same document datum, cache key and contract it had before checks existed.
document->datum, and the debug output built from it, include the check by design: they describe the whole document, not what readers see.
From Sigil code, pass the check to make-example as keys after the location: check-kind: 'inline check: "(expression)", or check-kind: 'file check: "path/to/check.sgl". example-check-kind returns #f, 'inline or 'file, and example-check returns the text or path.