annotations.md

Annotations used in Learn-OCaml autogen

This document is intended as a reference on the annotations supported by Learn-OCaml autogen. If you haven’t, it is advised reading how to write an exercise with autogen first.

Several annotations are used in Learn-OCaml autogen to discriminate some expressions from the rest of the program. There are currently eight different supported annotations.

%meta

This annotation is used to distinguish definitions of metadata fields that are to be transposed into meta.json.

%prelude

Transposes the annotated expression directly into prelude.ml.

%prepare

Transposes the annotated expression directly into prepare.ml.

%ref

This annotation is used to define a test checking that a reference has the expected value at the end of the execution of the code.

%sampler

This annotation is used to define a sampler for specific functions. It has to be associated with attributes naming these functions.

%solution

Transposes the annotated expression directly into solution.ml.

%template

Transposes the annotated expression directly into template.ml.

%test

Transposes the annotated expression directly into test.ml.

%var

This annotation is used on a variable definition. It identifies the variable definition as an exercise for the student and parses it to a test, as well as including it into the template.

You might have recognized OCaml’s ppx extensions. The following describes their use in the context of Learn-OCaml autogen. A detailed description of the syntax of extensions is given here.

Annotations apply to a global definition to discriminate them from the rest of the program. A definition with an annotation will be written with %annot appended to the keyword, without a space between them.

type%prepare tree =
  | Node of tree * tree
  | Leaf of int

let%prepare null_tree = Leaf 0

We can distinguish two classes of annotations. The first one contains the annotations that simply transpose a definition as is to a file. These are %prelude, %prepare, %solution, %template and %test. They can be used on any global definition. Valid keywords are:

keywords :=
  | class
  | class type
  | exception
  | external
  | include
  | let
  | module
  | module type
  | open
  | type

A recursive let definition can be defined using the following syntax.

let%annot rec f x = …

The second class is the set of annotations for which the expression is parsed before being written in one or more file(s). These annotations are only valid on let definitions.

keywords_specials := let

They are:

• %meta
• %sampler
• %ref
• %var