DIP16: Transparently substitute module with package

[Jonathan M Davis]

On Friday, March 30, 2012 09:46:19 Andrei Alexandrescu wrote:
> Starting a new thread from one in announce:
> 
> http://prowiki.org/wiki4d/wiki.cgi?LanguageDevel/DIPs/DIP16
> 
> Please comment, after which Walter will approve. Walter's approval means
> that he would approve a pull request implementing DIP16 (subject to
> regular correctness checks).
> 
> 
> Destroy!

The first part with package.d seems like a good idea and certainly affects some 
of what I've been doing with std.datetime. In order to split it right now, you 
need a new package name, leaving the original for importing everything, and 
this provides a better way of dealing with that.

However, I'm very nervous about the second part. e.g. std.sort instead of 
std.algorithm.sort seems like a bad idea to me. It increases the odds of name 
conflicts for little benefit. Not to mention, it'll make it a lot more confusing 
to find what modules stuff is actually in if people start doing stuff like

std.sort(arr);

In the case of sort, you may know where it's from - particularly since it's so 
common - but the less well-known the function is, the less likely that is at 
all obvious where it comes from, and if you're dealing with 3rd party 
software, then it wouldn't be at all obvious. For instance, how would you know 
that party.foo is really party.bar.foo? You wouldn't. Being so lax about 
importing could really harm code readibility (and maintainibility, since it 
increases the odds of name clashes). So, I'm inclined to say that that is a 
_bad_ idea.

I'd propose that we make it so that if a module publicly imports another 
module, then you could treat it as if it were in that module. So, because 
std.datetime.package publicly imports std.datetime.systime, you could use 
std.datetime.SysTime instead of std.datetime.systime.SysTime. The compiler 
would need to realize that they're exactly the same symbol (we've had bugs 
relating to importing with : and the like which ended up creating new symbols, 
and we don't want that here), but that shouldn't be all that hard. That gives 
you control over which symbols are able to be treated as if they were in a 
given package rather than affecting everything indiscriminitely (and if you use 
: with public imports, it should then be possible, to restrict it to the 
_exact_ set of symbols that you want if you don't want all of the symbols to 
be treated as if they were in that module).

Another question is how this affects the documentation. Does package.d generate 
a page just like the other modules do? The lack of a module declaration could 
make that difficult (not impossible, but it would probably require changes to 
ddoc in addition to the module stuff). Also, does that page get treated in any 
special manner in how the documentation is laid out, because it's for the 
package as a whole (probably more of a site question than a ddoc one though)? 
I'd like to be able to have a page describing the package as a whole for 
std.datetime in addition to having the individual pages rather than just 
splitting it up, and leaving the programmer to read each of the individual 
pages with no overview. And I think that however package.d works, it needs to 
enable that.

- Jonathan M Davis