Renaming convension for std modules and pub use as?

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?

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.

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.

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.

1 Like