1 unstable release
0.1.3 | Oct 21, 2019 |
---|
#11 in #conditional-compilation
22KB
dirmod
Tired of writing and updating all the mod
statements in mod.rs?
Generate them with dirmod
instead.
dirmod
scans your directory and generates the corresponding mod
statements automatically
with a simple macro call:
dirmod::all!();
And that's all!
(Note:
dirmod
is designed for Rust 2018 Edition, so macros take simple and ambiguous names likeall
,os
, etc. It is recommended to call the macros in fully-qualified fashion likedirmod::all!()
,dirmod::os!()
, etc. for clarity. The old#[macro_use] extern crate dirmod;
style is not recommended.)
Visibility
Default visibility
All modules can be set to a common visibility,
e.g. pub mod
or pub(self) mod
, etc. at your favour:
dirmod::all!(default pub);
Re-exporting
You can also make all modules private, and set the visibility for the re-exported items instead:
dirmod::all!(default pub use);
Separate file defaults and directory defaults
It might be common to handle file modules and directory modules separately:
dirmod::all!(default file pub use; default dir pub);
This re-exports all items from file modules, and makes all directory modules public by name. (This behaviour is similar to the package system in Go)
The default behaviour
If the default
argument is not given, default file priv use; default dir priv
is the default
choice.
Individual visibility
If there are individual modules among dozens that need special visibility configuration, it is also possible to write:
dirmod::all!(default pub; priv foo, bar);
Then all modules have pub
visibility,
except foo
and bar
which are private.
Similarly, if all modules are publicly re-exported and foo
and bar
are only exported as modules:
dirmod::all!(default pub use; pub foo, bar);
Conditional compilation
But I use
mod
to implement conditional compilation!
No problem, dirmod
generates cfg
attributes for some idiomatic styles:
- A directory where each module name is the feature name (e.g.
#[cfg(feature = "foo")] mod foo;
) - A directory where each module name is the OS/OS family name (e.g.
#[cfg(target_family = "unix")] mod unix;
)
This can be achieved by calling dirmod::os!()
, dirmod::family!()
or dirmod::feature!()
.
It is likely that different OS variants of the same module expose the same API, so it might be practical to write:
dirmod::os!(pub use);
If none of the modules support the current OS, you could trigger a compile error:
dirmod::os!(pub use ||);
Or with a custom error message:
dirmod::os!(pub use || "custom error message");
Note that it does not make sense to use the ||
on dirmod::feature!
,
because Cargo features are incremental and should not be restricted in amount.
File an issue if I missed any common styles!
But I am still unhappy about xxxx corner case!
No problem, you don't have to use dirmod
for every module.
dirmod::all!()
has an except
argument that excludes certain modules.
Since the macro simply generates mod
statements,
it is perfectly fine to add more items before/after the macro call.
dirmod::all!(except corge, grault);
Documentation
Instead of writing docs in mod.rs, write them in the module directly.
In addition to dirmod
constraints, there are a few advantages:
- Avoid lots of docs mixed together in a single mod.rs. Easier to navigate!
- Writing docs inside the module itself is much more relevant than references to the parent module.
To write docs for the module, use this syntax at the top of the module (before any other items):
//! Yay, I'm now describing myself!
//! I finally have my own place!
Supported Rust versions
Since detecting the source file requires the proc_macro_span
feature,
Rust Nightly is required to compile this crate.
Examples
See the testcrate
directory, which demonstrates the use of dirmod::all!
and dirmod::family!
.
Syntax reference
A BNF syntax reference is available at syntax.bnf
.
Known unresolved issues
rustfmt
support
rustfmt
and cargo fmt
operate on the modules directly included by the entry points
by detecting direct mod
statements in the included files.
Since rustfmt
does not expand (or even compile) macros (known issue),
modules included by dirmod
would not be formatted.
The most straightforward alternative for now is to run rustfmt src/**/*.rs
with shopt -s globstar
enabled on a Linux shell.
Error reporting
The Rust compiler may fail to locate syntax error locations correctly
(known issue).
However, this issue has only been reproduced with the specific case
where the syntax error is related to leading #[]
which could be an inner attribute.
Dependencies
~1.5MB
~38K SLoC