AtlatestRenderedmarkdown
Readme

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:

KeywordMeaning
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. Use begin for several forms. A quoted expression is written back as text with write, so it must hold only data that reads back the same: keywords such as name: don't, so use a string or check-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 with make-example can pass any of these.
  • check-file: takes a path under the verification root, resolved the same way as source-file:. Use it for anything longer than one expression. Give check: or check-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, plus example-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, and expect-stdout: compares the output of both parts.
  • example-result is an ordinary binding. If the shown source defines example-result itself, the verifier's set! 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: 'source is the default and 'source+expected is 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.