[Caml-list] automatic extraction of mli file?

[Caml-list] automatic extraction of mli file?

[Yang Shouxun]

First, I'd say I like the idea of OCaml has separate interface and 
implementation files.

I'm quite new in OCaml and I want to know what is the practice of the 
OCaml programmers. Will you first write the interface files, then 
implement, or vice versa? I think neither way is satisfactory. I guess 
the first approach goes against prototyping and the second means both 
duplicated work and violation of software engineering.

What I'm wondering is "wouldn't it be preferrable to automatically 
produce the interface file from the implementation file?", so that we 
can program in the literate programming style, do prototyping, and save 
the drudgery of writing the interface (though a little manual editing 
may be necessary, or some kind of markup in the source code).

Maybe such utility already exists. Only I'm not aware of. If so, I'd 
like to know how to get it.

Thanks.
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: [Caml-list] automatic extraction of mli file?

[Nicolas Cannasse]

> What I'm wondering is "wouldn't it be preferrable to automatically
> produce the interface file from the implementation file?", so that we
> can program in the literate programming style, do prototyping, and save
> the drudgery of writing the interface (though a little manual editing
> may be necessary, or some kind of markup in the source code).
>
> Maybe such utility already exists. Only I'm not aware of. If so, I'd
> like to know how to get it.

The "-i" ocamlc compiler flag is what you need.
It prints all the types found in the ML file.
But since there is no rule for interface exclusion, you have to maintain
separatly both ML & MLI files.

For example, if you start working on a new module, you can start writing it
without any interface ( then all members are "public" ) and after some
testing you write the interface and that way ensure that your implemenation
match exactly what's in your mind ( not always obvious :)

Nicolas Cannasse

-------------------
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 extraction of mli file?

[Yang Shouxun]

Nicolas Cannasse wrote:
>>What I'm wondering is "wouldn't it be preferrable to automatically
>>produce the interface file from the implementation file?", so that we
>>can program in the literate programming style, do prototyping, and save
>>the drudgery of writing the interface (though a little manual editing
>>may be necessary, or some kind of markup in the source code).

> The "-i" ocamlc compiler flag is what you need.

This seems to be not what I mean. OK, that is what I asked :(.

All the comments will be removed. That is not desirable, for the mli 
file is meant to be read by both machine and humans. The humans need the 
comments to make sense of the interface file, without reference to the 
implementation code.

I guess an extension to the ocamlweb is what I mean.

Best!
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: [Caml-list] automatic extraction of mli file?

[Sven LUTHER]

On Sat, Oct 12, 2002 at 07:50:55PM +0800, Yang Shouxun wrote:
> Nicolas Cannasse wrote:
> >>What I'm wondering is "wouldn't it be preferrable to automatically
> >>produce the interface file from the implementation file?", so that we
> >>can program in the literate programming style, do prototyping, and save
> >>the drudgery of writing the interface (though a little manual editing
> >>may be necessary, or some kind of markup in the source code).
> 
> >The "-i" ocamlc compiler flag is what you need.
> 
> This seems to be not what I mean. OK, that is what I asked :(.
> 
> All the comments will be removed. That is not desirable, for the mli 
> file is meant to be read by both machine and humans. The humans need the 
> comments to make sense of the interface file, without reference to the 
> implementation code.

Well, in general, you write the .ml, and once you are satisfied, you can
generate the .mli, and adapt it to your need : add comments, remove
uneeded info, etc.

Later one, you have to maintain both files separatedly. The idea being
that the .mli is the contract that the .ml has with its users, so
basically you can improve on the .ml, without changing much its
interface.

Another way of programming, is writting the .mli first, so it correspond
to what you want, and then write the implementation of it.

But any way you do it, normally you don't change the .mli very much
after the first writing, so it is ok to maintain it by hand.

Friendly,

Sven Luther
-------------------
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 extraction of mli file?

[Claude Marche]

>>>>> "Yang" == Yang Shouxun <yangsx@fltrp.com> writes:

    Yang> All the comments will be removed. That is not desirable, for the mli 
    Yang> file is meant to be read by both machine and humans. The humans need the 
    Yang> comments to make sense of the interface file, without reference to the 
    Yang> implementation code.

    Yang> I guess an extension to the ocamlweb is what I mean.

I would not have answered if you did not talk about ocamlweb. But as
one co-author, please let me say that I don't like this
idea. Mainly, because comments you put in a .mli and in the
corresponding .ml should not be the same. in the interface, you
document your module for use by another programmer, whereas the
comments of the implementation should be for explaining your code, your
algorithms, etc.

My advice is: always start a module by writing the .mli. When
prototyping, that usually means that you will add only one value, for
the main function of your module. When I teach ocaml to students, I
always insist on that, because it's better to force you write down
*what* you want to code, before thinking about *how*.  

Then later, you may add to the .mli other functions, exceptions,
etc. and in any case you will both maintain the .mli and the .ml
independently.

- Claude


-- 
| Claude Marché           | mailto:Claude.Marche@lri.fr |
| LRI - Bât. 490          | http://www.lri.fr/~marche/  |
| Université de Paris-Sud | phoneto: +33 1 69 15 64 85  |
| F-91405 ORSAY Cedex     | faxto: +33 1 69 15 65 86    |
-------------------
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 extraction of mli file?

[Remi VANICAT]

Yang Shouxun <yangsx@fltrp.com> writes:

[...]


> Maybe such utility already exists. Only I'm not aware of. If so, I'd
> like to know how to get it.

ocamlc with the -i option extract automatically a mli file with
everything public

-- 
Rémi Vanicat
vanicat@labri.u-bordeaux.fr
http://dept-info.labri.u-bordeaux.fr/~vanicat
-------------------
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 extraction of mli file?

[Xavier Leroy]

> I'm quite new in OCaml and I want to know what is the practice of the 
> OCaml programmers. Will you first write the interface files, then 
> implement, or vice versa?

Here is my recipe: you write an interface file when the interface of
your module becomes clearly defined, and you feel ready to document
the interface.

For some modules, typically data structures, this means the interface
is written first: you know that you'll need, say, doubly-linked
circular lists, and you have a fairly clear idea of what operations
you'll need.  Then, you can write the interface and some comments on
the behavior of the functions, and go ahead with writing the remainder
of the program.  Later, you'll implement the data structure.

For other modules, you'd typically start with the implementation and
no interface file, as the external interface to your module isn't
clear yet.  When it stabilizes and needs to be documented, now is the
time to write an interface file.

Think of it this way: the interface file is where you document (via
comments) the external, behavioral specification of your code.
Comments in implementation file should just be comments on how the
implementation works (e.g. "this is Kildall's worklist algorithm, as
documented in <blah> section 11.4.2").  If you ever feel like
writing a behavioral comment in an implementation file ("this function
computes this and that"), don't: create the interface file instead.

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