Renaming convension for std modules and pub use as?


#1

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:

ray::env
ray::fs

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?


#2

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.


#3

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.


#4

In rayon, we deliberately mirror the module layout of std for comparable types, like std::slice::Iter and rayon::slice::Iter. I haven’t heard any complaints about this.


#5

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.