Re: [Caml-list] Wanted: your feedback on the hierarchy of OCaml Batteries Included

[David Teller <David.Teller@univ-orleans.fr>]

On Tue, 2008-11-18 at 12:34 +0100, Daniel Bünzli wrote:
>Besides Hierarchies are anyway limited in their descriptive power and  
>one day you'll find something that will fit in two places, Rope is  
>already an example being both Data.Persistent and Data.Text.

That's correct, there are plenty of modules which could fit in different
places. For the moment, we decided that every module should appear only
in one place. However, we could easily change this -- in fact, to allow
this, we only need to alter our documentation generator.

> Thus my proposal would be to _present_ them as a hierarchy (but even  
> here a mean to tag/browse the modules with/by keywords would do a  
> better job) but keep the actual module structure of Batteries as flat  
> as possible, everything just under the toplevel Batteries. When I code  
> I really don't want to have to think about all these open directives  
> that essentially bring nothing.

Browsing by keywords sounds like an interesting idea. I'm adding this to
our TODO list. Of course, the next step will be to actually add these
keywords and that's going to be much longer if we intend to tag all
values.

However, we disagree on the necessity of a hierarchy. There are two good
reasons why the base library of OCaml doesn't have a hierarchy (almost):
it's small and there are almost no redundancies between modules. Neither
is true for Batteries.

For an example of this redundancy, consider threads. For the moment, we
have five thread-related modules: [Threads], [Mutex], [RMutex],
[Condition] and [Event]. These modules, which are essentially the same
modules as those of the base library, are all submodules of
[Control.Concurrency.Threads]. Now, I personally like
[Control.Concurrency] but I agree that this is debatable. The reason why
we group these modules into [Threads]  is because sooner or later, we
are going to have four or five other thread-related modules called
[Threads], [Mutex], [Condition], [Event] and perhaps [RMutex]. These
modules will get into [Control.Concurrency.CoThreads]. They won't
replace the first batch, they will exist side-by-side. Of course, we
could trim the hierarchy and remove [Control.Concurrency] -- trimming
the hierarchy is the main reason for launching this thread,
incidentally. But, to keep things ordered, we will still need modules
[Threads.Threads], [Threads.Mutex], [Threads.RMutex]...
[CoThreads.Threads], [CoThreads.Mutex]... and, well, that's a hierarchy
already.

coThreads is not an exceptional case, mind you. We may end up with two
definitions of [Graphics], several data structures with the same name
but different purposes, etc.

There's also the issue of labels and other partial redefinitions of
modules. The OCaml base library defines [Array]/[ArrayLabels],
[List]/[ListLabels], [Map]/[MoreLabels.MapLabels] etc. In Batteries
Included, we define [Array], [Array.Labels], [List], [List.Labels],
which clutters less the list of modules and makes for something more
consistent, especially since [FooLabel] is not the only kind of "module
[Foo] with a variant": we also have [Array.ExceptionLess], for
operations without exceptions, and [Array.Cap] for read-only/write-only
arrays. Other variants may still appear.

Do you see any better way of managing the complexity of all this?

Cheers,
 David
-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations.