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