{"id":15662304,"url":"https://github.com/sof3/dirmod","last_synced_at":"2025-08-24T06:46:32.001Z","repository":{"id":52367918,"uuid":"213116328","full_name":"SOF3/dirmod","owner":"SOF3","description":"Automatic `mod` declaration with visibility/re-export customization, conditional compilation and more.","archived":false,"fork":false,"pushed_at":"2023-03-20T11:58:37.000Z","size":4245,"stargazers_count":21,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-01T00:55:14.579Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.rs/dirmod/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SOF3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-06T05:56:17.000Z","updated_at":"2025-01-29T00:07:05.000Z","dependencies_parsed_at":"2024-10-23T07:48:03.293Z","dependency_job_id":"68ed273c-e519-4762-ab56-de2750f29cae","html_url":"https://github.com/SOF3/dirmod","commit_stats":{"total_commits":49,"total_committers":3,"mean_commits":"16.333333333333332","dds":"0.061224489795918324","last_synced_commit":"559e428e37d9bf62ad79e08456823f2a3afbc4d3"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2Fdirmod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2Fdirmod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2Fdirmod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2Fdirmod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SOF3","download_url":"https://codeload.github.com/SOF3/dirmod/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251806210,"owners_count":21646843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T13:31:28.155Z","updated_at":"2025-05-01T00:55:22.819Z","avatar_url":"https://github.com/SOF3.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# dirmod\n[![Travis-CI](https://travis-ci.com/SOF3/dirmod.svg?branch=master)](https://travis-ci.om/SOF3/dirmod)\n[![crates.io](https://img.shields.io/crates/v/dirmod.svg)](https://crates.io/crates/dirmod)\n[![crates.io](https://img.shields.io/crates/d/dirmod.svg)](https://crates.io/crates/dirmod)\n[![docs.rs](https://docs.rs/dirmod/badge.svg)](https://sof3.github.io/dirmod/)\n[![GitHub](https://img.shields.io/github/stars/SOF3/dirmod?style=social)](https://github.com/SOF3/dirmod)\n\nTired of writing and updating all the `mod` statements in mod.rs?\nGenerate them with `dirmod` instead.\n\n`dirmod` scans your directory and generates the corresponding `mod` statements automatically\nwith a simple macro call:\n\n```rust\ndirmod::all!();\n```\n\nAnd that's all!\n\n\u003e *(Note: `dirmod` is designed for [Rust 2018 Edition][rust-2018],\nso macros take simple and ambiguous names like `all`, `os`, etc.\nIt is recommended to call the macros in fully-qualified fashion\nlike `dirmod::all!()`, `dirmod::os!()`, etc. for clarity.\nThe old `#[macro_use] extern crate dirmod;` style is not recommended.)*\n\n## Visibility\n### Default visibility\nAll modules can be set to a common visibility,\ne.g. `pub mod` or `pub(self) mod`, etc. at your favour:\n\n```rust\ndirmod::all!(default pub);\n```\n\n### Re-exporting\nYou can also make all modules private, and set the visibility for the *re-exported* items instead:\n\n```rust\ndirmod::all!(default pub use);\n```\n\n### Separate file defaults and directory defaults\nIt might be common to handle file modules and directory modules separately:\n\n```rust\ndirmod::all!(default file pub use; default dir pub);\n```\n\nThis re-exports all items from file modules, and makes all directory modules public by name.\n(This behaviour is similar to the package system in Go)\n\n### The default behaviour\nIf the `default` argument is not given, `default file priv use; default dir priv` is the default\nchoice.\n\n### Individual visibility\nIf there are individual modules among dozens that need special visibility configuration,\nit is also possible to write:\n\n```rust\ndirmod::all!(default pub; priv foo, bar);\n```\n\nThen all modules have `pub` visibility,\nexcept `foo` and `bar` which are private.\n\nSimilarly, if all modules are publicly re-exported and `foo` and `bar` are only exported as modules:\n```rust\ndirmod::all!(default pub use; pub foo, bar);\n```\n\n## Conditional compilation\n\u003e But I use `mod` to implement conditional compilation!\n\nNo problem, `dirmod` generates `cfg` attributes for some idiomatic styles:\n- A directory where each module name is the feature name (e.g. `#[cfg(feature = \"foo\")] mod foo;`)\n- A directory where each module name is the OS/OS family name (e.g. `#[cfg(target_family = \"unix\")] mod unix;`)\n\nThis can be achieved by calling `dirmod::os!()`, `dirmod::family!()` or `dirmod::feature!()`.\n\nIt is likely that different OS variants of the same module expose the same API,\nso it might be practical to write:\n\n```rust\ndirmod::os!(pub use);\n```\n\nIf none of the modules support the current OS, you could trigger a compile error:\n\n```rust\ndirmod::os!(pub use ||);\n```\n\nOr with a custom error message:\n\n```rust\ndirmod::os!(pub use || \"custom error message\");\n```\n\nNote that it does not make sense to use the `||` on `dirmod::feature!`,\nbecause Cargo features are incremental and should not be restricted in amount.\n\n[File an issue][gh-issues] if I missed any common styles!\n\n## But I am still unhappy about xxxx corner case!\nNo problem, you don't have to use `dirmod` for every module.\n`dirmod::all!()` has an `except` argument that excludes certain modules.\nSince the macro simply generates `mod` statements,\nit is perfectly fine to add more items before/after the macro call.\n\n```rust\ndirmod::all!(except corge, grault);\n```\n\n## Documentation\nInstead of writing docs in mod.rs, write them in the module directly.\nIn addition to `dirmod` constraints, there are a few advantages:\n\n- Avoid lots of docs mixed together in a single mod.rs. Easier to navigate!\n- Writing docs inside the module itself is much more relevant than references to the parent module.\n\nTo write docs for the module, use this syntax at the top of the module (before any other items):\n\n```rust\n//! Yay, I'm now describing myself!\n//! I finally have my own place!\n```\n\n## Supported Rust versions\nSince detecting the source file requires the [`proc_macro_span`][proc-macro-span-issue] feature,\nRust Nightly is required to compile this crate.\n\n## Examples\nSee the [`testcrate`][testcrate-blob] directory, which demonstrates the use of `dirmod::all!` and `dirmod::family!`.\n\n## Syntax reference\nA BNF syntax reference is available at [`syntax.bnf`][bnf-blob].\n\n## Known unresolved issues\n### `rustfmt` support\n`rustfmt` and `cargo fmt` operate on the modules directly included by the entry points\nby detecting direct `mod` statements in the included files.\nSince `rustfmt` does not expand (or even compile) macros ([known issue][rustfmt-issue]),\nmodules included by `dirmod` would not be formatted.\n\nThe most straightforward alternative for now is to run `rustfmt src/**/*.rs`\nwith `shopt -s globstar` enabled on a Linux shell.\n\n### Error reporting\nThe Rust compiler may fail to locate syntax error locations correctly\n([known issue][compiler-issue]).\nHowever, this issue has only been reproduced with the specific case\nwhere the syntax error is related to leading `#[]` which could be an inner attribute.\n\n[rust-2018]: https://doc.rust-lang.org/edition-guide/rust-2018/index.html\n[gh-issues]: https://github.com/SOF3/dirmod\n[proc-macro-span-issue]: https://github.com/rust-lang/rust/issues/54725\n[testcrate-blob]: https://github.com/SOF3/dirmod/tree/master/testcrate\n[bnf-blob]: https://github.com/SOF3/dirmod/blob/master/syntax.bnf\n[rustfmt-issue]: https://github.com/rust-lang/rustfmt/issues/3253\n[compiler-issue]: https://github.com/rust-lang/rust/issues/66071\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsof3%2Fdirmod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsof3%2Fdirmod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsof3%2Fdirmod/lists"}