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