Re: [Caml-list] Literate (sort-of) programming in OCaml

[Philippe Wang <mail@philippewang.info>]

On Mon, Sep 2, 2013 at 9:16 PM, Jonathan Protzenko
<jonathan.protzenko@gmail.com> wrote:
> Hi everyone,
>
> Thanks for the numerous replies. There are a lot of good solutions in there,
> and the ones that looked closest to what I had in mind seem to be MPP and
> the rwo-run-toplevel script. Some questions about these two tools:
> - MPP seems to just have the built-in language. I couldn't find any example
> in the examples/ directory that used another language, such as OCaml. I
> guess that's because it's still in development?

Hi,

MPP currently has 2 things: the built-in language and its commands,
and the ability to bring OCaml as a pre-processor language.

With mpp -its (-its is an option to be less strict on trailing spaces
in commands) :

((x cmd ocamlopt foo.ml x))
will execute "ocamlopt foo.ml" in a shell and input its output.
Note that "x" is the name of the block. It could be FOO or 23NUI'è!çé
instead, so that one can write ((x cmd echo $((42+42)) x)) for
instance without being bothered by escaping stuff.
-> This is an example of the builtin commands.
To have the list of built-in commands: mpp -b

One may want to nest mpp commands. In this case, another pair of
tokens is used: {{ and }}.
so ((x cmd ocamlopt foo.ml x)) could be written {{x cmd ocamlopt
foo.ml x}} instead. In this precise case, there is absolutely no
difference. However, one can also write {{x cmd ocamlopt {{y get
filename y}} x}} or {{x cmd ocamlopt ((y get filename y)) x}}. But if
one write ((x ocamlopt ((y get filename y)) x)) then a shell will try
to run "ocamlopt ((y get filename y))", which is probably not what's
intended...

All tokens of the language provided by mpp are customisable on the
command line and live in mpp as well. mpp -so 42 will use "42" instead
of "((" to open blocks.
(( so TOTO)) will use TOTO to open blocks after this one, meaning that
to set the open token back to what it was, one could write TOTO so
(())

Well, it's up to the user to imagine how powerful it is.

Then, there is the ability to bring ocaml as a pre-processor language.
This is actually the main motivation for mpp.
Sometimes, you write something using a specific language and you just
wish you could easily use OCaml (or another language...) to preprocess
your file.
With mpp, the default tokens are {< and >} to embed ocaml.
This means that in any file, one can write ocaml and have its output.

Small example in markdown:

If you write this in the file e.md
```
# Number of the day
{< let foo = 42 >}
The number of the day is {< let () = Printf.printf "%d" foo >}.
```

And you run mpp -l ocaml over e.md (note the -l option), then you obtain
```
 let _ = print_string "# Number of the day\n\n"
 let foo = 42  let _ = print_string "\nThe number of the day is \n"
 let () = Printf.printf "%d" foo  let _ = print_string ".\n\n"
```
which is an ocaml programme that you can run to have your final document:

```
# Number of the day


The number of the day is
42.
```

You can see that the environment is shared. If you want different
environments, it's possible to run mpp several times with different
opening and closing tokens.

Of course, you may use ocaml as a preprocessor language in an ocaml
programme (instead of a markdown document), or any textual file
actually.

For the moment, ocaml is the only option supported by "mpp -l" but
I'll provide more language soon. (To provide a language X, one has to
write a "description" of how to convert a text file into an X
programme.)


I've not written much documentation for MPP yet because I've been
mainly working on OMD, a Markdown->HTML converted and Markdown parser
library in OCaml. Now I believe OMD is nearly done, so I'm getting
back to MPP soon...

-- 
Philippe Wang
   mail@philippewang.info