2 releases
0.1.1 | Jan 7, 2022 |
---|---|
0.1.0 | Jan 7, 2022 |
#21 in #visibility
204 downloads per month
Used in lending-iterator
26KB
357 lines
macro-vis
This crate provides an attribute for defining macro_rules!
macros that have proper visibility
and scoping.
The default scoping and publicity rules of macro_rules!
macros are arcane and confusing:
they behave like no other item in the Rust programming language,
and introduce several frustrating limitations that are hard to work around.
This problem will be eventually fixed by a new kind of macro known as declarative macros 2.0,
but that feature has been stuck in limbo for several years now
and likely won't be seen on stable Rust for several years more.
So that's where this crate comes in.
It allows you to place #[macro_vis]
or #[macro_vis(VISIBILITY)]
on any macro_rules!
macro
and have it be treated exactly like any other item that supports a visibility modifier -
structs, enums, functions, et cetera.
It works with both crate-local and public macros,
effectively superseding both #[macro_use]
and #[macro_export]
.
See the documentation of #[macro_vis]
for examples and usage.
The uncommon_codepoints
warning
You will get the uncommon_codepoints
warning if you use this library,
so you will probably want to place this in your crate root:
#![allow(uncommon_codepoints)]
Documenting public macros
The documentation of public macros can be slightly improved if run on a Nightly compiler. To enable this, you must first add this attribute to your crate root:
#![cfg_attr(doc_nightly, feature(decl_macro, rustc_attrs))]
Then you can build with the doc_nightly
cfg set,
either locally with RUSTDOCFLAGS="--cfg doc_nightly" cargo +nightly doc
or on docs.rs by adding this to your Cargo.toml
:
[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "doc_nightly"]
How it works
The trick to get non-pub
macros working is simple;
we just use
the macro after its definition to get it to be treated like an item.
The original macro is renamed to a randomly-generated identifier
so it can't be accessed by regular code.
This code:
#[macro_vis(pub(crate))]
macro_rules! example_macro { () => {}; }
Gets expanded to something like:
macro_rules! __example_macro_2994407750278293171 { () => {}; }
pub(crate) use __example_macro_2994407750278293171 as example_macro;
pub
macros work the same, but apply #[macro_export]
to the macro and ensure it doesn't show
up in the documentation:
#[doc(hidden)]
#[macro_export]
macro_rules! __example_macro_2994407750278293171 { () => {}; }
pub use __example_macro_2994407750278293171 as example_macro;
But because a re-export of a #[doc(hidden)]
item is itself #[doc(hidden)]
,
the macro doesn't show up in the documentation at all.
To solve this, the library employs two solutions depending on whether Nightly is available or
not:
-
When
doc_nightly
is not enabled, the library emits a public function whose name is the macro name concatenated with LATIN LETTER RETROFLEX CLICK (ǃ), a character that looks nearly identical to the exclamation mark used to invoke macros. This is done to avoid name collisions between other functions of the same name and the macro's documentation double. However, it has the flaw of causing the macro to appear as a function in the docs even though it isn't, and it doesn't work well with re-exports. -
When
doc_nightly
is enabled, the library instead changes the macro to be a macros 2.0-stylepub macro
which obeys proper visibility rules by default. Unlike the previous solution, this one displays the macro in the correct documentation section and with the correct text color, as well as it working properly with inlined re-exports. The drawback is that it doesn't work on stable, and so has a greater risk of breaking in future.
MSRV
This crate's minimum supported Rust version is 1.53,
the first version to stabilize non_ascii_idents
.
It is currently considered a breaking change to increase this.
Credit
Most of the ideas in this crate were discovered and shown to me by Daniel Henry-Mantilla, so much of the credit goes to them.
License: MIT
Dependencies
~78KB