Support `include` for libraries, to "merge" several libraries into one single namespace

[tahina-pro]

Consider a series of libraries pertaining to a data structure, e.g. FStar.Seq and FStar.SeqProperties for finite sequences. Then, to use finite sequences in their programs, end users would have to explicitly import all libraries through:

open FStar.Seq
open FStar.SeqProperties

Ideally, we would like to provide the user with a single library which would be enough for them to import, regardless of how and why the other underlying libraries are organized.
In our example, we would rename FStar.Seq into FStar.SeqBase, and we would like to provide the user with a single FStar.Seq library so that open FStar.Seq would automatically import FStar.SeqBase and FStar.SeqProperties. The contents of FStar.Seq would be something like:

module FStar.Seq
include FStar.SeqBase
include FStar.SeqProperties

This solution would be enough for the user to import all definitions of FStar.SeqBase and FStar.SeqProperties into the unqualified namespace.
(It would be actually similar to Export in Coq, to this respect, see for instance ZArith in the Coq standard library for mathematical integers.)

However, what if the user wants to use both finite sequences and lists in their programs? In particular, what if the user wants to use length and append from both FStar.Seq and FStar.List.Tot, and their associated lemmas? Then, the user will need to explicitly qualify their uses of append with correct namespaces.
In this case, the user will need to figure out that the append related to lists is actually defined in FStar.List.Tot, which is vulnerable to any refactoring of the underlying list libraries.

Ideally we would like to define FStar.List so that the user can access the list-related append using FStar.List.append, regardless of which underlying library it is actually defined in.

BEGIN DIGRESSION
In Coq, this is possible thanks to nested modules. For instance, for mathematical integers, one can do Import ZArith which provides the user with a Z namespace giving access to all operators and lemmas related to mathematical integers, such as Z.add (addition) and Z.add_0_r (the fact that x+0=x.)
In fact, this Z namespace is made of two modules called Z, one defined in BinIntDef and providing Z.add, and another defined in BinInt and providing Z.add_0_r. BinIntDef and BinInt are both exported by ZArith.
Now, if the user only wants to use mathematical integers, they can Import ZArith and Import Z once and get add and add_0_r both in the unqualified namespace, since BinInt.Z has Include BinIntDef.Z.
END DIGRESSION

Of course this is not currently possible in F*. So, we would like to have the proposed include mechanism take care of this namespace issue as well, so that, renaming FStar.List into Fstar.ListBase
and defining FStar.List as:

module FStar.List
include FStar.List.Tot
include FStar.ListBase
include FStar.ListProperties

[tahina-pro]

The following question may need to be spun off as a separate issue at some point: should we shift the focus of the F* standard list library from effectful to total functions? In other words, instead of having FStar.List for effectful functions and FStar.List.Tot for total functions:

• should we instead have FStar.List for total functions and FStar.List.Effectful for effectful functions?
• with the above namespace proposal, should we still have FStar.List.Tot exported by FStar.List, but not have effectful functions exported by FStar.List at all?
• or, on the contrary, should we have both effectful and total functions exported by FStar.List, and if so, which ones should we allow to shadow the others in the FStar.List namespace?

[msprotz]

Isn't it just a matter of having an include directive, where module FStar.List is just the inclusion of several other modules? This scenario may be supported by the "cheap functor" proposal I had a while ago... but maybe a proper export directive would be more appropriate, indeed.

[nikswamy]

I was expecting that this could be supported purely as a namespacing mechanism. If we have module A export B, then resolving A.f while would transitively search in the namespace of B.

[tahina-pro]

export renamed into include, since the proposed feature is similar to OCaml's include