Extract test code from OCaml doc-comments.

ocamlcodoc extracts the preformatted source code in OCaml
documentation comments, i.e. the code delimited by {[ ... ]} in
comments delimited by (** ... *). A typical usage is to write
examples in documentation comments that can be extracted and tested.

ocamlcodoc can be used as an
inline test
back-end with dune (version 1.3 and above):

(inline_tests (backend ocamlcodoc))

Basic usage

By default, ocamlcodoc acts as a filter from standard input to
standard output:

$ cat source.ml
let rec fib = function
  | 0 -> 1
  | 1 -> 1
  | n -> fib (n - 1) + fib (n - 2)
(**
   The Fibonacci function.
   {[
     assert (fib 0 = 1);
     assert (fib 1 = 1);
     assert (fib 10 = 89);
   ]}
 *)
$ ocamlcodoc <source.ml >extracted.ml
$ cat extracted.ml 

# 7 "stdin"

     assert (fib 0 = 1);
     assert (fib 1 = 1);
     assert (fib 10 = 89);

Source files can be given as command-line arguments:

$ ocamlcodoc source.ml

# 7 "source.ml"

     assert (fib 0 = 1);
     assert (fib 1 = 1);
     assert (fib 10 = 89)

All preformatted source code snippets are concatenated.

$ cat source.ml
let rec fib = function
  | 0 -> 1
  | 1 -> 1
  | n -> fib (n - 1) + fib (n - 2)
(**
   The Fibonacci function.

   Initial cases:
   {[
     assert (fib 0 = 1);
     assert (fib 1 = 1);
   ]}

   Some other test cases:
   {[
     assert (fib 10 = 89);
     assert (fib 20 = 10946);
   ]}
 *)
$ ocamlcodoc source.ml

# 9 "source.ml"

     assert (fib 0 = 1);
     assert (fib 1 = 1);
   
# 15 "source.ml"

     assert (fib 10 = 89);
     assert (fib 20 = 10946);

Insert code not appearing in the documentation

Code outside documentation comment can be inserted with (*{[ ... ]}*).

$ cat source.ml
(*{[ open Fib ]}*)

let rec fib = function
  | 0 -> 1
  | 1 -> 1
  | n -> fib (n - 1) + fib (n - 2)
(**
   The Fibonacci function.

   Initial cases:
   {[
     assert (fib 0 = 1);
     assert (fib 1 = 1);
   ]}

   Some other test cases:
   {[
     assert (fib 10 = 89);
     assert (fib 20 = 10946);
   ]}
 *)
$ ocamlcodoc source.ml

# 1 "source.ml"
 open Fib 
# 11 "source.ml"

     assert (fib 0 = 1);
     assert (fib 1 = 1);
   
# 17 "source.ml"

     assert (fib 10 = 89);
     assert (fib 20 = 10946);

Set output file

Output file name can be given as command-line argument with the
option -o.
-o - targets standard output (the default).

$ ocamlcodoc source.ml -o extracted.ml

The output file name can be a pattern where % stands for the base
name (without suffix) of each input file name. If the pattern path is
relative, the reference path is the path of the input file.

If two input files or more are given, then all extracted code will be
concatenated, except if the output file name is a pattern: in this
case, there will be one output file per input file.

Warnings and errors

Comments, preformatted source code and strings should be terminated
before the end of the input file.

A common mistake is to end prematurely a preformatted source code with
]}, by closing a list or an array inside a record. This should be
written by separating delimiters with a space ] }. Otherwise,
the resulting extracted code will be probably ill-formed. ocamlcodoc
will issue a warning in this case, except if the delimiters become
balanced in subsequent snippets. For example, the following code
produces a warning:

(*** {[ { list = ["a"; ]} *)

whereas the following code does not:

(*** {[ { list = ["a"; ]} (some comment) {[ "b" ] } ]} *)

Add code snippet before or after the extracted code

Options --before or --before-file may be used to insert a fixed
piece of code in preambule: --before takes the text to be inserted
as argument, --before-file takes a file name to read the text from
(the two options cannot be used simultaneously).

$ ocamlcodoc --before "(* This code is autogenerated. *)" source.ml
(* This code is autogenerated. *)
# 1 "source.ml"
 open Fib 
# 11 "source.ml"

     assert (fib 0 = 1);
     assert (fib 1 = 1);
   
# 17 "source.ml"

     assert (fib 10 = 89);
     assert (fib 20 = 10946);

Symmetrically, options --after and --after-file may be used to
insert a fixed piece of code at the end of the file.