---
name: "camlmix"
section: "1"
platform: "linux"
package: "camlmix"
version: "1.3.1-6+b3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/camlmix"
---

# camlmix(1)

preprocessor which converts text with embedded OCaml

## NAME

camlmix - preprocessor which converts text with embedded OCaml

## SYNOPSIS

**camlmix \[*Options...*\] *files*...**

## DESCRIPTION

**camlmix** processes text templates with embedded  **OCaml** code to generate text again. From one or several input files it generates an **OCaml** text generation program and executes this to obtain the result. Using option *-fun* one can also convert the text template into an  **OCaml** text generation function.

## OPTIONS

- **-o output**

  write the generated text into 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 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 (this man page was written from the output of *-help)*

## BASIC USAGE

Text enclosed with *##* markers is considered as a block of  **OCaml** code. It can be any kind of toplevel expressions such as definitions or application of printing functions:

This is ocaml version ## print Sys.ocaml\_version ##

If the **OCaml** code starts with *=* then it is interpreted as an expression of type string that will printed like the rest of the text:

This is ocaml version ##= Sys.ocaml\_version ##

The text block are printed together with the evaluated **OCaml** pieces using the  *print* function. Include *###* to print *##.*

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). It's 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

## 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).