NAME¶

camlmix - preprocessor which converts text with embedded OCaml.

SYNOPSIS¶

camlmix [options] file1 file2 ... fileN A temporary file “fileN.ml” is created and then executed with ocaml.

DESCRIPTION¶

General rules¶

Text between ## and ## is considered as a block of code. A block of code is normally some 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 it starts with = the OCaml code 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 document blocks are printed by default on stdout using the “print” function. For ## to be printed, ### should be used. White space introduced by OCaml can be controlled by ##. and .## symbols:

  ##. causes any white space to the left of the symbol
      to be omitted from the output. Similarly
  .## causes any white space followed by one newline
      to be omitted from the output.
    

 Directives¶

Blocks of code that start with the @ character (possibly preceded by spaces) are directives for Camlmix. The following directives are available:

include "somefile.mlx"; (* inserts a camlmix file *)
skip;                   (* ignores the next block of text *)
    

e.g.:

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

Conversion into a “render” function for dynamic rendering¶

The -fun option, used in combination with -c and often -co produces an OCaml source file which provides a function with the following signature: val render : ?print:(string -> unit) -> ANYTYPE -> unit where ANYTYPE is the type the “param” object which is available in the template. “param” can be used to pass runtime arguments, such as CGI parameters if you are serving dynamic web pages. The “print” function is used to set the initial value of Camlmix.printer (see below) and should be used if you want to be able to put the output into some other container than stdout. It's default value is: fun s -> print_string s; flush stdout

Advanced usage¶

The OCaml program that is generated from the Camlmix files first defines a module called Camlmix. This module contains several variables that are updated automatically and may be used explicitly by the user.

module Camlmix :
  sig
    val source : string ref
    val line   : int ref
    val char   : int ref
        (* source, line and char refer to the location of the
           first character of the current block in its source file
           (source file, line number starting from 1, position in
           the line starting from 1). They are updated
           automatically at the beginning of each (code or text)
           block. *)

    val printer : (string -> unit) ref
        (* the function that prints text blocks. It is initialized
           with the "print" function *)

    val print_with : (string -> unit) -> unit
        (* print_with f prints the next block of text using f
           instead of the current printer. Its behavior is
           undefined if it is called several times in the same
           OCaml block. *)

    val print_if : bool -> unit
        (* print_if cond prints the next block of text only
           if cond is true. It uses print_with. *)
  end
    

OPTIONS¶

-c

only generate the .ml file

-co filename

specify a name for the .ml file or “-” for stdout

-fun

make it the body of a function named “render”, using a single argument named “param”

-e ocaml

specify ocaml executable

-o file

specify an output file

-clean

remove the temporary .ml file after execution

-insert ocaml code

insert this code first

-remix

try a conversion to the camlremix syntax

-version

prints the version of Camlmix and exits

-help|--help

Display this list of options

AUTHORS¶

Sylvain Le Gall.