CAMLMIX(1)

💖 CAMLMIX(1) 💖

okay bestie, welcome to the camlmix manual page — yeah it's camlmix in section 1 of the User Manuals, and it's literally a whole preprocessor that takes text with OCaml stuffed inside and spits text back out. iconic behavior honestly 🦋

---

✨ NAME ✨

camlmix — a preprocessor which converts text with embedded OCaml

---

🌸 SYNOPSIS 🌸

camlmix [Options...] files...

---

💅 DESCRIPTION 💅

So camlmix processes text templates that have OCaml code embedded in them, and generates text again. Like, it eats templates and produces more text, no cap.

From one or several input files it generates an OCaml text generation program, and then it executes that program to get the result. ✨

And if you use the -fun option, you can also convert the text template into an OCaml text generation function instead. cute, right? 🎀

---

👑 OPTIONS 👑

• -o output — write the generated text into the file output
• -c — only generate the text generation program, don't execute it. By default, the program is called lastfile.ml when lastfile is the last file argument.
• -co file — specify the name of the text generation program
• -fun — generate OCaml code for a text generation function from the input (see ADVANCED USAGE below)
• -e ocamlc — set the name of the OCaml executable
• -clean — remove the text generation program after execution
• -insert ocaml_code — insert ocaml_code at the beginning of the text generation program
• -remix — try a conversion to the camlremix syntax
• -version — print version and exit
• -help | --help — print help and exit (and yes, this man page was written from the output of -help, so you're literally reading the help's help 💀)

---

🌈 BASIC USAGE 🌈

Text that's wrapped in ## markers is treated as a block of OCaml code. It can be any kind of toplevel expressions — definitions, applications of printing functions, whatever you want, bestie:

This is ocaml version ## print Sys.ocaml_version ##

If the OCaml code starts with =, then it's interpreted as an expression of type string, and that string gets printed like the rest of the text:

This is ocaml version ##= Sys.ocaml_version ##

The text blocks get printed together with the evaluated OCaml pieces, using the print function. And if you want to literally print ##, just include ###. 🫶

White space can be controlled with ##. and .##:

• ##. — don't print white space occurring on the left
• .## — don't print white space up to and including the first newline, following to the right.

---

🔥 ADVANCED USAGE 🔥

🧚 Directives

Blocks of code that start with the @ character (possibly preceded by spaces) are directives for Camlmix. There are two directives. include inserts a camlmix file, and skip skips the next block. For instance:

Hello ## @include "world.mlx"; skip .## ## let x = 123 ##!

💜 Conversion into a text generation function for dynamic rendering

The -fun option, used in combination with -c and often -co, produces an OCaml source file which provides a function render with the following signature:

val render : ?print:(string -> unit) -> 'a -> unit

The polymorphic argument is called param in the generated code and can be used to pass runtime arguments into the render function. The print function is used to set the initial value of Camlmix.printer (see below). Its default value is:

fun s -> print_string s; flush stdout

⭐ Runtime hooks

The text generation program, which camlmix generates, contains a module Camlmix at the beginning, which can be used in code blocks. This module has the following signature.

module Camlmix : sig

    val source : string ref

    val line : int ref

    val char : int ref
           Location of the first character of the current block in
           its source file. Line and character numbers count from 1.
           These references are updated by camlmix at the beginning
           of each block.

    val printer : (string -> unit) ref
           function for printing text blocks

    val print_with : (string -> unit) -> unit
           print_with f causes the next text block to be printed
           with f instead of the current printer. Its behavior is
           undefined if it is called several times in the same code
           block.

    val print_if : bool -> unit
           print_if cond prints the next text block only if
           condition cond is true. It uses print_with internally.

end

🚨 bestie heads up: print_with's behavior is undefined if you call it several times in the same code block. don't do it, fr fr.

---

🦋 SEE ALSO 🦋

The camlmix web page, http://mjambon.com/camlmix/

---

🍓 AUTHOR 🍓

This manual page was written by Sylvain Le Gall <gildor@debian.org> and Hendrik Tews <hendrik@askra.de>, specifically for the Debian project (and may be used by others).

---

and that's the whole vibe 💖 this was CAMLMIX, from the camlmix package, dated May 2013 — the CAMLMIX(1) manual page, section 1, User Manuals. slay, go preprocess something, bestie 👑✨