[Caml-list] Documenting CamlP4 syntax extensions

[Caml-list] Documenting CamlP4 syntax extensions

[Mitya Lomov]

Hello,

As I am heading to the release of Dynamic Caml 0.2,
it occurred to me that syntax extensions included there
grew quite complex, and will certainly require some
good deal of documenting to be released to the public.

It will be nice to be able to document camlp4 syntax
extensions in the same way as one documents his .mli
file...

The first step to that will be, I guess, some kind of
tool that is able to extract plain grammar definitions
(like BNF) from CamlP4 sources (just rules, without
semantics).

I see two ways to write such a tool: either reimplement
pa_extend.ml extensions so that they will output grammar
entries in readable form instead of adding them into CamlP4
internals, or some kind of "dummy syntax extension" module
which will dump internal CamlP4 grammar entries
in readable form.

The latter way is, to some extent, more clean - one does not
reimplement parsing (and do not need to reinvent
internal representation for grammars...). However, it is
possible that the first way is more extensible (say, if one
wants to add some fancy comments to syntax extensions, so
that the whole documentation is generated from source, then
it is easier to do that while parsing).

Any opinions? Probably such a beast already exists?

Regards,
Dmitry

-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners

Re: [Caml-list] Documenting CamlP4 syntax extensions

[Daniel de Rauglaudre]

Hi,

On Sat, Mar 02, 2002 at 01:59:37PM +0400, Mitya Lomov wrote:

> The first step to that will be, I guess, some kind of
> tool that is able to extract plain grammar definitions
> (like BNF) from CamlP4 sources (just rules, without
> semantics).

The function Grammar.Entry.print prints the rules of a grammar
entry. For example, the code:
    Grammar.Entry.print Pcaml.expr
prints the rules for expressions.

You can try it in the toplevel (load "camlp4o.cma" for normal syntax
or "camlp4r.cma" for revised syntax, before) or write a little program
displaying the main entry rules (defined in module Pcaml).

For example, to display expressions and patterns, file "foo.ml":
    Format.printf "@[<v 2>expr@ ";
    Grammar.Entry.print Pcaml.expr;
    Format.printf "@]@.";
    Format.printf "@[<v 2>patt@ ";
    Grammar.Entry.print Pcaml.patt;
    Format.printf "@]@.";

Compilation:
    ocamlc -pp camlp4r -I +camlp4 -c foo.ml

Print expressions and patterns rules of normal syntax:
    camlp4o ./foo.cmo

And of revised syntax:
    camlp4r ./foo.cmo

Perhaps a complete program displaying all entries (by scanning the
main grammar entries "interf" and "implem") could be useful. It is
possible to scan entries using the (undocumented) module Gramext.
I can do that, if you want it.

-- 
Daniel de RAUGLAUDRE
daniel.de_rauglaudre@inria.fr
http://cristal.inria.fr/~ddr/
-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners

Re: [Caml-list] Documenting CamlP4 syntax extensions

[Mitya Lomov]

Daniel de Rauglaudre wrote:
> 
> Hi,
> 
> On Sat, Mar 02, 2002 at 01:59:37PM +0400, Mitya Lomov wrote:
> 
> > The first step to that will be, I guess, some kind of
> > tool that is able to extract plain grammar definitions
> > (like BNF) from CamlP4 sources (just rules, without
> > semantics).
> 
> The function Grammar.Entry.print prints the rules of a grammar
> entry. For example, the code:
>     Grammar.Entry.print Pcaml.expr
> prints the rules for expressions.

This function is great for development purposes.
But for documenting syntax extensions its output is not 
quite acceptable, and coverting its output to more readable
form essentialy involves parsing camlp4 grammar definitions
(a la pa_extend.cmo). 
Moreover, one have to build a transitive closure of all grammar
entries referenced from an entry to get a complete doc...



> 
> Perhaps a complete program displaying all entries (by scanning the
> main grammar entries "interf" and "implem") could be useful. It is
> possible to scan entries using the (undocumented) module Gramext.



> --
> Daniel de RAUGLAUDRE
> daniel.de_rauglaudre@inria.fr
> http://cristal.inria.fr/~ddr/
> -------------------
> To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
> Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners

Re: [Caml-list] Documenting CamlP4 syntax extensions

[Daniel de Rauglaudre]

Hi,

On Fri, Sep 13, 2002 at 10:15:45PM +0400, Mitya Lomov wrote:
> Daniel de Rauglaudre wrote:
> > The function Grammar.Entry.print prints the rules of a grammar
> > entry. For example, the code:
> >     Grammar.Entry.print Pcaml.expr
> > prints the rules for expressions.
> 
> This function is great for development purposes.
> But for documenting syntax extensions its output is not 
> quite acceptable, and coverting its output to more readable
> form essentialy involves parsing camlp4 grammar definitions
> (a la pa_extend.cmo). 
> Moreover, one have to build a transitive closure of all grammar
> entries referenced from an entry to get a complete doc...

Ok. For the "transitive closure" point, I added two functions:
     Grammar.iter_entry
     Grammar.fold_entry
which iterate an entry and transitively all the entries it calls.

This is committed in the current CVS version of Camlp4.

For example:
   $ cat foo.ml
   Grammar.iter_entry
     (fun e ->
        Format.printf "@[<v 2>%s:@ %a@]@." e.Gramext.ename
          Grammar.print_entry e)
     (Grammar.Entry.obj Pcaml.expr)

This prints all entries of the OCaml grammar (normal syntax) starting
with "expr":
   $ ocaml -I +camlp4 camlp4o.cma foo.ml

This example uses "Grammar.print_entry" (equivalent to Grammar.Entry.print
for entries "obj"). If that display does not fit you, you can take its code
in camlp4/lib/grammar.ml and change it so that it is printed in LateX,
HTML, XML or any output format you want.

I can help, if needed, or I can do it if you or somebody tells me
how you want it to be displayed.

-- 
Daniel de RAUGLAUDRE
daniel.de_rauglaudre@inria.fr
http://cristal.inria.fr/~ddr/
-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners