Example

Doctests on slides: the examples a reflected declaration carries.

reflect fn f hands back a declaration as the formatter prints it, comment block included, so a docstring’s fenced examples arrive with it. Taking them back apart is all a slide needs in order to show an example beside the output that example produces.

The fences are the ones the compiler’s own doctest runner reads: a prism fence is the example, and an output fence opening on the line right after it is what running the example prints. The adjacency is the runner’s rule, kept here for a reason: an output block it would not pair up is one nothing checks, so a slide must not show it. Nothing here runs anything, so a deck stays a pure value. spectra build shells out to that runner instead, which is what makes the outputs printed on the slides the outputs the code actually produces. An example that defines main runs as a whole program and one that does not runs as a prompt line, exactly as in generated documentation.

A line marked as hidden compiles for the runner but stays off the slide, so setup a reader does not need never reaches the screen.

read_doc takes a reflected declaration apart into prose, examples, and the definition itself:

fn main() =
  let doc = read_doc("-- | Twice.\nfn double(x : Int) : Int = x * 2")
  println(doc.prose)
  println(doc.definition)

Twice.
fn double(x : Int) : Int = x * 2

Types

Example

type Example = Example { code: String, output: String } deriving (Eq, Show)

One fenced example: the source a slide shows, and the output the doctest runner proves it prints (empty when the docstring pins none).

Doc

type Doc = Doc {
  prose: String,
  examples: List(Example),
  definition: String
} deriving (Eq, Show)

A reflected declaration taken apart: the prose of its docstring, the examples that docstring fences, and the declaration itself.

Functions and Values

read_doc

read_doc : (String) -> Doc

Take a reflected declaration apart into prose, examples, and the declaration itself.

examples_of

examples_of : (String) -> List(Example)

The examples a reflected declaration’s docstring fences.

example_pict

example_pict : (Example) -> Layout.Pict

One example as its source over the output it prints.

doctest

doctest : (String) -> Layout.Pict

Every example a reflected declaration carries, stacked.

definition

definition : (String) -> Layout.Pict

A reflected declaration without its comment block, as a source block. This is the code a docstring documents, with the documentation left behind.