Cinaps is a trivial Metaprogramming tool for OCaml using the OCaml toplevel.
It is intended for two purposes:
- when you want to include a bit of generated code in a file, but writing a proper generator/ppx rewriter is not worth it
- when you have many repeated blocks of similar code in your program, to help writing and maintaining them
It is not intended as a general preprocessor, and in particular cannot only be used to generate static code that is independent of the system.
Cinaps is a purely textual tool. It recognizes special syntax of the
form (*$ <ocaml-code> *) in the input. <ocaml-code> is evaluated
and whatever it prints on the standard output is compared against what
follows in the file until the next ($ ... *) form, in the same way
that expectation tests works.
A form ending with $*) stops the matching and switch back to plain
text mode. In particular the empty form (*$*) can be used to mark
the end of a generated block.
If the actual output doesn’t match the expected one, cinaps creates a
.corrected file containing the actual output, diff the original file
against the actual output and exits with an error code. Other it
simply exits with error code 0.
For instance:
$ cat file.ml
let x = 1
(*$ print_newline ();
List.iter (fun s -> Printf.printf "let ( %s ) = Pervasives.( %s )\n" s s)
["+"; "-"; "*"; "/"] *)
(*$*)
let y = 2
$ cinaps file.ml
---file.ml
+++file.ml.corrected
File "file.ml", line 5, characters 0-1:
let x = 1
(*$ print_newline ();
List.iter (fun s -> Printf.printf "let ( %s ) = Pervasives.( %s )\n" s s)
["+"; "-"; "*"; "/"] *)
+|let ( + ) = Pervasives.( + )
+|let ( - ) = Pervasives.( - )
+|let ( * ) = Pervasives.( * )
+|let ( / ) = Pervasives.( / )
(*$*)
let y = 2
$ echo $?
1
$ cp file.ml.corrected file.ml
$ cinaps file.ml
$ echo $?
0You can also pass -i to override the file in place in case of
mismatch. For instance you can have a cinaps target in your build
system to refresh the files in your project.
In any form (*$ ... *) form, the variable _last_text_block
contains the contents of the text between the previous (*$ ... *)
form or beginning of file and the current form.
For instance you can use it to write a block of code and copy it to a second block of code that is similar except for some simple substitution:
(*$*)
let rec power_int32 n p =
if Int32.equal p 0 then
Int32.one
else
Int32.mul n (power n (Int32.pred p))
(*$ print_string (Str.global_replace (Str.regexp "32") "64" _last_text_block) *)
let rec power_int64 n p =
if Int64.equal p 0 then
Int64.one
else
Int64.mul n (power n (Int64.pred p))
(*$*)Now, whenever you modify power_int32, you can just run cinaps to update
the power_int64 version.
The toplevel directive #use works in CINAPS, and can be used to read in values
from other files. For example,
- In
import.cinaps,(* -*- mode: tuareg -*- *) include StdLabels include Printf let all_fields = [ "name", "string"; "age", "int" ]
- In
foo.ml,(*$ #use "import.cinaps";; List.iter all_fields ~f:(fun (name, type_) -> printf "\n\ external get_%s : unit -> %s = \"get_%s\"" name type_ name) *) external get_name : unit -> string = "get_name" external get_age : unit -> int = "get_age"(*$*)
- In
stubs.h,/*$ #use "import.cinaps";; List.iter all_fields ~f:(fun (name, _) -> printf "\n\ extern value get_%s(void);" name) */ extern value get_name(void); extern value get_age(void);/*$*/
Etc.
Note that the #use directive will read in OCaml from files of any extension.
*.cinaps is a safe choice in the presence of jenga and dune, which by default
try to use all *.ml files in the directory for the executables or library.
In files managed by automatic formatting tools such as ocp-indent or ocamlformat, the code need not come out of CINAPs already formatted correctly.
cinaps.exe -styler FOO uses FOO to reformat its output, before diffing
against the source file.