[Caml-list] Automatic generation of mli files

[Caml-list] Automatic generation of mli files

[Stefan Heimann]

Hi,

I searching for a way for generating the .mli file for a given source .ml
file automatically. My basic idea is like that:

(1) Specify in the .ml file which values and types should be exported
    and if a type should be exported abstract or not. This could be
    done with a special comment at the top of the file.

(2) Filter the output of `ocamlc -i' to exclude the values and types
    that should not be exported and to make the types abstract if
    needed.

Of course, the tool should check of there is an existing .mli
file. If the .mli file was not generated by the tool it is not
overwritten. If the list of exported values and types has not changed
the .mli file is not updated too.

I experimented a little bit with parsing the output of `ocamlc -i'
and printing the modified parse tree. I took must code from the ocaml
distribution. However, I don't think that this is a good way.

Any ideas of how to implement such a tool? Are there any existing
tools with this functionality?

Bye,
  Stefan

-- 
Stefan Heimann
http://www.stefanheimann.net :: personal website.
http://cvsshell.sf.net       :: CvsShell, a console based cvs client.

-------------------
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] Automatic generation of mli files

[Maxence Guesdon]

On Fri, 6 Jun 2003 11:57:23 +0200
Stefan Heimann <lists@stefanheimann.net> wrote:

> Hi,
> 
> I searching for a way for generating the .mli file for a given source .ml
> file automatically. My basic idea is like that:
> 
> (1) Specify in the .ml file which values and types should be exported
>     and if a type should be exported abstract or not. This could be
>     done with a special comment at the top of the file.
> 
> (2) Filter the output of `ocamlc -i' to exclude the values and types
>     that should not be exported and to make the types abstract if
>     needed.
> 
> Of course, the tool should check of there is an existing .mli
> file. If the .mli file was not generated by the tool it is not
> overwritten. If the list of exported values and types has not changed
> the .mli file is not updated too.
> 
> I experimented a little bit with parsing the output of `ocamlc -i'
> and printing the modified parse tree. I took must code from the ocaml
> distribution. However, I don't think that this is a good way.
> 
> Any ideas of how to implement such a tool? Are there any existing
> tools with this functionality?

You could develop a custom generator for ocamldoc, outputting an mli
file instead of html, latex, ... files. For example, only commented
elements would be printed to the generated .mli file, and custom tags
could be used to give additional information (abstract types, ...).

See the ocamldoc manual for more information about developing custom
generators, and feel free to ask me if you encounter difficulties.

-- 
Maxence Guesdon

-------------------
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] Automatic generation of mli files

[Brian Hurt]

On Fri, 6 Jun 2003, Stefan Heimann wrote:

> Hi,
> 
> I searching for a way for generating the .mli file for a given source .ml
> file automatically. My basic idea is like that:
> 
> (1) Specify in the .ml file which values and types should be exported
>     and if a type should be exported abstract or not. This could be
>     done with a special comment at the top of the file.
> 
> (2) Filter the output of `ocamlc -i' to exclude the values and types
>     that should not be exported and to make the types abstract if
>     needed.

Not sure what advantage this would gain.  Step #1 is about as difficult as 
simply writting the .mli file directly.  Actually, a fairly fast way to 
produce an mli file is to do ocamlc -i foo.ml > foo.mli and fire up your 
local text editor and delete everything out of foo.mli you don't want 
exported.

I don't have a problem with .mli files being seperate from .ml files for 
two reasons:

1) .mli is your external interface- changing that interface generally 
means changing other files as well.  In this case, you're generally 
already chaging other files.

2) The compiler checks the signature of the .mli file against what is 
produced by the .ml file, so if you do "accidentally" change an exported 
function's interface, and forget to change the .mli to match, the compiler 
will catch it.

Brian


-------------------
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: Re: [Caml-list] Automatic generation of mli files

[Stefan Heimann]

On Fri, Jun 06, 2003 at 10:33:25AM -0500, Brian Hurt wrote:
> On Fri, 6 Jun 2003, Stefan Heimann wrote:
> 
> > Hi,
> > 
> > I searching for a way for generating the .mli file for a given source .ml
> > file automatically. My basic idea is like that:
> > 
> > (1) Specify in the .ml file which values and types should be exported
> >     and if a type should be exported abstract or not. This could be
> >     done with a special comment at the top of the file.
> > 
> > (2) Filter the output of `ocamlc -i' to exclude the values and types
> >     that should not be exported and to make the types abstract if
> >     needed.
> 
> Not sure what advantage this would gain.  Step #1 is about as difficult as 
> simply writting the .mli file directly.  Actually, a fairly fast way to 
> produce an mli file is to do ocamlc -i foo.ml > foo.mli and fire up your 
> local text editor and delete everything out of foo.mli you don't want 
> exported.

I don't think that step #1 is as difficult as writing the .mli file by
hand. If you have a complex type definition it's much easier to write
`export my_type' than keeping the 2 definitions in the .ml and .mli file
in sync.
 
> I don't have a problem with .mli files being seperate from .ml files for 
> two reasons:

It is not my problem that there is this separation between interface
and implementation file. I think this is very good and helpful,
especially when you want to see what functionality a module
provides. I just want to make it easier to write the implementation
file. Programmers are lazy and so writing an interface file should be
as easy as possible.

> 1) .mli is your external interface- changing that interface generally 
> means changing other files as well.  In this case, you're generally 
> already chaging other files.
> 
> 2) The compiler checks the signature of the .mli file against what is 
> produced by the .ml file, so if you do "accidentally" change an exported 
> function's interface, and forget to change the .mli to match, the compiler 
> will catch it.

Maybe I should tell how I want to use the tool. I don't want to update
the .mli file automatically everytime I change something in the .ml
file. I want to use the compiler as I would do without the tool. The
tool comes only into play when the compiler complains about a
non-matching implementation for the interface. Then I have to decide
if this is because I "accidentally" changed something in the
implementation. If yes, I change to implementation. If no, I use to
tool to update to .mli file instead of applying the changes by hand.

Bye,
  Stefan

-- 
Stefan Heimann
http://www.stefanheimann.net :: personal website.
http://cvsshell.sf.net       :: CvsShell, a console based cvs client.

-------------------
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] Automatic generation of mli files

[Ville-Pertti Keinonen]

> Maybe I should tell how I want to use the tool. I don't want to update
> the .mli file automatically everytime I change something in the .ml
> file. I want to use the compiler as I would do without the tool. The

Having an .mli that may or may not be machine generated would probably 
cause unnecessary problems.

You could also generate the .cmi from the .ml; this is already done if 
it doesn't already exist.  Making minor additions to the top-level 
compiler syntax to indicate whether to exclude or make abstract 
definitions in the .ml when generating the .cmi shouldn't be too 
difficult.

-------------------
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] Automatic generation of mli files

[Chris Hecker]

>Not sure what advantage this would gain.  Step #1 is about as difficult as
>simply writting the .mli file directly.

Yeah, but not if things are changing a lot and you have big types and 
whatnot.  Cutting and pasting or doing the ocaml -i thing is a bit of a 
pain.  I could see it being a useful tool.  Basically anything that 
eliminates repetition is a positive.

>I don't have a problem with .mli files being seperate from .ml files for
>two reasons:
>1) .mli is your external interface-
>2) The compiler checks the signature of the .mli file

Don't forget "3) having a separate interface allows you to decouple 
implementations which is important for large scale software".  Oh wait.

:/

Chris

-------------------
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] Automatic generation of mli files

[Brian Hurt]

On Fri, 6 Jun 2003, Chris Hecker wrote:

> 
> >Not sure what advantage this would gain.  Step #1 is about as difficult as
> >simply writting the .mli file directly.
> 
> Yeah, but not if things are changing a lot and you have big types and 
> whatnot.  Cutting and pasting or doing the ocaml -i thing is a bit of a 
> pain.  I could see it being a useful tool.  Basically anything that 
> eliminates repetition is a positive.

My basic opinion here: feel free to create such a tool.  Have fun.  *I* 
won't use it, but it's no skin off my nose either way.

If I'm heavily modifying a file *and* it's interface, I generally don't 
even bother with a .mli file.  That gets generated when the interface 
settles down.  If you're making big changes in the interface *and* have 
other files that depend upon the interface you're trying to keep up to 
date, then you're going to be having fun anyways.  Be thankfull the 
compiler detects all of those places you forgot to update.

Here's one problem I've hit several times.  In the .ml file, I do 
something like:

type t = foo * bar * bang

Then several functions that use type t.  The type inference will come up 
with types like:
    val add: foo * bar * bang -> foo -> bar -> bang -> foo * bar * bang
when what I wanted was:
    vall add: t -> foo -> bar -> bang -> t

How do you deal with this?

> 
> >I don't have a problem with .mli files being seperate from .ml files for
> >two reasons:
> >1) .mli is your external interface-
> >2) The compiler checks the signature of the .mli file
> 
> Don't forget "3) having a separate interface allows you to decouple 
> implementations which is important for large scale software".  Oh wait.
> 

Function calls are about 1-1.5 clock cycles the last time I measured them.  
I wouldn't have a problem if ocaml disabled all cross-module inlining.  
Inlining within a module is, IMHO, critical- but between modules I would
bet is sigifigantly less important.  People who have hard numbers feel
free to jump in.

Brian



-------------------
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] Automatic generation of mli files

[Chris Hecker]

>If I'm heavily modifying a file *and* it's interface, I generally don't
>even bother with a .mli file.

Yes, this is what I do as well.  It's very nice that you don't need an mli 
at all in ocaml, that makes for a nice dynamic process during 
development.  (See, I said something positive! :)

And, for having mlis around for decoupling for build dependencies (as 
opposed to having them for interface design, where you care about what's 
exported), ocaml -i > foo.mli works just fine.

But, if the tool was lightweight and easy enough, it could be useful.

Chris


-------------------
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] Automatic generation of mli files

[Manos Renieris]

On Fri, Jun 06, 2003 at 12:21:17PM -0700, Chris Hecker wrote:
> 
> And, for having mlis around for decoupling for build dependencies (as 
> opposed to having them for interface design, where you care about what's 
> exported), ocaml -i > foo.mli works just fine.

At least under unix, it does not.
The shell creates foo.mli before the compilation starts; ocamlc sees 
that and believes a .cmi should exist; but it doesn't; so compilation 
aborts.

Xavier Leroy has promised 
(http://caml.inria.fr/archives/200302/msg00078.html)
a separate command line option to generate .mli's without compiling,
but I don't see it yet.

-- Manos

-------------------
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] Automatic generation of mli files

[Chris Hecker]

> > exported), ocaml -i > foo.mli works just fine.
> At least under unix, it does not.
> The shell creates foo.mli before the compilation starts; ocamlc sees
> that and believes a .cmi should exist; but it doesn't; so compilation
> aborts.

Yeah, I didn't mean it worked in a single build instance (Xavier's
replying to my feature request in your link, and yes, hopefully
that'll make it into the next release :), I just meant it works for
generating an mli file if you just want the text file.  In
other words, if I want an mli from an ml, ocamlc -i will generate one
that I can then use for later.  The output fix will make it workable
in a makefile, which will be even better!

Now if it only mattered for decoupling compiles!  :)

Chris


-------------------
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: Re: [Caml-list] Automatic generation of mli files

[Stefan Heimann]

On Fri, Jun 06, 2003 at 02:16:59PM -0500, Brian Hurt wrote:
> On Fri, 6 Jun 2003, Chris Hecker wrote:
> [...]
> 
> Here's one problem I've hit several times.  In the .ml file, I do 
> something like:
> 
> type t = foo * bar * bang
> 
> Then several functions that use type t.  The type inference will come up 
> with types like:
>     val add: foo * bar * bang -> foo -> bar -> bang -> foo * bar * bang
> when what I wanted was:
>     vall add: t -> foo -> bar -> bang -> t
> 
> How do you deal with this?

You could make an annotation in the comment of the method:

(**
  val add: t -> foo -> bar -> bang -> t
*)
let add a x y z = a

Bye,
  Stefan

-- 
Stefan Heimann
http://www.stefanheimann.net :: personal website.
http://cvsshell.sf.net       :: CvsShell, a console based cvs client.

-------------------
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: Re: [Caml-list] Automatic generation of mli files

[Jeffrey J. Cook]

> On Fri, Jun 06, 2003 at 02:16:59PM -0500, Brian Hurt wrote:
> 
> You could make an annotation in the comment of the method:
> 
> (**
>   val add: t -> foo -> bar -> bang -> t
> *)
> let add a x y z = a


Why not just:

let add (a : t) (x : foo) (y : bar) (z : bang ) : t = ...

I find this notation insanely helpful, especially for code inspection.

Jeff


-- 
Jeffrey J. Cook
Graduate Student, Electrical Engineering
University of Illinois at Urbana-Champaign
jjcook@uiuc.edu

-------------------
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] Automatic generation of mli files

[Yang Shouxun]

On Saturday 07 June 2003 04:38, Jeffrey J. Cook wrote:
> > On Fri, Jun 06, 2003 at 02:16:59PM -0500, Brian Hurt wrote:
> >
> > You could make an annotation in the comment of the method:
> >
> > (**
> >   val add: t -> foo -> bar -> bang -> t
> > *)
> > let add a x y z = a
>
> Why not just:
>
> let add (a : t) (x : foo) (y : bar) (z : bang ) : t = ...
>
> I find this notation insanely helpful, especially for code inspection.

I guess annotation in the comment is preferrable, because that allows the 
interface be more specific or general than the implementation.

I have raised the same issue last year. See the thread "automatic extraction 
of mli file?" at http://caml.inria.fr/archives/200210/msg00273.html . 

My idea is to conceive the procedure as part of literate programming in OCaml, 
though the feedback indicates my idea is not popular among the OCaml gurus by 
that time.

I still believe the tool is very valuable and worthwile to develop. Or it can 
be accomplished by enhancing ocamldoc. But I didn't try it.

If anybody wants to develop the tool, I'd be glad to discuss it further.

shouxun

-------------------
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: Re: [Caml-list] Automatic generation of mli files

[Stefan Heimann]

Hi,

On Mon, Jun 09, 2003 at 12:59:11PM +0800, Yang Shouxun wrote:
> On Saturday 07 June 2003 04:38, Jeffrey J. Cook wrote:
> > > On Fri, Jun 06, 2003 at 02:16:59PM -0500, Brian Hurt wrote:
> > >
> > > You could make an annotation in the comment of the method:
> > >
> > > (**
> > >   val add: t -> foo -> bar -> bang -> t
> > > *)
> > > let add a x y z = a
> >
> > Why not just:
> >
> > let add (a : t) (x : foo) (y : bar) (z : bang ) : t = ...
> >
> > I find this notation insanely helpful, especially for code inspection.
> 
> I guess annotation in the comment is preferrable, because that allows the 
> interface be more specific or general than the implementation.

The same can be achivieved with type constraints. But maybe it's the
best to offer both possibilities.
 
> I have raised the same issue last year. See the thread "automatic extraction 
> of mli file?" at http://caml.inria.fr/archives/200210/msg00273.html . 
> 
> My idea is to conceive the procedure as part of literate programming in OCaml, 
> though the feedback indicates my idea is not popular among the OCaml gurus by 
> that time.
> 
> I still believe the tool is very valuable and worthwile to develop. Or it can 
> be accomplished by enhancing ocamldoc. But I didn't try it.
> 
> If anybody wants to develop the tool, I'd be glad to discuss it further.

I've started and played around a little bit with different ways to
extract the information from the .ml file. I think the easiest way
to do it is the write a generator for ocamldoc. I'll clean up the code
written so far and send it to you by email (maybe today, maybe
tomorrow). Then we can discuss everything else.

Bye,
  Stefan

-- 
Stefan Heimann
http://www.stefanheimann.net :: personal website.
http://cvsshell.sf.net       :: CvsShell, a console based cvs client.

-------------------
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] Automatic generation of mli files

[John Max Skaller]

Brian Hurt wrote:

> On Fri, 6 Jun 2003, Chris Hecker wrote:

> type t = foo * bar * bang
> 
> Then several functions that use type t.  The type inference will come up 
> with types like:
>     val add: foo * bar * bang -> foo -> bar -> bang -> foo * bar * bang
> when what I wanted was:
>     vall add: t -> foo -> bar -> bang -> t
> 
> How do you deal with this?


The problem I have is that I instantiate a functor.

The ocamlc -i generated interface lists all the functions,
which sux big time, since one has to continually
reformat them to look pretty, and it's all clutter anyhow.

I'd rather see the interface instantiated.
Hmm .. can this be done?

-- 
John Max Skaller, mailto:skaller@ozemail.com.au
snail:10/1 Toxteth Rd, Glebe, NSW 2037, Australia.
voice:61-2-9660-0850


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