HereDoc

Introduction
Fragments
The <:here<..>> quotation
Other quotation expanders
This document
Conclusion

1. Introduction

HereDoc is a preprocessor for Objective Caml programs. Basically, it provides a quotation expander (see Camlp4) for strings with Caml expressions $(expr) in the middle:

     << The result of f applied to x is : $(f x). >>
     << Hello $(user.name) ! >>

There is also support for conditional sections $?(cond)...?() or $?(cond)...?(else)...?():

     << If you are me $?( user.id = me ) (and you are, actually) $(),
you can click here ... >>
     << $?( delta last_visit today > 10 ) Haven't seen you for a while !
$?(else) Oh, you again ... what do you want !? $() >>

And for iterations:

     << $[map_list players -> (name,score)] 
           <br> Player $(name) has score $(score). 
        $[] 
     >>

The natural way to compile these quotations would be to translate them into concatenation of strings. This can be quite expensive when you build complex documents with many levels of quotations (because each concatenation allocate a block and copy the strings), so HereDoc makes it possible to use an arbitrary representation of fragments.

Section to be written, see the interface ../text.mli

3. The `<:here<..>>` quotation

HereDoc defines a Camlp4 quotation called here and makes it the default one, so that you can just use double brackets as in the introduction. The type of the expression is Fragment.t (which may be string but not necessarily).

Caml expressions

They are supposed to be of type Fragment.t. Arbitrary expressions are allowed and it is possible to have nested quotations inside:


  << Hello $( <<world>> ) ! >>

The special form $() produce an empty fragment. This can be useful to "escape" sequences that would be recognized by HereDoc:

   << This is not an expression: $$()(). >>

The $() produce the empty string, so the result is : This is not an expression: $().

Conditional sections

See the introduction. The $?(else) part is optional and the $?() is mandatory to indicate the end of the conditional section. Conditional sections may be nested (also together with abstractions), with naturel scopes.

Abstractions and iterations

The general construction for abstractions is:

   $[expr -> pat1 -> .. -> patn] body $[]

This will produce a fragment equivalent to:

  expr (fun pat1 .. patn -> <<body>> )

That is: expr is a functional, which is feed by the abstraction of body w.r.t. the patterns p1,...,pn. If n=0, it is just the application of expr to body. This can be useful to post-process a fragment:

  $[rot13] This is a secret. $[]

(the function rot13: Fragment.t -> Fragment.t must be in the scope of the quotation where it appears) The other main application is the iteration over a list, for instance:

  $[map_list l -> (x,y,_)] x=$(x); y=$(y) $[]

(where map_list can be defined by let map_list l f = Fragment.list (List.map f l) actually, it is already defined by the functor Tools). You can iterate over an array and use the index:

  $[map_array a -> i -> name] $(name) is number $(int i). $[]

(with let map_array a f = Array.iteri f a and int: int -> Fragment.t is defined in Tools).

Formatting à la `Printf`

The construction

  ${format -> arg1 -> .. -> argn}

will produce a fragment equivalent to:

  Printf.sprintf format arg1 .. argn

For instance:

  Position: ${"(%03i,%03i,%03i)" -> x -> y -> z}

Literal fragments

Any text between the markups defined in the previous paragraphs are simply translated to literal fragments.

4. Other quotation expanders

HereDoc defines two other quotation expanders: html and meta.

The `html` quotation

The text of the quotation is copied verbatim, with html special characters ( <, >, &, " ) escaped. The result is a Fragment.t. No other expansion is done. Example:


    << Special html chars: $(<:html< <, >, &, " >>) >>

The program used to produce this document rely heavily on this quotation expander.

The `meta` quotation

This quotation define a few number of special forms:

<:meta<camlp4_version>> returns the release number of Camlp4 (as a fragment).
<:meta<heredoc_version>> returns the release number of HereDoc (as a fragment).
<:meta<filename>> returns the name of the current Caml file (as a fragment).
<:meta<date>> returns the current date (of the preprocessing), as a triple of ints: (year,month,day).
<:meta<lastmod>> returns the last modificatioon date of the current Caml source file, as a triple of ints: (year,month,day).
<:meta<system:cmd>> execute the command cmd (using /bin/sh) and returns its output as a fragment; the process must have the exit code 0.

5. This document

This file itself was produced by a Caml program: doc.ml generic.ml . You may want to have a look at the files produced by HereDoc: This file itself was produced by a Caml program: doc.ml.ppo generic.ml.ppo .

6. Conclusion

You can find more information about HereDoc on its homepage.

Actually, not for the moment ... It is an old version which is described on this page

Introduction
Fragments
The <:here<..>> quotation
Other quotation expanders
This document
Conclusion

This file doc.ml was last modified on 2001-07-22. It was preprocessed with HereDoc 20010722 and Camlp4 3.01, on 2001-07-22. The machine was running the SunOS OS and the current directory was /users/98/maths/frisch/caml/HereDoc/doc.