dirmod

厌倦了在 mod.rs 中编写和更新所有的 mod 语句？用 dirmod 来生成它们吧。

dirmod 会扫描您的目录，并通过简单的宏调用来自动生成相应的 mod 语句

dirmod::all!();

就这样！

(注意：dirmod 为 Rust 2018 版本 设计，所以宏使用简单且模糊的名称，如 all、os 等。建议使用完全限定的方式调用宏，如 dirmod::all!()、dirmod::os!() 等，以提高清晰度。不推荐使用旧的 #[macro_use] extern crate dirmod; 语法。)

可见性

默认可见性

可以将所有模块设置为共同的可见性，例如 pub mod 或 pub(self) mod 等，由您自行选择

dirmod::all!(default pub);

重新导出

您还可以将所有模块设置为私有，并设置 重新导出 项的可见性

dirmod::all!(default pub use);

单独文件默认值和目录默认值

可能需要分别处理文件模块和目录模块

dirmod::all!(default file pub use; default dir pub);

这将重新导出文件模块中的所有项，并将所有目录模块按名称设置为公共。 (此行为类似于 Go 的包系统)

默认行为

如果没有提供 default 参数，默认选择为 default file priv use; default dir priv

单独可见性

如果在数十个模块中存在需要特殊可见性配置的个别模块，也可以编写

dirmod::all!(default pub; priv foo, bar);

然后所有模块都有 pub 可见性，除了 foo 和 bar，它们是私有的。

同样，如果所有模块都公开重新导出，并且 foo 和 bar 只作为模块导出

dirmod::all!(default pub use; pub foo, bar);

条件编译

但是我使用 mod 来实现条件编译！

没问题，dirmod 为一些惯用风格生成 cfg 属性

• 一个目录，其中每个模块名称都是功能名称（例如 #[cfg(feature = "foo")] mod foo;)
• 一个目录，其中每个模块名称都是操作系统/操作系统家族名称（例如 #[cfg(target_family = "unix")] mod unix;)

这可以通过调用 dirmod::os!()、dirmod::family!() 或 dirmod::feature!() 来实现。

由于同一模块的不同操作系统变体可能暴露相同的 API，因此可能有必要编写

dirmod::os!(pub use);

如果没有任何模块支持当前操作系统，可以触发编译错误

dirmod::os!(pub use ||);

或者使用自定义错误消息

dirmod::os!(pub use || "custom error message");

请注意，在 dirmod::feature! 上使用 || 没有意义，因为 Cargo 功能是增量且不应受到数量限制。

如果遗漏了任何常见风格，请提交问题

但我对 xxxx 边缘情况仍然不满意！

没问题，您不必为每个模块使用 dirmod。 dirmod::all!() 有一个 except 参数，用于排除某些模块。由于宏仅生成 mod 语句，因此在宏调用之前/之后添加更多项是完全可以的。

dirmod::all!(except corge, grault);

文档

不要在 mod.rs 中编写文档，而是在模块中直接编写。除了 dirmod 约束之外，还有一些优点

• 避免在单个 mod.rs 中混合大量的文档。更容易导航！
• 在模块内部编写文档比引用父模块的相关性更大。

要为模块编写文档，请使用以下语法在模块顶部（在所有其他项之前）

//! Yay, I'm now describing myself!
//! I finally have my own place!

支持的 Rust 版本

由于检测源文件需要 proc_macro_span 功能，因此需要 Rust Nightly 来编译此包。

示例

请参阅 testcrate 目录，该目录展示了如何使用 dirmod::all! 和 dirmod::family!。

语法参考

BNF 语法参考可在 syntax.bnf 找到。

已知未解决的问题

rustfmt 支持

rustfmt 和 cargo fmt 通过检测包含文件中的直接 mod 语句来直接对入口点直接包含的模块进行操作。由于 rustfmt 不展开（甚至不编译）宏（已知问题），因此通过 dirmod 包含的模块将不会被格式化。

目前最直接的替代方案是在 Linux Shell 上启用 rustfmt src/**/*.rs 并使用 shopt -s globstar。

错误报告

Rust 编译器可能无法正确定位语法错误的位置（已知问题）。然而，这个问题仅在涉及有关可能为内部属性的起始 #[] 的特定情况下复现，这可能是一个起始属性。