I’m developing software (with the fictitious crate name “ray”) that will provide utility code and a simpler facade to some of the modules in the std library. To keep everything tidy, I’ve been mirroring the std library module structure, for example:
Of course, this would cause naming clashes with the std lib when used in client code, and I don’t want to force users to explicitly state
ray:: on every usage or force them to rename on import with
use ... as. Am I correct in concluding that you can’t re-export these modules at the root and at the same time rename the module using the
as keyword like so?..:
pub use ray::env as envr
Also, with regard to the module names, is there any convention for this use case where, for example, you’d want to add a prefix or suffix to the module name to imply that it’s an extension to an existing module by, for example, suffixing with a fairly common
x for extension?
Std uses many submodules, because it is large. If your library is not as large, then consider just having everything at the top level. Then
ray::File may be convenient enough to use.
Users of your crate will be able to do
pub use ray::env as envr. They can also do
extern crate ray as r and
r::env. However, you can’t do that for them. You can’t influence names outside your crate’s namespace.
Some crates have a
prelude module and instruct users to do
use ray::prelude::*, but that requires being extra careful about not conflicting with anyone else’s names, and it’s mostly necessary only if you rely on your traits being available by default.
Thanks for your input. I had considered having everything at the top level but that seemed impractical at the time (everything in one file), as it was before I discovered the ability to re-export at the top level.
I think if I keep the code mirroring the std libs file/directory structure, but re-export items at the top level, I can identify name clashes and always refactor if things get out of hand.
rayon, we deliberately mirror the module layout of
std for comparable types, like
rayon::slice::Iter. I haven’t heard any complaints about this.
Keep in mind that you can re-export items as public from private modules, so your internal crate structure can be anything you like, and different from publicly exported one.