1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110

//! # dirmod
//! [![Travis-CI](https://travis-ci.com/SOF3/dirmod.svg?branch=master)](https://travis-ci.om/SOF3/dirmod)
//! [![crates.io](https://img.shields.io/crates/v/dirmod.svg)](https://crates.io/crates/dirmod)
//! [![crates.io](https://img.shields.io/crates/d/dirmod.svg)](https://crates.io/crates/dirmod)
//! [![docs.rs](https://docs.rs/dirmod/badge.svg)](https://sof3.github.io/dirmod/)
//! [![GitHub](https://img.shields.io/github/stars/SOF3/dirmod?style=social)](https://github.com/SOF3/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:
//!
//! ```ignore
//! dirmod::all!();
//! ```
//!
//! And that's all!
//!
//! > *(Note: `dirmod` is designed for [Rust 2018 Edition](https://doc.rust-lang.org/edition-guide/rust-2018/index.html),
//! so macros take simple and ambiguous names like `all`, `os`, etc.
//! It is recommended to call the macros in fully-qualified fashion
//! like `dirmod::all!`, `dirmod::os!()`, etc. for clarity.
//! The old `#[macro_use] extern crate dirmod;` style is not recommended.)*
//!
//! ## Visibility
//! Modules can be set to a common visibility,
//! so all modules can be `pub mod` or `pub(self) mod`, etc. by default at your favour:
//!
//! ```ignore
//! dirmod::all!(default pub);
//! ```
//!
//! You can also make all modules private, and set the visibility for the *re-exported* items instead.
//!
//! If there are individual modules among dozens that need special visibility configuration,
//! it is also possible to write
//!
//! ```ignore
//! dirmod::all!(default pub; priv foo, bar);
//! ```
//!
//! Then all modules have `pub` visibility,
//! except `foo` and `bar` which are private.
//!
//! ## 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:
//!
//! ```ignore
//! dirmod::os!(pub use);
//! ```
//!
//! If none of the modules support the current OS, you could trigger a compile error:
//!
//! ```ignore
//! dirmod::os!(pub use ||);
//! ```
//!
//! Or with a custom error message:
//!
//! ```ignore
//! 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](https://github.com/SOF3/dirmod) 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.
//!
//! ```ignore
//! 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):
//!
//! ```ignore
//! //! 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`](https://github.com/rust-lang/rust/issues/54725) feature,
//! Rust Nightly is required to compile this crate.
//!
//! ## Examples
//! See the [`testcrate`](https://github.com/SOF3/dirmod/tree/master/testcrate) directory, which demonstrates the use of `dirmod::all!` and `dirmod::family!`.

pub use dirmod::*;