Question

Consider I have large library package with sophisticated tree of private or package modules — let’s call it funnylib. It’s not desirable for enduser to touch internal modules directly (like funnylib.foo, funnylib.bar etc), so I want to provide external interface instead — like this:

funnylib.d:

public import funnylib.foo;
public import funnylib.bar;
public import funnylib.baz;

to be just imported like import funnylib by enduser. The problem is that D disallows having funnylib.d and funnylib/ at the same time.

Is there something like “default package module” in D, like there is __init__.py in Python? If no, what is right way to do design described above?

Update1: I thought about moving iternal modules to package like funnylib_private, so funnylib will import fine, but this will have cost of protection lowering (strongly undesirable), as funnylib will no longer access package protected symbols, and will result in unpleasant file layout.

Answer 1

You cannot have a module and a package with the same name. So, for instance, Phobos couldn’t have a std/algorithm.d and a std/algorithm/sorting.d. std/algorithm.d and std/algorithm would conflict. The typical thing to do is what ratchet freak describes and use a module named all which publicly imports all of the modules within that package. But if you want to hide the fact that you’re using sub-modules at all, then you could simply do something like

funnylib.d
_funnylib/foo.d
_funnylib/bar.d
_funnylib/baz.d

and not document _funnylib anywhere, but that doesn’t work very well with ddoc, because it’s going to generate the documentation for each of the _funnylib modules, and the most that it’ll generate for funnylib.d is the module documentation, because it doesn’t have any symbols to document. The module system is not designed with the idea that you’re going to be hiding modules like you’re trying to do.

Now, there is currently a proposal under discussion for making it possible to cleanly split up a module into a package when it gets too large (e.g. so that when you split up std.algorithm into std.algorithm.search, std.algorithm.sorting, etc. code which explicitly uses std.algorithm.countUntil won’t break even though it’s now std.algorithm.search.countUntil). And once that’s sorted out, you could use that, but the documentation would still be done for each sub-module, not for your uber-module. It’s really meant as a means of transitioning code, not trying to hide the fact that you’re splitting up your modules. It’s basically just the equivalent of using an all module but with some semantic sugar to avoid breaking code in the case where the package used to be a single module.